Chapter 1. Finding Documentation
Documentation for Linux programs is abundant. Finding it can be a bit challenging, though. You’re not going to find lots of sleek, glossy printed manuals, because most Linux software is distributed online, rather than in shiny boxed sets.
There’s another difficulty, too: Linux follows the grand Unix tradition of small, specialized programs working cooperatively, so any Linux distribution contains a large number of individual programs. For example, Tom’s Root Boot, “The most GNU/Linux on one floppy disk,” contains over 230 separate, individual programs on a single 3.5” diskette. A general-purpose distribution such as Mandrake or SuSE contains several thousand programs and there are over 12,000 packages in the Debian repositories. While organizing and maintaining a printed library presents some difficulties, the good news is that all of these things are documented. Whatever you want to know, there is a way to find it.
man and info: The Universal Linux Manuals
Almost every program written for Linux has a man page. They’re usually not the best teaching tool for newbies. Their purpose is to document the command syntax and every command option, and to be universally available. No matter what kind of strange desert-island scenario you may find yourself in, there will always be man pages. And because man pages are incorporated into the programs to which they belong, you’ll find that only installed programs have man pages and that the versions of those pages are pertinent to your system.
info pages tend to be more verbose than man pages and are hyperlinked. The hyperlinks navigate to the various nodes, or chapters, inside the document and to cross-references in other info pages. Many info pages are simply reformatted man pages. But in some instances—primarily the GNU project programs—the info pages are more detailed, containing tutorials and extensive examples.
A large number of README, CHANGELOGS, RELEASE NOTES, COPYRIGHT, INSTALL, integrated Help systems, and HTML docs are going to be squirreled away in various locations on your system. Yes, it’s a jumble. Don’t worry, you’ll learn easy ways to find all these things in this chapter, including a nice Python script to do the finding for you.
There are many web sites that host complete archives of man and info pages, which comes in handy if your system is missing the ones you want, or you want to read them without having to download and install new programs. A Google search will find them quickly.
The commercial Linux distributions—for example, Red Hat, SuSE, Mandrake, Xandros, and Linspire—supply excellent user manuals. Every major Linux distribution provides a feast of online resources. Search engines, user mailing lists, Usenet, and all sorts of Linux web sites also supply a wealth of help and information.
The web and file browser in KDE also contains an excellent man and info page viewer. Simply type man:foo or info:/foo in the address bar. It is easy to print from Konqueror, and easy to select individual man or info pages for printing.
The Gnome viewer. Displays man and info pages, and Gnome’s help documents. It is indexed and searchable.
A nice ncurses-based info and man viewer for the console. Users can add new documents to it, and it supports regexp searches.
1.2. Understanding man Pages
You’re trying to use some programs (for example, everyone’s favorite, grep; the name tells you so much) and you can’t make them do what you want. So, heeding the standard “RTFM” (read the fine man page) advice, you dig up the relevant man pages. But they don’t make a lot of sense—now what?
Learn how man pages are organized, and familiarize yourself with their conventions for teaching command syntax and options, and you’ll find that man pages really are helpful.
Linux sees all the man pages on a system as part of a single manual. This manual is divided into sections:
|1 Executable programs or shell commands|
|2 System calls|
|3 Library calls|
|4 Special files (usually found in /dev)|
|5 File formats and conventions|
|8 System administration commands|
|9 Nonstandard kernel routines|
|n New documentation, which may be moved later|
|l Local documentation, specific to your system|
Each individual program, utility, or function has its own page in this manual, like a page in a book. Finding the man page for a program or command is usually as easy as typing man foo, where foo is the name of the program.
You’ve probably seen references to numbered man pages, like grep(1). This is referring to man grep in section 1. Call it up this way:
$ man 1 grep
Some man pages are in more than one section. man foo will only display the first one. You can list all of them with the -f switch:
$ man -f man man (1) an interface to the online reference manuals man (7) macros to format man pages
Each man page is divided into sections. The section names vary, but you’ll usually see these: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, EXAMPLES, SEE ALSO, BUGS, and AUTHOR.
command-name [optional flags] any-other-required-elements
Command flags are shown this way:
- bold text
Type this exactly as it is shown.
- italic text
Italic text indicates an argument, which means you replace it with your desired value. Depending on the viewer you are using, you may not see italics, but rather underlines or bold text.
Everything inside square brackets is optional and can be combined.
Options separated by the pipe | (Shift-backslash) cannot be combined.
The ellipsis indicates that several arguments can be listed. Watch out for delimiters—usually they are spaces, but sometimes commas are used.
- [expression] ...
The ellipsis indicates that several expressions can be listed.
Short options can be typed two ways:
-a -b -c
Long options must be individually hyphenated, and they use double hyphens:
--option1 --option2 --option3
Long options are especially useful in scripts, so you can remember what the script does.
The bulk of most man pages is a list of the options available.
1.3. Finding Appropriate man Pages
You need a program or utility to perform a specific function—for example, counting the words in a file—but you don’t know what to look for. If you knew what you were looking for, you wouldn’t need to look for it, right? How do you get out of this dilemma?
$ apropos count words
$ man -k count words american-english (5) - a list of english words grpconv (8) - convert to and from shadow passwords and groups. grpunconv (8) - convert to and from shadow passwords and groups. kmessedwords (1) - a letter order game for KDE lppasswd (1) - add, change, or delete digest passwords. pwconv (8) - convert to and from shadow passwords and groups. pwunconv (8) - convert to and from shadow passwords and groups. shadowconfig (8) - toggle shadow passwords on and off wc (1) - print the number of newlines, words, and bytes in files
It doesn’t matter which you use; apropos and man -k are the same. There are a lot of options, but wc looks like the program you want.
$ man -f manpath manpath (1) - determine search path for manual pages manpath (5) - format of the /etc/manpath.config file
These commands perform keyword searches in the NAME sections of the man pages. You can use any number of search terms, but the more you use, the more results you’ll get, because they search each keyword in sequence.
Because these are literal keyword searches, broad concepts like “bandwidth shaping” or “user management” do not carry the same meaning for apropos and man -k; they see “bandwidth shaping” as two unrelated search terms, so single-word searches usually work best.
1.4. Finding Lost man Pages
$ whereis -m cat cat:/usr/man/man1/cat.1.gz /usr/share/man/man1/cat.1.gz
Now you’ve found the page. Read it with man:
$ man /usr/man/man1/cat.1.gz
$ locate / cat. | egrep -w 'cat\.[1-9][a-zA-Z]*[.gz]?'
This works for any man page—simply replace cat with whatever you’re looking for.
If none of these approaches turn up the man page you are looking for, try the finddoc script in Recipe 1.11. If this doesn’t find it, it’s not on your system.
There are all kinds of man page repositories on the Web, so you can always try a Google search. However, some programs simply don’t have man pages, so don’t ruin your health searching for one that may not exist.
grep comes in several flavors; see grep(1) for details
1.5. Reading man Pages Without a man Viewer
$ zcat /usr/man/man1/cat.1.gz | nroff -man | less
$ zless /usr/man/man1/cat.1.gz .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.32. .TH CAT "1" "July 2003" "cat (coreutils) 5.0" "User Commands" .SH NAME cat \- concatenate files and print on the standard output .SH SYNOPSIS .B cat [\fIOPTION\fR] [\fIFILE\fR]...
It’s not pretty, but it works.
nroff is a wrapper for groff , for formatting man pages. groff is a document-formatting, or typesetting, program. It enables you to create many differently formatted documents from a single source file: HTML, .pdf, printed hard copies, info pages, and many more. See Chapter 9 of Running Linux for a good introduction.
mandb(8), locate(1), grep(1), nroff(1), groff(1), zless(1), zcat(1)
Chapter 9 of Running Linux , by Matt Walsh, Matthias Dalheimer, Terry Dawson, and Lar Kaufman (O’Reilly)
1.6. Configuring Your manpath
You’re repeatedly having trouble finding man pages; using tools from Recipe 1.4, you find that most of the missing pages are in a directory that man doesn’t seem to know about. Perhaps a newly-installed program put its man pages in a strange place, like /opt/man. Or perhaps you want to put some man pages in a nonstandard location. How do you configure man to find them?
Suppose the directory you want to add is /opt/man. Add /opt/man to /etc/manpath.config:
# every automatically generated MANPATH includes # these fields MANDATORY_MANPATH /usr/man MANDATORY_MANPATH /usr/share/man MANDATORY_MANPATH /usr/X11R6/man MANDATORY_MANPATH /usr/local/man MANDATORY_MANPATH /opt/man
And you’re done. Now man will find the man pages in the new directory.
When you create a custom man page directory, be sure to include the section directories:
$ ls /opt/man/local man1 man2 man3 man4 man5 man6 man7 man8 man9
It’s not necessary to include all the numbered sections, just the ones pertinent to the man pages you’ll be storing there.
If you’re going to have subdirectories—for example, /opt/man and /opt/man/local—be sure to list them in this order:
MANDATORY_MANPATH /opt/man/local MANDATORY_MANPATH /opt/man
Subdirectories must be listed before parent directories, or they will be overlooked by the man viewer.
$ manpath /usr/local/man:/usr/share/man:/usr/X11R6/man:/usr/man
1.7. Using info Pages
You decide to give info pages a try, so you call up info tar (or any other info page of your choice). But you find that navigating info tar is confusing and difficult. What is the best way to learn your way around?
Use info’s built-in tutorial. Type info at any command line, hit the letter h, then do what it says. It should take 15-30 minutes, and it is time well-spent.
Even though some folks think that info pages are unnecessarily complicated to navigate, it is worth getting acquainted with them. Even though they are more difficult to navigate than man pages, they are (usually) easier to understand. Once you get the hang of moving around in them, you can go very fast and find information quickly. Info pages often contain more information than man pages, and they sometimes include tutorials and extensive examples.
There are also a number of nice info viewers, such as pinfo, Konqueror, and Yelp. Pinfo runs in the console, and Konqueror and Yelp need X. Konqueror is especially easy to navigate and to use for printing selected pages.
1.8. Printing man Pages
One way to print a nicely formatted man page is to use the -t flag, which formats it especially for printing. man finger is good for practice, because it’s only two pages long:
$ man -t finger | lpr
To use a networked printer:
$ man -t finger | lpr -P printername
To see your available printers:
$ lpstat -p -d
$ man -Hmozilla finger
Then use the browser’s print command. Be sure there is no space between -H and the browser name.
All of the major Linux distributions ship with CUPS, the Common Unix Printing System. CUPS supports both the System V (lp) and Berkeley (lpr) commands. This recipe uses the Berkeley commands. Here is the System V equivalent.
$ man -t finger | lp
To use a networked printer:
$ man -t finger | lp -d printername
man(1), lpr(1), lp(1)
CUPS Software Users Manual (http://localhost:631/documentation.html)
1.9. Printing info Pages
$ info finger | lpr
However, this may result in too-small margins and odd line breaks, depending on your printer defaults. Use lpr options to format it:
$ info finger | lpr -o cpi=12 -o page-left=54 -o page-right=54 -o page-top=54 \ -o page-bottom=54
The numbered values are points, or 1/72”. This example creates 3/4” margins all the way around. cpi=12 sets the number of characters to 12 per inch. All of these options are documented in the CUPS Software Users Manual, at http://localhost:631/documentation.html.
All of the major Linux distributions ship with CUPS, the Common Unix Printing System. CUPS supports both the System V (lp) and Berkeley (lpr) commands. This recipe uses the Berkeley commands. Here are the System V equivalents.
To print an info page use:
$ info finger | lp
To print the info page using lp's formatting options use:
$ info finger | lp -o cpi=12 -o page-left=54 -o page-right=54 -o page-top=54 \ -o page-bottom=54
info info, lpr(1), lp(1)
CUPS Software Users Manual (http://localhost:631/documentation.html)
1.10. Printing Selected man or info Pages
$ man bash | col -b > bash.txt $ info bash | col -b > bash.txt
If you just type man bash > bash.txt, the results will be unpleasant. col -b cleans things up considerably by removing reverse line feeds, or backspaces. This is especially suited for converting man pages to plain text, because man pages are full of reverse line feeds, which then appear in text files as either empty boxes or repeated characters.
1.11. Finding All of the Documentation for a Program
Use finddoc, that wonderful Python script that comes to you courtesy of the excellent Akkana Peck.
You can call it anything you like. Remember to make it executable:
$ chmod +x finddoc
Using it requires only the script name and the name of the program for which you need the documentation. For example:
$ ./finddoc grep /usr/share/doc/grep /usr/share/doc/grep-dctrl /usr/share/doc/grep-dctrl/changelog.gz ...
The output can be filtered through other commands, or redirected to a file:
$ ./finddoc | grep -i examples | lpr $ ./finddoc | grep -i faq $ ./finddoc | grep -i examples > python-examples.txt
#!/usr/bin/env python # Finddoc: A Script For Finding Linux Program Documentation # When making your own copy of this script, be sure to # preserve the leading spaces exactly as they are written # here, because Python needs them. # Search for documentation related to the given strings; # case-insensitive, and whole-word only. # Relies on "locate" and assumes that the locate # database is current. # # Copyright 2003 by Akkana Peck. # You may use, distribute or modify this program # under the terms of the GPL. import sys, os, string, re # This is the list of document-related filenames # to search for. You may edit this list as needed. # Be sure to add only lowercase names. docfilenames = [ "changelog", "readme", "install", "howto", "authors", "news", "todo", "config", "sample", "samples", "example", "examples", "ref", "guide", "manual", "quickstart", "thanks", "notes", "features", "faq", "acknowledgement", "bugs", "problems" ] def system_out (cmdstr) : retlist = [ ] fp = os.popen(cmdstr) while 1: s = fp.readline( ) if not s : break retlist.append(s) fp.close( ) return retlist # main( ) for arg in sys.argv : #print string.split(arg, " \t./") files = system_out("locate " + arg + " | grep -w " + arg); for path in files : #print path # Special case for anything with "man", "doc", or "info" in the path: if (string.find(path, "/man") >= 0) \ or (string.find(path, "/doc") >= 0) \ or (string.find(path, "/info") >= 0) : print path, ) continue # Now see if it matches any of the docfilenames: base = os.path.basename(path) for nam in docfilenames : if base = = "" : continue # Non full word search would use this: : # Full-word-search: # Make a regexp to search for nam as full-word only pat = "^" + nam + "$" if (re.compile(nam).search(base, 1)) : print path, base = "" continue