Creating manual pages, or man pages, for your custom scripts and programs in Linux can greatly enhance their accessibility and usability. By providing users with detailed documentation accessible directly from the command line, you ensure that anyone can understand how to use your tools effectively. In this guide, we'll walk through the process of crafting a man page for a simple bash script, using the roff markup language.

Let's consider a straightforward bash script that outputs a greeting based on the argument provided:

#!/bin/bash

if [ "$1" == "h" ]; then
        echo "Hello"
fi
if [ "$1" = "b" ]; then
        echo "Bye"
fi

This script performs two simple actions: it prints "Hello" if the argument 'h' is provided, and it prints "Bye" if the argument 'b' is given.

Step 1: Create a man page for the script by opening a new text file with the '.1' extension using vim or your preferred text editor.

vim test.1

The '.1' extension indicates that the man page is for an executable command. While not mandatory, it's a common convention that helps categorize the manual pages appropriately.

Manual pages are divided into several sections, each designated by a number. According to the manual page for man (man man), the sections are as follows:

   1   Executable programs or shell commands
   2   System calls (functions provided by the kernel)
   3   Library calls (functions within program libraries)
   4   Special files (usually found in /dev)
   5   File formats and conventions (e.g., /etc/passwd)
   6   Games
   7   Miscellaneous (including macro packages and conventions), e.g., man(7), groff(7)
   8   System administration commands (usually only for root)
   9   Kernel routines [Non standard]

The man page is created using the roff markup language, a typesetting system that uses specific commands to format the text. Here are some basic roff commands used in man pages:

  • .TH – Sets the title of the man page; it should be the first command in the file.
  • .SH – Denotes a section heading.
  • .B – Formats the following text in bold.
  • .TP – Begins a paragraph with a hanging tag; useful for listing options.
  • .BR – Formats text in bold and then switches back to the normal font.

Below is the content of the man page for our script, utilizing these roff commands:

.TH test.sh 1
.SH NAME
test.sh \- Print Hello or Bye 
.SH SYNOPSIS
.B test.sh
[ h ]
[ b ]
.SH DESCRIPTION
.B test.sh
This is a sample script which does only 2 things. It either prints "Hello" if argument is 'h' or it prints "Bye" if argument is 'b'
.SH OPTIONS
.TP
.BR h
Print Hello
.TP
.BR b 
Print Bye

Step 2: Save the file and exit the editor. In vim, press ESC, then type :wq to write the file and quit.

Step 3: Test the new man page by running the following command in your terminal:

man ./test.1

For more details on creating and using man pages, you can consult the manual pages themselves by running man man-pages in your terminal.

💡 Tip
Writing man pages manually can be tedious. To simplify the process, you might consider using tools like txt2man, which can convert text files in other markup formats to the roff format required for man pages.

By following these steps, you can create custom man pages for your scripts, enhancing their usability and providing users with convenient access to documentation directly from the command line.