Sounds like "you can't learn true Judo without traveling to some mountain temple and eating nothing but rice and punching a brick wall all day for 3 years"
Furthermore, it's another case of some old Usenet hyperbole being taken as Gospel (or taken down as Gospel, which is ore the style now). One of the most important lessons the Jargon file has for "how to become a hacker", is "don't take anything too seriously."
> One of the most important lessons the Jargon file has for "how to become a hacker", is "don't take anything too seriously."
Especially not the Jargon File. It largely comes from a particular period of time at MIT and Stanford, which is interesting in a historical sense but nobody should try and "become a hacker" by reading the Jargon File. Also it's had all sorts of injections and alterations by self-appointed Jargon File steward Eric Raymond, who should be ignored completely.
I only wish I could have told my 16-year-old self this.
>Sounds like "you can't learn true Judo without traveling to some mountain temple and eating nothing but rice and punching a brick wall all day for 3 years"
Nothing but rice.
Typical comment :)
Let the other points go, but it's Kung Fu, and not just a brick wall.
An enormous page full of switches and options, yet if you're a beginner it's basically useless. You're just looking for a simple example of how to search for a file. find . -i -name <regex> is NOT mentioned anywhere, you have to figure it out yourself. And if you mess it up, your terminal gets flooded.
I've found tldr (https://tldr.sh/) very useful for quick lookups - basically gives examples with short descriptions, which is very often mostly what's needed.
My favorite is cheat.sh, which is a similar thing to tldr, but the best part about cheat is that you can just `curl cheat.sh/ln` (or whatever command) and get the cheat sheet on any system. I use this all the time.
"An enormous page full of switches and options, yet if you're a beginner it's basically useless."
Maybe 30 years ago you could learn through manpages but today that's how all the man pages of all the useful commands look. If you think grep is nice it would be the exception; for me it is indeed short, simple and easily searchable, but too terse for a beginner to learn with easily. (Plus even the regex documentation only documents grep mode, not egrep or pgrep or anything else.) Very useful in its own way, but most man pages are useless for learning.
I am disappointed at how few man pages take the opportunity to have a useful selection of "the 10 most popular things to do with this command" but web search has filled in reasonably decently. You do still have to understand the basics of how shell works, though, because most of them aren't quite what you want today and honestly a fair number of them aren't even what the poster thought they were. I am also in the habit of making sure that I understand every command line switch before I copy & paste a command off the internet, again, because many of them aren't what you need today. I don't always mean in a malicious manner, but things like either do or do not follow HTTP redirects in curl may or may not matter to you today, but the poster may be in the habit of setting it one way or another for no reason relevant to you.
I wonder if chatgpt will start “closing” questions as “not a good fit for its Q&A format,” or “too opinionated,” or “a duplicate” of something that is acutely unrelated.
Actually, this seems to be a case where chatgpt is smarter than the humans.
As of now, there is no LLM without confabulation, so your third item is effectively "hypothetical fantasy ChatGPT that we hope will be available some time in the future", not the actual tools we have right now.
A recent example: I used ChatGPT 4 to draft an mkvmerge command - take 2 video files, and merge them by only copying certain audio and subtitle tracks from the second file into the first file.
The resulting command looked good at first sight, something like „mkvmerge -o output.mkv first.mkv —-no—video -s 1 -a 2 -a 3 -a 4“. The problem here is that there can only be one -a flag, so it should have been „-a 2,3,4“ instead. But mkvmerge didn’t really care and just discarded every -a flag except the last one. So I ended up with only one of the audio tracks copied over. I only noticed when I actually checked the resulting file that it had less audio tracks than it was supposed to.
This would not have happened to a human after studying the man page - the documentation is very clear about the -a flag and I have no idea what led ChatGPT to come to the conclusion it did.
The lesson here is not to anthropomorphize ChatGPT. It didn't "conclude" anything. Based upon a corpus that includes tonnes of humans writing rubbish on the WWW, it came up with plausibly human-appearing rubbish that can fool humans. GIGO would apply, except that one can remix non-garbage into garbage with suitable statistical processes, we have now (re-)discovered. (-:
There is a pre-internet and Internet pre-Stackoverflow bit. Called O'reilly books.
Learning to program for example Perl. I had the learning book, the reference book and the cookbook. learning I did once, the reference had post its on it and was on my work desk. The cookbook was more the facebook type you read it on the toilet.
They had books on everything that were the industry standard. DNS, Apache, Javascript, ... The revised them regularly. For Js had the 1st, 2nd, 3rd edition. I know this sounds all ancients like real paper books. But even work had O'reilly subscription so you could order what you need.
For me it was O'reilly books, man pages. But lets not forget when you installed Linux like RedHat (not fedora yet) you could install the linux howtos. Oh boy did I learn a lot from them too: https://tldp.org/HOWTO/HOWTO-INDEX/howtos.html
Finally there was IRC if you were stuck but this was off course the internet stage. I just went online to ask a question, dialup was expensive ;)
the openbsd manuals usually have examples. you can see how compact https://man.openbsd.org/grep.1 is compared to the gnu grep manual.
i've been using https://git.causal.agency/exman/about/ to compare linux and bsd manpages, and it has saved me an incredible amount of time looking things up.
Are info pages still a thing? I remember being very confused by them back when I started out with Linux, and eventually just stopped trying to understand how they worked.
They are, but my impression is that only Emacs users use them to some extent. (Emacs has a built-in info reader that is better than the standalone client, and ships mainly info pages as its documentation.) Outside of Emacs, I’d say very few people know info is even a thing, and I remember some Linux distributions also stripped info pages from packages since everyone used man pages.
In fairness, if one were to come to more, pg, or less with no prior knowledge of the conventions, the madness of some of the character choices would be just as grating.
Ironically, this sort of stuff -- the basic conventions like qhjkl0^$G + CRFFBSSPC keyboard navigation and :/? prompt modes -- is exactly what one initially learns from guides, tutorials, other people in IRC, and whatnot, long before coming to reference doco. The _Introduction to Linux_ book at TLDP covers the bare essentials of these conventions, q, b, and SPC, in the "quickstart" chapter 2.
Every time I could not find and answer to a question in a man page and consulted info, it was a waste of time. I like info, really, but the remark at the end of most GNU man pages to look at the info pages is misleading at best.
For emacs stuff, yes, it's very convenient. I remember once upon a time, Python docs were available in info as well. When you have good documentation available in info, it's very nice.
I remember offering to make a PR w/ examples for something when I was a junior dev and was politely told that they didn't want examples. I assumed - and still assume - that this was a generational difference in what people expected competence to look like.
While this attitude made sense pre-internet, reading about every switch for common use cases is just not realistic today. Maybe if the number of command-line programs were less, and the complexity of each command was significantly less, I could see how it would be done, but not today.
This goes deeper, since understanding grep regexes involves understanding quoting.
This means not only how regexes distinguish between literals and control characters, but how the shell distinguishes and passes on characters to the regex that grep receives as an argument.
I think regex quoting is one of the major stumbling blocks of comprehension.
Even after decades using regexes, I still stumble (especially when my regexes are used in the shell, in emacs, in python re.match, etc...)
Which rather reinforces the point of the headlined article: People actually learn a lot of stuff when they start out from tutorials, guides, handbooks, and whatnot; not from purely reading reference doco. I started out with books, too. Later people would have started with the likes of TLDP.
I suspect that the author is right that most people started with guides/handbooks/tutorials, even the ones who later on convince themselves that they only read reference doco.
Do you mean the other way around? The manpage of find contains examples, including searching for files by name. This alone make the manpage somewhat usable for beginners. The grep manpage does not have any examples.
The grep manpage spends much explaining regex and environment variables, find more on options.
Both manpages are searchable, what makes the grep manpage more searchable?
find(1) is a classic example. The first two or three pages are of essentially zero practical use. I open the manual, skim the first page, no obvious clues about how to actually use `find`, so my next step is always to go to web search.
I've got a thousand things to do that are better uses of my time than reading 20 pages of arcane documentation that may or may not answer my question.
Then remember that some operating systems come with handbooks and guides, and if one wants a tutorial for beginners, reference doco is not the place to start at all. So next contrast with the SCO UnixWare users guide, which also starts off with find file by name and print:
NetBSD doesn't look all that more helpful, you just get to examples sooner because it has far less options
The NetBSD examples also only document what command do, while the util-linux sometimes go into details of why, like when describing how exactly the time directive works and why `-mtime 0` shows files from last 24 hours.
That's a little inflammatory. Could you provide constructive input on your reasoning behind that statement? I personally found it a simple, concise explanation of what find is for.
After about 30y of using *nix of one kind or another, I only use the EXAMPLES section of man pages as I know that most writers write to sound out their ideas, and the first bits are worse than useless. If there isn't one, I go to stackoverflow.
The same style extends to library documentation, where you have functions and arguments with types and no other context. It's basically for posterity.
Agreed, lack of examples was my biggest gripe with the manly pages when I was a Linux newbie. The most frustrating part is, you know they do it on purpose, so that you have to read the entire thing! News flash, I'm here because I'm stuck and want to get unstuck ASAP, not because I'm bored and want to learn the intricate details of find/grep/whatever.
it's like looking at a ton of gibberish and trying to figure out what it says. it doesn't match the languages, it doesn't appear to match any standards.
I learned a lot from man pages in the 80's and 90's, and if I had to try to learn now from something like this, I'd likely just throw up my hands and choose another career.
My educated guess is that something is trying to italicize various keywords, and whatever text processing is going on isn't working, but producing bogus "In" literal text instead.
It even prettifies those ``'' quotes, notice. This is vanilla older FreeBSD man, using groff, but actually allowing groff to do the things that it is capable of.
As others have noted, the 'In' looks like a rendering bug with whatever terminal emulator you're using. Otherwise it looks pretty normal: `fopen (const char *restrict filename, const char *restrict mode)` looks like a perfectly good C function, and (if you already know C) it's easy to see the parts that don't look like they belong.
Find is the worst example given it breaks the do one thing and do it well motto of unix. (and you can do one thing and do it well), After discovering dmenu's stest and googles walk, most times I just need a { walk $PWD | stest -f | rg } and I'm done. Maybe you need more, in which case, instead of find, you should run stat with the output formatted to json/csv and then filter using your preferred csv method or jq.
I was pleased with how expect's man page [0] oriented me (instead of "it's all there, go figure"):
> Commands are listed alphabetically so that they can be quickly located. However, new users may find it easier to start by reading the descriptions of spawn, send, expect, and interact, in that order.
In addition to being informative, they're also sometimes funny. I remember that the HP/UX tunefs man page said, "You can tune a filesystem, but you can't tune a fish."
As with many things in UNIX, the ability to tune a fish is implementation-dependent, and testing is recommended before using it in production on any given platform.
One of my favorite man pages is openbsd's scan_ffs. mainly because it contains this pearl of wisdom
The basic operation of this program is as follows:
1. Panic. You usually do so anyways, so you might as well get it over with. Just don't do anything stupid. Panic away from your machine. Then relax, and see if the steps below won't help you out.
Books remained current for a longer time back then but it was already clear to me that they are not the way to go. Manpages were current. Experimenting is the way to learn stuff. Books as references have been basically dead since 1994 and the first websites with Javadocs IMHO.
The numerous similar books, now about Linux, that have been published in the first quarter of the 21st century indicates that your humble opinion is out of step with reality. (-:
I've always found reference books a lot easier to get my head around than instructional textbooks. One of my favorite finds as a kid was a book about the Apple II that covered topics like the memory map and hardware registers, and my least favorite format was the 300-page book where you start with writing "Hello World" and twenty chapters in you're following instructions on how to schedule asynchronous messages or something. I don't think I've ever gotten past chapter three in a book like that, and I've had a reasonably successful, decades-long career in development.
What I don't understand is why don't manpages have clear example of common usages? I imagine there's many many people that want to contribute that to the manpages, are they not there because leadership doesn't allow them for some reason?
Take grep for example https://linuxcommand.org/lc3_man_pages/grep1.html - it has everything and the kitchen sink but hell bro tell me how to find something is the 99% use case most people will use it.
From my experience most manuals actually don't have scenarios. Is git or docker better? I need to check and see, but from memory their manual pages mostly list all switches but a couple of examples at best. I could be wrong and need to double check.
They do have. You're just looking at the manual from one particular source of utilities, GNU, and overgeneralizing. Aside from the well-known antipathy to man pages, with every GNU manual page telling you at its foot to go and use a different tool to read a different doco format, it is not representative of manual pages in general.
The Illumos manual page for grep(1) has an examples section:
From my experience some manpages glaringly miss examples or explanations. Hint: all manpages that you don't need to move down for more contents probably fall into this catalog.
I completely agree that they are only useful if you know what you are looking for, and nothing else.
Although I'm still a newbie, but I'll never tell a complete newbie to RTFM, considering there is not many high quality manual out there. Actually most hottie open source tools we happened to introduce into our workflow have half-assed doc at most. I'll just teach him to Google stuffs efficiently and let himself figure out the rest. Sometimes it's surprisingly difficult to know what exactly to put into that search box.
I'm not a hacker. I'll never be even close to Ritchie, Carmack, whoever write state of art malwares. I know the pain.
Too many people think that GNU manual pages are what all manual pages look like. Not everyone has the GNU tradition of telling you to switch to a different doco format for better man pages. (-:
The thing to remember is that for many systems there are both guides and handbooks, tutorial style doco, in addition to the reference doco, the manual pages. Linux-based operating systems come up a bit short in comparison to the old commercial Unices which had specific user guides, and in comparison to the BSDs, all of which have handbooks. Even Debian only has an admininstrators' guide, not a users' guide.
But The Linux Documentation Project is oft forgotten. It's stale. It's unfashionable. It's oddly chock full of how-tos for things that one wouldn't dream of wanting to do this century. But it also has longer format stuff, and it's still there.
> This is how we get monstrosities like the Git documentation, that are only of any use to someone who already knows how it works and just needs a bit of a reminder.
Git is seriously weird in that regard. It reads like someone just really wanted to build a content-addressable file system and a generic append-only graph data structure on top, and then, to their mild annoyance, people were starting to use it as a version control system...
To be fair, manpages were intended for tools that followed the Unix philosophy ("small programs that do one thing well, and can be composed together easily"). git does not follow this philosophy. If it did, we'd have tools named checkout, clone, push, etc. rather than one git binary that does all of them (with highly irregular and non-orthogonal syntax!)
Man pages are generally not always that great. I recommend people instead digest the GNU `info' manuals, as you'll come away with a much deeper understanding of all the userspace binaries you're likely to interact with on many common Linux systems today.
I'll make this iron clad promise: if you sit down and read the coreutils manual end-to-end (it'll take a couple of hours) you'll come away brimming with new ways to optimise your CLI workflow.
If you're allergic to the `info' program itself, you can of course read the manuals on GNU's website or, better still: use Emacs's info viewer (`C-h i' or M-x info), which is far superior.
Info has some really crap defaults. I invested some time to make a nice custom config and now I wish more things had info pages, because they're a joy to read.
The only key bindings I added were the ability to scroll up/down single lines, because I find page-scrolling annoying. But other than that, by crap defaults I mostly meant presentational issues. Once you spend a couple of minutes to learn the navigation shortcuts, they're not that hard to learn and they make using info quite pleasurable.
Here is my own .infokey file, in case it is of interest.
#info
j up-line
k down-line
#var
link-style=blue,underline
active-link-style=yellow,bold,underline
cursor-movement-scrolls=Off
scroll-behaviour=Page Only
highlight-searches=On
nodeline=print
Here's how people will learn Unix from here on out - they'll ask the chatbot to teach it to them:
Q "Please provide an outline and course syllabus for a ten-week course on Unix, aimed at undergraduate students in a college-level computer science program, as taught by an expert in Unix operating systems who has comprehensive historical knowledge of their development."
E.g. > "Week 4: Process Control; Process creation and termination; Process states and signals; Job control and background processes"
Need more? Q: "What are the most popular and useful process management tools for a Unix operating system?"
As far as how to read the man pages for any command, for beginners:
Q: "Provide a synopsis of the ps command's man page in a format suitable for a student who is just beginning to learn about process management."
Yes, you still should double-check those commands against the man reference - but think of all the benefits - students can get answers to their questions without having to pay private tutors or run the gauntlet of online forums where their ignorance will result in ridicule and similar unhelpful behavior, e.g. 'just read the man pages and think about it!', and they can ask as many dumb questions as they need to to figure things out, with no fear of embarrassment or humiliation (as long as the ChatGPT logs don't get leaked, I guess...)
I agree with the author's broader point about being more open to alternative paths into UNIX/hackery/etc. However, I'm not sure that I agree entirely with this statement at the end:
> I’m pretty confident that someone who practices programming strictly as a hobby, less than ten hours a week, will eventually get just as good at it as one of these "fledgling hackers" who doesn’t do anything else with their spare time.
I'm not sure. Maybe, if the fledgling hacker isn't able to use their time effectively and the hobbyist is. But that assumes that very thing the author discussed in the beginning: the hobbyist has some prior foundational experience that allows them to be more effective with their time than the fledgling.
In my experience if you want to excel in any discipline, you have to spend some time at some point deeply-focused on it. If we assume the path to mastery is linear, 10 hrs/week for 10 years (~5000 hours) leaves less time for mastery than 60 hrs/week for 2 years (~6000 hours). In my experience mastery is not linear and makes this calculus even worse for the casual learner. Learnings compound and not all hours of practice are equal in efficacy. The more experience practitioner is likely to be getting more out of the time that they spend.
I do believe, emphatically, in the value of consistent effort over time. I've spent a few years picking up piano, but its 4 hrs/week. My goal with piano is to "be good in 10 years." But still, this to me highlights the gap between casual progress and dedicated effort. One of the main reasons I feel like I'm able to actually make progress with only 4 hr/week is because I have the prior experience of reaching a fairly high level of proficiency playing bass after 20+ years. There were times earlier in my musical study where I spent 30+hrs/week with the bass and built a foundation of musical knowledge and discipline that allows me to be more effective with a lesser time investment on piano now. Even with that prior foundation I don't expect that with 10 years of 4 hrs/week effort that I will be comparable in skill or knowledge to a professional pianist.
I think, based on my experience, that immersing yourself in a subject and making it a major pursuit in your life, taking up a large portion of your waking hours, is qualitatively different than the same amount of time invested over a longer horizon. You make connections faster when the study is top-of-mind. You notice patterns and build up intuitions that you miss when it's more spread out. The path of learning is extremely non-linear, in my experience. Slow and steady is effective, but let's not kid ourselves. If it is sustained, fast and steady is more effective.
I learned Unix through its manpage. I learned abotu sh, awk, grep, I learned about sockets and tcp, I learned about semaphore and shared memory. When I started working on Unix, in the early 90s', it was on a true-to-form physical VT220. I quickly learned to run make in the background so I could read the manpage while compiling.
Something I don't understand. Everyone talks about how they wish man pages had examples. What's stopping people from making/copying some examples and making a pull request to the maintainers of the man pages?
Tangential, but can someone explain the dichotomy of man pages vs info pages? Are they competitors, complements? Seems like many tools, like find, have sections for both.
Seems like man pages get all the love. Google searches often result in man page results, but not info pages.
GNU tried to push everything to info pages (a simple hyperlink browser) and it backfired spectacularly. Because man was simple, info was confusing and complicated and annoying.
The irony is that Daniel J. Bernstein said in the late 1990s that switching to HTML is the answer. And here we are, almost a quarter of a century later: Most of the people claiming that they are reading manual pages are actually reading HTML documents with WWW browsers. (All of the people following the hyperlinks to man pages found in this very discussion are doing that, for example.)
I feel the real key is having it in a separate window/terminal - I remember a TSR for Dos that would drop down a half window with command help - and you could scroll it AND still work on your command line with special modifier keys.
We do that now with a browser window open as we enter commands.
tmux and screen users would say that one can use the roff-based man system and still do that. The key is, rather, in what M. Bernstein wrote: "Much more effort has gone into web browsers than into roff readers."
And this is true. I just recently fixed a bug in a 2018-ish man command that prevented it from displaying Japanese manual pages, because it defaulted to 7-bit ASCII instead of UTF-8. Any WWW browser that couldn't have handled UTF-8 in 2018 would have been junked by most people. That sort of stuff was fixed years before for WWW browsers.
Indeed, there's been the reverse process going on. The effort that has gone into roff readers has sometimes even been actively suppressed. Did you know that your manual pages actually contain italics for emphasis and denoting certain syntactical elements, and have done pretty much all along? groff got the ability to display them, like troff originally could, long ago, as well as colour; but these abilities have been explicitly disabled in most operating systems.
We'd laugh at WWW browsers that couldn't do all of <i> and <em> and <u> and suchlike, or (of course) their CSS equivalents. But we suppress the ability of free software roff readers to reinstate what Unix text processing could likewise actually do in the 1970s.
And there are tools such as Debian's dwww (<https://packages.debian.org/bullseye/dwww>) which present virtually all local system information through a Web interface, also queryable through shell tools.[1] Both man and info pages (as well as numerous other document formats) are presented as Web pages, making info's distinction between man and hypertext formats largely irrelevant.
Note that this is a case of Debian's packaging conventions, standards, and requirements, as well as the wealth of available packages (including many documentation packages) being leveraged with a small additional bit of glue package to provide a fantastic utility.
As concerns man and info: I prefer manpages for their simplicity, use of ubiquitous tools and pagers (info by default relies on its own idiosyncratic viewer programme which I can never remember how to use or navigate, though you can bypass this for other tools). Info pages can offer richer documentation in more detail, in instances, though I find that generally HTML would be preferable for this. Note that both info and the WWW were invented within about five minutes of each other. Well, a few months, at any rate. Stallman really should acknowledge the clear winner here, as info's idiosyncrasies very much hurt rather than help it.
________________________________
Notes:
1. That is, in addition to man and info pages, you can point your browser at <https://localhost/dwww/> to see the content. You'll also get the /usr/share/doc/<packagename> trees, any installed manuals, auxiliary package information, and access to installed documentation such as RFCs, Linux Gazette, and other sources, if you've chosen to install those as well. Search is via swish++. Presentation can be limited to the localhost interface only (that is, only users on that system can view the docs) or opened up to specified IP ranges.
At some point, seems like in the late 90s, but who knows, the GNU project decided man pages weren't good enough, and tried to switch to info pages. As far as I can tell, nobody ever figured out how to use the info pages, and eventually either the GNU project relented and put the information back into the man pages, or the distributions did it for them. Info pages are supposed to be better because the different sections are hyperlinked or something, but as I recall, man info was useless and so was info info, so I never learned how to use it. :P
man comes from Unix, info comes from Emacs and maybe the OSes it was developed on. The GNU project also comes from that ecosystem, so even their drop-in replacements for the original Unix tools have info pages.
Specifically, info appears to come from ITS. Stallman hacked on ITS back in the day, and the first time I logged into an ITS system (http://up.dfupdate.se/, if you're curious) and used the online help system, I suddenly realized why GNU was always trying to foist this weird manpage alternative on us.
(I remember back when I first got into Linux, like early 2000s, it seemed like a lot of the core GNU man pages were just stubs that said "For documentation, use the info system". Luckily they seem to have backtracked on that?)
I'm sure there are some other good books about the subject of Unix usage and scripting in general, and I've read some of them, but IMO, UPE is one of the best.
FWIW, here are some of my HN comments about The Unix Programming Environment book by Kernighan and Pike, over the years:
166 comments
[ 4.1 ms ] story [ 337 ms ] threadhttps://web.archive.org/web/20190304153147/https://dilbert.c...
Furthermore, it's another case of some old Usenet hyperbole being taken as Gospel (or taken down as Gospel, which is ore the style now). One of the most important lessons the Jargon file has for "how to become a hacker", is "don't take anything too seriously."
Especially not the Jargon File. It largely comes from a particular period of time at MIT and Stanford, which is interesting in a historical sense but nobody should try and "become a hacker" by reading the Jargon File. Also it's had all sorts of injections and alterations by self-appointed Jargon File steward Eric Raymond, who should be ignored completely.
I only wish I could have told my 16-year-old self this.
Change that to "how to live", and it is still true. :)
Nothing but rice.
Typical comment :)
Let the other points go, but it's Kung Fu, and not just a brick wall.
I hope. :)
Shaolin.
If not, add more tequila.
>If you mix a metaphor hard enough, it begins to taste like metaphysics
Make a new cocktail with that name:
MetaPhorMetaPhysics
>If not, add more tequila.
Not my poison. Mine is H2O, like in your username.
>MetaPhorMetaPhysics
Did that blow your mind?
It doesn't meta.
An enormous page full of switches and options, yet if you're a beginner it's basically useless. You're just looking for a simple example of how to search for a file. find . -i -name <regex> is NOT mentioned anywhere, you have to figure it out yourself. And if you mess it up, your terminal gets flooded.
Contrast with grep(1) https://linux.die.net/man/1/grep which is short, simple, and easily searchable with keywords
Manpages are very useful, having offline documentation is great. But it is more of a specification reference than a manual.
Maybe 30 years ago you could learn through manpages but today that's how all the man pages of all the useful commands look. If you think grep is nice it would be the exception; for me it is indeed short, simple and easily searchable, but too terse for a beginner to learn with easily. (Plus even the regex documentation only documents grep mode, not egrep or pgrep or anything else.) Very useful in its own way, but most man pages are useless for learning.
I am disappointed at how few man pages take the opportunity to have a useful selection of "the 10 most popular things to do with this command" but web search has filled in reasonably decently. You do still have to understand the basics of how shell works, though, because most of them aren't quite what you want today and honestly a fair number of them aren't even what the poster thought they were. I am also in the habit of making sure that I understand every command line switch before I copy & paste a command off the internet, again, because many of them aren't what you need today. I don't always mean in a malicious manner, but things like either do or do not follow HTTP redirects in curl may or may not matter to you today, but the poster may be in the habit of setting it one way or another for no reason relevant to you.
there are not enough of them now, they used to be more prevalent
StackOverflow is Internet Age help
ChatGPT is post-Internet Age help
In ascending order of helpfulness (modulo LLM confabulation)
ChatGPT inherited "confidently wrong" and "misunderstanding question and then answering to question they misunderstood" from stackoverflow
Actually, this seems to be a case where chatgpt is smarter than the humans.
As of now, there is no LLM without confabulation, so your third item is effectively "hypothetical fantasy ChatGPT that we hope will be available some time in the future", not the actual tools we have right now.
The resulting command looked good at first sight, something like „mkvmerge -o output.mkv first.mkv —-no—video -s 1 -a 2 -a 3 -a 4“. The problem here is that there can only be one -a flag, so it should have been „-a 2,3,4“ instead. But mkvmerge didn’t really care and just discarded every -a flag except the last one. So I ended up with only one of the audio tracks copied over. I only noticed when I actually checked the resulting file that it had less audio tracks than it was supposed to.
This would not have happened to a human after studying the man page - the documentation is very clear about the -a flag and I have no idea what led ChatGPT to come to the conclusion it did.
Learning to program for example Perl. I had the learning book, the reference book and the cookbook. learning I did once, the reference had post its on it and was on my work desk. The cookbook was more the facebook type you read it on the toilet.
They had books on everything that were the industry standard. DNS, Apache, Javascript, ... The revised them regularly. For Js had the 1st, 2nd, 3rd edition. I know this sounds all ancients like real paper books. But even work had O'reilly subscription so you could order what you need.
For me it was O'reilly books, man pages. But lets not forget when you installed Linux like RedHat (not fedora yet) you could install the linux howtos. Oh boy did I learn a lot from them too: https://tldp.org/HOWTO/HOWTO-INDEX/howtos.html
Finally there was IRC if you were stuck but this was off course the internet stage. I just went online to ask a question, dialup was expensive ;)
i've been using https://git.causal.agency/exman/about/ to compare linux and bsd manpages, and it has saved me an incredible amount of time looking things up.
Ironically, this sort of stuff -- the basic conventions like qhjkl0^$G + CRFFBSSPC keyboard navigation and :/? prompt modes -- is exactly what one initially learns from guides, tutorials, other people in IRC, and whatnot, long before coming to reference doco. The _Introduction to Linux_ book at TLDP covers the bare essentials of these conventions, q, b, and SPC, in the "quickstart" chapter 2.
* https://tldp.org/LDP/intro-linux/html/sect_02_03.html
For emacs stuff, yes, it's very convenient. I remember once upon a time, Python docs were available in info as well. When you have good documentation available in info, it's very nice.
While this attitude made sense pre-internet, reading about every switch for common use cases is just not realistic today. Maybe if the number of command-line programs were less, and the complexity of each command was significantly less, I could see how it would be done, but not today.
This means not only how regexes distinguish between literals and control characters, but how the shell distinguishes and passes on characters to the regex that grep receives as an argument.
I think regex quoting is one of the major stumbling blocks of comprehension.
Even after decades using regexes, I still stumble (especially when my regexes are used in the shell, in emacs, in python re.match, etc...)
I suspect that the author is right that most people started with guides/handbooks/tutorials, even the ones who later on convince themselves that they only read reference doco.
The grep manpage spends much explaining regex and environment variables, find more on options.
Both manpages are searchable, what makes the grep manpage more searchable?
The FreeBSD Handbook was an amazing resource.
https://www.gnu.org/software/findutils/manual/html_mono/find...
info some-tool
some-tool --help
just help me dammit some-tool
I've got a thousand things to do that are better uses of my time than reading 20 pages of arcane documentation that may or may not answer my question.
Manpages aren't all the same quality. Look at the manpage for util-linux find(1):
* https://manpages.debian.org/bullseye/findutils/find.1.en.htm...
Contrast with the manpage for NetBSD find(1), where something similar to what you mention is in fact the very first example in the EXAMPLES section:
* https://man.netbsd.org/find.1
Compare with the manpage for Illumos find(1), where like util-linux it leaps into -exec and expressions in brackets with the second example:
* https://illumos.org/man/1/find
Then remember that some operating systems come with handbooks and guides, and if one wants a tutorial for beginners, reference doco is not the place to start at all. So next contrast with the SCO UnixWare users guide, which also starts off with find file by name and print:
* http://uw714doc.xinuos.com/en/FD_files/Moving_and_managing_f...
Then remember that GNU has a long-standing antipathy to man pages, and that actually one should have magically known the name "findutils":
* https://www.gnu.org/software/findutils/manual/html_node/find...
And there's also this thing that someone decided to call The Linux Documentation Project which has a book titled _Introduction to Linux_:
* https://tldp.org/LDP/intro-linux/html/sect_03_03.html#sect_0...
The NetBSD examples also only document what command do, while the util-linux sometimes go into details of why, like when describing how exactly the time directive works and why `-mtime 0` shows files from last 24 hours.
"find -- walk a file hierarchy"
what an idiotic summary
"file hierarchy" - Something to do with my file organization?
"walk" - Most programmers are familiar with trees.
Oh, we are walking through the file tree!
EXAMPLES
Examples are critical to comprehension, are immensely practical, yet are often viewed as fluff.
The same style extends to library documentation, where you have functions and arguments with types and no other context. It's basically for posterity.
Right balance of exact operation of software and examples, put in order that's useful in normal usage, and explanation for the more complex parts
I learned a lot from man pages in the 80's and 90's, and if I had to try to learn now from something like this, I'd likely just throw up my hands and choose another career.
.I is the "an" macro for italics, after all.
* https://tty0.social/@JdeBP/110427220635184435
It even prettifies those ``'' quotes, notice. This is vanilla older FreeBSD man, using groff, but actually allowing groff to do the things that it is capable of.
What terminal are you using? I just tested on Terminal.app and iTerm2.app -- `man fopen` looks correct on both.
The following should be equivalent, but might perform differently for you depending on what part of your config is bad:
TERM=xterm-256color and LESS_TERMCAP_us=In
you've got some typos here, it's not mentioned because... that's not how find works.
find has no -i like grep ; to ignorecase you use -iname ; and for name regular expression matching you need to use
cheers :)> Commands are listed alphabetically so that they can be quickly located. However, new users may find it easier to start by reading the descriptions of spawn, send, expect, and interact, in that order.
[0] https://linux.die.net/man/1/expect
https://www.tuhs.org/cgi-bin/utree.pl?file=4.2BSD/usr/man/ma...
and is still present in most BSD-derived tunefs implementations, e.g.,
https://man.freebsd.org/cgi/man.cgi?query=tunefs&apropos=0&s...
AFAICT, this restriction does not apply to versions of tunefs provided by System V and its derivatives, e.g.,
https://docs.oracle.com/cd/E86824_01/html/E54764/tunefs-1m.h...
As with many things in UNIX, the ability to tune a fish is implementation-dependent, and testing is recommended before using it in production on any given platform.
The basic operation of this program is as follows:
1. Panic. You usually do so anyways, so you might as well get it over with. Just don't do anything stupid. Panic away from your machine. Then relax, and see if the steps below won't help you out.
http://man.openbsd.org/scan_ffs
I read Foxley's Unix for Superusers, the Unix Text Processing book, and a couple of other books.
Take grep for example https://linuxcommand.org/lc3_man_pages/grep1.html - it has everything and the kitchen sink but hell bro tell me how to find something is the 99% use case most people will use it.
For cases like this ChatGPT has been helpful.
The Illumos manual page for grep(1) has an examples section:
* https://illumos.org/man/1/grep#examples
So has the FreeBSD manual page for grep(1):
* https://man.freebsd.org/cgi/man.cgi?query=grep&sektion=1#EXA...
Not everything is written like GNU man(1) pages.
Even the Linux Documentation Project has a novice's approach to grep with several basic examples in its _Introduction To Linux_:
* https://tldp.org/LDP/intro-linux/html/sect_03_03.html#sect_0...
Is this like a youtube-dl / ytp-dl situation?
And no, it's not like youtube-dl and yt-dlp. Some of the Unix implementations might have shared ancestry, but GNU grep is a from-scratch clone.
I completely agree that they are only useful if you know what you are looking for, and nothing else.
Although I'm still a newbie, but I'll never tell a complete newbie to RTFM, considering there is not many high quality manual out there. Actually most hottie open source tools we happened to introduce into our workflow have half-assed doc at most. I'll just teach him to Google stuffs efficiently and let himself figure out the rest. Sometimes it's surprisingly difficult to know what exactly to put into that search box.
I'm not a hacker. I'll never be even close to Ritchie, Carmack, whoever write state of art malwares. I know the pain.
The thing to remember is that for many systems there are both guides and handbooks, tutorial style doco, in addition to the reference doco, the manual pages. Linux-based operating systems come up a bit short in comparison to the old commercial Unices which had specific user guides, and in comparison to the BSDs, all of which have handbooks. Even Debian only has an admininstrators' guide, not a users' guide.
But The Linux Documentation Project is oft forgotten. It's stale. It's unfashionable. It's oddly chock full of how-tos for things that one wouldn't dream of wanting to do this century. But it also has longer format stuff, and it's still there.
Consider the _Introduction To Linux_ for example:
* https://tldp.org/LDP/intro-linux/html/sect_05_01.html
Or the _Linux Command-Line Tools Summary_:
* https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/working-fi...
Or the _Bash Guide for Beginners_:
* https://tldp.org/LDP/Bash-Beginners-Guide/html/sect_04_03.ht...
Preach.
I'll make this iron clad promise: if you sit down and read the coreutils manual end-to-end (it'll take a couple of hours) you'll come away brimming with new ways to optimise your CLI workflow.
If you're allergic to the `info' program itself, you can of course read the manuals on GNU's website or, better still: use Emacs's info viewer (`C-h i' or M-x info), which is far superior.
Here is my own .infokey file, in case it is of interest.
https://tldr.sh/
in browser: https://tldr.inbrowser.app/
[0]: https://github.com/dbrgn/tealdeer
Q "Please provide an outline and course syllabus for a ten-week course on Unix, aimed at undergraduate students in a college-level computer science program, as taught by an expert in Unix operating systems who has comprehensive historical knowledge of their development."
E.g. > "Week 4: Process Control; Process creation and termination; Process states and signals; Job control and background processes"
Need more? Q: "What are the most popular and useful process management tools for a Unix operating system?"
As far as how to read the man pages for any command, for beginners:
Q: "Provide a synopsis of the ps command's man page in a format suitable for a student who is just beginning to learn about process management."
Yes, you still should double-check those commands against the man reference - but think of all the benefits - students can get answers to their questions without having to pay private tutors or run the gauntlet of online forums where their ignorance will result in ridicule and similar unhelpful behavior, e.g. 'just read the man pages and think about it!', and they can ask as many dumb questions as they need to to figure things out, with no fear of embarrassment or humiliation (as long as the ChatGPT logs don't get leaked, I guess...)
> I’m pretty confident that someone who practices programming strictly as a hobby, less than ten hours a week, will eventually get just as good at it as one of these "fledgling hackers" who doesn’t do anything else with their spare time.
I'm not sure. Maybe, if the fledgling hacker isn't able to use their time effectively and the hobbyist is. But that assumes that very thing the author discussed in the beginning: the hobbyist has some prior foundational experience that allows them to be more effective with their time than the fledgling.
In my experience if you want to excel in any discipline, you have to spend some time at some point deeply-focused on it. If we assume the path to mastery is linear, 10 hrs/week for 10 years (~5000 hours) leaves less time for mastery than 60 hrs/week for 2 years (~6000 hours). In my experience mastery is not linear and makes this calculus even worse for the casual learner. Learnings compound and not all hours of practice are equal in efficacy. The more experience practitioner is likely to be getting more out of the time that they spend.
I do believe, emphatically, in the value of consistent effort over time. I've spent a few years picking up piano, but its 4 hrs/week. My goal with piano is to "be good in 10 years." But still, this to me highlights the gap between casual progress and dedicated effort. One of the main reasons I feel like I'm able to actually make progress with only 4 hr/week is because I have the prior experience of reaching a fairly high level of proficiency playing bass after 20+ years. There were times earlier in my musical study where I spent 30+hrs/week with the bass and built a foundation of musical knowledge and discipline that allows me to be more effective with a lesser time investment on piano now. Even with that prior foundation I don't expect that with 10 years of 4 hrs/week effort that I will be comparable in skill or knowledge to a professional pianist.
I think, based on my experience, that immersing yourself in a subject and making it a major pursuit in your life, taking up a large portion of your waking hours, is qualitatively different than the same amount of time invested over a longer horizon. You make connections faster when the study is top-of-mind. You notice patterns and build up intuitions that you miss when it's more spread out. The path of learning is extremely non-linear, in my experience. Slow and steady is effective, but let's not kid ourselves. If it is sustained, fast and steady is more effective.
* IN/ix (16 bit UNIX) Documents. The Docs were the old UNIX documents, most were man pages
* Later I got Coherent for my 286, the book that came with it was awesome.
FWIW, OpenBSD's man pages are very good, much better that what Linux has.
Seems like man pages get all the love. Google searches often result in man page results, but not info pages.
Can someone educate me? Thank you :)
* https://cr.yp.to/slashdoc.html
Strictly speaking it's not advocating HTML, but "browser-compatible" documents, which in fact includes DocBook XML.
We do that now with a browser window open as we enter commands.
And this is true. I just recently fixed a bug in a 2018-ish man command that prevented it from displaying Japanese manual pages, because it defaulted to 7-bit ASCII instead of UTF-8. Any WWW browser that couldn't have handled UTF-8 in 2018 would have been junked by most people. That sort of stuff was fixed years before for WWW browsers.
Indeed, there's been the reverse process going on. The effort that has gone into roff readers has sometimes even been actively suppressed. Did you know that your manual pages actually contain italics for emphasis and denoting certain syntactical elements, and have done pretty much all along? groff got the ability to display them, like troff originally could, long ago, as well as colour; but these abilities have been explicitly disabled in most operating systems.
We'd laugh at WWW browsers that couldn't do all of <i> and <em> and <u> and suchlike, or (of course) their CSS equivalents. But we suppress the ability of free software roff readers to reinstate what Unix text processing could likewise actually do in the 1970s.
Note that this is a case of Debian's packaging conventions, standards, and requirements, as well as the wealth of available packages (including many documentation packages) being leveraged with a small additional bit of glue package to provide a fantastic utility.
As concerns man and info: I prefer manpages for their simplicity, use of ubiquitous tools and pagers (info by default relies on its own idiosyncratic viewer programme which I can never remember how to use or navigate, though you can bypass this for other tools). Info pages can offer richer documentation in more detail, in instances, though I find that generally HTML would be preferable for this. Note that both info and the WWW were invented within about five minutes of each other. Well, a few months, at any rate. Stallman really should acknowledge the clear winner here, as info's idiosyncrasies very much hurt rather than help it.
________________________________
Notes:
1. That is, in addition to man and info pages, you can point your browser at <https://localhost/dwww/> to see the content. You'll also get the /usr/share/doc/<packagename> trees, any installed manuals, auxiliary package information, and access to installed documentation such as RFCs, Linux Gazette, and other sources, if you've chosen to install those as well. Search is via swish++. Presentation can be limited to the localhost interface only (that is, only users on that system can view the docs) or opened up to specified IP ranges.
(I remember back when I first got into Linux, like early 2000s, it seemed like a lot of the core GNU man pages were just stubs that said "For documentation, use the info system". Luckily they seem to have backtracked on that?)
Then the man pages make more sense.
[0]https://en.wikipedia.org/wiki/The_Unix_Programming_Environme...
[0]https://en.wikipedia.org/wiki/The_Unix_Programming_Environme...
UPE for short, like K&R.
Yes, totally.
I'm sure there are some other good books about the subject of Unix usage and scripting in general, and I've read some of them, but IMO, UPE is one of the best.
FWIW, here are some of my HN comments about The Unix Programming Environment book by Kernighan and Pike, over the years:
https://hn.algolia.com/?dateRange=all&page=0&prefix=false&qu...
Is where those came from it started circa 1992.