MAN(5)

NAME
man - macros for formatting UNIX system manual page entries

SYNOPSIS
troff -man [-rs1 []] [ options []] [ files []]

nroff -man [ options []] [ files []]

DESCRIPTION
The manual page macros are used to lay out the format of the entries of this manual. These macros are used by the man(1) command.

The default page size is 8.5"×11", with a 6.5"×10" text area. The [-rs1] option reduces these dimensions to 6"×9" and 4.75"×8.375", respectively; this troff-only option also reduces the default type size from 10-point to 9-point, and the vertical line spacing from 12-point to 10-point.

Macro usage is summarized below. Type font and size are reset to default values before each paragraph and after processing any macro that effects a change in font or size (e.g., .I(,) .RB(,) .SM().) Tab stops are neither used nor set by any macro except and .TH(.)

DIAGNOSTICS
The macros used are not compatible with man(5), but rather are defined in the Version 6 man entry package. Use the option (if available) to format this manual page.

CAVEATS
In addition to the macros, strings, and number registers listed in SUMMARY, a number of internal macros, strings, and number registers are defined as well. Except for names predefined by troff and number registers d(,) m(,) and y(,) all such internal names are of the form XA, where X is one of )(,) ](,) and }(,) and A stands for any alphanumeric character.

In order to format and print manual pages on-line, the man(1) command needs to know if any preprocessing is required. If the first line of the manual page file has the format
    '\" x
where x can be for tables, for equations, or for tables and equations; the eqn(1) and tbl(1) preprocessors will be used as appropriate.

The programs that prepare the Table of Contents and the Permuted Index for this manual assume the NAME section of each entry consists of a single line of input that has the following format:
    name[, name, name ] - explanatory text
The macro package increases the inter-word spaces (to eliminate ambiguity) in the SYNOPSIS section of each entry.

This version of the manual page macros recognizes most macro commands defined in other versions of UNIX man(5) (e.g., from Research V10, UCB BSD and SunOS systems). Inclusion of these macros (see SUMMARY) ensures that text arguments are retained and appear reasonable on output. These macro definitions may not be identical to those on the originating system.

BUGS
If the argument to contains any blanks and is not enclosed by double quotes (""), there will be strange irregular dots on the output.

FILES

SEE ALSO
eqn(1), man(1), neqn(1), nroff(1), tbl(1), tc(1), troff(1)

SUMMARY

Any macro argument text may be one to six strings; any string that includes one or more blanks must be enclosed in a pair of double quotes (e.g., if text is "a few words"). If text is empty, the special treatment is applied to the next line that contains text to be printed. For example, may be used to italicize a whole line, or followed by to print text in the bold font and a smaller point size. By default, hyphenation is turned off for nroff, but remains on for troff.

Default units for indents in are ens; in may be a scaled value (.e.g, or 4P). When in is omitted, the previous indent is used.

Set the title and entry heading; t is the title, s is the section number, c is an extra commentary (e.g., ``local'') n is a new manual name. Invokes (see below). Place subhead text (e.g., ``SYNOPSIS'') here. Place sub-subhead text (e.g., ``Options'') here. Begin a paragraph with normal font, point size, and indent; is a synonym. Begin paragraph with hanging indent. Begin indented paragraph with hanging tag. The next line that contains text to be printed is taken as the tag. If the tag does not fit, it is printed on a separate line. Same as .TP(,) but with tag t; often used to get an indented paragraph without a tag. Increase relative indent (initially zero). Indent all output an extra in units from the current left margin. Return to the kth relative indent level (initially, k=1; k=0 is equivalent to k=1); if k is omitted, return to the most recent lower indent level. Begin example. Example text is set in the monowidth font, using no-fill mode and an indented block format. If x is ``-1'', the point size and vertical spacing is reduced one point. End example. Produces the appropriate proprietary marking at the bottom of the page. Usage for m is:
    P    AT&T - Proprietary
    RS   AT&T - Proprietary (Restricted)
    RG   AT&T - Proprietary (Registered)
    CR   Copyright notice
    UW   Unpublished Work notice
    CP   See Cover Page notice
y is the year used in the date for the copyright notice (default is current year).
Produce a command line option of the form [-f file] where opt is the option flag, arg is the option argument, x is regular-font text appended to the argument, and y is regular-font text prepended to the option. If x is ``[]'' the option is enclosed in square brackets (e.g., ``.OP -f file []'' produces [-f file []] on output). Restore default tab settings (every ½-inch). Set the interparagraph distance to v vertical spaces. If v is omitted, set the interparagraph distance to the default value (0.4v in troff, 1v in nroff). Make text bold; if text is missing, switch to bold font. Make text italic; if text is missing, switch to italic font. Make text monowidth (e.g., typewriter-like); if text is missing, switch to monowidth font (also known as constant-width). Make text one point smaller than default point size. Make text one point smaller and bold. Make text roman; if text is missing, switch to roman font. Concatenate roman a with italic b; alternate these fonts for up to six arguments. Concatenate italic a with roman b; alternate these fonts for up to six arguments. Concatenate roman a with bold b; alternate these fonts for up to six arguments. Concatenate bold a with roman b; alternate these fonts for up to six arguments. Concatenate bold a with italic b; alternate these fonts for up to six arguments. Concatenate italic a with bold b; alternate these fonts for up to six arguments. Concatenate monowidth a with roman b; alternate these fonts for up to six arguments. Concatenate roman a with monowidth b; alternate these fonts for up to six arguments. Concatenate monowidth a with italic b; alternate these fonts for up to six arguments. Concatenate italic a with monowidth b; alternate these fonts for up to six arguments. Concatenate monowidth a with bold b; alternate these fonts for up to six arguments. Concatenate bold a with monowidth b; alternate these fonts for up to six arguments.

The following strings are defined:
    Rg     registered mark symbol:
    Tm     trademark symbol: ™
    Sm     service mark symbol:
    lq     left quote: “ (" in nroff)
    rq     right quote: ” (" in nroff)
    S      changes to the default point size
    mW     changes to the monowidth font (bold in nroff)
    mB     changes to the monowidth-bold font (bold in nroff)
The macro assigns default values to these number registers:
    IN     Left margin indent relative to subheads
    LL     Line length including indent from register IN
    PD     Current interparagraph distance
Additional macros taken from the Research V10 system version of man(5):
Turn hyphenation on. Set text in the file font (monowidth); if text is missing, switch to file-font. Concatenate file-font a with roman b . Set text in the literal font (monowidth); if text is missing, switch to literal-font. Concatenate literal font a with roman b. Concatenate roman a with file-font b and roman c. Concatenate roman a with literal-font b and roman c. Indented paragraph; set hanging label text in monowidth font.

Additional macros taken from various UCB systems' version of man(5):
Use t as title heading for IBM ACIS distribution. Use t as title heading for BSD distribution. End display. Start display. Display text is set in no-fill mode as an indented block. Generate index entry; write arguments and current page number to stderr as:
.IE→ENTRY→a→b→c→d→e→f→page
where → represents a tab and page is the page number field used elsewhere on the manual page (e.g., ``Page 15''). Limitations statement for NFS distribution; u is the utility type (e.g., utility, file, system call). Set text in smaller point size and bold font. Use t as title heading for SunOS distribution. Use abbreviation code x to resolve title reference for SunOS distribution. Use t as title heading for BSD distribution. End version changes. Start version changes. If mark m is 4, use small vertical bar as margin character.