To say nothing about the astonishing quality of the man pages and online documentation.

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?

These are two pretty complex manpages for setting up network interfaces:

http://man.openbsd.org/ifconfig.8

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.

Apples and oranges. The relevant man page for Linux is ip-address(8), not ip(8).

Hmm I started at:

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.

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...

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)

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.

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?

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

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.

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.

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).

You can search a whole info file just as quickly as a man page, and using the index you can jump to the canonical docs for any argument or command in one go (ever spent time trying to find the hyphen-character section of a man page but struggled because it's referenced in 10 places?). I'll admit that whenever in man or info, I will generally go straight to the examples section because that's just how my brain works, but at that point I appreciate that info files aren't stingy with detail.

> You can search a whole info file just as quickly as a man page

It's possible that I just don't know how to use info. I always end up in the wrong place. That does not happen with man.

> and using the index you can jump to the canonical docs for any argument or command in one go

How?

> (ever spent time trying to find the hyphen-character section of a man page but struggled because it's referenced in 10 places?)

No, because the options are indented and inserting a few spaces before the hyphen in search string eliminates virtually all in-text references. Conventionally, the options are alpha-sorted too. In info pages, I end up wondering which section the option I want might be covered in.

> How?

I in Emacs info-mode. The prompt also has autocompletion.

`info x | less` gives you a better info browser than info

If only I could somehow coax info to render all subnodes into a single page and then pipe it through less it'd be useful to me.

Info is great for people who live and breathe Emacs, and terrible for non-Emacs users who are just trying to figure out how to get something done. If it's been a while since you last used it, you probably have to refresh yourself on the navigation commands, and the really useful features (the index[1] and incremental search[2]) are buried in different sub-nodes of the Info info manual.

As sibling commenters have mentioned, the Info tooling and format encourages people to split up their content into a bunch of nodes. In my experience, ~80% of Info manuals would be better if they were just concatenated into a single node, which the user could quickly Ctrl-F through with the tool of their choice.

[1] https://www.gnu.org/software/texinfo/manual/info-stnd/info-s...

[2] https://www.gnu.org/software/texinfo/manual/info-stnd/info-s...

You can use arrow keys and enter to navigate if you want, or tab like in every other hypertext system in the world. The search key is exactly the same as man, as well as supporting the same ones as readline, and they work across the whole file. I mean, it's 2019, it's a lost argument, but it'd be a shame to think it was lost on this basis.

Fwiw I used Emacs as my go-to editor & IRC client for a few years but I just could not bring myself to like info much at all. The format feels more suitable for something that wants to be a book. I don't want manuals to read like books.

Yes, info is horrendous, I hate to say this about a free documentation system, but they could not come up with a worse environment if they tried.

But the good news is I read GNU is moving away from INFO for something else, forgot what it was.

Info is kind of cool but as others have stated requires learning yet another command line user interface. It's nice to hear that in recent years it's been made more user friendly by respecting arrow keys, etc but IMHO nothing can touch man foo | col -b > /tmp/foo.1 && vi /tmp/foo.1 for simplicity. It's not a vi vs emacs thing as much as I just want to get to the data and get the tool out of my way kind of thing.

Particularly when taking a certain vendor's certification tests, it was the work of seconds to write a man page example to disk and turn that into a script.

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...

Wow, that's a huge difference. I'm tempted to try OpenBSD just for those man pages.

OpenBSD firewall:

https://man.openbsd.org/pf.4

https://man.openbsd.org/pfctl

https://man.openbsd.org/pf.conf#EXAMPLES

vs

https://linux.die.net/man/8/iptables

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.)

are you recommending iptables as an example of 'better' ?!

No. Reverse that.

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/

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

(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...)

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.

Do you have the source somewhere public by chance? Sounds like a fun learning project.

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.)

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

[2] https://linux.die.net/man/1/stat

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

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.

Well.. Debian was pretty straightforward to install and i've learned a lot from it. But OpenBSD was not. I don't know if the current OpenBSD installer has made it a lot easier. I just want a secure easy desktop with a frequently updated browser. I'd love to try OpenBSD again, but it scares me.

Eh, it takes 5-10 minutes to install OpenBSD, it's very straightforward. The installer requires little more than tapping return a few times and entering a root password & optional user at some point. I've yet to see a Linux distro that is so fast and simple to install.

This depends on what you need out of it. I found it difficult to install despite being somewhat technical at the time. My goal was a secure desktop install.

Probably Slackware. Quite similar to OpenBSD although I did have a hard time with driver support. But if I remember correctly, installation was blazing fast and you'd get a barebone system up and running in no time.

Totally agree. I recently moved away from Debian after using it and OpenBSD for various things both at home and work. After trying a few different distros I gave Slackware a try because I had used it years and years ago. I bought a book, think around 1995, that came with Slackware on a CDROM so it was my first experience with Linux.

I was pleasantly reminded how much Slackware still resembles BSD in how it configures things and it's emphasis on a minimal install that can be added to as needed. Other than new apps, a few improvements and, of course, updated hardware support Slackware has changed surprisingly little since I used it in 1995!

Patrick Volkerding is a great maintainer and I really appreciate his efforts over the past few decades!

Slackware's certainly fast to install once you've gotten past partitioning, but partitioning is one of the things Slackware intentionally does not do for you in the installer. OpenBSD's a bit easier in that regard.

Thank you for your answer. I'll try it on some old laptop.

> OpenBSD's unfriendly reputation ensured that I languished in Linux land way longer than I should have

Funny enough, OpenBSD's unfriendly behavior just had me go back to Linux land after running a FreeNAS server for two years. I got tired of every single help thread I was reading start with "Well you're stupid and you shouldn't do that" in one form or another.

Once Ubuntu got mature ZFS support in mainline, I was out.

What does OpenBSD have to do with FreeNAS? Or did you just mean unfriendly behaviour in general.

What I've noticed about the OpenBSD mailing lists is that while people are generally decent and helpful if you show that you put at least some effort into your question, I also see negative responses to the less good questions that are just not needed, and without value.

I still like OpenBSD because it's just a good OS, but I think some people could stand to tune up their filters a bit.

>FreeNAS is a free and open-source network-attached storage (NAS) software based on FreeBSD and the OpenZFS file system [0]

So its a BSD, but not OpenBSD

[0] https://en.wikipedia.org/wiki/FreeNAS

> Funny enough, OpenBSD's unfriendly behavior just had me go back to Linux land after running a FreeNAS server for two years. I got tired of every single help thread I was reading start with "Well you're stupid and you shouldn't do that" in one form or another.

In fairness to the people who called you stupid, you have some pretty glaring misunderstandings about whichever product you were using. (FreeNAS? OpenBSD?)

What does FreeNAS have to do with OpenBSD?

>I got tired of every single help thread I was reading start with "Well you're stupid and you shouldn't do that" in one form or another.

This is why I jokingly call OpenBSD a full contact operating system; interacting with the community can feel like being at the bottom of a rubgy scrum. Still, the hardware requirements are so low and configuration and management easy enough I use it on old refurbished PCs as a firewall. Any refurbished $100 PC from microcenter and a couple of Intel gigabit ethernet cards is enough to make a decent firewall as long as you don't have gigabit ethernet to your ISP. OpenBSD really shines on legacy hardware.

I also enjoyed the fact it was the work of a few minutes to cut certificates for all my wifi devices and switch to certificate-based authentication instead of password-based. Unfortunately IOT vendors don't support that so you end up with a separate network just for semi-trusted devices.

I have found the FreeNAS forums to be very helpful and friendly. Besides, like others said, FreeNAS is on FreeBSD, not OpenBSD.

Considering how many people like to fiddle with ArchLinux there is a niche for everybody.

Although I found that I barely have to touch my OpenBSD system...

I don't use BSD on the desktop though, still need Java.

I use IntelliJ on OpenBSD no problems (had to google some env var to set to make it render properly as I use a tiling window manager, apart from that it "just works").

One thing I do notice is OpenBSD's malloc implementation is much more serious about killing misbehaving apps so occasionally a process which does something it would get away with on linux/other will be taken out the back and lined up against the wall -- that's a feature and not a bug though (and configurable)