I also babysit trolls....

What's up, Doc? A guide to Linux Documentation

Date/Time Permalink: 03/17/06 07:29:50 am
Category: HOWTOs and Guides

Eric S. Raymond referred once to Unix documentation formats as "a zoo"
in his book "The Art of Unix Programming" - and he wasn't off by a
hair. When I was new to Linux, I was absolutely befuddled at this
aspect; every time I wanted to learn something, I had to hunt around
until I'd discovered *which* kind of documentation was to be
had. Herein, a trail of breadcrumbs. Hang on, it's a big wilderness
and my box of crumbs is very small!

man pages

- Short for "manual". By far the most ubiquitous. Man pages
were supposed to be phased out, but nevertheless man pages have
stayed. To read one on topic "Foo", grovel your way to a command line
and type:

man foo

Sometimes there will be more than one man page on a topic - for
instance, printf is both a programmer's function and a Bash
utility. So you have to specify the section like this:

man 1 printf

for the man pages in section one. But how do you know *which* section?
Not everybody in the Linux community even agrees, but here's a rough

1: user level commands
2: system calls
3: system libraries/programmer's reference
4/5: devices/file formats
6: games and optional apps
7: special files and devices
8: sysadmin/maintenance commands
9: kernel and driver reference

Special manual sections may also be found for specific topics, such as
developer's tools. For instance, on my Slackware system, the Tcl/Tk
programming reference manual pages are in /usr/man/mann. In which case
I summon thusly:

man n menubar

to get docs on the Tcl menubar builtin. I won't even say YMMV (your
mileage may vary). Your mileage is GUARANTEED to vary from one
distribution to another. Best to poke around and explore. It's usually
always best to leave off the section specification - unless you know
for sure that your topic's name is duplicated in more than one

Wait, there's more to man: the cousin command is "apropos", which will
pull up every man page which mentions your topic in the title. So when
I go:

apropos png

I get:

libpng (3) - Portable Network Graphics (PNG) Reference
Library 1.2.5
libpng [libpngpf] (3) - Portable Network Graphics (PNG) Reference
Library 1.2.5 (private functions)
png (5) - Portable Network Graphics (PNG) format
png2eps (1) - create greyscale .eps postscript image
from a .png file, scaled if necessary
pngtopnm (1) - convert a Portable Network Graphics file
into a portable anymap
pnmtopng (1) - convert a portable anymap into a Portable
Network Graphics file
read-notepad (1) - Connect to the Palm handheld and list the
record information found in the Palm Notepad application (found on OS4
and newer devices). Alternately, if no options are given, each
record's image will be converted to files, using Portable Network
Graphic (.png) or Portable Pixmap (.ppm) format. The default type is

and I know right away what all on my system involves png files. The
number in parenthesis is the man page section! Man pages range from
pithy and terse to downright taciturn - experienced Linux users use
them for a quick reference card, but newbies are actually advised not
to rely entirely on man pages and sometimes even not to turn to man
pages unless as a last resort. Man pages, however, are frequently a
last resort, especially for finding out all the option switches that
you can type for a given function and what they do. I make it a habit
to at least skim the man page for any new concept I'm exploring. Is it
any wonder why we're trying to phase these out?

A GUI reader for man pages exists - "xman", which has the benefit of
listing all the man pages on your system in one big whack. This is
somewhat convenient, but we could go a lot farther as far as developed
user interfaces go. KDE and Gnome typically include the man page
sections in the system documentation browser, a much more comfortable
interface. And the last man program I should mention is "whatis" -

whatis apropos

and you'll get an apropos-style listing for apropos! In fact, the
"whatis" database is where apropos gets the data from for it's output.
All of the rest of Linux documentation gets much, much simpler from
here, I promise!


- the GNU info system is man's less primitive brother. Simply
typing "info" at a command line will reward you with a full-screen
display. You navigate a cursor around in this display, and when you
see a link that you want to visit:

* Text utilities: (textutils). GNU text utilities.

place the cursor anywhere between the * and the : and press enter -
you will go to that node, which may have further menus or may be an
end to itself. To go back, press "l". You can also press "p" to go to
the previous node entry, "n" to see the next entry, or "u" to go up
out of the current directory - pressing "u" repeatedly gets you to the
"top of the info tree" and you can dive in again. Pressing "h" gets
you a first-timer's tutorial. Almost like a little web system in your
console! Info pages are much more complete than man pages, more
newbie-friendly, and now the bad news: some distros don't include the
info system.

If you know what your topic is, you can type

info foo

just like with man, and get the info page if it exists for foo, or the
top of the info tree if it doesn't. As an extra added bonus
attraction, if info doesn't find an info page (all of which live
snuggled together in one big directory, usually /usr/doc/info), but
finds a manual page, it will pull up the man page instead.


- Just about any tarball you download will have a file named
"README" in the top directory. READMEs are included right from the
programmer, and usually have nothing more than compilation
instructions and pointers to where to get more help. Sometimes a file
named "INSTALL" will be in the same place, giving you install
instructions. READMEs are plain old text files, readable with any
lovely thing at all.


- HOWTO documents are not documentation on specific programs, as
the prior examples, but overall, comprehensive tutorials on a general
subject, like "Bash-Prog-Intro-HOWTO". No special program is required
to read them, and if they're included in your distro, they'll be in
someplace like /usr/doc/Linux-HOWTOs/ So far, Slackware, God bless it,
is the only distro I've encountered that includes the full HOWTO
catalog - if you're high and dry, look no farther than the Linux
Documentation Project
. HOWTOs are almost always well-written and
maintained, and a refreshing overview of the subject at hand.

HTML files

- second in popularity only to man pages. Hurray! HTML
files can be read with a regular, ordinary web browser! HTML docs, if
your system has them, will usually be in folders inside the /usr/doc/
directory (or /usr/share/doc/, or just plain /doc/, or...) So, docs
about "foo" would start at "/usr/share/doc/foo/index.html". This isn't
always predictable - sometimes the files in /usr/doc/ will be plain
text, or info files, or contained in a folder named "html", or who
knows what.


- DocBook was another "supposed to happen" - initially created
as a way to knit the sprawling documentation formats into a unified
whole, and instead increasing the confusion by adding just another
format. Docbook can be readily converted to HTML, XHTML, Post Script,
PDF, man page files, good ol' text, etc. Docbook itself is either SGML
or XML, it can't decide which. Docbook is heavily represented at Linux
Documentation Project, endorsed by many, and is usually the format
your KDE docs are in.

PDF and PS

- lowly as these methods are, some people are still naive
enough to release their Portable Document Format/PostScript manuals
for on-screen reading. I really wish PDF and PS files auto-converted
to HTML after being used to do their intended purpose - printing to
hardcopy - so no one would be tempted to do this. It is especially
frustrating when I have no GUI as a result of hosing my system, and
the only help I can find after hours of searching in console-land is a
PDF file. Have you ever tried using "ps2ascii" to make a text-dump of
a postscript file? One word of advice - don't. I only read PDF/PS as
the absolute bottom choice. The exception is when whole books are
released for free online in pdf/ps form - here at least the material
was originally intended for print as an actual paper book - in which
case I grudgingly settle for it. It's only a minor annoyance, really.
But I'm a blogger; I'm *supposed* to whine!

Special readers are of course required to browse this cursed format,
which offer you no comfort as you drag the little white hand down the
page to get the interface to take two minutes to load the next
page. As reading experiences go, reading a PDF/PS document onscreen
feels about as natural as eating dinner while gripping the fork with
your feet. However, if you have either a copy of the Nautilus file
manager or Konqueror, you have a built-in PDF viewer that's downright
luxurious compared to other viewers such as xpdf or ghostscript.


- good old help buttons in the GUI interface of the program are
always useful. Sometimes "help" will be a link to the desktop's help
system - in gnome this is "yelp" and in KDE this is "khelpcenter". The
usual icon for help in either system is an icon of a red-and-white
life preserver, rescuing you from the seas of madness.

Depending on how well-put-together your Linux distro is, you might be
able to access man pages, docbooks, HTML indexes, and other forms of
documentation all from the desktop system's main helper app.

Finally, the


convention. Many programs, when
invoked from the command line, will utter something helpful when you
follow it with one of these switches. Note the dashes - by convention,
single character switches get a single dash, multiple-character
switches get a double dash. That's just a *convention* - it's up to
whoever wrote the program whether it works that way or not!

Goooooooooooood luck!

Follow me on Twitter for an update every time this blog gets a post.
Stumble it Reddit this share on Facebook

suddenly the moon