back-to-school 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:

  1. Commands
  2. System calls
  3. Subroutines
  4. Special files
  5. File formats
  6. User-maintained programs
  7. 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:

Name

The name and 1-line summary of what the program does

Synopsis

How to run the program from the command line, in brief

Description

More detailed description of the program and any command line options it might accept

Files

If the program requires special files, list them here

See also

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.

.SH [text]

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.

.SS [text]

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.

.P or .PP or .LP

You have several options to start a new paragraph. The .P and .PP and .LP macros all create the same paragraph. On most implementations, these are all aliases for the same paragraph.

.TP

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:

.B [text]

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.

.I [text]

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

The -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

screenshot of printed manual page

The printed manual page (image: Jim Hall, Creative Commons)

 

For more information about using the -man macros with GNU groff, see Man usage (The GNU Troff Manual)

photo of jhall

Jim Hall is an open source software advocate and technical writer. At work, Jim is CEO of Hallmentum, an IT executive consulting company that provides hands-on IT Leadership training, workshops, and coaching.