How to Create a Linux Man Page
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.
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:
For more info on
man usage, run
man man-pages command in your terminal.
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.