Of course man pages are written in a format called troff. It’s not overly complicated and something you can easily get used to. But some times you don’t need to know the format to make a few minor changes. I have used this system many times to make notes in man pages (so when/if I have to refer back to them I don’t have to depend upon a fading memory) that aren’t necessary for all users (otherwise I would submit them to the maintainer). Now, after reading this article (and thanks to gmanedit), you will be able to edit your Linux man pages as well.

Installation

As you would expect, installation is simple. All you have to do is follow these steps:

1. Open up your Add/Remove Software utility.
2. Search for “gmanedit” (no quotes).
3. Select gmanedit for installation.
4. Click Apply to install.

There may be some dependencies to meet for the installation. But more than likely you will already have those met. Now, let’s get to using this handy tool.

Usage

Figure 1

In order to edit/save man pages you will have to open up gmanedit with root privileges. So open it up from command line by either first su‘ing to root or using sudo. The command to start is gmanedit. When you open up gmanedit you will see a fairly minimal interface. Although it looks like a standard, basic text editor, there is a bit more under the hood than that. For instance, the man pages you will be editing are typically in the tar.gz form. And by using this tool you do not have to unpack the files, edit the files, and repack the files. You simply open them, edit them, and save them.

The first tiny hiccup you might encounter is that, when you go to open up a man page, you won’t know where to look. Fear not…man pages are housed in /usr/share/man. Within that directory you will see numerous sub-directories. The directories you want to focus on are manX (Where X is a number). The only downfall of this system is that you might have to poke around within those directories to find the man page you need. Once you find the page, and have it open, it will look like that in Figure 1.

Obviously you will see the troff formatting – which might make you want to turn away. But – when you see the standard wording of the man page you might see sections you want/need to change. All you need to do is make your changes and save the man page. Now when you issue the man command your changes will be there.

Final thoughts

At first you might not see the handi-ness of this system, but after you use it for a while you will see how nice it is to be able to put your own personal notes within man pages – or be able to help the maintainers of man pages with issues.

Of course the usefulness of a man page is dictated by the create of said page. Some man pages are an outstanding resource for learning about that particular application. Conversely, some man pages are fairly worthless. This article is not about discerning which man pages are worthwhile and which are not. This article will help you understand how best use the man command so you can make the most of this reference system.

Basic usage

Using the man command is easy. The structure of man is:

man COMMAND_OR_APPLICATION

Where COMMAND_OR_APPLICATION is the command or the application you want to read about. But there are more ways to use the man command. If you issue the command man man you can read the man manpage (would that be a recursive command?).

There aren’t too many useful switches to use with the man command. There is one switch, in particular, that is helpful – the k switch. The -k switch will search the collective man pages for the string you declare. For example, if you want to search all of the man pages for anything containing “net” you could issue:

man -k net

Any man page containing the string “net” will appear as such:

tcpd []              (8)  - access control facility for internet services
tcpdump []           (8)  - dump traffic on a network
telnet []            (1)  - user interface to the TELNET protocol

What man pages contain

All man pages are supposed to follow the structure:

1. Name: The name of the command or function with an included description.
2. Synopsis: This is a description of what the command does or what parameters the function takes (and what header file contains its definition.)
3. Description: A full description of the command or function.
4. Examples: Examples of common usage.
5. See Also: Related commands or functions.

Although it might seem the fastest way to learn about a command is to skip immediately to the Description. This is often not the fastest means of learning a command. Often the Synopsis will give you the structure of the command usage. You need this information to know where the switches and/or options go in the command structure. So make sure you examine the Synopsis first. Once you know how the command works you can jump down tot he description which is where much of the commands switches and options will be explained.

Of course most of the time a man page will only contain the bare bones of the information you need. For some it takes a while to grow accustomed to sifting out the useful information from the man pages.

Final thoughts

Man pages are a great first place to look for information about a Linux/UNIX command/applicaiton or function. Many think the man page is antiquated, but there is still much to be learned from this simple information system. Give the man page a try so the next time someone says “RTFM” you can reply “I did, and I still am not sure what I am doing.” (or better yet “I did and now I know everything I need to know.”)