How to Create Man Pages for Script, Package, Library in Linux

Man pages are super useful resource for every Linux user. They contain an exhaustive list of all options long with syntax and explanation. Adding man pages to your script or package improves its usability and adoption. But have you wondered how to create a man page for your script or module? In this article, we will learn how to create man pages for script, package, library in Linux. You can use these steps on all Linux distributions.

How to Create Man Pages for Script, Package, Library in Linux

Typically, man pages are written using a bunch of formatting macros. When you call man command, it calls groff command which parses the man file for the command and formats its output, which is piped to less command and then displayed to you. It is very tedious process to write formatting macros and can be difficult for first timers.

Luckily, there are many other tools to help you build man pages. We will use pandoc utility for our purpose, which is much easier to use.

Pandoc program reads markdown files and generates formatted output in 40 different markup languages and file formats, including man pages. Pandoc makes it easy to define your man page content using simple markdown files, instead of writing macros.

1. Install Pandoc

Open terminal and run the following command to install pandoc tool.

Ubuntu/Debian

# sudo apt-get install pandoc

Redhat/Fedora/CentOS/SUSE

# sudo dnf install pandoc

2. Sections of Man Pages

Before you proceed to create a man page using pandoc, it is important the different sections of man pages to format it the right way.

Here are the minimum sections a man page must have.

Name: Name of command with one-liner that describes its function.
Synopsis: Short description of the invocations someone can use to launch the program. Syntax of command along with placeholders for options and parameters.
Description: Description of the command or function.
Options: List of command-line options, with explanation
Examples: Some examples of common usage.
Exit Values: Return codes with their meanings.
Bugs: List of known bugs and issues. You can also include links to issue tracker if available.
Author: Person or people who wrote the command.
Copyright: Your copyright message with license information

There are many other sections applicable for a man page but the above ones will be sufficient.

Each man page is classified as one of the following sections in Linux manual.

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.

Each man page must specify the section it belongs to, and be stored in the appropriate location for that section.

3. Create Man Markdown

Each section of man page must be specified after its own # sign at the beginning followed by space. It acts as a section header. Here is a simplified layout of man page. You can type your text below the section header.

# NAME
...

# SYNOPSIS
...

# OPTIONS
...

# EXAMPLES
...

You can also format your text by adding ** on either side of the text, to make it appear in bold in man page. You can add * on either side of text to underline it in man page. Here is a sample of OPTIONS section.

# OPTIONS
**-h**,**--help**
: Displays friendly text message

Using colon(:) above nests the text under the line “-h, –help” instead of under “OPTIONS” by indenting it. Here is how it will look like in man page.

OPTIONS
    -h, --help
         Displays friendly text message.

Of course, there are many other formatting rules available. We have only covered a small subset for our example.

4. Create Man page

Let us say you have stored your above markdown for command ‘ms’ in a file called ms.1.md. Here is the pandoc command to store it in man page ms.1.

$ pandoc ms.1.md -s -t man -o ms.1

Now that we have the man page file, we need to store it in right location. Run manpath command for this purpose.

$ manpath

The result will give you the following information.

/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.

First, we create a separate subfolder man1 for our command. If your command has more than 1 man pages, you can store them in folders man2, man3, .. here.

$ sudo mkdir /usr/local/man/man1

Next, copy ms.1 file created to this folder.

$ sudo cp ms.1 /usr/local/man/man1

You need to compress this file for man command, as it is required.

$ sudo gzip /usr/local/man/man1/ms.1

Run the following command to add the man pages to man database.

$ sudo mandb

That’s it. Now you can get man page for your command ms using the following command.

$ man ms

In this article, we have learnt how to create man page in Linux.

How to Create Man Pages for Script, Package, Library in Linux