manuals - Format of manuals
The ProLine Reference Manual consists of individual files, called entries, that describe a part of the system, be it a command, a file format, miscellaneous information, etc.
Manuals follow a specific visual format. Shown at the top of each page is an entry’s title and section, e.g. MANUALS(F), and at the bottom is its modification date, page number, and date printed.
These subheaders are standard in manual entries and typically
follow in the order presented here:
A short, one-line summary of the document follows.
Included for entries that describe a command with parameter arguments.
Begins the descriptive body of the entry. The body of an entry is generally undefined. Though, it should not use any subheader other than those described here. It may contain, however, its own paragraph headings.
(or Notes, Bugs, Warning, Important, etc.) This subheader proceeds important information that should stand out from the body of the description, such as hazards or side effects.
Error messages and their meanings.
If any files are associated with an entry, they are listed after this subheader, usually near the end of the entry. Each file listed should include a short description.
Usually, an entry ends with a “See Also” subheader, followed by a reference list to related entries.
(Optional). The name of the author (for the entry and/or the command it describes) is given, along with the author’s e-mail address. If this subheader is not included, it is assumed that the author is Morgan Davis.
Manuals are punctuated with “dot” commands for interpretation by
processing programs such as man and manps. Each command has the
form of a period (.) followed by a two-letter command name. Arguments
to a command are separated from the command by a space. Text that does
not start with a period is considered text to be processed. Text
portions need not be formatted in the source file, as the processing
programs will perform all the necessary formatting.
The “dot” commands are described below. In the descriptions,
“s” denotes a set of characters while “n” denotes a number.
Arguments shown between [ ] brackets are optional. If the optional
number is omitted, zero is assumed, unless otherwise noted.
Title Header. s1 is the entry’s title, followed by a space, and then the associated section, s2. Both arguments must be in uppercase. (e.g. .TH MANUALS F)
Date. s contains the date of the last modification of the entry in this format: 12 March 1992.
Subheader. Displays s fully left justified.
Left Margin. The value of n is added to the current left margin. A negative value narrows the margin, while a positive value widens it.
Right Margin. The value of n is added to the current right margin. A negative value narrows the margin, while a positive value widens it.
New Paragraph (with optional s paragraph header).
Indented Paragraph. Begins a new paragraph, setting the indentation to n columns. If s is included, it is displayed at the left margin, and the print position tabs out to the indentation point. The effect is what you see here — the dot commands are left-margin justified, while the descriptions are indented. Use .IP with no arguments to disable indentation.
Centers s, followed by line break.
Spaces. Print n spaces (default is 1).
Repeat Character. Prints the s character n times. If n is omitted, s is repeated up to the right margin and a line break follows. Use this command to display characters that would be misinterpreted if included in text (e.g. “.RC 1 _ ”).
Break. Inserts n line breaks (default is 1). This moves the printing position to the next line, respecting current indentation settings.
Auto-Fill. If n is given, auto-fill is turned on (1) or off (0). If no argument is given auto-fill is toggled. Proceeding text lines are displayed with no formatting. Blank lines are ignored, but commands such as .BR are still recognized.
Underline Character. Sets the emphasis-toggle character to s (default is the underscore ‘ _ ’). Text selections surrounded by this character are emphasized. For video displays, this results in either highlighted or underscored text. For dot matrix printers, the text is underlined. For PostScript devices, the text is italicized.
New Page. Ends the current page by printing the appropriate number of lines, followed by the page footer.
If fewer than n lines remain on the page, a new page (.NP) is performed. Include .IF before tables or lists that should not be broken across pages. The .SH, .PP and .IP commands include built-in widow control, as if “.IF 2” precede them.
Tab to column n from current print position.
An excellent way to learn to “program” a new manual entry is to compare the contents of an existing entry with its printed output, noting how each dot command effects the display.
Whenever reference is made to the command being described by the entry,
always highlight it using the underscore/highlight quoting character.
Similarly, reference to other commands should be highlighted as well.
Highlighting is valuable for making urgent or important passages of
text stand out. Such text is displayed in italics on PostScript printers.
Use typographer’s quotation marks. These consist of the apostrophe (’) and accent grave (‘) characters, either singularly or in pairs. “Like this,” for example.
Whenever examples are used that reference items that the user might see on the screen, turn off the auto-fill mode (.AF). Text that is not auto-filled is displayed in Courier, a monospace font, on PostScript printers. This has a the desirable effect of making the text stand out in a “computer-like” typeface.