The HP-UX Man: nroff, The Making of man
Fred discusses nroff, how it is used in making man pages and teaches you how to do it yourself.
When any of the descendents of roff are mentioned, the most common reaction seems to be either people running off, or holding up crossed sticks to ward off the speaker. The first reaction is the more interesting of the two, since roff’s full name is "Run Off," referring to it’s original use of preparing text to be ‘run off’ on the printer. The second reaction is rather disturbing, since most of these same people use roff unknowingly almost every time they read a man page.
By default, all of the "runoff" family of commands will break text into lines of approximate length. This means that a text file without line breaks except at paragraphs can be easily reformatted into equal length lines (typically 6.5 inches on paper, or 65 characters) by issuing:
nroff textfile.name
In order to perform more complex formatting, you must delve deeper. Most of the actual work of formatting is controlled with formatting markup inserted into the text file. Markup commands are generally alone on a line, begin with a period, and contain one or two letters (with possible arguments). There are also escape sequence commands, where a backslash precedes a format directive.
Formatting directives come in three flavors:
• One-time effect
• Persistent effect
• Programmatic control (for writing macros)
An example of the one-time effect is the .sp or \bu used above. Some others that are frequently used are:
• .br line break
• .bp page break
• .ce center next line
• .ti temporary indent
Some examples of persistent effect formatting directives include:
• .nf disable filling
• .fi enable filling
These two directives allow you to specify sections of a text file that should not be formatted. For example, think of writing a man page; you would not want filling to occur in the examples sections.
• .ll n set line length to n
• .in set indent (persistent)
• .ad enable line adjustment
• .nh disable hyphenation
Some directives accept an argument, such as the .ll seen above. As an example, the following text (with a directive):
.ll 20
this
text will be formatted to 20 characters wide
Would be processed by nroff to the following:
this text will be formatted to 20 characters wide
Note the unusual spacing in the formatted text. This is due to justification. IF we also put .ad l as a directive before any of the lines of text were processed, the output would have appeared as:
this text will be
formatted to 20
characters wide
The .ad format directive also takes c for center, b for both, and r for right margin justification. There are many more formatting directives, but by now you should recognize some similarities to HTML. Using these directives are rather simple except for a few gotcha’s. One of them is that whenever filling is turned on, lines are not output until a line is filled, thus it can appear that nroff is ignoring format directives. To prevent this, you must often put in .br directives to force previous text to be output.
Getting back to how nroff is used in the making of man pages, we need to discuss macros. All of these tools are tied to the mm and ms commands. These commands use similar formatting directives, written as named groups of commands, called macros. These macros can be marked into text documents, and processed as the document is formatted. Many of these macros are used when marking up man pages, since similar tasks are performed repeatedly. In many versions of nroff and ditroff you have to issue the -mm option on the command line to get these macros to run.
Some examples of the macros used in man pages include the .TH Titleheader .SH Sectionhead and .SS Subsection directives which are used to define sections of a man page, such as:
• . TH title section comment
• . SH NAME
• . SH SYNOPSIS
• .SS Options
Looking at the markup from a typical man page can be rather informative about how these macros are used. If your man pages look like line noise when you more them, they are probably compressed. If the directory name has a .Z on it, this is true. Be sure to use man pages from a man directory, not a cat directory (which contains the output of nroff, not the input to nroff). Copy a man page file into a temporary location, then rename it with a .Z extension so you can uncompress it.
Once you have done that, read the man 5 man page, which documents the man specific macros. After that, you can write your own man pages, copying them into the system man page directories, and access these files with the man command.