Comment by begriffs
8 years ago
When people think of manpages, they tend to think of Linux. At least that's what I thought of, until a few months ago when I discovered OpenBSD. Their manual is concise and coherent, unlike the rambling hodgepodge on Linux.
Of course it's always nice to have a bunch of curated examples like TLDR or "bro" pages, but just wanted to point out that the manpage situation isn't universally grim.
By Linux do you mean GNU? Because those are the wordiest and least straightforward. BSDs tend to have excellent documentation as do some individual projects (git), while others (OpenSSL) leave something to be desired. And of course GNU tar is a special little hell. But Linux just happens to run on a GNU userland most of the time so you get those a lot.
> BSDs tend to have excellent documentation as do some individual projects (git)
Should we really point to git as an example of great documentation? I mean, this exists and has to have a giant banner at the top saying "these are NOT REAL": https://git-man-page-generator.lokaltog.net/
Yeah, I use the git manpages all the time when I need to do something unusual and have generally found them to be very helpful, but they aren’t written for people who don’t know how to use git.
On many Linux systems there are likely to be more non-GNU commands than GNU commands, so I'm not sure your argument fully works here.
GNU historically never made man pages: they used Texinfo for documentation, possibly combined with a tool to convert Texinfo to man pages. That shows in the result: an entire manual all joined together in a single unreadably long manual page. The bash man page is a nice example of that. I'm not sure if the use of Texinfo is still a requirement for GNU projects.
The verbosity of the generated man pages for GNU software probably did influence a lot of non-GNU Linux software.
At least in bash 4.4, the manpage and the info page are two different documents.
Many GNU manpages are generated with help2man, which causes the opposite problem, i.e. they are too terse. (Also, their typographical quality is often low.)
That's a good distinction. Yeah, GNU.
The man pages for Linux kernel internals and syscalls are pretty good stuff like, inotify, procfs etc all have really good detailed man pages. The userland stuff is a different story. I think it is because BSD doesn't distinguish userland from kernel they are all shipped in the same package so manual pages are probably kept more consistent. Linux uses stuff like GNU etc for a lot of userland tools so it is more of a mixed bag different community different developers etc.
Manpages are UNIX thing, and I can tell you that GNU ones are much better than what commercial UNIXes used to be like.
And as someone who, even nowadays, still points to the commercial manual pages for SCO Unix, HP/UX, AIX, Solaris, and suchlike, oftentimes for things that the GNU and BSD manual pages simply do not cover, I can tell you that you are quite wrong.
* https://manpages.debian.org/stretch/coreutils/ls.1.en.html
As can be seen, the commercial manual pages are not worse, and are indeed in several aspects better than the GNU one. The same is pretty much true of the non-GNU free operating systems (FreeBSD, OpenBSD, and Illumos) as well.
Notice that ...
* ... only the HP-UX, AIX, Solaris, Illumos, and OpenBSD manual pages have examples (quite apposite considering the headline for this discussion)
* ... only the HP-UX, AIX, Solaris, and Illumos manual pages explain that output falls into three basic forms
* ... only the Solaris, Illumos, and FreeBSD manual pages actually explain in detail the configuration of the colour scheme (HP-UX, AIX, and OpenBSD not having a colour scheme mechanism, in fairness)
* ... only the HP-UX, AIX, Solaris, Illumos, OpenBSD, and FreeBSD manual pages explain what the characters output by the -F option actually signify
* ... only the HP-UX, AIX, Solaris, Illumos, and FreeBSD manual pages explain that the time format used in -l changes according to how long ago the timestamp was (an odd removal for OpenBSD, considering that OpenBSD ls does the same thing)
... and so on.
This, so much this. Having only transitioned into RHEL from Solaris in the latter 1/4 of my career, I still hark back to Solaris man pages and to this day, on Linux I will do -
man foo
/EXAMPLES
And frequently find what I find, if there are any at all, very lacking compared to Solaris.
I have often thought I and others who complain about this should get involved in working on these man pages and improve this situation.
Note that the GNU ls manpage is just `ls --help` in manpage format, with a "SEE ALSO" section at the bottom which tells you where the real documentation is.
Well, that was my memory going back to 2000. It has been a while since I bothered to look into them.
I remember having to go into the official documentation available on the HP, IBM and Sun web sites to find usable information, instead of just going through man pages.