Personally I think ubiquitous software is even more important to have Easter eggs, because they're the most widely distributed, and we want as much joy as we could possibly have, before you know.
My favorite piece of man trivia is from the source of the tunefs BSD man page, which contains:
.\" Take this out and a Unix Daemon will dog your steps from now until
.\" the time_t's wrap around.
.Pp
You can tune a file system, but you cannot tune a fish.
One very important section number is 5 - it's for file formats. So if you forget the crontab format, you need to invoke `man 5 crontab` to read about it.
That is incredibly stupid. A documentation system designed by someone who doesn't understand how people use documentation.
If man was designed by someone with any taste at all it would at least give you a menu to select (1) crontab command, (5) crontab file format. Maybe we need a rewrite in Rust to fix that.
In fact, the only reference to crontab(5) is in the SEE ALSO section (on my version anyway), but that doesn't say why you might want to see crontab(5), just that it exists. That is spectacularly useless
Depends. If one is aware of the meaning of section numbers, that "(5)" is very obviously suggesting that there is a file format named "crontab" which is documented. It's also pretty reasonable to suppose that the command and the file format of the same name are related.
A novice might miss the convention and the connection. Man pages are not quite novice material.
Incidentally, man --help on my machine shows "-k, --apropos equivalent to apropos", which isn't very useful. I know the two are equivalent, because they're on the same line of switches, what does it actually do?
With some further man digging, apropos is actually a separate program that looks through man page names/descriptions for the argument. Unless you run it with no arguments, in which case it just outputs "apropos what?" Instead of an actual error message like "No search term provided" or something
Interestingly, the section doesn't actually have to start with a number. TCL man pages use the 'n' section and 'man' resolves them just fine despite the ambiguity. Conversely, manpage names can also start with numbers, although this is rare (I found only one such example: man 30-systemd-environment-d-generator)
That may "answer" a specific question. And all llms can do as they include manpages in training data (and any Agentic thing can search) however the value in reading documentation is that one can find different angles by learning about different options, which allow tontackle problems from a different perspective. The answer to a question is constrained by assumptions which are part of the question.
If you like man trivia (and why else would you be reading this?) you could check out the top comment at https://unix.stackexchange.com/questions/405783/why-does-man...
(discussed at https://news.ycombinator.com/item?id=27994194)
Reading this makes me wonder if Easter eggs are ever appropriate for something as ubiquitous as man.
Easter eggs are always appropriate but it is imperative (and important) to understand how they could affect anything and everything.
Which means you need to usually make it explicit to call them (man --abba or something) than something that "surprises" the user.
Personally I think ubiquitous software is even more important to have Easter eggs, because they're the most widely distributed, and we want as much joy as we could possibly have, before you know.
"The developer of the man-db, Colin Watson, decided that there was enough fun and the story won't get forgotten"
Haha! Adequate amount of fun was provided, please resume regular man activities.
My favorite piece of man trivia is from the source of the tunefs BSD man page, which contains:
https://github.com/freebsd/freebsd-src/blob/main/sbin/tunefs...
I guess the joke is you can scale a file system or a fish, but can only tune a file system?
Tuna is a type of fish so the joke is that they sound the same.
You can tune a fish, it's that the command for that is fish_config instead.
> (... less common section numbers)
One very important section number is 5 - it's for file formats. So if you forget the crontab format, you need to invoke `man 5 crontab` to read about it.
... because if you do `man crontab` you get section 1, which does not document the crontab fields.
That is incredibly stupid. A documentation system designed by someone who doesn't understand how people use documentation.
If man was designed by someone with any taste at all it would at least give you a menu to select (1) crontab command, (5) crontab file format. Maybe we need a rewrite in Rust to fix that.
Or a minor alteration to an existing program to support a good suggestion.
Why is it that the Rust community thinks that the solution to every flaw in an application is a rewrite in Rust?
It might be more helpful to write a Rust-based snark detector first.
Could be, but I don't think so in this case given a cursory review of the parent poster's history.
It does that, depending on implementation.
> If man was designed by someone with any taste at all it would at least give you a menu [...]
My goodness. Man was written on a paper teletype.
There are a multitude of manpagers and viewers and frontends. It's one of those things you can write yourself very easily.
In fact, the only reference to crontab(5) is in the SEE ALSO section (on my version anyway), but that doesn't say why you might want to see crontab(5), just that it exists. That is spectacularly useless
> That is spectacularly useless
Depends. If one is aware of the meaning of section numbers, that "(5)" is very obviously suggesting that there is a file format named "crontab" which is documented. It's also pretty reasonable to suppose that the command and the file format of the same name are related.
A novice might miss the convention and the connection. Man pages are not quite novice material.
man -k crontab is the real trick here. shows both sections so you don't have to already know the number exists.
It only shows a description though.
Incidentally, man --help on my machine shows "-k, --apropos equivalent to apropos", which isn't very useful. I know the two are equivalent, because they're on the same line of switches, what does it actually do?
With some further man digging, apropos is actually a separate program that looks through man page names/descriptions for the argument. Unless you run it with no arguments, in which case it just outputs "apropos what?" Instead of an actual error message like "No search term provided" or something
Interestingly, the section doesn't actually have to start with a number. TCL man pages use the 'n' section and 'man' resolves them just fine despite the ambiguity. Conversely, manpage names can also start with numbers, although this is rare (I found only one such example: man 30-systemd-environment-d-generator)
The POSIX standard manual pages for the utilities can be found here:
https://pubs.opengroup.org/onlinepubs/9799919799/idx/xcu.htm...
These would all be in section 1, if I am correct.
I looked up what the numbers mean a couple of times, but always forget it immediately
Section meaning varies somewhat widely by *nix flavor.
For me man(3) is the most interesting of them all.
Run `apropos . | grep "(3)"`; you'll be surprised how many libraries come with man pages for their functions (e.g; curl).
Now I wonder if there are any IDEs that can automatically dial into these man pages and pull up documentation for functions?
There's guaranteed to be some sort of context-sensitive man plugin for vim &| nvim for shell scripts.
Also, have you ever seen the DOS Borland IDE context sensitive help UX?
I think for Vim, it’s “K”. But for emacs, you only need to use “m-x man” and have a nice viewer.
I'm feeling old now.
Step 1: Read `man man`
Step 2: Feel the urge to write an article about that
I admire people who do that.
Writing down what you learn cements knowledge, and sharing what you write might help someone else.
Is there a man man man article that will explain how to read man man?
The full documentation for man is maintained as a Texinfo manual. If the info program is properly installed at your site, the command
Ah that crap is/was so rage inducing!
Ideally, read or write while listening to https://en.wikipedia.org/wiki/Man_Man
Confession. I think I haven't read manpages since stackoverflow and certainly not since LLMs.
Perhaps the modern version of "man" should be a program you can talk to.
i have made llms read manpages, it is great lol
Please no. I want to read the manual without having to talk to anything.
It's called Claude. Or Gemini-cli. Or any other agent capable of running man.
"Hey <agent>, use `man` to help answer these questions about grep"
That may "answer" a specific question. And all llms can do as they include manpages in training data (and any Agentic thing can search) however the value in reading documentation is that one can find different angles by learning about different options, which allow tontackle problems from a different perspective. The answer to a question is constrained by assumptions which are part of the question.
My experience with LLMs is that they often give me different angles that I didn't think of.