Nroff by example: Manual pages
If you work on Linux-based projects, you may need to write "man" documentation suitable for Unix systems. Use this file as a template to write your next "man" page.
Unix systems have maintained a set of online manuals called "man" pages, named after the
man command. Historically, the manual is divided into seven sections:
- System calls
- Special files
- File formats
- User-maintained programs
- Miscellaneous information
The first such manuals were also printed. In fact, because the manual was written with a set of special formatting macros for
nroff called the
-man macros, the same document files can be either displayed in a user's terminal or printed in book form. The
-man macros remain in use today, and technical writers partnered with Unix-based projects may need to write or maintain documentation in this format.
Organization and structure
Unix manual pages typically include these sections to describe the functionality and features of a program:
The name and 1-line summary of what the program does
How to run the program from the command line, in brief
More detailed description of the program and any command line options it might accept
If the program requires special files, list them here
Other programs or commands that are similar to this one
Use these macros to provide the major structure for your manual page:
.TH title section
Set the top header of the manual page to describe the page's title and section.
Create a major section heading. You can include the heading text as the first argument, or you can put the heading text on the following lines before the first paragraph.
Create a subsection, for programs that require more hierarchy to describe the options. Like the section heading macro, you can include subsection heading text either as the first argument or on following lines.
You have several options to start a new paragraph. The
.LP macros all create the same paragraph. On most implementations, these are all aliases for the same paragraph.
To create a tagged paragraph. The line that immediately follows is the hanging tag for the other lines that make up the paragraph body. This is often used to display command line options and their meaning.
Bold and italics
Technical writers have developed a de facto style to describe the syntax for a program. The program name and its command line options are usually printed in bold type, while placeholder fields are displayed in italics type. Optional text is usually surrounded by square brackets in normal type. For example, to describe a program called
foo that can accept an option to display help or an option to specify a file, you might write this command synopsis:
foo [ --help ] [ --file=filename ]
This tricky mix of formatting is made easier with a set of special macros to alternate between different font styles:
Display text in bold. You can provide the text as an optional first argument; otherwise, the macro will set the next line's text in bold.
.BR text [ [text] .. ]
Alternate text between bold and normal (Roman) type without spaces between them.
.BI text [ [text] .. ]
Alternate text between bold and italics without spaces between them.
Display text in italics. You can provide the text as an optional first argument; otherwise, the macro will set the next line in bold.
.IR text [ [text[ .. ]
Alternate text between italics and normal without extra spaces.
.IB text [ [text] .. ]
Alternate text between italics and bold without spaces.
.RB text [ [text] .. ]
Display text alternately as normal and bold type, without extra spaces.
.RI text [ [text] ..]
Display text alternately as normal and italics, without extra spaces.
Putting it all together
-man macros are the standard way to format an online manual page for Unix and Linux systems. Let's look at this example to see how to format manual pages using the most common macros. This documents the usage of a made-up program that we'll call
refill that cleans up nroff source files. This sample
refill.man file demonstrates how you might write typical Linux manual pages:
.TH REFILL 1 .SH NAME .PP refill - clean up nroff source files .SH SYNOPSIS .B refill .RB [ --help ] .RI [ OPTIONS.. ] .RI [ FILES..] .SH DESCRIPTION .PP Note that major section headings are ALL CAPS. Subsection headings are usually typed in Title Case. .PP Clean up nroff source files by refilling the text. This does .i not refill lines that begin with a period. .SS "Command Line Options" .PP Use these command line options to control refill of certain nroff documents: .TP .B --help Displays usage and immediately exits .TP .BI --output= file Save the output to .I file rather than print to standard output. .TP .B -me Adjust refill to accommodate the .I -me macros. .TP .B -ms Adjust refill to accommodate the .I -ms macros. .TP .B -man Adjust refill to accommodate the .I -man macros. .SH FILES .TP .BI /usr/local/refill/conf/ mac .conf Configuration files to accommodate nroff macro packages. The .BI -m mac command line options refer to these files by name. .SH "SEE ALSO" .BR fmt (1)
(Oops! There's an error with
.i not that doesn't generate any output. This should be
.I not instead.)
Process this file into a plain text file using this command:
$ nroff -man refill.man > refill.txt
REFILL(1) General Commands Manual REFILL(1) NAME refill - clean up nroff source files SYNOPSIS refill [--help] [OPTIONS..] [FILES..] DESCRIPTION Note that major section headings are ALL CAPS. Subsection headings are usually typed in Title Case. Clean up nroff source files by refilling the text. This does refill lines that begin with a period. Command Line Options Use these command line options to control refill of certain nroff docu‐ ments: --help Displays usage and immediately exits --output=file Save the output to file rather than print to standard output. -me Adjust refill to accommodate the -me macros. -ms Adjust refill to accommodate the -ms macros. -man Adjust refill to accommodate the -man macros. FILES /usr/local/refill/conf/mac.conf Configuration files to accommodate nroff macro packages. The -mmac command line options refer to these files by name. SEE ALSO fmt(1) REFILL(1)
Or you can use groff to process the manual page into a Postscript file that's ready to print:
$ groff -man -Tps refill.man > refill.ps
For more information about using the -man macros with GNU groff, see Man usage (The GNU Troff Manual)