Rubenerd

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.

GNU/Linux

NAME
ls – list directory contents

SYNOPSIS
ls [OPTION]…. [FILE]…

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

NAME
ls — list directory contents

SYNOPSIS
ls [-ABCFGHLPRSTW@abcdefghiklmnopqrstuwx1] [file …]

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