With the advent of the internet, all help is just a search away. Whether it is a very specific usage of a tool or an error code that you may have encountered. Although, it is sometimes easier to have a handy reference to command syntax and usage without having to fire up a web browser and search. Enter man pages. Output from man, gives you a general idea of how a command works and how you can invoke it. If you want to up your geek quotient, why not follow this article and create a cool man page for your script/command-line app?
We will use the example of this script (whatsnew.sh) to write a man page.
This script does nothing other than accept an argument while invocation and echoes this to the user with a “What’s new?” question. If there are no arguments, the user is addressed as a stranger.
We will create a man page that covers what the script does, command usage and of course, information about the author. There are various ways to create a man page (such as perlpod or pandoc), we will cover the groff macro approach
man pages usually contain the following sections (though you may skip some of them if you don’t have any content for that). This is not an exhaustive list, as sections vary by Linux distribution. You could add your own sections too (maybe DONATIONS).
The other sections you may want to add are ERRORS, DIAGNOSTICS, CAVEATS etc.
One last thing before we start writing our man page is a quick introduction to the macro language.
Macro commands usually start with a ‘.’ followed by the command. As I introduce each macro, we will build our final man page
.\” – This is a comment. Add as many as you want for maintainability
./” This is the man documentation for the script
.TH – Overall heading of the man page. You must provide the title and man section this entry belongs to. You can also include information such as date created, date modified etc. (3 optional arguments)
The text “7 May 2018” will appear at the center of the footer section of the man page
.SH – Section heading. This contains one of the section names mentioned earlier
./” This is the man documentation for the script
This format is mandatory, you need the /- to split the script name and what it does Let’s add another section
.SS – Subsection heading
If you wish to split the section into smaller parts, you can use the .SS macro. The format is the same as the Section Heading – .SS SUBSECTION NAME
.TP – Tagged list item
This is usually used to create an explanation for different options. For e.g.,
We do not have any sub-sections or options, so here is the final file for whatsnew
To test how the man page looks like, you can use the groff command.
groff -Tascii -man whatsnew | more
The option -Tascii instructs groff to create the output in ascii format and the -man option lets you display the output like a man page. This way you test and make changes as you see fit before moving your page to the man folder.
Here is the output from our documentation
A confusing nomenclature in man, is the overall man documentation is divided into sections and every time you request man to provide information it takes a page out of the appropriate section and displays it. Therefore, all we have created is a page that needs to be placed in the right section of the man documentation.
There are 8 different sections of man, whose scope varies by OS flavor, but are usually these
We will place our man page into section 1 as we have created an executable shell command
cat whatsnew | gzip > /usr/share/man/man1/whatsnew.1
(If this directory does not exist, type whereis man to get the location of the man pages)
You can now invoke your manual page by typing man whatsnew at the command prompt to get this
