5 ms·

Are there some good examples comparing man pages on OpenBSD and man pages on Linux where the former is clearly better? Are we talking about man pages for end-us

by jl6 7y ago

Are there some good examples comparing man pages on OpenBSD and man pages on Linux where the former is clearly better? Are we talking about man pages for end-user applications rather than, say, for system calls? And can these differences be resolved with some copy & paste so they are both up to standard?

anjbe 7y ago
I’d say it’s not just that OpenBSD’s manpages are written well (though they are), but that the userland tools are simpler and have a better interface. For example, people often bring up tar as a tool with a less‐than‐intuitive interface. Compare the manual to GNU tar with OpenBSD’s tar: https://manpages.debian.org/stretch/tar/tar.1.en.html https://manpages.debian.org/stretch/tar/tar.1.en.html https://man.openbsd.org/tar.1 https://man.openbsd.org/tar.1 Not only does GNU tar have a bewildering array of options that make reading through the manual a chore, it lists (as far as I can tell) only one example, and in a section devoted to explaining the many ways to specify command‐line options to tar. OpenBSD tar has a whole section dedicated to examples (as is typical for OpenBSD); the manual as a whole is clear, concise, and complete. Another example: GnuPG versus OpenBSD’s signify. https://manpages.debian.org/stretch/gnupg2/gpg2.1.en.html https://manpages.debian.org/stretch/gnupg2/gpg2.1.en.html There’ve got to be over 100 options in there. And although it helpfully places --sign first (and --clear-sign, and --detach-sign, and --encrypt, and --symmetric, and --store, before it finally gets to --decrypt), let’s be real: anyone who’s not already comfortable with encryption software will be completely intimidated by this manual, which is 175 (!) page‐downs in a 80×24 terminal. Contrast with signify: https://man.openbsd.org/signify.1 https://man.openbsd.org/signify.1 The description section starts with the four major operations (sign file, verify file, verify many files, generate key), and is again followed by an examples section. Of course, the OpenBSD tools are much less featureful than the mainstream counterparts. But the reality is that most people, and certainly I myself, need only a few features in day‐to‐day life. Even being a real terminal junkie, I’ve only needed GNU tar specifically once or twice in the last ten years; and when I did, on OpenBSD, it was a mere “pkg_add gtar” away. OpenBSD has a great self‐contained base system, with elegant tools and useful documentation, and an extensive package collection for when that’s not adequate. I continue to use it because it serves my needs as a primary driver, and the interface is just so gosh darn pleasant to use.
- djgs 7y ago
  Said much better than I could. :)
- eb0la 7y ago
  If the software and the documentation differ, that's a bug. If you don't understand the docs, there's a bug in the documentation. OpenBSD does not like bugs :-)
- hutzlibu 7y ago
  Since I got frustrated with linux man pages a lot, I am glad to see OpenBSD does it different. (one of the reasons why I finally want to give it a try) The tar example is indeed much cleaner. But it seems to be a bit old ... "A tar archive is often stored on a magnetic tape, but can be stored equally well on a floppy, CD-ROM, or in a regular disk file" Not that it hurts much, though.
  - moviuro 7y ago
    See the blame on tar.1 [0] : documentation does not change very much... [0] https://github.com/openbsd/src/blame/f84583fe5d7899ab1504dc1d58a04742db4a3058/bin/pax/tar.1 https://github.com/openbsd/src/blame/f84583fe5d7899ab1504dc1...
- teddyh 7y ago
  It’s slightly disingenuous of you to compare the GNU man page to the OpenBSD man page, since while the OpenBSD man page is the official documentation, the GNU man page is not. As clearly stated in the GNU man page for tar: “This manpage is a short description of GNU tar. For a detailed discussion, including examples and usage recommendations, refer to the GNU Tar Manual […]”, and it gives a link to it: https://www.gnu.org/software/tar/manual/tar.html#SEC1 https://www.gnu.org/software/tar/manual/tar.html#SEC1 If you had compared the OpenBSD man page to that, it would be a more fair comparison.
  - anjbe 7y ago
    “Disingenous” suggests malice. That is both unkind and untrue. I had simply forgotten. In any case, the info page is far larger than the already‐large manual page, which I think only further illustrates one of my points, that the software is itself intimidatingly complex.
djgs 7y ago
I would say it's both the user application and the system calls. Here is the man page of the driver for the wireless card in my laptop https://man.openbsd.org/iwm.4 https://man.openbsd.org/iwm.4 It's clear and concise, has links to the related tools that I might need to get the card working. Is there a similar man page for Linux? I'm not sure, honestly. Copy and paste? You'd have to copy and paste the whole driver for a start.
sverige 7y ago
I don't know anyone who relies on man pages for Linux. I know a lot of people who use man pages almost exclusively for OpenBSD. Yes, they are there for system calls, but also for applications -- depending on your definition of end-user applications, since some of what Linux considers "end-user" are, as TFA mentions, first-class applications that ship with OpenBSD. I don't think the differences can be resolved with copy and paste since many Linux man pages deal with programs that are very different under the hood than those with the same or similar names in OpenBSD. I also don't think it's unfair or arrogant to consider OpenBSD's man pages to be the standard of what man pages should be, btw. Search one or two of your favorites and see for yourself: https://man.openbsd.org https://man.openbsd.org
JdeBP 7y ago
It cannot be resolved with some copy and paste. Take "ps", for example. The BSD "ps" program is fundamentally different to the Linux "ps" program. It's also, quite importantly, different to what the Linux "ps" manual erroneously claims the BSD "ps" to be. * https://manpages.debian.org/testing/procps/ps.1.en.html https://manpages.debian.org/testing/procps/ps.1.en.html * http://man.openbsd.org/ps http://man.openbsd.org/ps * http://netbsd.gw.com/cgi-bin/man-cgi?ps http://netbsd.gw.com/cgi-bin/man-cgi?ps * https://freebsd.org/cgi/man.cgi?query=ps https://freebsd.org/cgi/man.cgi?query=ps * https://unix.stackexchange.com/a/511530/5132 https://unix.stackexchange.com/a/511530/5132

by jl6 7y ago

anjbe 7y ago

I’d say it’s not just that OpenBSD’s manpages are written well (though they are), but that the userland tools are simpler and have a better interface. For example, people often bring up tar as a tool with a less‐than‐intuitive interface. Compare the manual to GNU tar with OpenBSD’s tar: https://manpages.debian.org/stretch/tar/tar.1.en.html https://manpages.debian.org/stretch/tar/tar.1.en.html https://man.openbsd.org/tar.1 https://man.openbsd.org/tar.1 Not only does GNU tar have a bewildering array of options that make reading through the manual a chore, it lists (as far as I can tell) only one example, and in a section devoted to explaining the many ways to specify command‐line options to tar. OpenBSD tar has a whole section dedicated to examples (as is typical for OpenBSD); the manual as a whole is clear, concise, and complete. Another example: GnuPG versus OpenBSD’s signify. https://manpages.debian.org/stretch/gnupg2/gpg2.1.en.html https://manpages.debian.org/stretch/gnupg2/gpg2.1.en.html There’ve got to be over 100 options in there. And although it helpfully places --sign first (and --clear-sign, and --detach-sign, and --encrypt, and --symmetric, and --store, before it finally gets to --decrypt), let’s be real: anyone who’s not already comfortable with encryption software will be completely intimidated by this manual, which is 175 (!) page‐downs in a 80×24 terminal. Contrast with signify: https://man.openbsd.org/signify.1 https://man.openbsd.org/signify.1 The description section starts with the four major operations (sign file, verify file, verify many files, generate key), and is again followed by an examples section. Of course, the OpenBSD tools are much less featureful than the mainstream counterparts. But the reality is that most people, and certainly I myself, need only a few features in day‐to‐day life. Even being a real terminal junkie, I’ve only needed GNU tar specifically once or twice in the last ten years; and when I did, on OpenBSD, it was a mere “pkg_add gtar” away. OpenBSD has a great self‐contained base system, with elegant tools and useful documentation, and an extensive package collection for when that’s not adequate. I continue to use it because it serves my needs as a primary driver, and the interface is just so gosh darn pleasant to use.

djgs 7y ago
Said much better than I could. :)
eb0la 7y ago
If the software and the documentation differ, that's a bug. If you don't understand the docs, there's a bug in the documentation. OpenBSD does not like bugs :-)
hutzlibu 7y ago
Since I got frustrated with linux man pages a lot, I am glad to see OpenBSD does it different. (one of the reasons why I finally want to give it a try) The tar example is indeed much cleaner. But it seems to be a bit old ... "A tar archive is often stored on a magnetic tape, but can be stored equally well on a floppy, CD-ROM, or in a regular disk file" Not that it hurts much, though.
- moviuro 7y ago
  See the blame on tar.1 [0] : documentation does not change very much... [0] https://github.com/openbsd/src/blame/f84583fe5d7899ab1504dc1d58a04742db4a3058/bin/pax/tar.1 https://github.com/openbsd/src/blame/f84583fe5d7899ab1504dc1...
teddyh 7y ago
It’s slightly disingenuous of you to compare the GNU man page to the OpenBSD man page, since while the OpenBSD man page is the official documentation, the GNU man page is not. As clearly stated in the GNU man page for tar: “This manpage is a short description of GNU tar. For a detailed discussion, including examples and usage recommendations, refer to the GNU Tar Manual […]”, and it gives a link to it: https://www.gnu.org/software/tar/manual/tar.html#SEC1 https://www.gnu.org/software/tar/manual/tar.html#SEC1 If you had compared the OpenBSD man page to that, it would be a more fair comparison.
- anjbe 7y ago
  “Disingenous” suggests malice. That is both unkind and untrue. I had simply forgotten. In any case, the info page is far larger than the already‐large manual page, which I think only further illustrates one of my points, that the software is itself intimidatingly complex.

djgs 7y ago

I would say it's both the user application and the system calls. Here is the man page of the driver for the wireless card in my laptop https://man.openbsd.org/iwm.4 https://man.openbsd.org/iwm.4 It's clear and concise, has links to the related tools that I might need to get the card working. Is there a similar man page for Linux? I'm not sure, honestly. Copy and paste? You'd have to copy and paste the whole driver for a start.

sverige 7y ago

I don't know anyone who relies on man pages for Linux. I know a lot of people who use man pages almost exclusively for OpenBSD. Yes, they are there for system calls, but also for applications -- depending on your definition of end-user applications, since some of what Linux considers "end-user" are, as TFA mentions, first-class applications that ship with OpenBSD. I don't think the differences can be resolved with copy and paste since many Linux man pages deal with programs that are very different under the hood than those with the same or similar names in OpenBSD. I also don't think it's unfair or arrogant to consider OpenBSD's man pages to be the standard of what man pages should be, btw. Search one or two of your favorites and see for yourself: https://man.openbsd.org https://man.openbsd.org

JdeBP 7y ago

It cannot be resolved with some copy and paste. Take "ps", for example. The BSD "ps" program is fundamentally different to the Linux "ps" program. It's also, quite importantly, different to what the Linux "ps" manual erroneously claims the BSD "ps" to be. * https://manpages.debian.org/testing/procps/ps.1.en.html https://manpages.debian.org/testing/procps/ps.1.en.html * http://man.openbsd.org/ps http://man.openbsd.org/ps * http://netbsd.gw.com/cgi-bin/man-cgi?ps http://netbsd.gw.com/cgi-bin/man-cgi?ps * https://freebsd.org/cgi/man.cgi?query=ps https://freebsd.org/cgi/man.cgi?query=ps * https://unix.stackexchange.com/a/511530/5132 https://unix.stackexchange.com/a/511530/5132