Want your new Linux program to look professional? Give it a
man page. We’ll show you the easiest, and fastest, way to do it.
The man Pages
There’s a kernel of truth in the old Unix joke, “the only command you need to know is
man pages contain a wealth of knowledge, and they should be the first place you turn when you want to learn about a command.
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.
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.
pandoc to the Rescue
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:
sudo apt-get install pandoc
On Fedora, the command you need is the following:
sudo dnf install pandoc
On Manjaro, type:
sudo pacman -Syu pandoc
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”.
- Miscellaneous: Macro packages and conventions, such as
- System administration commands: Usually reserved for root.
- Kernel routines: Not usually installed by default.
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
groff macro format is not easy to visually parse. In contrast, markdown is a breeze.
Below is a man page in
The same page is shown below in markdown.
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
manpage 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
manpage. 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.
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.
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 (
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.
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.
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.
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.
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.
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:
pandoc ms.1.md -s -t man | /usr/bin/man -l -
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”):
-s(standalone) option generates a top-to-bottom complete
manpage, rather than just some text in
-t(output type) option with the “man” operator tells
pandocto generate its output in
manformat. We haven’t told
pandocto send its output to a file, so it’ll be sent to
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
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
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”:
pandoc ms.1.md -s -t man -o 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
The results give us the following info:
- /usr/share/man: The location of the standard library of
manpages. 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
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:
sudo mkdir /usr/local/man/man1
We then copy the “ms.1” file to the correct directory:
sudo cp ms.1 /usr/local/man/man1
man expects the
man pages to be compressed, so we’ll use
gzip to compress it:
sudo gzip /usr/local/man/man1/ms.1
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:
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 . . .
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