3 ms·

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

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.

IgorPartola 9y ago
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.
- begriffs 9y ago
  That's a good distinction. Yeah, GNU.
- wichert 9y ago
  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.
  - jwilk 9y ago
    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.)
- jlebar 9y ago
  > 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/ https://git-man-page-generator.lokaltog.net/
  - fiddlerwoaroof 9y ago
    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.
pjmlp 9y ago
Manpages are UNIX thing, and I can tell you that GNU ones are much better than what commercial UNIXes used to be like.
- JdeBP 9y ago
  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://news.ycombinator.com/item?id=15541694 https://news.ycombinator.com/item?id=15541694 * https://unix.stackexchange.com/a/406545/5132 https://unix.stackexchange.com/a/406545/5132 * https://unix.stackexchange.com/a/196471/5132 https://unix.stackexchange.com/a/196471/5132 Here are the HP-UX, AIX, Solaris, Illumos, FreeBSD, and OpenBSD manual pages for the ls command: * http://nixdoc.net/man-pages/HP-UX/man1/lsf.1.html http://nixdoc.net/man-pages/HP-UX/man1/lsf.1.html * https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds3/ls.htm https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.i... * https://docs.oracle.com/cd/E23824_01/html/821-1461/ls-1.html https://docs.oracle.com/cd/E23824_01/html/821-1461/ls-1.html * https://illumos.org/man/1/ls https://illumos.org/man/1/ls * https://www.freebsd.org/cgi/man.cgi?query=ls https://www.freebsd.org/cgi/man.cgi?query=ls * http://man.openbsd.org/ls http://man.openbsd.org/ls And here is the GNU one from Debian Linux written (it says) by Richard Stallman: * https://manpages.debian.org/stretch/coreutils/ls.1.en.html 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.
bigger_cheese 9y ago
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.

IgorPartola 9y ago

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.

begriffs 9y ago
That's a good distinction. Yeah, GNU.
wichert 9y ago
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.
- jwilk 9y ago
  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.)
jlebar 9y ago
> 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/ https://git-man-page-generator.lokaltog.net/
- fiddlerwoaroof 9y ago
  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.

pjmlp 9y ago

Manpages are UNIX thing, and I can tell you that GNU ones are much better than what commercial UNIXes used to be like.

JdeBP 9y ago
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://news.ycombinator.com/item?id=15541694 https://news.ycombinator.com/item?id=15541694 * https://unix.stackexchange.com/a/406545/5132 https://unix.stackexchange.com/a/406545/5132 * https://unix.stackexchange.com/a/196471/5132 https://unix.stackexchange.com/a/196471/5132 Here are the HP-UX, AIX, Solaris, Illumos, FreeBSD, and OpenBSD manual pages for the ls command: * http://nixdoc.net/man-pages/HP-UX/man1/lsf.1.html http://nixdoc.net/man-pages/HP-UX/man1/lsf.1.html * https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds3/ls.htm https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.i... * https://docs.oracle.com/cd/E23824_01/html/821-1461/ls-1.html https://docs.oracle.com/cd/E23824_01/html/821-1461/ls-1.html * https://illumos.org/man/1/ls https://illumos.org/man/1/ls * https://www.freebsd.org/cgi/man.cgi?query=ls https://www.freebsd.org/cgi/man.cgi?query=ls * http://man.openbsd.org/ls http://man.openbsd.org/ls And here is the GNU one from Debian Linux written (it says) by Richard Stallman: * https://manpages.debian.org/stretch/coreutils/ls.1.en.html 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.

bigger_cheese 9y ago

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.