I didn’t learn Unix by reading all the manpages (2022)

Manpages aren't all the same quality. Look at the manpage for find(1) https://linux.die.net/man/1/find

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.

I see a lot of people talking about examples, and while having more of them could be good, I think the actual problem with most modern man pages is a lack of clear description of program behaviour.

I am nowhere near old enough to have used an old Unix implementation, but the man pages back in those days just hit different. just compare how the ls man page starts for the GNU and Unix V7 version.

GNU: "List information about the FILEs"

Unix V7: "For each directory argument, ls lists the contents of the directory; for each file argument, ls repeats its name and any other information requested."

The GNU man page's description continues with one sentence on default ordering before getting to the list of arguments. The only mention ls lists diretory contents is in the description of the -d flag (the flag to make it not do that). The GNU man page also goes on in detail avout the time formats supported by the command, but nowhere does it have anything to say about the format of -l info.

Trying to read modern man pages is like trying to read a library documentation where only the parameteres and return values for function are documented, but no description of the function in itself is given.

Strangely enough, I did learn Unix by reading all the man pages.

My first introduction to a Unix was via 'Coherent', a v7 clone back in the early 1990s. That came with a huge book. That huge book was pretty much a chapter or two on how to install Coherent, followed by hundreds and hundreds of pages of nothing but man pages in alphabetical order.

It was good night time or spare time reading. You could delve anywhere into the book and read away. And I did. Or you could look up some particular man page if you felt like it.

Most value-for-money book I've ever read.

https://archive.org/details/CoherentMan/page/n3/mode/2up

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.

> 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.

Preach.

I remember when you could print out all of the manpages and put them in a 3-ring notebook. Yes, in those days I did read them all.

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."

The correct order of learning Unix commands is: get a copy of Kernihan/Pike[0] and read that, do the examples.

Then the man pages make more sense.

[0]https://en.wikipedia.org/wiki/The_Unix_Programming_Environme...

Honestly manpages with and without an `EXAMPLES` section are completely different types of documents.

I did, I remember working night shift in operations feeding tapes and in the down time I installed openbsd on an old pc. I would read the man pages following the "see also:" sections. I remember using a script to show me random man pages so I could learn about things that would not catch my eye.

I have this really cool wiki sort of software I made during that time it was written in shell, awk, sed, m4 and rcs. It was mainly written as an exercise to learn the unix environment. Probably full of every sort of injection vulnerability know to man. but it worked well enough in a benign environment. The shell bits are funny because a lot of it was built before I figured out shell functions. so every function was a separate shell script.

The thing is the text of the article contradicts it's headline. yes there is a lot of auxiliary knowledge that seeps in from many sources, this is why a person good at operating one os will be good at operating another os, they will not be happy about it but should know the fundamentals and can pick up the incidentals quickly. however these incidentals are important, and you learn the unix incidentals by reading the unix manual.

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.

I learned it from 2 sources:

* 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.

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.

For cases like this ChatGPT has been helpful.

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 would have a hard time believing someone who learnt Unix at some point in the previous 20 years did so by reading some manpages.

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.

> I got so much more out of Starting FORTH and TCP/IP Network Administration and the Lisp 1.5 Primer and some 1975-vintage algorithms textbook whose name I can’t remember (all the examples were in Pascal) than I ever got out of the manpages.)

Well, page 13 of Lisp 1.5 has Maxwell's Laws of Software, after all. (Might have an error or two though.) ;-)

Pascal algorithms book is likely Wirth's Algorithms + Data Structures = Programs (subsequently revised as Algorithms and Data Structures, with an Oberon version as well.)

The Forth, Lisp, and Wirth books are readily available online.

One thing that the language books have in common is that they describe programming language (Forth, Lisp, Pascal) implementation. (Note Wirth subsequently removed the compiler section in deference to his longer compiler book, which covers more material and compiles an Oberon subset onto his own RISC processor design.)

This post resonates with me as someone who tried to get into Unix as a very young person. The culture at the time felt like people really wanted you to figure it out by yourself. "Read the man pages, they have the answers." If someone thought that's all I needed, I could expect no further guidance as if I didn't deserve to be a user.

That was very discouraging when I was twelve.

I don't think this article would have existed without that terrible culture. Man pages are still here. I still use them. But, who in their right mind these days would suggest to a brand new user, RTFM or GTFO and leave it at that.

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.

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 picked up Ubuntu 14 years ago because it ran twice as fast on my parent's Dell laptop as Windows XP, and because I didn't have to worry nearly as much about getting a virus on it.

I didn't learn Linux using it that way, but I was immersed in it in a way that made the whole thing much easier when I finally took the plunge last year and started seeking work for real as a software engineer, instead of as an electrical engineer, which was what I went to college in.

I rarely read the manpages. I know a handful of switches and I prefer to ask the live Internet for easier material.

I also didn't learn Unix this way, but I sure learned a lot more once I did.

I didn't either, but if I needed help with a command- I'd consult the manpages first. But then again, I learned unices back in the days before resources were easily searchable online, and multiple flavors as well. Solaris, BSD, Linux, etc. They all had slightly different flags and it was always wise to check.

Sitting in a datacenter, with no wifi and working on a downed server... you learn to appreciate the manpages at the console.

All the manpages are bad IMO. A set of examples with a textual description of what each is doing would be far more useful in 99% of cases than a list of flags.

I remember that I read a book with the main UNIX commands plus a vi tutorial and then a lot of manpages. That was in the second half of the 80s.

I almost did, but by a book called "Guia Foca Linux" it's a brazilian author that created a book for those beginning their journey on Unix/Linux, it was a little bit hard for a 12 year kid but it took the job done:

https://www.guiafoca.org/

Follow examples. Hack other people's scripts. Troubleshoot some half-working tool. Don't hesitate to flip back to manpages for reference, but other people's scripts will show you how it's done (or serve as a warning.)

Oh yeah, Linux has a tradition of the HOWTO tutorials. grep those in /usr/share/doc.

I remember how many distros come with a package of Linux HOWTOS about varios topics, I did learn a lot from those

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.

Can someone educate me? Thank you :)

I and many others from my generation learned unix from the 'devil' book (Design and Implementation of the 4.3BSD Operating System). As I recall the Sun system documentation wasn't too shabby either.

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?

Ever since I got CoPilot CLI access, it's all I use. I just tell it what I want to do and it spits out a nice CLI command that works 99% of the time with only filename changes.

I start with tldr then move into help or manpages as necessary. Then when I understand, I still come back to tldr to remember.

https://tldr.sh/

in browser: https://tldr.inbrowser.app/

I learned by trying to get my window manager to have flame effects on my windows... I also started on Linux when I was 12 probably at least two decades after the author started on Unix. I still use man pages and/or -h today though. More as swap memory for my brain than as something I would read top to bottom:

*What was the flag to flash firmware over the network? <types -h> Crap, too much text. <types -h | less> Ah, I remember now even though I used that flag five minutes ago. <types -d 0.0.0.0>*

I have no proof for what I am about to say, but I did grow up in the 1970s... tl;dr: man and info pages were never the way to learn Unix

There was a strong culture in nearly every professional competency 40+ years ago for social learning. It simply wasn't "done" back then for loners (and I am one) to sulk away with manuals for how to do... anything complicated and expect to gain mastery. One great example of this was trying to learn how to set non-electronic ignition points (for a gasoline engine). You _could_ try to figure it out with a manual and decipher the crude diagrams, but 25 minutes with someone who'd been taught by someone else transmitted much more knowledge than you could ever expect to get out of a handbook. Afterward, those crude diagrams would spring to life with fresh and helpful visual context. man pages weren't for beginners; they were for people who knew the basic forms and wanted to learn all of the other options. Yet, once you understood the basics of the top dozen Unix commands, then man pages could be used in isolation to learn most other commands. We didn't learn c back then by combing through the standard c library references, etc. Later on, Bjarne Stroustoup summed up how to improve (in general) in the first section of his seminal "The C++ Programming Language" when he wrote (paraphrasing from memory): 1) Know what you want to say. 2) Read others' works and copy from the best.

The development of the initial Unix userland tools at Bell Labs (and the drafting of most of the initial RFCs) was a social process and the use of those tools was passed down socially for decades. Even in school, older students were a major source of understanding for how to use these tools. As this era began to fade away in the mid-1990s, it wasn't Stack Overflow that filled the void (yet) but rather "recipe" books such as Oreilly's "Unix Power Tools". These were often written in a conversational style, as if the social learning context was continuing, only in written form. It is somewhat ironic that AI tools like ChatGPT are now bringing the process full-circle, where we must once again seek the wisdom of a competent agent by engaging in conversation, carefully crafting our questions so as not to elicit an incorrect answer or go off on an irrelevant tangent.

Its like no-ones heard of the 'info' command..

I've used tldr (https://github.com/tldr-pages/tldr) if I'm a beginner to a specific tool, then read up the manpages and/or SO if I need more flags.

I use frequently and recommend tldr pages: https://tldr.sh/

I’m a big fan of command line tools and probably the one I use the most is tldr. It’s what all man pages should have in their first paragraph but don’t, it’s just snippets of how to actually use the thing in the most common ways with a brief explanation.

as a beginner, how can i practice linux commands.

I haven't seen this mentioned anywhere here, but the program `tldr` is a solid compliment to manpages, you run it like `tldr ls`, and it spits out a couple of examplesof how ls can be used

Ai chatbots are perfect for this