Chapter 3 The -man Macro Package
3.2. Coding Conventions
The Header and Footer Line
( • TH) - Identifying the Page
The NAME Line
Leave out sections that do not apply - it is not necessary to have a title without any content to go with it. Definitely avoid sections that read:
BUGS None.
The following subsections compose a fairly detailed description of what the dif-ferent sections of the manual page contain.
The . T H macro is the macro that identifies the page. The format is ( . TH nc xvm
This means, for example: Begin page named n of chapter c. The x argument is for extra commentary for the center page footer. The v argument alters the left portion of the page footer. The m argument alters the center portion of the page header. The . TH command line also incidentally sets the prevailing indent and tabs to .5i.
To code a manual page called troff (l) , for example, you would code a . TH macro like:
( . TH TROFF 1 .. today' s dare"
The third parameter to the . TH macro is the date on which you created or last changed the manual page. You code today's date in international form:
numerical day spelled-out month numerical year So if today is September 3rd, 1984, you code the . TB macro like:
( .TH TROFF 1 "3 September 1984"
The NAME line is a one-liner that identifies the command or program. You code the information like this:
.SH NAME
troff \- typeset or format documents
This line must be typed all in the Roman font with no font changes or point-size changes or any other text manipulation. Typing the command line all in Roman with no text manipulation is for the permuted index generator. It gets all con-fused if there is anything in that line other than plain text.
]
]
]
Revision A, of 9 May 1988
The SYNOPSIS Section
The DESCRIPTION Section
Chapter 3 - The -man Macro Package 61
Note the \- in there - why do we type a \-? Well, in troff jargon, a simple-sign gets you a hyphen. We actually would like a en-dash (like - ) instead of a hyphen, in lieu of actually having a em-dash (like -). This use of the \- to get a - is a UNIXt tradition.
The SYNOPSIS line(s) show the user what options and arguments can be typed.
The conventions for the S YNOP SIS have varied wildly over the years. Nonethe-less, here are the guidelines:
D Literal text (that is, what the user types) is coded in boldface.
D Variables (that is, things someone might substitute for) are typed in italic text.
D Optional things are enclosed in brackets - that is the characters [ and ] .
o Alternatives are separated by the vertical bar sign ( I ).
The synopsis should show what the options are - some manual pages used to read like this:
SYNOPSIS
trofT [options] filename ...
but it should read:
SYNOPSIS
trofT [-opagelist] [-nN ] [-m name] ... [filename]
The DESCRIPTION section of a manual page should contain a brief description of what the command does for the user, in tenns that the user cares about.
Within the DESCRIPTION and OPTIONS sections, italic text is used for filenames and command names. The rationale here is that UNIX commands are simply files. When referring to other manual pages, you type the name in italics and the following parenthesized section number in Roman, as in make ( 1). Use the -man macro . I R to get alternating words joined in italic and Roman fonts.
Note that the macros that join alternating words in different fonts (. IR, . IB, . BR, . BI, . RI, • RB) all accept only six parameters .. See the section on how to
fonnat a manual page for more fonnatting rules.
Part of the description in the grep manual page used to read:
. . . .. grep patterns are limited regular expressions in the style of ed ( 1 ) ; it uses a compact nondetenninistic algorithm. egrep patterns are full regular expressions; it uses a fast deterministic algorithm that sometimes needs exponen-tial space. fgrep patterns are fixed strings; it is fast and compact.
Most users do not care that egrep uses a fast detenninistic algorithm. As an example of a more useful way of describing a command for the user, here is how
t UNIX is a registered trademark of AT&T.
Revision A, of 9 May 1988
62 Formatting Documents
The OPTIONS Section
that sentence in the grep manual page currently reads.
. . . .. grep patterns are limited regular expressions in the style of ed ( 1 ) . egrep patterns are full regular expressions including alternation. fgrep searches for lines that contain one of the (newline-separated) strings. fgrep patterns are fixed strings - no regular expression metacharacters are supported.
Here's another bad example: the Ipr (1) command used to tell you that the -s option uses the syrnlink (2) system call to make a symbolic link to the data file instead of copying the data file to the spool area. The user may not know what this means or how to use the information. The description was changed to just tell you that the -s option makes a symbolic link to the data file. How it is done is of little concern to some poor blighter who just wants to print a file.
The OPTIONS section of a manual page contains an itemized list of the options that the command recognizes, and how the options affect the behavior of the command. The general format for this section is
-option Description of what the option does.
A specific example from the troff manual page looks like this:
OPTIONS
Options may appear in any order as long as they appear before the files.
-oUst
Print only pages whose page numbers appear in the comma-separated list of numbers and ranges. A range N-M means pages N through M;
an initial -N means from the beginning to page N; and a final N- means from N to the end.
-nN
Number first generated page N.
-mname
Prepend the macro file /usr/lib/tmac/tmac.name to the input files.
-raN
-i
-q
-t
-a
Set register a (one-character) to N.
Read standard input after the input files are exhausted.
Invoke the .simultaneous input-output mode of the rd request.
Direct output to the standard output instead of the
phototypesetter. In general, you will have to use this option if you don't have a typesetter attached to the system.
Revision A, of 9 May 1988
The FILES Section
Chapter 3 - The -man Macro Package 63
Send a printable ASCII approximation of the results to the standard output.
Some options oftroff only apply if you have a C/A{f typesetter attached to your system. These options are here for historical reasons:
-sN
-f
Stop every N pages. troff stops the phototypesetter every N pages, produces a trailer to allow changing
cassettes, and resumes when the typesetter's start button is pressed.
Refrain from feeding out paper and stopping phototypesetter at the end of the run.
-w
-b
Wait until phototypesetter is available, if currently busy.
Report whether the phototypesetter is busy or available. No text processing is done.
-pN
Print all characters in point size N while retaining all
prescribed spacings and motions, to reduce phototypesetter elapsed time.
The FILES section of a manual page contains a list of the files that the program accesses, creates, or modifies. Obviously, you can leave this section out if the program uses no files.
The example from the troff manual page looks like this:
.\sun
• microsystemsIf the file /usr / adm/tracct is writable, troff keeps phototypesetter accounting records there. The integrity of that file may be secured by making troff a 'set user-id' program.
FILES /tmp/ta*
/usr/lib/tmac/tmac. * /usr/lib/term/*
/usr/lib/font/*
/dev/cat /usr/adm/tracct
temporary file standard macro files
terminal driving tables for nroff font width tables for troff phototypesetter
accounting statistics for /dev /cat
Revision A. of 9 May 1988
64 Formatting Documents
The SEE ALSO Section
The BUGS Section
3.3. New Features of the