Making manpages work for you

Once upon a time, Linux was a hacker's operating system, in the sense that only the most dedicated and enthusiastic computer geeks had the motivation and skill to make sense of it and make it work for them. That has been changing for several years, and now it's entirely possible for casual computer users to make the transition from Microsoft Windows without undue difficulty. In fact, it is possible now for someone to make the switch to Linux and never even have to use the command line interface. GUI utilities and configuration tools are available from installation onward, and in the case of some operations -- like using the graphical interfaces for software management programs -- basic system functionality is made even easier to use than equivalent tasks in Microsoft Windows.

To really understand Linux, to be more than a mere end user, you should still learn to navigate the command line interface. While it is getting ever easier to configure common system resources and behaviors from GUI tools, you can still get things done faster, in finer-grained detail and with more certainty, from the shell. The shell, a command interpreter application that gives you the familiar Linux command prompt, can be cryptic to newcomers. Learning to use it can be a daunting task when you don't know where to begin, but the tools you need to quickly adopt the necessary skills are actually quite simple to use. The only real problem is that it can be difficult to figure out how to get started.

One of the most important skills to have for navigating the command line in Linux is the ability to use manpages. The term "manpage", also sometimes spelled "man page", is short for "manual page". It refers to the online UNIX "manual", the traditional and most commonly available form of electronic documentation included with UNIX-based operating systems. They are often the subject of complaints for new Linux users who are used to GUI help systems and are not accustomed to using the keyboard to navigate through documentation, but the truth of the matter is that manpages are incredibly easy to use, and an indispensable resource. When using a Linux distribution that has very comprehensive manpage support, such as Debian GNU/Linux, manpages can become even more helpful than usual, and you might be surprised at the wide range of subject matter covered by manpage documentation on such a system.

Learn to take advantage of manpages, and you'll be taking a necessary step on the path from Linux newbie to Linux expert.

Basic use
The basics of manpage use are quite simple. To open a manpage about a particular application, simply enter the command man foo, where "foo" is replaced by the command about which you want information. This is particularly useful for command line utilities, though many GUI applications also have manpages you can read to find out about configuration options and how they are used.

One of the most important things to know about any program with a captive interface, of course, is how to exit it. For many command line tools, the Q key exits the program, and that is true of manpages as well.

There is a pager -- a program used for viewing text a page at a time, in the simplest form of this type of application -- called less. On Linux systems, man will typically make use of less to provide the interface behavior for viewing manpages. Assuming less is installed on your system, you can navigate up and down in a manpage one line at a time by using the up and down arrow keys on your keyboard. The PgUp and PgDn ("Page Up" and "Page Down") keys will allow you to move up and down one page at a time through the manpage as well. Additionally, you can search for a string of text by typing /foo, where "foo" is the text you want to find.

In the unlikely event that less isn't installed, man generally defaults to using more as its pager. In this case, you will have to use a more limited set of commands for navigating your manpage text, but it's not as bad as it might at first seem. The first, and probably most important, command to learn is the H key, which produces a summary of the commands that can be used within the more pager.

As with less, the Q key exits the program, and a forward slash triggers text search. The spacebar, or the D key, allows you to move down one screen's-worth of text at a time, and the B key moves up one screen's-worth of text at a time. The Enter key allows you to move forward one line at a time. More information can be had from the manpage for more (of course), and it's probably a good idea to have a look at that manpage first, and then use the H key to remind yourself when you need it.

All the above works with less as well: less is more, and then some.

For the most part, the important thing in the above to remember are man foo, the H key, the Q key, and the arrows, PgUp and PgDn keys, and possibly the spacebar and Enter key.

Advanced use
There is of course a manpage for man. Simply enter the command man man for more information about how to use it. Unfortunately, man woman returns no useful results.

As the manpage for man will tell you, the UNIX manual that the man command accesses is split up into nine sections on Linux systems, analogous to chapters of the manual as if it were a physical book, as follows:

1. Executable programs or shell commands
2. System calls
3. Library calls
4. Special files
5. File formats and conventions
6. Games
7. Miscellaneous
8. System administration commands
9. Kernel routines

Sections 1 and 7 are probably the most commonly helpful to users, though programmers and sysadmins may also make extensive use of other sections. When invoking the man command without specifying a section, it will default to the lowest-number section if a given term refers to manpages in more than one manual section. When you want to access a manpage from a later section, you specify the section number in the command. For instance, there are manpages for getopt in sections 1 and 3: to access the section 3 manpage for getopt, enter man 3 getopt. For most purposes, however, simply entering the man foo command will give you all the information you need on whatever "foo" happens to be in this case.

Reading manpages
Manpages themselves are broken up into several parts, indicated and organised by heading terms. Most heading terms you will see in manpages are common across different manpages, and will be presented in the same order in each case. Occasionally, a given heading might be omitted because it doesn't apply to the manpage in question, or additional headings may be added for more information about the specific topic you're reading. More rarely, headings may be specific to a given manpage for entertainment purposes -- such as in the manpage for mutt, a Mail User Agent application, whose BUGS heading declares that mutts don't have bugs. Following this incredible statement is a FLEAS heading, describing current known bugs (or fleas) in the software.

The most common headings in manpages are:

|> NAME is for the name of the manpage's subject, usually a command or filename, and a very brief descriptive statement about it.
|> SYNOPSIS includes a summary of the syntax used to invoke the command that is the topic of the manpage.
|> DESCRIPTION explains the subject in more depth, to give the reader a better understanding of it, any uses it may have, and other details that might provide greater overall comprehension.
|> OPTIONS provides an explanation of the available execution options for commands.
|> FILES indicates files that are related to the manpage's topic, such as configuration files.
|> SEE ALSO provides a list of other places to find related information, typically in the form of other manpages with information relevant to the subject of the current manpage.
|> BUGS describes known bugs in the software that is documented in the manpage. Unlike some proprietary software vendors, open source software developers have a tendency to be very forthcoming and descriptive about the bugs in their applications, and as a result the BUGS heading will often provide a surprisingly in-depth discussion of current problems. Some manpages go so far as to list "bugs" such as "too bloated".
|> AUTHOR, or sometimes HISTORY, gives information about who wrote or has contributed to the development of the subject of the manpage. This section often provides contact information for these developers so that you can contact them directly if you wish to congratulate them on a job well-done (or maybe arrange to send money, if you like the software that much). You may also be able to get help directly from the developer, but keep in mind that these are real people with real jobs and real lives who cannot devote all their time to answering questions -- particularly if those questions are easily answered with a Web search.

Finding manpages
Sometimes, you might know what you want to do, but not know what program or file does it. There are two simple ways to solve this problem with manpages:

1. Use related manpages
When you want to know how to do something, or even if something can be done, that relates to something else you're doing, reading a related manpage can be the best way to get the information you seek.

For instance, you may find that you don't always want a full manpage's contents when investigating what a command line utility does. In your search for a means of getting a more summarised description of the program, you might check the manpage for man in search of information on how to find such a summary. Under the SEE ALSO heading, you might run across a reference to the whatis manpage. This leads you to enter man whatis at the shell prompt, and you discover that whatis does what you need. Thus, you find the manpage you really need, but can't find, by way of a manpage you can find, but don't really need.