Create a MAN page for your own program or script with Pandoc

A MAN page is documentation for a software program or script, created in the groff typesetting system. Ever tried writing a MAN page? I bet you thought to yourself: “Yeez, there’s got to be an easier way to do this”. Luckily, there is. In this tutorial, I’ll show you how to write a MAN page comfortably in Markdown. Then we’ll use Pandoc to create the actual MAN page for your program or script, properly formatted in the groff typesetting system.

Background

On Linux, each program installed by your distribution’s package manager is required to include a MAN page. A MAN page documents a software program or script and is created in the groff typesetting system. Why is this a good thing? Well, it means that for each program on your Linux system, you can simply open up your terminal and type: man [PROGRAM NAME] to view detailed information about the program. It typically includes:

• A brief description of the program.
• The available command line options and what they mean.
• Example usage of the program.
• The name of the author(s).
• Links for additional information and bug reporting.

Thanks to MAN pages, you can quickly access information about a program. No need for an Internet connection and online search engines.

How to read a MAN page

Let’s say you found instructions in a tutorial somewhere to run a specific command. You hesitate to just copy-paste the command in your terminal and you’d rather find out more first. For example the command:

rm -rf wordpress/

In this case you type man rm in your terminal:

Quickly you learn that the command rm -rf wordpress/ would remove the wordpress directory, including all its contents (recursive) and without any further confirmation prompts (force).

While reading a MAN page, you can scroll up and down with the PAGE UP and PAGE DOWN keys, respectively. Pressing the q key closes the MAN page.

Goal of this tutorial

Did you develop your own program or script and would like to share it with other Linux users? In this case you should seriously consider writing a MAN page for it and distributing it with your program. Especially if your goal is to have the program packaged as a DEB or RPM package. That opens up the path for getting your program directly included in the package repository of popular Linux distributions.

I still remember the first time I needed to create a MAN page for a Python script I developed. After learning the intricate syntax of the groff typesetting system, I kept thinking to myself: “Man, there has to be an easier way to do this”. No pun intended. Luckily, I found out that you can actually create a MAN page for your own program of script, comfortably in Markdown format. With the help of the versatile Pandoc program, you can convert it to groff to create your MAN page.

In this article, I’ll teach you how to create a MAN page for your own program or script. We’ll do the actual writing in Markdown and then use Pandoc to convert it to an actual MAN page. I’ll also show you how to preview the MAN page for your program or script, after you created it. For completion purposes, I’ll include instructions on how to install the MAN page on your Linux system. Although, your distribution’s package manager normally takes care of this for you. This assumes that you plan on packaging your software as a DEB and/or RPM package.

What do you need

It goes without saying that you’ll need a Linux PC to work through this tutorial. You can use your Linux distribution of choice. Ideally with a desktop environment installed to work in a graphical text editor. However, that’s optional as you can also work completely in the terminal with the Nano text editor.

We plan on converting our Markdown file to a MAN page with Pandoc. Therefore you should install Pandoc on your system:

• Debian/Ubuntu: sudo apt install pandoc
• Fedora: sudo dnf install pandoc
• openSUSE: sudo zypper install pandoc

Other than that, I assume you have a basic understanding of the Markdown format. You can still following along with this tutorial though, if you never heard of Markdown before.

Python script to write a MAN page for

Since we intend to create a MAN page for our own program or script, it would help if we actually have a program or script. For this reason, I wrote a short and simple Hello world type Python script:

#!/usr/bin/env python3
"""
Hello world type program meant as a reference to show how to create a MAN page for your
own program or script, written in Markdown and converted with Pandoc.
"""
__docformat__ = 'reStructuredText'

import argparse


def main():
    """
    Entry point into the program.
    """
    # Create command line parameter parser object.
    parser = argparse.ArgumentParser(description="Hello world type program for greeting someone.")
    # Add optional command line parameters.
    parser.add_argument('-n', action='store', dest='user_name', default='world',
                        help='Name of the person to say hello to')
    # Perform actual command line parameter parsing.
    args = parser.parse_args()
    # Display greeting
    print('Hello, ' + args.user_name + '!')


if __name__ == '__main__':
    exit(main())

Create a directory called ManPageDemo inside your home directory. Then go ahead and copy the contents of this Hello world Python script into a text file. Save the text file as hello.py inside the ManPageDemo directory. Now we just need to flag the Python script as executable by running this command:

chmod +x ~/ManPageDemo/hello.py

To run this Python script, open up your terminal in the ManPageDemo directory and run the command:

./helly.py

The Python script accepts two parameters: -n to specify a name and -h to display help info:

With the example Python script in place, we can proceed with the creation of the MAN page for this script.

Create the MAN page for the script with Pandoc

Together we’ll create a MAN page for our Python script in this section. We’ll start by setting up the framework of our Markdown file and then add sections step-by-step.

The filename of a MAN page should always be:

[PROGRAM NAME].[SECTION NUMBER]

Our MAN page documents an executable program or script and therefore the section number should be “1”. For an overview of all available section numbers, you can actually view the MAN page of the man command itself. Note that it also includes a listing of conventional section names typically present in a MAN page:

man man

So in our case the filename for our MAN page should be hello.1. However, this is for the final groff formatted MAN page. We plan on writing our MAN page in Markdown, so a good filename for our MAN page framework would be hello.1.md.

MAN page framework in Markdown

Start by creating an empty text file in the ManPageDemo directory with the filename hello.1.md. Next, open it with your preferred text editor and copy-paste the following text into it:

---
title: HELLO
section: 1
header: User Manual
footer: hello 1.0.0
date: January 13, 2021
---

The text between the --- lines is called frontmatter and allows us to embed meta-data into the Markdown file. When writing MAN pages in Markdown, this frontmatter declares variables (title, section, header, footer, date) for configuring the MAN page. I understand that this might sound vague, so let me show you what I mean with this.

Save the hello.1.md file and open up a terminal in the same directory as this file. Next, we’ll use Pandoc to convert our Markdown formatted MAN page framework, to an actual groff MAN page:

pandoc hello.1.md -s -t man -o hello.1

You just created your first MAN page! Although an empty one with filename hello.1. Run the following command to view the MAN page:

man -l hello.1

The red colored text and lines I added, show you how the frontmatter variables relate to the layout of the MAN page. Feel free to play around with changing the frontmatter variables in hello.1.md and viewing the changes in the MAN page. Just make sure to save the hello.1.md file and convert it again with the Pandoc command, each time you made changes. In the following subsections, we’ll add actual content to our empty MAN page.

Adding the NAME, SYNOPSIS and DESCRIPTION sections

The first three sections in a MAN page are always called NAME, SYNOPSIS and DESCRIPTION. Open up the hello.1.md file in your text editor. Add the following text right after the frontmatter section:

# NAME
hello - Hello world type program for greeting someone.

# SYNOPSIS
**hello** [*OPTION*]...

# DESCRIPTION
**hello** is a simply Python script meant as a reference to show how to create a MAN
page for your own program or script, written in Markdown and converted with Pandoc.

The NAME section lists the script name, followed by a one-line summary of the script. The SYNOPSIS section describes the format of running the program. This will probably always be the same as shown in the example above. The DESCRIPTION section contains a full description of the script.

Let’s find out what our MAN page looks like now. Save the hello.1.md file and create the MAN page for our script by running:

pandoc hello.1.md -s -t man -o hello.1

Then preview its current state with:

man -l hello.1

Adding the OPTIONS section

The OPTIONS section explains the command line arguments that the script accepts. In the case of our script:

• The -n argument for specifying the name of the person to greet.
• The -h argument for displaying the program’s help information.

To add an argument description you enter the argument itself on the first line, surrounded by double asterisks to format it as bold. Then on the next line you first enter a colon, followed by a space and then the description of the argument. The colon takes care of properly aligning the argument description in the MAN page.

For our script, continue by adding the following text at the end of the hello.1.md file:

# OPTIONS
**-h** 
: display help message

**-n** 
: name of the person to say hello to

Remember that at any point you can preview the MAN page. You just run the Pandoc command again to create the MAN page for the script:

pandoc hello.1.md -s -t man -o hello.1

Afterwards you can open the created MAN page with command:

man -l hello.1

Adding the EXAMPLES section

The EXAMPLES section contains one or more examples to further explain how to run the script. Its format resembles that of a command line argument description, as found in the OPTIONS section. Here’s what the EXAMPLES section could look like for our script:

# EXAMPLES
**hello -n Joe**
: Displays "Hello, Joe!" and then exits.

Once you entered this text at the end of the hello.1.md file, feel free to preview it again, as explained before.

Adding additional sections

At this point we added all the common sections that you normally encounter in a MAN page. There are additional sections that you can add. You can find their names in the MAN page of the actual man command as shown earlier on in the article:

• CONFIGURATION
• EXIT STATUS
• RETURN VALUE
• ERRORS
• ENVIRONMENT
• FILES
• VERSIONS
• CONFORMING TO
• NOTES
• BUGS
• AUTHORS
• SEE ALSO

For demonstration purposes, we can add the AUTHORS, BUGS and SEE ALSO sections for our script. Add the following text at the end of the hello.1.md file:

# AUTHORS
Written by PragmaticLinux.

# BUGS
Submit bug reports online at: <https://github.com/pragmaticlinuxblog/pandocmanpage/issues>

# SEE ALSO
Full documentation and sources at: <https://github.com/pragmaticlinuxblog/pandocmanpage>

View the completed MAN page

Alright, at this point we completed writing the MAN page in the Markdown format. Let’s create the final groff formated MAN page with Pandoc and look at what we concocted:

pandoc hello.1.md -s -t man -o hello.1

And to view the MAN page we created for our script:

man -l hello.1

Not bad for our first MAN page!

Note that I added both the initial helly.py Python script and the hello.1.md Markdown file for the MAN page to a GitHub repository. You can refer to it, in case some part of this tutorial didn’t quite work out. More importantly, you can use the hello.1.md file as a starting point, whenever you need to create a MAN page for your own program or script.

Install the MAN page on your Linux system

By now, you learned all there is to know about writing your own MAN pages. What doesn’t yet work is opening the MAN page, as you would normally do with command:

man hello

This has a simple reason: we haven’t actually installed the MAN page on our system. I’ll cover the installation of a MAN page in this last section of the tutorial.

Keep in mind that the package manager normally installs software on a Linux system. So you would first create a DEB or RPM package for your program or script. Once it is packaged, you install it with your distribution’s package manager, such as: apt, dnf or zypper. The person packaging your program or script usually takes care of the MAN page installation.

Of course you can also manually install a program or script. In this scenario you would install the MAN page manually as well. I’ll outline this procedure for your hello.py Python script here.

Script and MAN page installation

We’ll kick off by installing our hello.py Python script onto our Linux system. That way every user can run it, simply by typing the hello command:

sudo cp ~/ManPageDemo/hello.py /usr/bin/hello

Although optional, before installing a MAN page you should compress it with Gzip. This keeps all MAN pages nice and small. Run the following command to compress our hello.1 MAN page into a GZ archive called hello.1.gz:

gzip ~/ManPageDemo/hello.1

Now we can copy the MAN page for our script to the directory where all MAN pages for programs and scripts reside:

sudo cp ~/ManPageDemo/hello.1.gz /usr/share/man/man1/

As a final step we update MAN’s internal database:

sudo mandb

Every user on your Linux system can now view the MAN page, by typing man hello in the terminal.

Script and MAN page removal

Once you completed the tutorial, you probably do not want to keep the hello program and its MAN page installed on your system. Run these commands for removal:

sudo rm /usr/bin/hello

sudo rm /usr/share/man/man1/hello.1.gz

sudo mandb

Wrap up

After working your way through this hands-on article, you now know how to create a MAN page for your own program or script. Instead of writing the MAN page in the somewhat cryptic groff format, we used the much easier to learn and use Markdown format.

The versatile Pandoc utility program can convert your Markdown formatted MAN page, into a properly groff formatted MAN page. The command syntax for this:

pandoc [INPUT FILE] -s -t man -o [OUTPUT FILE]

In our example:

pandoc hello.1.md -s -t man -o hello.1

To preview the created MAN page for our hello.py Python script you can load and view the MAN page from a local file with command:

man -l [MAN PAGE FILE]

For our MAN page:

man -l hello.1

You can access all the files created in this tutorial in this GitHub repository. Feel free to bookmark it, because you can use these files as a starting point, whenever you need to create a MAN page for your own program or script.