Categories
Linux

How to Create a Linux Man Page

The command man on Linux is embedded in the muscle memory of every Linux developer and user. It is used by literally everyone; from amateur and novice developers to Linux professionals and experts.

Advertisements

It is used for reading the command line manual page for a Linux command, configuration file, or any other feature. Manual pages are usually installed along with installation of a software in Linux. There is a defined syntax for manual pages, which is parsed by the command.

Let us create a man page for the following bash script I have written:

#!/bin/bash if [ "$1" == "h" ]; then echo "Hello" fi if [ "$1" = "b" ]; then echo "Bye" fi

This script does only two things : It prints “Hello” if option ‘h’ is specified as argument, and it prints “Bye” if option ‘b’ is specified as argument.

Advertisements

Let us create a man page for this program. Use vim or any editor of your choice to create a text file.

vim test.1

The extension ‘.1’ is signifying that this man page is for an executable command. It is not a compulsion but rather a widely followed convention while writing man pages. The manual page for man (man man !) lists the categories:

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 eg /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]

A man page is created using the very old roff markup language. It has commands (read markers) for various titles and sections.

  • .TH – This should be first command in the man file. It is used to specify title heading of the man page.
  • .SH – Section Heading.
  • .B – It is used to display the text next to it in bold.
  • .TP – It is used to display information about an argument (flag) to the command.
  • .BR – It is used to display text in bold and in the normal Roman font.

Following is the man page for my program created using only the above (simple) 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

Save the file by first pressing the ESC key, and then type :wq to save the file and exit the vim console.

Advertisements

Test the man page we just created using the command below:

man ./test.1

For more info on man usage, run man man-pages command in your terminal.

💡 Tip
This is the basic syntax for writing man pages. To make things easier, you could use tools like txt2man convert a file in some markup language format to roff format.