Open Source

Managing your man pages

In this Daily Drill Down, Vincent Danen explains how to take advantage of those helpful man pages.


Anyone using Linux, new or old, will have come across the term man pages at a very early point in their Linux adventure. Everybody knows what man pages are—and probably knows how to use them—but some newcomers to Linux will spend a lot of time searching for documentation on their computer or on the Internet without realizing that the answers are right there at their fingertips.

Basically, man pages are documentation for a program. Not all programs have man pages, but the majority of them do. Although man pages aren't the easiest documentation to follow, they are usually very concise and accurate. Man pages are quick-and-dirty manuals (hence the name) for most of your Linux commands and programs. Because of this, they do not explain things easily for the most part, but they do explain them accurately and in detail.

Before looking at your first man page, be warned that they are not the easiest documentation to read. They are written in a very formal and stylized way so that as much information as possible can be crammed into a small space. The writing style often doesn't even resemble standard English. The man pages are meant as quick-reference material, not full-fledged documentation. In this Daily Drill Down, I’ll describe how you can take advantage of man pages.

How man pages are organized
If you’ve never heard of man pages before, try the following at a Linux prompt:
man ls

When you do this, the man page will pop up. Basically, every man page consists of a few core parts that make up the full man page. The first part of the man page is the COMMAND(1) section. This gives the name of the command you have called up; in the previous example, it would say LS(1). The number in parentheses is the man page section. Since some programs have the same name as commands, or programs can behave in different ways, man pages have a distinct section that they are placed into depending on the type of command. User commands are always in section 1, UNIX system calls are in section 2, file formats are in section 5, and system administration commands are in section 8. Typically, these are the man page sections you will be using most often.

If you need something in a certain section, you can specify the section (which is useful for programs or commands with multiple sections) by using:
man 1 ls

This tells man that you want the command ls and that you want section 1 for that command.

The next part of the man page is the NAME section, which gives a quick summary of the command and what it does. Next is the SYNOPSIS section, which gives you the complete syntax of the command in typical Linux form. For example, the SYNOPSIS section for the ls command looks like this:
ls [OPTION] ... [FILES] ...

This illustrates what arguments ls takes on the command line. Now, many people who have never looked at a man page before may become intimidated by this particular section—it can be quite cryptic. To help shed a little light on this section, let’s dissect it. Commands specified in square brackets are groups of commands. For example, something like -[012345] means that you can specify -0, -1, -2, -3, -4, or -5 for command-line options. Not all command groups in brackets are required. For instance, a dozen command groups in square brackets may be listed, but only two of them may be required or wanted. Commands separated with a pipe symbol, like [-W | -w], mean that they can be interchanged. In other words, you can use either command to specify the same thing (in this instance, -W and -w will do the same thing), sometimes with very slight variations (for example, -W will list files, -w will list files in color). Commands not in brackets are necessary on the command line and you will need to include them for the program to work.

The next part is the DESCRIPTION section, which gives a more verbose description of what the command does, and likely an example or two.

The following section, OPTIONS, gives a detailed list of every command-line argument or option that the command can use and what it is used for, as well as a comprehensive description of the command.

The FILES section lists any files that are used by or related to the command. These are usually configuration files or other files that the command relies on.

The SEE ALSO section lists any other related documents or man pages for this command or other commands that are either used with this command or closely related. This section is a good place to find further information on the program if the man page does not provide the information you’re looking for.

The next part is the BUGS section, which is used to list any known bugs in the program or command.

The final section is the AUTHOR section, which lists the author of the program and usually an e-mail address or Web site where you can reach him or her.

Searching man pages
You can search man pages as well. The ability to search is quite useful when you’re looking for a command having to do with something you are trying to accomplish, or when you’re looking for alternate commands that may work better for you than what you are used to. To accomplish this, you can search man pages using keywords. Then, man will search every man page's NAME section for any text that matches your keyword. Remember that the NAME section also contains a brief description, so this will broaden your search a little without making the search extremely slow by having to search every section in every man page. (And you will have many man pages installed on your system to search through!) To search man pages, use the man command with the syntax:
man -k [keyword]

For example:
man -k manual

may return the following:
man (1)       - Format and display the online manual pages
whereis (1) - Locate binary, manual, and or source for the program
xman (1)      - Manual page display program for the X Window System


Compressing man pages
You can compress your man pages as well. Consider the number of programs on your Linux system, and then consider that each program will usually have one or more man pages. You're looking at quite a bit of disk real estate being used. The man command will decompress and display man pages on the fly, which means that it will be relatively transparent to you whether the man pages are compressed or not. Typically, man pages should be compressed in Gzip or Bzip2 format. Some distributions, like Linux Mandrake, usually come with man pages compressed as a de facto standard, so you don’t have to do it yourself. Since man pages are typically stored in the /usr/man directory tree, you can use a simple script to compress all of your man pages quite easily:
#!/bin/sh
count=1
while [ $count -le 9 ]
do
 cd /usr/man/man$count
 list="`ls -1 *.$count`"
for file in $list
do
 bzip2 -9 $file
done
 count=`expr $count + 1`
done


This will go into the man page directories, from /usr/man/man1 to /usr/man/man9, and compress every man page found with Bzip2 compression. If you look in your man page directories now, you will see every man page ending with a .bz2 extension.

Viewing man pages with less and xman
You can use a few commands while viewing man pages. Basically, what man does is translate the raw man page code into something a little more viewable. The raw source of a man page is similar to a raw LaTeX document in that it is filled with codes and commands that control the formatting of the document. The man command translates this raw file into something we can read and understand in a clear, concise format. Then, man takes the output and pipes it into the less utility. The less utility, like more, is similar to the DOS TYPE program or to the UNIX cat program, except less and more provide you with a little more control over what you are viewing.

Of course, less is the more advanced viewer, which is why man uses it instead of more. The less utility will let you search a document using regular expressions or simple pattern matching, as well as allow you to scroll up and down your document. It has some fairly simple commands that let you scroll the man page (or any other document) you are viewing.

The less command uses the [Page Up] and [Page Down] keys to scroll up and down by screens. You can also use the arrow keys to scroll up and down by one line. Pressing the [Enter] key will display the next line, and pressing the Spacebar will display the next screen of text. To exit the viewer, press q or Q, and to get extended help on the keys you can use to view and search your document, press h or H.

At the bottom of the screen you will see the length of the document and where you are in relation to the end of the file. You’ll see something like line 63/163 78%. This tells you that the top line on the screen is line number 63 and that there are 163 lines in the document. It also tells you that the last line on the screen is 78%, which means you have viewed 78 percent of the entire document.

There is also a GUI version of man, called xman. The xman viewer will enable you to view man pages within X Windows. Simply open up a terminal and type:
xman

and the viewer will begin. With the xman viewer, you select man pages by selecting a section and scrolling through the directory. The xman viewer contains two buttons: Options and Sections. Click Sections to view a drop-down list of the ten different sections you can choose from. Just select whichever section you are interested in. The viewer will then display a directory list, and you simply click on whichever man page you wish to view. The xman viewer is relatively straightforward, and it’s a nice viewer for looking at man pages within X Windows without using man in a terminal itself.

The man configuration file
The man configuration file is typically /etc/man.config and has a number of options that can be configured to suit your tastes and system type. Perhaps one of the most important options in this file is the MANPATH keyword. This keyword defines the directories that man will search for man pages when you invoke it.

Let us assume for a moment that you have installed a program like qmail that places all the man pages in a nonstandard directory. For example, qmail installs into the /var/qmail directory tree and places its man pages in the /var/qmail/man directory tree. Obviously, by simply calling man you won't be able to view these man pages because they are not placed in the standard /usr/man or /usr/local/man directory. Simply edit /etc/man.config and add a new MANPATH keyword, as in:
MANPATH /var/qmail/man

Now you will be able to view those qmail man pages without specifying the full pathname to the man page you want to view.

You can specify man page decompression in the configuration file as well. Some distributions may not by default include support for Bzip2 compressed man pages, and you may want to use it because of the higher compression ratio over GZip. To enable support for Bzip2 compressed man pages, insert into your /etc/man.config file:
.bz2   /usr/bin/bzip2 -c -d

To enable support for Gzipped man pages, you would use:
.gz    /bin/gunzip -c

Of course, make sure the absolute paths are correct for your archiver.

Another important section of the configuration file deals with compressing cat pages. A cat page is simply a formatted copy of the corresponding man page saved in a similar cat directory. The reason cat pages exist is to save formatting time if you view a recently viewed man page again. Instead of reformatting the entire man page, man will look to see if there is a corresponding cat page, and if there is, man will use it instead. To compress cat pages to save disk space, use the following keyword directives in /etc/man.config:
COMPRESS/usr/bin/bzip2
COMPRESS_EXT  .bz2

This will compress your cat pages with Bzip2. All cat pages are typically stored in the directory tree. For example, if you recently viewed the man page for man(1), then looked in the /var/catman/cat1 directory, you will see a file called man.1.bz2 if you use Bzip2 compression. This is simply a formatted copy of the /usr/man/man1/man.1.bz2 man page.

Conclusion
Whether you are a programmer, systems administrator, or a user of Linux, man is a very handy system. Although man pages can be somewhat cryptic at times, they are concise and to the point, and will generally help you understand how to use any program, library, or system call. The man page provides the information you need immediately—and provides it in a clear and descriptive format.

The more you use Linux, the more you will come to rely on man pages. They are much handier than books, Web pages, how-to documents, or any other documentation, because they are available at your fingertips at all times. If you have never looked at a man page before, take a look now. You will find that man pages help make Linux much easier to use and understand.

Vincent Danen, a native Canadian in Edmonton, Alberta, has been computing since the age of 10, and he’s been using Linux for nearly two years. Prior to that, he used OS/2 exclusively for approximately four years. Vincent is a firm believer in the philosophy behind the Linux "revolution,” and heattempts to contribute to the Linux causein as many ways as possible—from his FreezerBurn Web site to building and submitting custom RPMs for the Linux Mandrake project. Vincent also has obtained his Linux Administrator certification from BrainBench.He hopes to tackle the RHCE once it can be taken in Canada.

The authors and editors have taken care in preparation of the content contained herein, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for any damages. Always have a verified backup before making any changes.

About Vincent Danen

Vincent Danen works on the Red Hat Security Response Team and lives in Canada. He has been writing about and developing on Linux for over 10 years and is a veteran Mac user.

Editor's Picks