It’s FreeBSD’s documentation, stupid


TuxGNUThe BSD Daemon

As you might remember a few months ago I switched from FreeBSD to Arch Linux on my 2002-era Compaq Armada M300 sub-notebook which I use for downloading torrents and as a coffee shop computer. Since then I might have figured out how to get my wireless card working on FreeBSD after all, but that's for another post.

One thing I have really noticed using the GNU Project's userland tools on Linux instead of FreeBSD's userland tools on FreeBSD is while the GNU tools generally have more features, the difference in the quality of the bundled documentation, specifically manual pages (Wikipedia) is huge. There's absolutely no comparison, FreeBSD's manual pages are more comprehensive, complete and better written.

As a FreeBSD user who has been spoilt silly and has come to expect this level of documentation, to use GNU/Linux has been somewhat of a shock. Often manual pages for the GNU userland tools contain a blunt dictionary style description of what the tool does, followed by a skeleton explanation of each of the options and a reference to a URL.

For example, check out the first screen of the manual page for the ls command for Linux and FreeBSD respectively, before the options are presented. Given Mac OS X's BSD underpinnings the man page for ls is the same too.


ls – list directory contents

ls [OPTION]…. [FILE]…

List information about the FILEs (the current directory by default). Sort entries alphabetically if one of the -cftuvSUX nor –sort.

Mandatory arguments to long options are mandatory for short options too.

FreeBSD (and Mac OS X)

ls — list directory contents

ls [-ABCFGHLPRSTW@abcdefghiklmnopqrstuwx1] [file …]

For each operand that names a file of a type other than directory, ls displays its name as well as any requested, associated information. For each operand that names a file of type directory, ls displays the names of files contained within that directory, as well as any requested, associated information.

If no operands are given, the contents of the current directory are displayed. If more than one operand is given, non-directory operands are displayed first; directory and non-directory operands are sorted separately and in lexicographical order.

The following options are available:

What I've since learned is the GNU project eschews manual pages for Texinfo pages which you access with a separate command. According to the Wikipedia page on the subject, Texinfo pages are designed as tutorials as well as general references, meaning they're more like books and less like traditional help files.

While I understand the merits of this approach, I still think this shunning of manpages or the lowering of their development priority is a bit short sighted. Even if the benefits of Texinfo pages are real, I don't see why one should be developed at the expense of the other.

I guess to be fair, this is something I'd get used to eventually if I switched to GNU/Linux as my primary OS.

Author bio and support


Ruben Schade is a technical writer and infrastructure architect in Sydney, Australia who refers to himself in the third person. Hi!

The site is powered by Hugo, FreeBSD, and OpenZFS on OrionVM, everyone’s favourite bespoke cloud infrastructure provider.

If you found this post helpful or entertaining, you can shout me a coffee or send a comment. Thanks ☺️.