Writing and reading man pages
The Mechanics of Writing man Pages
Man pages are written in a simple markup language using nroff/groff macros (Table 3). Each markup tag begins with a period and is followed by one or two letters. Typically, the markup is placed at the start of a line and continues to be in use until either the next tag or a closing parenthesis – ) – appears. One or two tags comprise pairs of starting and closing tags. Spacing on a line is handled either by tabs or by the markup's macro.
Table 3
Man Markup
| .TH |
[name of program] [section number] [center footer] [left footer] [center header] The title/header of the man page, generally written entirely in uppercase. Always the first line of a man page. |
| .SH |
[text] Section heading. |
| .PP |
Creates a line break. Always use to leave a space, rather than leaving a line blank. |
| ." |
Comment line (for source file). |
| .TP |
Indent the text 2 lines below. |
| .nf |
Start of pre-formatted text. |
| .fi |
End of pre-formatted text. |
| .RS |
Start of a relative margin indent. |
| .RE |
End of a relative margin indent. |
| .B |
Bold weight. |
| .I |
Italics. |
| /-/ |
A dash. |
Compiling and Formatting Man Pages
Man pages are stored as bzip or gzip files. You can prepare a man page in several ways, including Perl's pod2man script. However, most methods use some variant of the troff/groff document formatting systems, which are even older than man in Unix-like systems. These commands are a subject in themselves, but using them to create man pages requires little knowledge.
Write the man page in a text editor or nroff/groff, remembering to spell check. If your editor does not support spell checking, you can copy and paste it to one that does. The first parts of the file name should be the page name, separated by a period from the man section number. As you write, you can check your formatting with the command:
nroff -man FILE | less
When you have finished entering, enter the basic command:
ngroff -man FILE > OUTPUTFILE
Compress the output file with gzip or bzip, and place the compressed file in a directory in the MANPATH environment variable. To access the new file, add it to the man database with mandb -c or, in some distributions, make what is.
You can also convert the output file to Postscript with:
groff -man -Tps FILE > FILE.ps
Similarly, the command to produce a PDF file is
groff -man -Tpdf FILE > FILE.pdf
Another option for PDF conversion is to use the command-line utility ps2pdf to produce the PDF file from the Postscript file.
Converting to HTML is even simpler. With the man2html utility installed, enter:
man2html FILE
The output is an HTML file of the same name in the output file's directory
« Previous 1 2 3 Next »
Buy this article as PDF
Pages: 4
(incl. VAT)
Buy Raspberry Pi Geek
US / Canada
UK / Australia
Related content
-
Writing and reading man pages
Man pages provide essential information but may seem cryptic if you're not familiar with their structure. We explain how they're organized so you can get the most out of them.
-
Installing a customized Raspbian system with Netinstaller
The standard Raspbian is too bulky for some projects. You can use Netinstaller to set up a pre-defined customized version.
-
Twidge microblog client
The Twidge microblogging tool is easy to learn and provides a much less cluttered environment than Twitter.
-
Print with shell commands courtesy of CUPS
Send documents to a printer and automate many tasks from the command line.
-
Pydio on Raspberry Pi
Pydio transforms the Raspberry Pi into a powerful file sharing and collaboration platform.
