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.

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.

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.

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.