11 ms·

This is often presented as one of the strengths of OpenBSD. I find it hard to believe that Linux man pages are so far behind (why would they not be copied from

This is often presented as one of the strengths of OpenBSD. I find it hard to believe that Linux man pages are so far behind (why would they not be copied from BSD?), but do of course not claim that it would be impossible. Could someone please point to an example, so that the difference in quality becomes apparent?

IcePic 7y ago
I know these are dist-specific issues, but it seems far easier on linux dists to end up with an installed program (from rmp/debs) and still don't have the manpages, OR, getting a dud manpage that tells you to run "info gnufrotzomatic" and then you run that and since there were no info pages, info will very helpfully tell you to run itself again, since it shows a manpage if the info page is missing. Semi-recent Centos7: $ which find /usr/bin/find $ rpm -q --whatprovides '/usr/bin/find' findutils-4.5.11-6.el7.x86_64 $ man find No manual entry for find $ more /etc/redhat-release CentOS Linux release 7.7.1908 (Core) So it claims to have the findutils rpm installed, which comes with manpages (especially since there is no find-man rpm) but I didn't get them for reasons. You just don't get that kind of experience on BSDs unless you very deliberately unmark manpages for installations. (which could be some kind of usecase, sure)
- throw7 7y ago
  That's very strange. Probably centos is stripping "docfiles" from the installation (maybe a "container-optimized" install?). You can see which files are marked as documentation with "rpm -qd findutils". On my rhel 7, the man page is packaged along with findutils and I do see it.
- somerandomqaguy 7y ago
  I'm seeing the man pages for find on my Centos 7.7 boxes. Are you looking at a docker container or a cloud image?
brobdingnagians 7y ago
OpenBSD firewall: https://man.openbsd.org/pf.4 https://man.openbsd.org/pf.4 https://man.openbsd.org/pfctl https://man.openbsd.org/pfctl https://man.openbsd.org/pf.conf#EXAMPLES https://man.openbsd.org/pf.conf#EXAMPLES vs https://linux.die.net/man/8/iptables https://linux.die.net/man/8/iptables
- mistrial9 7y ago
  are you recommending iptables as an example of 'better' ?!
  - brobdingnagians 7y ago
    No. Reverse that.
- juped 7y ago
  Imagine if your email daemon could be configured with a syntax similar to pf.conf - you're in luck, because OpenSMTPD exists and you can! (Many of us out there have serious m4 trauma.)
clarry 7y ago
For a different take, consider audio APIs. I've yet to find a man page that tells me how to use ALSA. There's a clutterfuck of doxygen docs if you want to get lost.. https://www.alsa-project.org/alsa-doc/alsa-lib/ https://www.alsa-project.org/alsa-doc/alsa-lib/ Or you can buy a nice little library from OpenBSD where the PCM part is sufficiently described in one short man page: http://man.openbsd.org/sio_open.3 http://man.openbsd.org/sio_open.3 (With enough detail so that you can use it to write e.g. a latency-aware rhythm game that manages to keep audio and video in sync...)
- jim-jim-jim 7y ago
  I love sndio. I was able to write a little synthesizer for it using nothing more than the man pages. It's weird to think that I'm using OpenBSD rather than macOS for music-making, but the latter is just too complex and unpleasant to work with.
  - basilisks 7y ago
    Do you have the source somewhere public by chance? Sounds like a fun learning project.
- juped 7y ago
  A very endearing trait of OpenBSD developers is that when they make a system facility, it has a great C API. Can you beat "uint32_t arc4random(void); void arc4random_buf(void *buf, size_t nbytes); uint32_t arc4random_uniform(uint32_t upper_bound);" as a RNG API? (No. Add it, glibc.)
bluGill 7y ago
GNU long ago decided man pages were bad and quit writing good ones, preferring to use their info system instead. Debian has been trying to get good man pages with some success. BSD never agreed with GNU on this and so they tended to write good documentation in man pages.
cpach 7y ago
Here’s one example: https://bugzilla.kernel.org/show_bug.cgi?id=71211 https://bugzilla.kernel.org/show_bug.cgi?id=71211
mprovost 7y ago
These are two pretty complex manpages for setting up network interfaces: http://man.openbsd.org/ifconfig.8 http://man.openbsd.org/ifconfig.8 https://linux.die.net/man/8/ip https://linux.die.net/man/8/ip The Linux one doesn't have an example anywhere of how to assign an IP address to an interface. Which is probably the most basic thing that you would be looking for.
- teddyh 7y ago
  Apples and oranges. The relevant man page for Linux is ip-address(8), not ip(8).
  - mprovost 7y ago
    Hmm I started at: https://linux.die.net/man/8/ifconfig https://linux.die.net/man/8/ifconfig which says "This program is obsolete! For replacement check ip addr and ip link" and references ip(8) in the See Also section. Neither page refers to ip-address. In fact that entry doesn't exist on die.net which seems to be what Google considers to be the authoritative source for Linux man pages.
    - teddyh 7y ago
      I can’t vouch for the updatedness of “linux.die.net”, of which I know nothing. Try this one: https://manpages.debian.org/testing/iproute2/ip-address.8.en.html https://manpages.debian.org/testing/iproute2/ip-address.8.en...
ainar-g 7y ago
You can see the difference even in primitive stuff like stat(1). E.g. compare the EXAMPLES section in OpenBSD[1] and Linux[2]. [1] https://man.openbsd.org/stat.1 https://man.openbsd.org/stat.1 [2] https://linux.die.net/man/1/stat https://linux.die.net/man/1/stat
clarry 7y ago
One thing that annoys me is excess verbosity (that doesn't make the manual any more readable or easier to skim through). Man page for find(1) is a typical example. http://man.openbsd.org/find http://man.openbsd.org/find https://linux.die.net/man/1/find https://linux.die.net/man/1/find I usually read man pages on OpenBSD, even when I'm working on Linux. I also often link people on IRC OpenBSD man pages when they're struggling with their tools (or their manuals) on Linux. The reception is generally positive.
- teddyh 7y ago
  For GNU tools such as find (part of GNU Findutils), the official documentation is almost always not the man pages (which are therefore not as good as they could be), but the Info documentation. In this case: https://www.gnu.org/software/findutils/manual/html_mono/find.html#Finding-Files https://www.gnu.org/software/findutils/manual/html_mono/find...
- thom 7y ago
  Yeah, the difference here is very stark. I do sometimes wish that info had won as I always found it more accessible (compared to Linux man pages at least), but I suppose the vast majority of people just google now and almost all of these things are redundant.
  - clarry 7y ago
    Info is even worse IMHO. Navigating a hierarchy makes it harder to skim and search through, as well as easier to get lost. And when you have such hierarchy, manual writers can use that as an excuse to write even longer (sigh) manuals. To me, much like code and math, the art of writing good documentation is all about finding a way to make it short and simple (but still correct and complete).
    - fanf2 7y ago
      `info x | less` gives you a better info browser than info

IcePic 7y ago

I know these are dist-specific issues, but it seems far easier on linux dists to end up with an installed program (from rmp/debs) and still don't have the manpages, OR, getting a dud manpage that tells you to run "info gnufrotzomatic" and then you run that and since there were no info pages, info will very helpfully tell you to run itself again, since it shows a manpage if the info page is missing. Semi-recent Centos7: $ which find /usr/bin/find $ rpm -q --whatprovides '/usr/bin/find' findutils-4.5.11-6.el7.x86_64 $ man find No manual entry for find $ more /etc/redhat-release CentOS Linux release 7.7.1908 (Core) So it claims to have the findutils rpm installed, which comes with manpages (especially since there is no find-man rpm) but I didn't get them for reasons. You just don't get that kind of experience on BSDs unless you very deliberately unmark manpages for installations. (which could be some kind of usecase, sure)

throw7 7y ago
That's very strange. Probably centos is stripping "docfiles" from the installation (maybe a "container-optimized" install?). You can see which files are marked as documentation with "rpm -qd findutils". On my rhel 7, the man page is packaged along with findutils and I do see it.
somerandomqaguy 7y ago
I'm seeing the man pages for find on my Centos 7.7 boxes. Are you looking at a docker container or a cloud image?

brobdingnagians 7y ago

OpenBSD firewall: https://man.openbsd.org/pf.4 https://man.openbsd.org/pf.4 https://man.openbsd.org/pfctl https://man.openbsd.org/pfctl https://man.openbsd.org/pf.conf#EXAMPLES https://man.openbsd.org/pf.conf#EXAMPLES vs https://linux.die.net/man/8/iptables https://linux.die.net/man/8/iptables

mistrial9 7y ago
are you recommending iptables as an example of 'better' ?!
- brobdingnagians 7y ago
  No. Reverse that.
juped 7y ago
Imagine if your email daemon could be configured with a syntax similar to pf.conf - you're in luck, because OpenSMTPD exists and you can! (Many of us out there have serious m4 trauma.)

clarry 7y ago

For a different take, consider audio APIs. I've yet to find a man page that tells me how to use ALSA. There's a clutterfuck of doxygen docs if you want to get lost.. https://www.alsa-project.org/alsa-doc/alsa-lib/ https://www.alsa-project.org/alsa-doc/alsa-lib/ Or you can buy a nice little library from OpenBSD where the PCM part is sufficiently described in one short man page: http://man.openbsd.org/sio_open.3 http://man.openbsd.org/sio_open.3 (With enough detail so that you can use it to write e.g. a latency-aware rhythm game that manages to keep audio and video in sync...)

jim-jim-jim 7y ago
I love sndio. I was able to write a little synthesizer for it using nothing more than the man pages. It's weird to think that I'm using OpenBSD rather than macOS for music-making, but the latter is just too complex and unpleasant to work with.
- basilisks 7y ago
  Do you have the source somewhere public by chance? Sounds like a fun learning project.
juped 7y ago
A very endearing trait of OpenBSD developers is that when they make a system facility, it has a great C API. Can you beat "uint32_t arc4random(void); void arc4random_buf(void *buf, size_t nbytes); uint32_t arc4random_uniform(uint32_t upper_bound);" as a RNG API? (No. Add it, glibc.)

bluGill 7y ago

GNU long ago decided man pages were bad and quit writing good ones, preferring to use their info system instead. Debian has been trying to get good man pages with some success. BSD never agreed with GNU on this and so they tended to write good documentation in man pages.

cpach 7y ago

Here’s one example: https://bugzilla.kernel.org/show_bug.cgi?id=71211 https://bugzilla.kernel.org/show_bug.cgi?id=71211

mprovost 7y ago

These are two pretty complex manpages for setting up network interfaces: http://man.openbsd.org/ifconfig.8 http://man.openbsd.org/ifconfig.8 https://linux.die.net/man/8/ip https://linux.die.net/man/8/ip The Linux one doesn't have an example anywhere of how to assign an IP address to an interface. Which is probably the most basic thing that you would be looking for.

teddyh 7y ago
Apples and oranges. The relevant man page for Linux is ip-address(8), not ip(8).
- mprovost 7y ago
  Hmm I started at: https://linux.die.net/man/8/ifconfig https://linux.die.net/man/8/ifconfig which says "This program is obsolete! For replacement check ip addr and ip link" and references ip(8) in the See Also section. Neither page refers to ip-address. In fact that entry doesn't exist on die.net which seems to be what Google considers to be the authoritative source for Linux man pages.
  - teddyh 7y ago
    I can’t vouch for the updatedness of “linux.die.net”, of which I know nothing. Try this one: https://manpages.debian.org/testing/iproute2/ip-address.8.en.html https://manpages.debian.org/testing/iproute2/ip-address.8.en...

ainar-g 7y ago

You can see the difference even in primitive stuff like stat(1). E.g. compare the EXAMPLES section in OpenBSD[1] and Linux[2]. [1] https://man.openbsd.org/stat.1 https://man.openbsd.org/stat.1 [2] https://linux.die.net/man/1/stat https://linux.die.net/man/1/stat

clarry 7y ago

One thing that annoys me is excess verbosity (that doesn't make the manual any more readable or easier to skim through). Man page for find(1) is a typical example. http://man.openbsd.org/find http://man.openbsd.org/find https://linux.die.net/man/1/find https://linux.die.net/man/1/find I usually read man pages on OpenBSD, even when I'm working on Linux. I also often link people on IRC OpenBSD man pages when they're struggling with their tools (or their manuals) on Linux. The reception is generally positive.

teddyh 7y ago
For GNU tools such as find (part of GNU Findutils), the official documentation is almost always not the man pages (which are therefore not as good as they could be), but the Info documentation. In this case: https://www.gnu.org/software/findutils/manual/html_mono/find.html#Finding-Files https://www.gnu.org/software/findutils/manual/html_mono/find...
thom 7y ago
Yeah, the difference here is very stark. I do sometimes wish that info had won as I always found it more accessible (compared to Linux man pages at least), but I suppose the vast majority of people just google now and almost all of these things are redundant.
- clarry 7y ago
  Info is even worse IMHO. Navigating a hierarchy makes it harder to skim and search through, as well as easier to get lost. And when you have such hierarchy, manual writers can use that as an excuse to write even longer (sigh) manuals. To me, much like code and math, the art of writing good documentation is all about finding a way to make it short and simple (but still correct and complete).
  - fanf2 7y ago
    `info x | less` gives you a better info browser than info