The man Pages
There’s a kernel of truth in the old Unix joke, “the only command you need to know is man.” The man pages contain a wealth of knowledge, and they should be the first place you turn when you want to learn about a command.
Providing a man page for a utility or command you’ve written elevates it from a useful piece of code to a fully-formed Linux package. People expect a man page to be provided for a program that’s been written for Linux. If you’re natively supporting Linux, a man page is mandatory if you want your program to be taken seriously.
Historically the man pages have been written using a set of formatting macros. When you call upon man to open a page, it calls groff to read the file and generate formatted output, according to the macros in the file. The output is piped into less, and then displayed for you.
Unless you create man pages frequently, writing one and manually inserting the macros is hard work. The act of creating a man page that parses correctly and looks right can overtake your aim to provide a concise, yet thorough, description of your command.
You should be concentrating on your content, not battling an obscure set of macros.
RELATED: How to Use Linux’s man Command: Hidden Secrets and Basics
pandoc to the Rescue
The pandoc program reads markdown files and generates new ones in about 40 different markup languages and document formats, including that of the man page. It totally transforms the man page writing process so you don’t have to wrestle with hieroglyphics.
To get started, you can install pandoc on Ubuntu with this command:
On Fedora, the command you need is the following:
On Manjaro, type:
RELATED: How to Use pandoc to Convert Files on the Linux Command Line
Sections of a man Page
man pages contain sections that follow a standard naming convention. The sections your man page needs are dictated by the sophistication of the command you’re describing.
At a minimum, most man pages contain these sections:
Name: The name of the command and a pithy one-liner that describes its function. Synopsis: A terse description of the invocations someone can use to launch the program. These show the types of accepted command-line parameters. Description: A description of the command or function. Options: A list of command-line options, and what they do. Examples: Some examples of common usage. Exit Values: The possible return codes and their meanings. Bugs: A list of known bugs and quirks. Sometimes, this is supplemented with (or replaced by) a link to the issue tracker for the project. Author: The person or people who wrote the command. Copyright: Your copyright message. These also usually include the type of license under which the program is released.
If you look through some of the more complicated man pages, you’ll see there are many other sections, as well. For example, try man man. You don’t have to include them all, though—just those you really need. man pages are no place for wordiness.
Some other sections you’ll see reasonably frequently are:
See Also: Other commands related to the subject matter some would find useful or relevant. Files: A list of files included in the package. Caveats: Other points to know or watch out for. History: A change history for the command.
Sections of the Manual
The Linux manual is made up of all the man pages, which is then split into these numbered sections:
Executable programs: Or, shell commands. System calls: Functions provided by the kernel. Library calls: Functions within program libraries. Special files. File formats and conventions: For example, “/etc/passwd”. Games. Miscellaneous: Macro packages and conventions, such as groff. System administration commands: Usually reserved for root. Kernel routines: Not usually installed by default.
Every man page must indicate to which section it belongs, and it must also be stored in the appropriate location for that section, as we’ll see later on. The man pages for commands and utilities belong in section one.
The Format of a man Page
The groff macro format is not easy to visually parse. In contrast, markdown is a breeze.
Below is a man page in groff.
The same page is shown below in markdown.
Front Matter
The first three lines form something called front matter. These must all start with a percentage sign (%), with no leading spaces but one afterward, followed by:
The first line: Contains the name of the command, followed by the manual section in parentheses, with no spaces. The name becomes the left and right sections of the man page header. By convention, the command name is in uppercase, although you’ll find plenty that aren’t. Anything that follows the command name and manual section number becomes the left section of the footer. It’s convenient to use this for the software version number. The second line: The name(s) of the author(s). These are displayed in an automatically-generated authors section of the man page. You don’t have to add an “Authors” section—just include at least one name here. The third line: The date, which also becomes the center part of the footer.
Name
Sections are indicated by lines that start with a number sign (#), which is the markup that indicates a header in markdown. The number sign (#) must be the first character on the line, followed by a space.
The name section holds a snappy one-liner that includes the name of the command, a space, a hyphen (-), a space, and then a very short description of what the command does.
Synopsis
The synopsis holds the different formats the command line can take. This command can accept a search pattern or a command-line option. The two asterisks (**) on either side of the command name mean the name will be displayed in bold on the man page. A single asterisk (*) on either side of some text causes the man page to display it underlined.
By default, a line break is followed by a blank line. To force a hard break without a blank line, you can use a trailing backslash ().
Description
The description explains what the command or program does. It should cover the important details succinctly. Remember, you’re not writing a user’s guide.
Using two number signs (##) at the start of a line creates a level two heading. You can use these to break your description into smaller chunks.
Options
The options section contains a description of any command-line options that can be used with the command. By convention, these are displayed in bold, so include two asterisks (**) before and after them. Include the text description of the options on the next line and start it with a colon (:), followed by a space.
If the description is short enough, man will display it on the same line as the command-line option. If it’s too long, it’s displayed as an indented paragraph that begins on the line below the command-line option.
Examples
The examples section contains a selection of different command-line formats. Note that we start the description lines with a colon (:), just as we did the options section.
Exit Values
This section lists the return values your command sends back to the calling process. This might be the shell if you called it from the command line, or a script if you launched it from a shell script. We start description lines with a colon (:) in this section, too.
Bugs
The bugs section lists known bugs, gotchas, or quirks people need to know about. For open-source projects, it’s common to include a link here to the project’s issue tracker to check on the status of any bugs or report new ones.
Copyright
The copyright section contains your copyright statement, and, usually, a description of the type of license under which the software is released.
An Efficient Workflow
You can edit your man page in your favorite editor. Most that support syntax highlighting will be aware of markdown and color the text to highlight headings, as well as bold and underline it. That’s great as far as it goes, but you’re not looking at a rendered man page, which is the real proof in the pudding.
Open a terminal window in the directory that contains your markdown file. With it open in your editor, periodically save your file to your hard drive. Each time you do, you can execute the following command in the terminal window:
Once you’ve used this command, you can press the Up arrow to repeat it, and then press Enter.
This command also invokes pandoc on the markdown file (here, it’s called “ms.1.md”):
The -s (standalone) option generates a top-to-bottom complete man page, rather than just some text in man format. The -t (output type) option with the “man” operator tells pandoc to generate its output in man format. We haven’t told pandoc to send its output to a file, so it’ll be sent to stdout.
We’re also piping that output into man with the -l (local file) option. It tells man not to search through the man database looking for the man page. Instead, it should open the named file. If the filename is -, man will take its input from stdin.
What this boils down to is you can save from your editor and press Q to close man if it’s running in the terminal window. Then, you can press the Up arrow, followed by Enter to see a rendered version of your man page, right inside man.
RELATED: What Are stdin, stdout, and stderr on Linux?
Creating Your man Page
After you’ve completed your man page, you need to create a final version of it, and then install it on your system. The following command tells pandoc to generate a man page called “ms.1”:
This follows the convention of naming the man page after the command it describes and appending the manual section number as though it were a file extension.
This creates an “ms.1” file, which is our new man page. Where do we put it? This command will tell us where man searches for man pages:
The results give us the following info:
/usr/share/man: The location of the standard library of man pages. We don’t add pages to this library. /usr/local/share/man: This symbolic link points to “/usr/local/man. ” /usr/local/man: This is where we need to place our new man page.
Note that the different manual sections are contained within their own directories: man1, man2, man3, and so on. If the directory for the section doesn’t exist, we need to create it.
To do so, we type the following:
We then copy the “ms.1” file to the correct directory:
man expects the man pages to be compressed, so we’ll use gzip to compress it:
To make man add the new file to its database, type the following:
That’s it! We can now call our new man page the same as any other by typing:
Our new man page is found and displayed.
It looks just like any other man page, with bold, underlined, and indented text in the appropriate places.
Lines of description that fit next to the option they describe appear on the same line. Lines that are too long to fit appear below the option they describe.
We’ve also automatically generated an “Authors” section. The footer also includes the software version number, date, and command name, as defined in the front matter.
If You Want to . . .
Once pandoc has created your man page, you can also directly edit the file in the groff macro format before moving it to the man page directory, and gzip it.
