6.1 Objective 1: Use and Manage Local System Documentation

Each Linux system is configured out of the box with extensive documentation from programmers, authors, and other contributors. Some of this documentation is formal while some is quite informal. Combined, this documentation offers a comprehensive body of knowledge for Linux users.

6.1.1 Text and Paging

At a fundamental level, documents stored electronically may be encoded in a bewildering variety of formats. For example, most word processors use proprietary file formats to store characters, text formatting, and printing control languages such as Adobe PostScript to manage printer hardware. While these relatively modern features can be found on Linux systems, most of the documents and configuration files are in plain text.

In the context of Linux systems, "plain text" means files or streams of both printable characters and control characters. Each is represented using a standard encoding scheme, such as the American Standard Code for Information Interchange (ASCII) and its relatives. Text files are most conveniently viewed using a paging program.

6.1.1.1 Paging programs

The most popular pager for Unix systems was once the more command, so named because it gave you "one more screen." more exists on Linux systems and probably every recent Unix variant; however, more is somewhat limited in its capability. The less command (so named because, of course, "less is more!") is more commonly used. The less command is a full-featured text pager that emulates more but offers an extended set of capabilities.

One particularly important feature of less is that it does not read all of its input before starting, which makes it faster for large input than an editor. less also offers many useful features and is available for almost every operating environment.

less begins execution by first examining the environment in which it is running. It needs to know some things about the terminal (or window) in which its output will be displayed. Once that's known, less formats the text and displays the first screen's output. The last line of the screen is reserved for user interaction with the program. less will display a colon on the first column of the last line and leave the cursor there. This colon is a command prompt, awaiting command input from the user. Most commands to less are single-character entries, and less will act upon them immediately and without a subsequent carriage return (this is known as cbreakmode). The most basic command to less (and more) is a single space, which instructs the pager to move ahead in the text by one screen. Table 6-1 lists commonly used less commands.

Table 6-1. Commonly Used less Commands

Command	Description
Space	Scroll forward one screen.
D	Scroll forward one-half screen.
Return	Scroll forward one line.
B	Scroll backward one screen.
U	Scroll backward one-half screen.
Y	Scroll backward one line.
g	Go to the beginning of the text (could be slow with large amounts of text).
G	Go to the end of the text (could be slow with large amounts of text).
/pattern	Search forward for pattern, which can be a regular expression.
?pattern	Search backward for pattern, which can be a regular expression.
H	Display a help screen.
:n	Display next file from command line (two-character command).
:p	Display previous file from command line (two-character command).

less has a rich command set, and its behavior can be modified as needed for your use. See the less manpage for further details.

Pagers are important to the topic of manpages because they provide the user with an interface to the man program. For each man command you enter, the man program works quietly to locate a manual page (or pages) to match your query, then displays the result using a pager.

6.1.2 The man Facility

Traditional computer manuals covered everything from physical maintenance to programming libraries. While the books were convenient, many users didn't always want to dig through printed documentation. So, as space became available, the man (for manual ) facility was created to put the books on the system, allowing users immediate access to the information they needed.

There is a manpage for most commands on your system. There are also manpages for important files, library functions, shells, languages, devices, and other features. The man facility is to your system what a dictionary is to your written language. That is, nearly everything is defined in exacting detail, but you probably need to know in advance just what you're looking for. Manpages are generally written for those who already have an idea of what the item in question does, but regardless of your level of experience, manpages are invaluable.

Syntax

man [options] [section] command

Description

Format and display manpages from manual section on the topic of command using a pager. If section is omitted, the first manpage found is displayed.

Frequently used options

-a

Normally, man exits after displaying a single manpage. The -a option instructs man to display all manpages that match name, in a sequential fashion.

-d

Display debugging information.

-w

Print the locations of manpages instead of displaying them.

Example 1

View a manpage for mkfifo:

$ man mkfifo
...

Results for the first manpage found are scrolled on the screen using a pager.

Example 2

Determine what manpages are available for mkfifo:

$ man -wa mkfifo
/usr/man/man1/mkfifo.1
/usr/man/man3/mkfifo.3

This shows that two manpages are available, one in section 1 (mkfifo.1) of the manual and another in section 3 (mkfifo.3). See the next section for a description of manpage sections.

Example 3

Display the mkfifo manpage from manual section 3:

$ man 3 mkfifo

6.1.2.1 Manual sections

Manpages are grouped into sections, and there are times when you should know the appropriate section in which to search for an item. For example, if you were interested in the mkfifo C-language function rather than the command, you must tell the man program to search the section on library functions (in this case, section 3, Linux Programmer's Manual ):

$ man 3 mkfifo

An alternative would be to have the man program search all manual sections:

$ man -a mkfifo

The first example returns the mkfifo(3) manpage regarding the library function. The second returns pages for both the command and the function. In this case, the pages are delivered separately; terminating the pager on the first manpage with Ctrl-C causes the second to be displayed.

Manual sections are numbered 1 through 9 and N. They are searched in the order shown in Table 6-2 by default.

Table 6-2. Man Sections and Search Order

Section	Description
1	Executable programs or shell commands
8	System administration commands
2	System calls
3	Library calls
4	Special files (usually found in /dev)
5	File formats and conventions
6	Games (sorry, no Quake here!)
7	Macro packages and conventions
9	Kernel routines
N	Tcl/Tk commands

6.1.2.2 Manpage format

Most manpages are presented in a concise format with information grouped under well-known standard headings such as those shown in Table 6-3. Other manpage headings depend on the context of the individual manpage.

Table 6-3. Standard Manpage Headings

Heading	Description
Name	The name of the item, along with a description
Synopsis	A complete description of syntax or usage
Description	A brief description of the item
Options	Detailed information on each command-line option (for commands)
Return values	Information on function return values (for programming references)
See also	A list of related items that may be helpful
Bugs	Descriptions of unusual program behavior or known defects
Files	A list of important files related to the item, such as configuration files
Copying or Copyright	A description of how the item is to be distributed or protected
Authors	A list of those who are responsible for the item

6.1.2.3 man mechanics

System manpages are stored in /usr/man and elsewhere. At any time, the manual pages available to the man command are contained within directories configured in your man configuration file, /etc/man.config. This file contains directives to the man, telling it where to search for pages (the MANPATH directive), the paging program to use (PAGER), and many others. This file essentially controls how man works on your system. To observe this, use the debug (-d) option to man to watch as it constructs a manpath (a directory search list) and prepares to display your selection:

$ man -d mkfifo

6.1.3 Information in /usr/doc

Manpages are particularly useful when you know what you're looking for, or at least have some good leads on how to find it. However, they are not tutorial in nature, nor do they often describe overall concepts. Fortunately, individuals in the Linux world not only contribute their programming skills, but many also generate excellent tutorial documents to assist others with features, procedures, or common problems. Many of these documents end up as HOWTO guides, FAQs (lists of Frequently Asked Questions), README files, or even exhaustive user manuals. These documents are often part of the source distribution of a particular program, and while valuable, don't fit elsewhere on the Linux system and are deposited in /usr/doc. Most of these files are ASCII text, which can be viewed with a pager, such as less, or with your favorite text editor. Some documents may be written in HTML for use with your web browser. Some text files may also be compressed with the gzip program, and thus have the .gz extension. The handy zless utility allows you to page these files without first decompressing them.

The contents of /usr/doc can be classified broadly into these categories:

Package-related

These documents are typically useful snippets of information included with program source distributions. Packages offering this type of documentation will install a subdirectory in /usr/doc that contains the documentation files and may be specific to a version of the package.

For example, /usr/doc/tcsh-6.08.00 contains the following files related to the tcsh shell, Version 6.08.00:

FAQ

A list of frequently asked questions about tcsh

NewThings

Aptly named, contains descriptions of new features in this release (and previous releases) of tcsh

Complete.tcsh

An interesting portion of source code from tcsh

eight-bit.txt

A description of ways to use 8-bit (international) characters with tcsh

In this example, no general documentation is included in /usr/doc, though this particular command has a thorough manpage. Of the files available, the FAQ and perhaps the version information file (see Section 6.1.4) will be of interest to most users.

Frequently Asked Questions

A Frequently Asked Questions (FAQ) page contains detailed information in a Q&A format. FAQ topics can range from simple questions such as "What is Linux," to more specific questions about how to configure or troubleshoot a particular program. While FAQs may be found for specific packages in a /usr/doc package directory (as with tcsh), a number of important FAQs reside in /usr/doc/FAQ. FAQ lists are generated in many different formats. Inside /usr/doc/FAQ are subdirectories for these formats, including:

html

HTML files suitable for viewing with a web browser

ps

PostScript files, suitable for viewing with a reader such as Ghostscript or in a printer-friendly format

txt

Plain text files

HOWTO documents

A HOWTO document details information on completing a particular task. They can be as simple as a narrative describing one individual's success in configuring some software under Linux, or they can be a complete author's description. For example, /usr/doc/HOWTO/Printing-HOWTO (a text file) tells you how to configure a printer under Linux. HOWTOs often serve as reference material for new administrators working with printers. Like FAQs, many HOWTO documents are stored in their own directory under /usr/doc/HOWTO. Some smaller HOWTO documents are titled mini-HOWTOs, which are generally of limited scope and can be found in /usr/doc/HOWTO/mini.

6.1.4 Info Pages

Among the many contributions from the Free Software Foundation (http://www.fsf.org/) is the GNU documentation format called info. Info pages are part of a system called Texinfo, which uses a single source file to display information on screen and on paper. Texinfo is hypertext and creates a browser-like interface on a terminal or terminal window (Emacs users will recognize the menu system as the editor's online help). For GNU software, Texinfo is the definitive documentation mechanism. Texinfo can be viewed by running the infocommand. For example, the Texinfo document on mkfifo can be displayed using the following command:

$ info mkfifo

The result will be a display similar to the example in Figure 6-1.

Figure 6-1. Info display in a terminal window

Basic navigation commands for the info system are listed in Table 6-4.

Table 6-4. Info Commands

Command	Description
Tab	Move among hypertext links.
Enter	Follow hypertext links.
d	Return to the top (directory node) of the menu.
?	List all info commands.
p and n	Move to previous and next pages, respectively.
u	Move up one level in the Texinfo hierarchy.
q	Terminate the system.
h	Show a primer for first-time users.
/string	Enter a string.
/pattern	Search forward for pattern, which can be a regular expression.

Manpages and other types of system documentation are packaged and installed by default with most Linux distributions. For example, this means that both the manpage and executable program for wc are contained in the textutils package. Other documentation, such as LDP guides and HOWTOs, may be contained in standalone packages, depending on the distribution.

6.1.5 Oddities

Occasionally you'll come across an application or program that provides excellent documentation but places it in nonstandard locations. Perl is one such program. Perl's online documentation is very thorough and detailed. However, Perl uses the man facility to document not just the syntax and options for the perl program, but just about anything you'd want to know about the Perl interpreter and language. By adding a large number of man targets, the Perl distribution documents its function library, its FAQ, data structures, syntax, and many others. This extensive use of man ensures that the Perl documentation will be available to anyone who needs it. However, despite Perl's ubiquitous presence on the Linux system, it is not mentioned in /usr/doc. It's worth remembering that documentation for the concept you're after is probably available, but you may need to check multiple sources.

6.1.6 Using the locate Command

While the availability of these various sources of information is reassuring, finding what you want when time is limited can sometimes be frustrating. To assist, most Linux systems will periodically create a database of files on the system that you can query using the locate command. If the database is configured correctly, such a query returns all instances of the command or command fragment you enter. For example, entering a locate request for the gzip utility, using only a fragment of "gzip," yields something similar to this:

$ locate gzi
/usr/bin/gzip
/usr/doc/gzip-1.2.4
/usr/doc/gzip-1.2.4/NEWS
/usr/doc/gzip-1.2.4/README
/usr/info/gzip.info.gz
/usr/man/man1/gzip.1
/bin/gzip

These results can be extremely helpful, as they tell you:

• The only item matching "gzi " is gzip, because nothing other than gzip was found.

• Exactly where gzip is located in the filesystem ( /bin/gzip, and its symbolic link /usr/bin/gzip).

• That there is a package directory under /usr/doc ( /usr/doc/gzip-1.2.4 ).

• That there are both man and info pages for gzip.

• gzip is a user command, because its manpage is found in section 1 ( /usr/man/man1).

Typically, to proceed from this point with researching gzip, you would use info gzip or perhaps man gzip.

locate is dependent on a database created by the updatedb command. This utility searches the filesystem and constructs the index used by locate. Depending on your system's configuration, this update could be set to occur periodically at night when your system might be off. The cron facility is used to schedule these updates. Many routine tasks such as the use of updatedb will be placed in special files under the /etc directory, grouped for their frequency. The /etc/crontab file contains instructions for cron to execute the commands in these special files on a routine basis. In this case, your locate database may be stale. To refresh the database, you can run updatedb manually or leave your system running overnight to execute periodic updates. See Section 4.8 for more on locate and updatedb.