Writing a manpage is often looked upon as a very difficult task but this doesn't necessarily need to be the case. I was recently faced with the unpleasant task of needing a manpage for a small Python script I was writing. Although there are some tools that can automate this process or generate manpages from other files, I figured it would just be easier to write the manpage myself and then I would be able to share this knowledge with others who want a quick guide on the process.

Why Write a manpage?

The first question you are likely to ask is simply "why?" Well, if you are a programmer and you have written a program, users will appreciate the ability to quickly look up documentation for the command and find out what command line arguments are supported, etc. If you are not a programmer, you might still find yourself writing a manpage - perhaps you are tasked with maintaining a package or you want to help an upstream project. Debian policy mandates a manpage for any binaries in a package.

What Exactly Is a manpage?

In order to write a manpage, we need to know exactly what a manpage is. Obviously the best way of getting an idea is to take a look at an existing manpage. If you are running Ubuntu (you are running Ubuntu, right?), then you can find manpages for some common commands in /usr/share/man/man1. (I will explain the '1' in a minute.) Inside that folder you will see a lot of files and all of them will end with the extension '.1.gz'. As you would expect, the '.gz' extension indicates that the file is compressed with gzip compression.

Make a copy of one of the files (say, 'unity.1.gz' for example) and place it in a folder you have write access to. If you have a terminal open, try running this command:

cp /usr/share/man/man1/unity.1.gz /tmp ; cd /tmp ; gunzip unity.1.gz

You should end up with a file /tmp/unity.1 which you can open up in your text editor of choice (be it nano or Gedit). This answers the question which we originally asked at the beginning of this section: a manpage consists of a single gzip'ed file with a bunch of strange-looking markup codes inside (not really a technical definition, but definitely something we can understand).

Before we leave this section, I promised to explain the '1' that is appended to the end of the manpage's filename. What does it mean? Well, each manpage has a category it fits under. You can find a list of all categories here. As you can see, the manpage for the unity command is categorized under '1' - which indicates that it is a general command.

What Are the Strange Symbols in the File?

Now that you've opened the file, we can begin examining the contents. The first thing you will notice is a set of commands that begin with a '.' and are followed by a set of letters. These commands (as you might infer) control the formatting of elements in the manpage. The first formatting command is usually '.TH'. What does this command do? Well, this is probably slightly ironic, but the best way to find out is to view the man-pages manpage (no joke!). You can find an online version here.

According to the documentation, '.TH' should be the first command in a manpage and the text following it contains information about the manpage. Each "parameter" that follows the '.TH' needs to be separated by a space. If any of the parameters contains a space in it, you need to wrap that parameter in quotation marks. Here is an example for an imaginary application called "ping-local-server":

.TH ping-local-server 1 "2 November 2011" "" "Linux User's Manual"

There are a couple things to take note of in the example above. First of all, as mentioned before, any of the parameters that contained spaces need to be wrapped in quotation marks. Secondly, to leave a parameter blank, we use empty quotation marks. You can try this out for yourself by sticking that line in a file and using the instructions below to preview it.

Can I Preview My manpage?

Yes, you can easily preview the manpage by using the following command:

man -l <filename>

This will display the specified file and allow you to get an idea of what it looks like with formatting applied. Our example looks something like this:

That Was Neat! Now What?

There is definitely more to writing a manpage than just coming up with a title. Most manpages consist of sections that describe various parts of the application, such as how to invoke the application, what command line parameters are supported, and where to find other related commands. A section begins with '.SH' followed by the name of the section. We'll add a name section to our example:

.TH ping-local-server 1 "2 November 2011" "" "Linux User's Manual"
.SH NAME
ping-local-server \- pings the local loopback interface

We now have our first section in the file which basically just tells the user what the command is. Notice on the third line that the dash is escaped. If you're curious, try previewing the file again. It's starting to take shape now, isn't it?

But What About the Formatting Codes?

We still haven't got into a discussion about formatting codes yet - we'll take a look at them when we write the next section. After the NAME section, it is typical to have a SYNOPSIS section that describes how the command is invoked. If you take a look at the Unity manpage from earlier, you'll notice that some lines begin with '.B', some with '.RI', etc. These are used to format the text that follows them - the formatting is applied only to the remaining text on that line. The '.B' formatting code is used to make text bold, so let's add the following line to the end of our sample file:

.SH SYNOPSIS
.B ping-local-server
[options]

This causes the text "ping-local-server" to be displayed in bold lettering while the text "[options]" is displayed with a normal weight. If you still have the source to the Unity manpage open, you'll notice that the line containing "[options]" begins with '.RI'. What does this do? Well, "RI" is an acronym for Roman / Italic, so the parameters that follow are divided by spaces of alternating Roman and italic lettering. The first parameter will be in Roman (regular) lettering, the second will be italicized (underlined), and so on. If any of the individual parameters contain spaces, simply wrap them in quotation marks.

You can find documentation for the formatting commands by viewing the manpage of the (wait for it...) man command. (You can view it online here.) You will also find the documentation for formatting macros and the like.

That's It?

Yup, that's it. You now know everything there is to know about writing manpages. Well, maybe not everything, but enough to get started. If you are packaging an application for Debian, you can add the manpages to the package by creating a file named <package_name>.manpages in the debian/ folder and inserting the filename of the manpage on the first line.

If you ever require assistance writing a manpage or run into something you weren't expecting, Stack Overflow is an excellent place to ask your question and get some answers.