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?
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.
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.
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.
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
If you had compared the OpenBSD man page to that, it would be a more fair comparison.
“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.
Seems that OpenBSD folks understand what the page in manpage means. Too bad they do not have something similar to info for full manuals (yes, you hate the default GNU info viewer, i know, my point is about the hypertext format with indexing and working as an ebook file that takes advantage of the fact that computers are interactive and does not try to simulate dead trees).
OpenBSD manpages are written in a semantic format, -mdoc, that readily converts to HTML with inter‐ and intra‐document hyperlinks, and facilitates searching and hyperlinking even from within the terminal (via more(1)’s tags support).
I know, but writing a coherent manual is a different task than writing a short reference page, especially if you want to include more content than just a reference (e.g. user guides or tutorial sections) and writing text that assumes inline hyperlinking is always available.
Note that this isn't about it being technically impossible, you can certainly do it, but it isn't the right tool for the job - a dedicated manual reader provides a better UX here (and the failure of GNU info to provide a user friendly experience is, IMO, the reason manpages are abused so much in Linux).
You're talking about the grossly-misnamed (since large portions of it do not contain any questions) OpenBSD FAQ, which is where guide and tutorial stuff is to be found.
BSDs (and some others) come with variously-named Handbooks. OpenBSD has the aforementioned. FreeBSD has a Handbook. So do DragonFly BSD, NetBSD, and others. They are distinct from the user manuals, which are the reference doco. They are, indeed, hyperlinked. Already.
I'm not talking about any specific guides or manuals, but yes the OpenBSD FAQ, FreeBSD Handbook, etc are the sort of manuals i am talking about. But those are not made in manpage format and at least the OpenBSD FAQ HTML pages seem to be edited by hand. And since those are in HTML (at least the OpenBSD one, i didn't look into the others) they lack the indexing and ebook-like reading features that something like info provides (e.g. there are no browsing links - there used to be a pseudostandard with special <link> tags, but it was only ever supported by classic Mozilla/SeaMonkey and it never caught on).
EDIT: i see some of those are authored in DocBook but still info files can in theory be written in DocBook too. The main focus of my comments here is the end user format and viewer capabilities, not the authoring format (and honestly i'm not a big fan of info format with its hardcoded text formatting).
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"
Good examples are critical. Examples are not a substitute for a thorough explanation, but they can make utilities so much easier to understand. If you're writing technical documentation, please include some examples starting with the simplest use cases.
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.
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.
And can these differences be resolved with some copy & paste so they are both up to standard?