 |
Index for
Section 5 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
man(5)
NAME
man, man.page - The man macro packages for reference pages
SYNOPSIS
tbl file... | neqn | nroff -h [options] -man | ...
tbl file... | neqn | nroff -h [options] -man.page | ...
OPTIONS
-h Uses output tabs during horizontal spacing to speed output and reduce
output character count. Tab settings are assumed to be every eight
nominal character widths.
-nN Numbers the first generated page as N.
Ignored by the man macros for nroff output. Ignored for *troff output
unless -rpS is also specified.
-rlN
Turns on line double-spacing mode if N is greater than 0.
-rnN
Numbers the first generated page as N. Page numbers always print on the
outside end of the page footer.
Ignored by the man macros for nroff output.
-rpS
Sets the section number to S. Section numbers appear in output page
footers as S-N (chapter-page-number).
Page numbers always print on the outside end of the page footer.
Starting page number defaults to "1" unless -nN or -rnN is also
specified.
Ignored by the man macros for nroff output.
-rv2
Prints crop marks. Only for use with *troff formatters.
DESCRIPTION
The man macro package is used to format reference pages for unpaginated
viewing, or for printing on ASCII printers. The man macro package is the
default. The reference pages installed on the base system are formatted by
the man and the catman commands, using the man macro package.
The man.page macro package is used to format reference manual pages for
paginated ASCII output.
The file argument is the name of the reference page source file.
The page width is 77 columns when formatted by the nroff command and the
man or man.page macro packages. The output is paginated when formatted by
the nroff command and the man.page macro package, with page numbers
appearing at the bottom right of each output page.
Macros
The following describes the macros in the man and man.page macro packages.
Note that some of the macro descriptions contain information about *troff
output. This is provided for completeness, only. We do not supply or
support any *troff formatters.
Any text argument can range from zero to six words. Quotation marks (" ")
can be used to include blanks in words. If text is not specified, special
treatment is applied to the next input line that has text to be printed. In
this way, .I can be used to italicize a whole line or .SM followed by .B to
make small bold letters.
A prevailing indent distance is remembered between successive indented
paragraphs, and is reset to a default value upon reaching a nonindented
paragraph. Default units for indents i are ens (an en is 1 nroff character
or 1/2 em space in the current point size).
Typeface and size are reset to default values before each paragraph, and
after processing font and size setting macros.
.AT [ 3|4|5 ] [ number ]
For *troff output only. Specifies the text string to be printed as the
inside page footer. No argument, or the argument 3, specifies the text
"7th Edition." The argument 4 specifies the text "System III." The
argument 5 specifies the text "System V." The argument 5 followed by a
number argument specifies the text "System V Release number."
.B [ text... ]
Sets text text in boldface. If no text is specified, only the next
source text line is set in boldface.
.BI word1 word2 [ words... ]
Sets word1 in boldface, word2 in an italic typeface, and then
alternates between these two fonts for the remaining words, up to six
words. Blanks between words are stripped unless the string is enclosed
in quotation marks (" ").
.BR word1 word2 [ words... ]
Sets word1 in boldface, word2 in a roman typeface, and then alternates
between these two fonts for the remaining words, up to six words.
Blanks between words are stripped unless the string is enclosed in
quotation marks (" ").
.CM [ number ]
For *troff output only. Specifies the text string to be printed as the
inside page footer. No argument, or the number 1, specifies the text
"1st Carnegie-Mellon Update." The number 2 specifies the text "2nd
Carnegie-Mellon Update." The number 3 specifies the text "3rd
Carnegie-Mellon Update." Any whole number n above 3 specifies the text
"nth Carnegie-Mellon Update."
.CT character
Prints the keyboard control character indicator <CTRL/character>. For
example, .CT A prints as <CTRL/A>.
.CW Sets text in a constant width font until another font change is
encountered.
.De Ends an unfilled display block (started by .Ds). Also ends automatic
centering, if it was in effect.
.DE Ends an unfilled display block (started by .DS) and restores the left
margin to the previous position.
.Ds Starts an unfilled display block. Text between .Ds and .De is printed
in a roman typeface, with `no fill' mode (no wrapping and blank lines
allowed) in effect. The display block is set flush left.
.DS Starts a display block with `no fill' mode (no wrapping and blank lines
allowed) in effect. The display block is shifted right .5 inch for
nroff and four picas for *troff formatters.
.DT Restores default tabs. Default tabs are set to every 8 ens for nroff
and to every .5 inches for *troff text formatters, starting with .5i,
1i, ... .
.EE Ends an example and restores basic text defaults and indents.
.EX [ i ]
Starts an example. Text between .EX and .EE is printed in a constant
width font with `no fill' mode (no wrapping and blank lines allowed) in
effect. The example is set flush left unless an indent i is specified.
Units of i are ens.
.G [ text... ]
Sets text in a sans-serif typeface. If no text is specified, only the
next source text line is set in a sans-serif typeface.
.GB [ words... ]
Sets text in a sans-serif bold typeface. If no text is specified, only
the next source text line is set in a sans-serif bold typeface.
.GL [ text... ]
Sets text in a sans-serif italic typeface. If no text is specified,
only the next source text line is set in a sans-serif italic typeface.
.HP [ i ]
Begins a paragraph with a hanging indent of i ens.
.I [ text... ]
Sets text in an italic typeface. If no text is specified, only the
next source text line is set in an italic typeface.
.I1 word
Sets a temporary indent to the length of the specified word.
.I2 word
Reverses one line and then sets a temporary indent to the length of the
specified word.
.IB word1 word2 [ words... ]
Sets word1 in an italic typeface, word2 in boldface, and then
alternates between these two fonts for the remaining words, up to six
words. Blanks between words are stripped unless the string is enclosed
in quotation marks (" ").
.IP x [ i ]
Sets the prevailing indent to i. Then begins the indented paragraph
with a hanging tag given by the next text line. If the tag does not
fit, the macro places the next text on a separate line. Tag x appears
in bold typeface.
.IR word1 word2 [ words... ]
Sets word1 in an italic typeface, word2 in a roman typeface, and then
alternates between these two fonts for the remaining words, up to six
words. Blanks between words are stripped unless the string is enclosed
in quotation marks (" ").
.MS reference_page section_subsection [ punctuation ]
Sets reference_page immediately followed by section_subsection in
parentheses followed by optional punctuation, using fonts that
distinguish this reference page reference from ordinary text. For
example, man(5).
.NE Ends a note. Also cancels automatic centering if it was in effect.
.NT [ header1 ] [ C ]
.NT [ C ] [ header2 ]
Starts a note. If no arguments are specified, the default header for
the note is `Note'. If the first argument is the letter `C', all text
in the note is centered, for the next 99 text lines or until the .NE
macro is called, whichever comes first. If the first argument is not
`C', it becomes the header of the note, even if header2 is also
specified. The header2 argument becomes the header of the note if the
first argument is `C'.
.PD [ v ]
Sets the interparagraph distance to v vertical spaces. Resets the
distance to the default value if v is omitted.
.PN x [ y ]
Sets x in an italic or constant width typeface (depending on the *roff
formatter type) and then reverts to the previous typeface. The optional
argument y is appended to x with no space, but printed in the previous
typeface. The x argument is usually a path name; y is usually
punctuation.
.Pn x y [ z ]
Sets x in the current typeface, sets y in an italic or constant width
typeface (depending on the *roff formatter type) and appends it to x,
and finally reverts to the previous typeface. The optional argument z
is appended to y, but printed in the previous typeface. Spaces are
removed between x, y, and z, unless quotation marks (" ") are used to
enclose strings with spaces. The x argument is usually a fixed path
name; y is usually a variable path name; and z is usually punctuation.
.PP Starts a block paragraph. Sets the prevailing indent to .5i for nroff
and four picas for *troff text formatters.
.R Sets the text in a roman typeface until another font change is
encountered. Also ends nroff underline mode if it was in effect.
.RB word1 word2 [ words... ]
Sets word1 in a roman typeface, word2 in boldface, and then alternates
between these two fonts for the remaining words, up to six words.
Blanks between words are stripped unless the string is enclosed in
quotation marks (" ").
.RE [ k ]
Returns to the kth relative right shift indent level. (Restores the
left margin to the position prior to the kth .RS call). Specifying k=0
is equivalent to specifying k=1. If k is omitted, .RE restores the
left margin to the most recent previous position. When k=1 or 0, the
default .RS indent increment is restored.
.RI word1 word2 [ words... ]
Sets word1 in a roman typeface, word2 in an italic typeface, and then
alternates between these two fonts for the remaining words, up to six
words. Blanks between words are stripped unless the string is enclosed
in quotation marks (" ").
.RN Prints the return character indicator, <RETURN>.
.RS [ i ]
Shifts the left margin to the right (relatively) the amount of i ens.
The .RS macro calls can be nested up to nine levels. If i is not
specified for the first .RS call, the relative right shift increases .5
inch for nroff and four picas for *troff text formatters. Nested .RS
calls increment the relative indent by i ens, or by .2 inch for nroff,
or by 2 picas for *troff text formatters.
.SH text
Creates a section header.
.SM [ text ]
Sets text to be two points smaller than the current point size. If no
text is specified, only the next source text line is set in the smaller
point size.
.SS text
Creates a subsection header.
.TH n c[s] [fc] [fl] [hc] [o] [a]
Begins a new reference page and sets the page title. Also sets up
headers and footers for printed output pages, sets up all defaults and
traps, and calls the .DT and .PD macros. The title appears as a header
on all pages of the formatted reference page. The n argument is the
reference page name. The c argument is the primary section number or
letter. The s argument is the subsection, if any. The fc argument is
optional and specifies the text for the page foot center. The fl
argument is optional and specifies the text for the page foot left. The
hc argument is optional and specifies the text for the page head
center. The o argument is optional and can be used for "origin"
information; for example, "Free Software Foundation" or "X11R5." The a
argument is optional and can be used to specify the machine
architecture, for example "RISC."
Fields n, c, and s appear together at the top of each output page (see
the top of this page for an example). These fields are displayed at
both the top left and right of the screen, or printed page. Fields fc
and fl are in effect only with the man.page macro package, or when
using a *troff formatter. Field hc appears at the top center of each
output page. Field o, the "origin" label, appears under the reference
page name and section number, at the top left and right sides of the
screen, or printed page. Field a appears under the "origin" label, or
under the reference page name and section number if there is no
"origin" label, at the top left and right sides of the screen, or
printed page.
The last five fields are optional. To skip a field, specify a pair of
quotation marks ("") in the field to be skipped.
.TP [ i ]
Sets the prevailing indent to i. Then begins the indented paragraph
with a hanging tag given by the next text line. If the tag does not
fit, the macro places the next text on a separate line.
.UC [ 3|4|5|6|7 ]
For *troff output only. Specifies the text string to be printed as the
inside page footer. No argument, or the number 3, specifies the text
"3rd Berkeley Distribution." The number 4 specifies the text "4th
Berkeley Distribution." The number 5 specifies the text "4.2 Berkeley
Distribution." The number 6 specifies the text "4.3 Berkeley
Distribution." The number 7 specifies the text "4.4 Berkeley
Distribution."
.VE End a vertical margin bar.
.VS [ 4 ]
Starts a vertical margin bar, if `4' is specified; otherwise, the macro
does nothing.
Macros That Cause Line Breaks
The following macros cause line breaks:
De DE Ds DS EE EX
HP IP PP RE SH SS
TH TP
Macros That Need Text Lines
The following macros affect the following line of text if they are
specified in the input without arguments:
B BI BR G GB GL
I IB IR RI RB SH
SS SM
Defaults
Automatic hyphenation is turned on. However, last lines (ones that will
cause a trap) are not hyphenated and the last and first two characters of a
word are not split off.
Characters printed from the Special Font are artificially bolded by three
units whenever the current font is `3'.
The default page width is 77 columns for nroff output and 8.5 inches for
output generated by *troff text formatters. For nroff output, section
headers and page headers are output flush left, primary paragraphs are
indented two columns, and the maximum line length is a total of 77 columns
for an effective right margin of .3 inches. This allows for printing on A4
paper. Left and right page margins are 7.5 picas when *troff text
formatters are used.
The default page length is unlimited (unpaginated) for nroff output with
the man macros, and is 66 lines long for nroff with the man.page macros.
The default page length is 11 inches for output generated by *troff text
formatters.
The .TH macro sets up the following defaults:
· Text is set in "noadjust" mode; the right margin is ragged.
· The default interparagraph distance is 1v for nroff and .5v for *troff
text formatters.
· The basic text indent is two columns for nroff and four picas for
*troff text formatters, from the left margin.
· The maximum text line length is 7.5 inches for nroff and 36 picas for
*troff text formatters.
· Sets tab stops every 8 ens for nroff and every .5 inches for *troff
text formatters.
· The basic text point size is 11 points, with line spacing set to 12
points.
· The basic text font is "R" (a roman typeface).
· Reference page headers, section headers, and subsection headers are
set in a sans-serif bold typeface for *troff formatters.
There are no page footers for nroff output with the man macros. Page
footers are printed when using *troff formatters, and when using the
man.page macros with either nroff or *troff.
The default page number, when footers are printed, has the format:
name(c[s])-pg
where:
name
is the .TH n argument
c[s]
is the .TH c[s] argument (section[subsection])
pg is the current page number
By default, the page number prints on the right side of the page foot.
When printing multiple pages, the page number is reset to "1" at the start
of each new reference page.
RESTRICTIONS
Predefined Registers
The following registers are predefined by the man macro packages and should
not be changed:
PO Page offset and page margin
IN Left margin indent relative to the section headers
LL Line length including IN
PL Page length
The register `l' is predefined when you specify the *roff -rl option. Its
default value is 0. The man command does not use this option.
The register `n' is predefined when you specify the *roff -rn option. Its
default value is 0. The man command does not use this option.
The register `p' is predefined when you specify the *roff -rp option. Its
default value is 0. The man command does not use this option.
The register `v' is predefined when you specify the *roff -rv option. Its
default value is 0. The man command does not use this option.
Reserved Registers
The following registers are reserved for internal use by the man and
man.page macro packages:
A1 d DX EX l m
p p# PF pg pn v
y
In addition, registers beginning with the characters `)', `]', and `}' are
also reserved for internal use.
Registers predefined by the nroff, neqn, and tbl commands, and the *eqn and
*troff text preprocessors and formatters should not be redefined.
Predefined Strings
The following strings are predefined by the man macro package and should
not be changed:
lq " if nroff, " if *troff
rq " if nroff, " if *troff
S Command string to change type size to 10 points.
Reserved Strings and Macros
The following string and macro names are reserved for internal use by the
man and man.page macro packages:
## A1 BD BK CD D
HB HH ID LD NO NX
P TB UF ya yn yl
ys
In addition, names beginning with the characters `)', `]', and `}' are also
reserved for internal use.
Names predefined by the nroff, neqn, and tbl commands, and the *eqn and
*troff text preprocessors and formatters should not be redefined.
.TH Macro Restrictions
Section numbers should only be those listed in the man(1) reference page as
recognized by the man command.
Sections 5, 6, and the single-letter sections listed in the man(1)
reference page normally do not have subsections, so none should be
specified.
Subsections ".z" and ".Z" are not valid and should never be used.
For nroff output, keep the size of the reference page name, including its
section and subsection, to a maximum of 38 characters to prevent
overprinting in the reference page header. Similarly, restrict the size of
the o and a fields to a maximum of 38 characters. If the hc field is used,
reduce the size of the name, section, and subsection fields by the size of
the hc field + 1.
The maximum sizes for the reference page name, o and a fields, are much
shorter if the reference page is formatted with a *troff formatter.
The NAME Section
The catman command assumes the NAME section of a reference page has the
following format:
name[, name, name ...] - explanatory text
There should be at least one space after any comma and only one space
following the "hyphen" (-). A "backslash hyphen" (\-) may also be used to
produce a longer dash. Avoid using macros or other markup to code
information in the NAME section. The explanatory text should be brief. The
catman command combines information in the NAME section with parameters of
the .TH macro to create an entry in a database searched by the apropos,
man, and whatis commands.
PORTABILITY CONSIDERATIONS
The Tru64 UNIX man macro packages contain extensions and enhancements
borrowed from other macro packages. If you need to write portable
reference pages, you should not use the following macros:
AT CM CT CW De Ds
EE EX G GB GL I1
I2 LP MS NE NT PN
Pn R RN UC UF
The .LP macro is obsolete, but is provided for backward compatibility with
other vendors.
The .TH macro permits the use of the percent (%) character in any of its
fields. The presence of the percent character may cause problems for other
implementations of this macro.
The width of the nroff output is 77 columns, with a 2-column indent, for an
effective maximum line length of 75 columns. On other systems, the width of
the nroff output may be only 65 columns, with a 5-column indent, for an
effective maximum line length of 60 columns. Avoid creating tables and
no-fill text that require the full 75 columns available. Plan for a maximum
line length of 60 columns, instead.
FILES
/usr/share/lib/tmac/tmac.an
The man macro package interface
/usr/share/lib/tmac/tmac.an.new
The primary man macros package
/usr/share/lib/tmac/tmac.an6n
Old BSD V6 man macros for nroff
/usr/share/lib/tmac/tmac.an6t
Old BSD V6 man macros for troff
/usr/share/lib/tmac/tmac.an.page
The man.page macro package interface
/usr/share/lib/tmac/tman.an.new.page
The primary man.page macros package
SEE ALSO
Commands: checkeq(1), man(1), neqn(1), nroff(1), tbl(1), catman(8)
Files: rsml(5)
|
Index for
Section 5 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|