GROFF_MAN(7) Miscellaneous Information Manual GROFF_MAN(7)
NAME
groff_man - GNU roff macro package for formatting man pages
SYNOPSIS
groff -man [option ...] [input-file ...]
groff -m man [option ...] [input-file ...]
DESCRIPTION
The man macro package for groff is used to produce manual pages
(“man pages”) like the one you are reading. GNU roff's implementation
was written by James Clark.
This document presents the macros thematically to aid learners; for
those needing only a quick reference, the following table lists them
alphabetically, with cross-references to appropriate subsections below.
Macro Meaning Subsection
───────────────────────────────────────────────────────────────────
.B Bold Font style macros
.BI Bold, italic alternating Font style macros
.BR Bold, roman alternating Font style macros
.EE Example end Document structure macros
.EX Example begin Document structure macros
.I Italic Font style macros
.IB Italic, bold alternating Font style macros
.IP Indented paragraph Paragraph macros
.IR Italic, roman alternating Font style macros
.LP (Left) paragraph Paragraph macros
.ME Mail-to end Hyperlink and email macros
.MT Mail-to start Hyperlink and email macros
.OP (Command-line) option Command synopsis macros
.P Paragraph Paragraph macros
.PP Paragraph Paragraph macros
.RB Roman, bold alternating Font style macros
.RE Relative-indent end Document structure macros
.RI Roman, italic alternating Font style macros
.RS Relative-indent start Document structure macros
.SB Small bold Font style macros
.SH Section heading Document structure macros
.SM Small Font style macros
.SS Subection heading Document structure macros
.SY Synopsis start Command synopsis macros
.TH Title heading Document structure macros
.TP Tagged paragraph Paragraph macros
.TQ Tagged paragraph continuation Paragraph macros
.UE URL end Hyperlink and email macros
.UR URL start Hyperlink and email macros
.YS Synopsis end Command synopsis macros
Macros whose use we discourage (.AT, .BT, .DT, .HP, .PD, .PT, and .UC)
are described in subsection “Deprecated features”, below.
Macro reference preliminaries
Each macro is described in a tagged paragraph. Closely related macros,
such as .EX and .EE, are grouped together.
Optional macro arguments are indicated by surrounding them with square
brackets. If a macro accepts multiple arguments, arguments containing
whitespace must be double-quoted ("one two"), to be interpreted cor-
rectly. Most macro arguments are strings that will be output as text;
exceptions are noted.
Bear in mind that groff is fundamentally a programming system for type-
setting. Consequently, the verb “to set” is frequently used below in
the sense “to typeset”.
Document structure macros
The highest level of organization of a man page is determined by this
group of macros. .TH (title heading) identifies the document as a man
page and defines information enabling its indexing by mandb(8) or a
similar tool. Sections (.SH), one of which is mandatory and many of
which are standardized, facilitate quick location of relevant material
by the reader and aid the man page writer to discuss all essential as-
pects of the topic. Subsections (.SS) are optional and permit sections
that grow long to develop in a controlled way. Many technical discus-
sions require examples; lengthy ones, especially those reflecting mul-
tiple lines of input to or output from the system, are usefully brack-
eted by .EX and .EE. When none of the foregoing meets a structural de-
mand, a section of the discussion can be manually indented within .RS
and .RE macros.
.TH title section [footer-middle] [footer-outside] [header-middle]
Define the title of the man page as title and the section as
section. See man(1) for details on the section numbers and suf-
fixes applicable to your system. title and section are posi-
tioned together at the left and right in the header line (with
section in parentheses immediately appended to title). footer-
middle is centered in the footer line. footer-outside is posi-
tioned at the left in the footer line (or at the left on even
pages and at the right on odd pages if double-sided printing is
active). header-middle is centered in the header line. If sec-
tion is a simple integer between 1 and 9 (inclusive), or is ex-
actly “3p”, there is no need to specify header-middle; the macro
package will supply text for it.
For HTML output, headers and footers are completely suppressed.
Additionally, this macro starts a new page; the page number is
reset to 1 (unless the -rC1 option is given on the command
line). This feature is intended only for formatting multiple
man pages.
A man page should contain exactly one .TH call at or near the
beginning of the file, prior to any other macro calls.
By convention, footer-middle is the most recent modification
date of the man page source document, and footer-outside is the
name and version or release of the project providing it.
.SH [heading-text]
Set heading-text as a section heading flush left. The text fol-
lowing .SH up to the end of the line, or the text on the next
input line if .SH is given no arguments, is set in bold (or the
font specified by the string register HF) slightly larger than
the base font size. Additionally, the left margin and indenta-
tion affecting subsequent text are reset to their default val-
ues. Text on input lines after heading-text is set as a normal
paragraph (.PP).
The content of heading-text and ordering of sections has been
standardized by common practice, as has much of the layout of
material within sections. For example, a section called “Name”
or “NAME” must exist, must be the first section after the .TH
call, and must contain only a line of the form
page-topic[, ...] \- summary-description
for a man page to be properly indexed. See man(7) for the con-
ventions prevailing on your system.
.SS [subheading-text]
Set subheading-text as a subsection heading indented (by de-
fault) partway between a section heading and a normally-indented
paragraph (.PP). The text following .SS up to the end of the
line, or the text on the next input line if .SS is given no ar-
guments, is set in bold (or the font specified by the string
register HF) at the base font size. Additionally, the left mar-
gin and indentation affecting subsequent text are reset to their
default values. Text on input lines after subheading-text is
set as a normal paragraph (.PP).
.EX
.EE Begin and end example. After .EX, filling and hyphenation are
disabled and a constant-width (monospaced) font is selected.
Calling .EE enables filling and restores the previous hyphena-
tion setting and font.
Example regions are useful for formatting code, shell sessions,
and text file contents.
These macros are defined on many (but not all) legacy Unix sys-
tems running classic troff. To be certain your page will be
portable to those systems, copy their definitions from the
an-ext.tmac file of a groff installation.
.RS [indent]
Move the left margin to the right by the value indent, if speci-
fied, and by a default amount otherwise; see subsection “Hori-
zontal and vertical spacing” below. Calls to .RS can be nested;
each call increments by 1 the indentation level used by .RE.
The indentation level prior to any .RS calls is 1.
.RE [level]
Move the left margin back to that corresponding to indentation
level level. If no argument is given, move the left margin one
level back.
Paragraph macros
A typical paragraph (.PP) is set at the current left margin, which by
default is indented from the left margin of the output device. In man
pages and other technical literature, definition lists are frequently
encountered; these can be set as “tagged paragraphs” (.TP and .TQ),
which have one or more leading tags followed by a paragraph that has an
additional left indent. The indented paragraph (.IP) macro is useful
to continue the indented content of a narrative started with .TP, or to
present an itemized or ordered list.
.LP
.PP
.P Begin a new paragraph; these macros are synonymous. They break
the output line at the current position, followed by a vertical
space downward by a default amount (which can be changed by the
deprecated .PD macro). The font size and style are reset to de-
faults; see subsection “Font style macros” below. Finally, the
left margin and indentation are reset to default values.
.TP [indent]
Set a tagged, indented paragraph. The input line following this
macro, known as the tag, is printed at the current left margin.
Subsequent text is indented by indent, if specified, and by a
default amount otherwise; see subsection “Horizontal and verti-
cal spacing” below.
If the tag is not as wide as the indentation, the paragraph
starts on the same line as the tag, at the applicable indenta-
tion, and continues on the following lines. Otherwise, the de-
scriptive part of the paragraph begins on the line following the
tag, entirely indented. The line containing the tag can include
a macro call, for instance to set the tag in bold with .B.
.TP was used to write the first paragraph of this description of
.TP, and .IP the subsequent ones.
.TQ Set an additional tag for a paragraph tagged with .TP. The
pending output line is broken. The tag on the input line fol-
lowing this macro and subsequent lines are handled as with .TP.
This macro is not defined on legacy Unix systems running classic
troff. To be certain your page will be portable to those sys-
tems, copy its definition from the an-ext.tmac file of a groff
installation.
The descriptions of .LP, .PP, and .P above were written using
.TP and .TQ.
.IP [tag] [indent]
Set an indented paragraph with an optional tag. The tag and in-
dent arguments, if present, are handled as with .TP, with the
exception that the tag argument to .IP cannot include a macro
call.
Two convenient use cases for .IP are
(1) to start a new paragraph with the same indentation as
the previous .IP or .TP paragraph, if no indent argu-
ment is given; and
(2) to set a paragraph with a short tag that is not se-
mantically important, such as a bullet (•)—obtained
with the ‘\(bu’ character escape—or list enumerator,
as seen in this very paragraph.
Command synopsis macros
Command synopses are a staple of section 1 and 8 man pages. These
macros aid you to construct one that has the classical Unix appearance.
Furthermore, some tools are able to interpret these macros semantically
and treat them appropriately for localization and/or presentation. A
command synopsis is wrapped in .SY/.YS calls, with command-line options
of some formats indicated by .OP.
These macros are not defined on legacy Unix systems running classic
troff. To be certain your page will be portable to those systems, copy
their definitions from the an-ext.tmac file of a groff installation.
.SY command
Begin synopsis. Hyphenation is turned off. The command argu-
ment is set in bold. The output line is filled as normal, but
if a break is required, subsequent output lines are indented by
the width of command plus a space.
.OP option-name [option-argument]
Indicate an optional command parameter called option-name, which
is set in bold. If the option takes an argument, specify op-
tion-argument using a noun, abbreviation, or hyphenated noun
phrase. If present, option-argument is preceded by a space and
set in italics. Square brackets (in roman) surround both argu-
ments.
.YS End synopsis. Restore indentation and hyphenation to previous
values.
Multiple .SY/.YS blocks can be specified, for instance to distinguish
differing modes of operation of a complex command like tar(1); each
will be separated by a paragraph space.
.SY can also be repeated multiple times before a closing .YS, which is
useful to indicate synonymous ways of invoking a particular mode of op-
eration.
For example,
.SY groff
.OP \-abcegiklpstzCEGNRSUVXZ
.OP \-d cs
.OP \-f fam
.OP \-F dir
.OP \-I dir
.OP \-K arg
.OP \-L arg
.OP \-m name
.OP \-M dir
.OP \-n num
.OP \-o list
.OP \-P arg
.OP \-r cn
.OP \-T dev
.OP \-w name
.OP \-W name
.RI [ file
\&.\|.\|.\&]
.YS
.
.SY groff
.B \-h
.SY groff
.B \-\-help
.YS
produces the following output.
groff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir]
[-I dir] [-K arg] [-L arg] [-m name] [-M dir] [-n num]
[-o list] [-P arg] [-r cn] [-T dev] [-w name] [-W name]
[file ...]
groff -h
groff --help
Several features of the above example are of note.
• The empty request (.), which does nothing, is used for vertical
spacing in the input file for readability by the document main-
tainer. Do not put empty lines in a roff source document.
• The command and option names are presented in bold to cue the
user that they should be input literally.
• Option dashes are specified with the ‘\-’ escape sequence; this
is an important practice to make them clearly visible and to fa-
cilitate cut-and-paste from the rendered man page to a shell
prompt or text file.
• Option arguments and command operands are presented in italics
(underlined on some output devices, such as terminals and emula-
tors), to cue the user that they must be replaced with appropri-
ate text.
• Symbols that are neither to be typed literally nor simply re-
placed appear in the roman style; brackets surround optional ar-
guments, and an ellipsis indicates that the previous syntactical
element may be repeated arbitrarily.
Some man pages use a brace-and-pipe notation such as
“{--diff|--compare}” to indicate that one and only one of the
‘|’-separated items within the braces must be input. If this
braced construct is furthermore surrounded by square brackets,
it means that at most one of the items is accepted.
Authors of man pages should note the use of the zero-width space
escape sequence ‘\&’ on both sides of the ellipsis; this is a
good practice to avoid surprises in the event the ellipsis gets
refilled in your text editor. See “Portability”, below. The
morbidly curious may consult groff(7) regarding the narrow-space
escape sequence ‘\|’.
Hyperlink and email macros
Email addresses are bracketed with .MT/.ME and URL hyperlinks with
.UR/.UE.
These macros are not defined on legacy Unix systems running classic
troff. To be certain your page will be portable to those systems, copy
their definitions from the an-ext.tmac file of a groff installation.
.MT address
.ME [punctuation]
Identify address as an RFC 6068 addr-spec for a “mailto:” URI
with the text between the two macro calls as the link text. A
punctuation argument to .ME is placed at the end of the link
text without intervening space. Note that address may not be
visible in the output text, particularly if the man page is be-
ing viewed as HTML. On a device that is not a browser, address
is set in angle brackets after the link text and before punctua-
tion.
When rendered by groff to a TTY or PostScript output device,
Contact
.MT fred.foonly@\:fubar.net
Fred Foonly
.ME
for more information.
displays as: “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for
more information.”.
The use of ‘\:’ to insert hyphenless discretionary breaks is a
groff extension and can be omitted.
.UR URL
.UE [punctuation]
Identify URL as an RFC 3986 URI hyperlink with the text between
the two macro calls as the link text. A punctuation argument to
.UE is placed at the end of the link text without intervening
space. Note that URL may not be visible in the output text,
particularly if the man page is being viewed as HTML. On a de-
vice that is not a browser, URL is set in angle brackets after
the link text and before punctuation.
When rendered by groff to a TTY or PostScript output device,
The GNU Project of the Free Software Foundation hosts the
.UR https://\:www.gnu.org/\:software/\:groff/
Groff home page
.UE .
displays as: “The GNU Project of the Free Software Foundation
hosts the Groff home page ⟨https://www.gnu.org/software/
groff/⟩.”.
The use of ‘\:’ to insert hyphenless discretionary breaks is a
groff extension and can be omitted.
Font style macros
The man macro package is limited in its font styling options, offering
only bold (.B), italic (.I), and roman (the default). Italic text is
usually set underscored instead on terminals and other classical nroff-
style output devices. The .SM and .SB macros set text in roman or
bold, respectively, at a smaller point size; these differ visually from
regular-sized roman or bold text only on troff-style output devices.
The foregoing macros cause word breaks before and after their argu-
ments, but it is often necessary to set text in different styles with-
out intervening whitespace. The macros .BI, .BR, .IB, .IR, .RB, and
.RI, where ‘B’, ‘I’, and ‘R’ indicate bold, italic, and roman, respec-
tively, set their odd- and even-numbered arguments in alternating
styles, with no whitespace separating them.
Because font styles are presentational rather than semantic, conflict-
ing traditions have arisen regarding which font styles should be used
to mark file or path names, environment variables, in-line literals,
and even man page cross-references.
The default font size and family (for troff output devices) is 10-point
Times. The default style is roman.
.B [text]
Set text in bold. If the macro is given no arguments, the text
of the next input line is set in bold.
Use bold for literal portions of syntax synopses, for command-
line options in running text, and for literals that are major
topics of the subject under discussion; for example, this page
uses bold for macro and register names. In .EX/.EE examples of
interactive I/O (such as a shell session), set only the user-
typed input in bold.
.I [text]
Set text in italics. If the macro is given no arguments, the
text of the next input line is set in italics.
Use italics for file and path names, for environment variables,
for enumeration or preprocessor constants in C, for variable
(user-determined) portions of syntax synopses, for the first oc-
currence only of a technical concept being introduced, for names
of works of software (including commands and functions, but ex-
cluding names of operating systems or their kernels), and any-
where a parameter requiring replacement by the user is encoun-
tered. An exception involves variable text in a context that is
already marked up in italics, such as file or path names with
variable components; in such cases, follow the convention of
mathematical typography: set the file or path name in italics as
usual (see .IR below), but use roman for the variable part, and
italics again in running roman text when referring to the vari-
able material.
.SM [text]
Set text one point size smaller than the default size. If the
macro is given no arguments, the text of the next input line is
set smaller.
Note: nroff-style output devices, such as terminals, will render
text at the normal font size instead. Do not rely upon .SM to
communicate semantic information distinct from using roman style
at the normal size; it will be hidden from readers using such
devices.
.SB [text]
Set text in bold, one point size smaller than the default size.
If the macro is given no arguments, the text of the next input
line is set smaller and in bold.
Note: nroff-style output devices, such as terminals, will render
text in bold at the normal font size instead. Do not rely upon
.SB to communicate semantic information distinct from using bold
style at the normal size; it will be hidden from readers using
such devices.
Note what is not prescribed for setting in bold or italics above: ele-
ments of “synopsis language” such as ellipses and brackets around op-
tions; proper names and adjectives; titles of anything other than works
of literature or software; identifiers for standards documents or tech-
nical reports such as CSTR #54, RFC 1918, Unicode 11.0, or
POSIX.1-2017; acronyms; and occurrences after the first of a technical
term or piece of jargon. Again, the names of operating systems and
their kernels are, by practically universal convention, set in roman.
Be frugal with the use of italics for emphasis, and particularly with
the use of bold. Brief runs of literal text, such as references to in-
dividual characters or short strings, including section and subsection
headings of man pages, are suitable objects for quotation; see the
‘\(lq’, ‘\(rq’, ‘\(oq’, and ‘\(cq’ escapes in subsection “Portability”
below.
Unlike the above font style macros, the font alternation macros below
accept only arguments on the same line as the macro call. If white-
space is required within one of the arguments, first consider whether
the same result could be achieved with as much clarity by using the
single-style macros on separate input lines. When it cannot, double-
quote an argument with one or more embedded space characters. Setting
all three different styles within one whitespace-delimited word
presents challenges; it is possible with the ‘\c’ and/or ‘\f’ escapes,
but see subsection “Portability” below for caveats.
.BI bold-text italic-text ...
Set each argument in bold and italics, alternately.
.BI \-r name = n
.BR bold-text roman-text ...
Set each argument in bold and roman, alternately.
Any such change becomes effective with the first use of
.BR .NH ,
.I after
the new alias is defined.
.IB italic-text bold-text ...
Set each argument in italics and bold, alternately.
All macro package files must be named
.IB name .tmac
to fully use the
.I tmac
mechanism.
.IR italic-text roman-text ...
Set each argument in italics and roman, alternately.
This is the first command of the
.IR prologue .
.RB roman-text bold-text ...
Set each argument in roman and bold, alternately.
Also, the statement
.RB \(oq "delim on" \(cq
is not handled specially.
.RI roman-text italic-text ...
Set each argument in roman and italics, alternately.
.RI [ file
\&.\|.\|.\&]
Horizontal and vertical spacing
The indent argument accepted by .RS, .IP, .TP, and the deprecated .HP
is a number plus an optional scaling indicator. If no scaling indica-
tor is given, the man package assumes ‘n’; that is, the width of a let-
ter “n” in the font current when the macro is called. See section “Nu-
merical Expressions” in groff(7) for further details. An indent speci-
fied in a call to .IP, .TP, or the deprecated .HP persists until (1)
another of these macros is called with an explicit indent argument, or
(2) .SH, .SS, or .PP or its synonyms is called; these clear the indent
entirely.
Indents set by .RS move the left margin and persist until .RS, .RE,
.SH, or .SS is called. The default indentation, exhibited by ordinary
.PP paragraphs not within an .RS/.RE relative indent, is 7.2n in troff
mode and 7n in nroff mode. The HTML output device is an exception; it
ignores indentation completely. This same indentation is used again
(additively) for the defaults of .IP, .TP, .RS, and the deprecated .HP.
Section headings (.SH) are set flush with the left margin of the output
device, and subsection headings (.SS) are indented 3n.
Resist the temptation to mock up tabular or multi-column output with
ASCII tab characters or the indentation arguments to .IP, .TP, .RS, or
the deprecated .HP; the result may not render comprehensibly on an out-
put device you fail to check, or which is developed in the future. The
table preprocessor tbl(1) can likely meet your needs.
The following macros cause a line break with the insertion of vertical
space: .SH, .SS, .TP, .TQ, .PP (and its synonyms), .IP, and the depre-
cated .HP. The default inter-section and inter-paragraph spacing is
1 line in nroff mode, and 0.4v in troff mode. (The deprecated macro
.PD can change this vertical spacing, but its use is discouraged.) The
macros .RS, .RE, .EX, and .EE also cause a break but no insertion of
vertical space.
Number registers
Number registers are described in section “Options” below.
String registers
The following strings are defined.
\*R expands to the character escape for the “registered sign” glyph,
‘\(rg’, if available, and “(Reg.)” otherwise.
\*S expands to an escape setting the font size to the document de-
fault.
\*(HF expands to the font identifier used to print headings and sub-
headings. The default is ‘B’.
\*(lq
\*(rq expand to the character escapes for left and right double-quota-
tion marks, ‘\(lq’ and ‘\(rq’, respectively.
\*(Tm expands to the character escape for the “trade mark sign” glyph,
‘\(tm’, if available, and “(TM)” otherwise.
Interaction with preprocessors
When a preprocessor like tbl or eqn is needed, a hint can be given to
the man page formatter by making the first line of a man page look like
this:
'\" word
Note that the line starts with an apostrophe ('), not a dot, and that a
single space character follows the double quote. The word consists of
one letter for each needed preprocessor: ‘e’ for eqn, ‘r’ for refer,
and ‘t’ for tbl. Modern implementations of the man program interpret
this first line and automatically call the right preprocessor(s).
The usual tbl and eqn macros for table and equation inclusion, .TS,
.T&, .TE, .EQ, and .EN, may be used freely. Note that nroff output de-
vices are extremely limited in presentation of mathematical equations.
Portability
The two major syntactical categories of roff languages are requests and
escapes. Since the man macros are implemented in terms of groff re-
quests and escapes, one can, in principle, supplement the functionality
of man with these lower-level elements where necessary.
Note, however, that using raw groff requests is likely to make your
page render poorly on the class of viewers that transform it to HTML.
Some requests make implicit assumptions about things like character and
page sizes that may not hold in an HTML environment; also, many of
these viewers don't interpret the full groff vocabulary, a problem that
can lead to portions of your text being silently dropped.
For portability to modern viewers, it is best to write your page en-
tirely with the macros described in this page (except for the ones
identified as deprecated, which should be avoided). The macros we have
described as extensions (.EX/.EE, .SY/.OP/.YS, .UR/.UE, and .MT/.ME)
should be used with caution, as they may not yet be built in to some
viewer that is important to your audience. If in doubt, copy the im-
plementation into your page—after the .TH call and the “Name” section,
to accommodate timid mandb implementations.
Similar caveats apply to escapes. Some escape sequences are however
required for correct typesetting even in man pages and usually do not
cause portability problems:
\" Comment. Everything after the double-quote to the end of the
input line is ignored. Whole-line comments are frequently
placed immediately after the empty request ‘.’.
\newline
Join the next input line to the current one. Except for the up-
date of the input line counter (used for diagnostic messages and
related purposes), a series of lines ending in backslash-newline
is transparent to groff. Use this escape to break excessively
input long lines for document maintenance.
\~ Adjustable, non-breaking space character. Use this escape to
prevent a break inside a short phrase or between a numerical
quantity and its corresponding unit(s).
Before starting the motor, set the output speed to\~1.
There are 1,024\~bytes in 1\~kiB.
CSTR\~#8 documents the B language.
\& Zero-width space. Append to an input line to prevent an end-of-
sentence punctuation sequence from being recognized as such, or
insert at the beginning of an input line to prevent a dot or
apostrophe from being interpreted as the beginning of a roff re-
quest.
\(aq ASCII apostrophe. Use for syntax elements of programming lan-
guages because some output devices might replace unescaped apos-
trophes with right single quotation marks.
\(oq Opening single quotation mark.
\(cq Closing single quotation mark.
Use these for paired directional single quotes, ‘like this’.
\(dq ASCII double-quote. Sometimes needed after macro calls to pre-
vent the interpretation of the ASCII quotation mark character
‘"’ as the beginning or end of a macro argument.
\(lq Left double quotation mark.
\(rq Right double quotation mark.
Use these for paired directional double quotes, “like this”.
\(em Em-dash. Use for an interruption in a sentence—such as this
one.
\(en En-dash. Use to separate the two ends of a range, in particular
between numbers, for example: the digits 1–9.
\(ga ASCII grave accent. Use for syntax elements of programming lan-
guages, for example shell command substitutions, because some
output devices might replace unescaped grave accents with left
single quotation marks.
\(ha ASCII circumflex accent. Use for syntax elements of programming
languages because some output devices might replace unescaped
circumflex accents with non-ASCII glyphs like the Unicode U+02C6
modifier letter circumflex.
\(ti ASCII tilde. Use for syntax elements of programming languages
because some output devices might replace unescaped tildes with
non-ASCII glyphs like the Unicode U+02DC small tilde.
\- Minus sign. Also use this to display syntax elements that re-
quire the ASCII hyphen-minus character, for example command-line
options and C language operators. The unescaped ‘-’ input char-
acter is not appropriate for these cases because it may render
as a hyphen on some output devices.
\c If this escape sequence occurs at the end of an input line, no
white space is inserted between the last glyph on it and the
first glyph resulting from the next input line. This is occa-
sionally useful when three different fonts are needed in a sin-
gle word.
Normally, the final output file should be named
.IB file .pdf\c
\&.
Note that when using this trick with the .BI or .RI macros, you
will need to manually add an italic correction escape ‘\/’ be-
fore the ‘\c’ due to way macros expand their arguments.
Files processed with
.B groff \-mom
(or
.BI "\-m " mom\/\c
) produce PostScript output by default.
Alternatively, and perhaps with better portability, the ‘\f’
font escape sequence can be used; see below. Using ‘\c’ to in-
clude the output from more than one input line into the next-
line argument of a .TP macro will render incorrectly with groff
1.22.3, mandoc 1.14.1, older versions of these programs, and
perhaps with some other formatters.
\e Widely used in man pages to represent a backslash output glyph.
It works reliably as long as the .ec request is not used, which
should never happen in man pages, and it is slightly more porta-
ble than the more exact ‘\(rs’ (“reverse solidus”) escape se-
quence.
\fB, \fI, \fR, \fP
Switch to bold, italic, roman, or back to the previous font, re-
spectively. Either these or ‘\c’ is needed when three different
fonts are required in a single whitespace-delimited word.
.RB [ \-\-reference\-dictionary=\fI\,name\/\fP ]
.RB [ \-\-reference\-dictionary=\c
.IR name ]
Font escapes may be more portable than ‘\c’. As shown above, it
is up to you to account for italic corrections with ‘\/’ and
‘\,’, which are themselves groff extensions, if desired and if
supported by your implementation.
Note that ‘\fP’ reliably returns to the style in use immediately
preceding the previous ‘\f’ escape only if no sectioning, para-
graph, or font face macro calls have intervened.
As long as only two fonts are needed in any single whitespace-
delimited word, font alternation macros like .BI usually result
in more readable source code than ‘\f’ escapes do.
For maximum portability, escape sequences and special characters not
listed above are better avoided in man pages.
Deprecated features
Use of the following is discouraged.
.AT [system [release]]
Alter the footer for use with AT&T man pages, overriding any
definition of the footer-outside argument to .TH. This macro
exists only for compatibility; don't use it.
The first argument system can be:
3 7th edition (default)
4 System III
5 System V
The optional second argument release specifies the release num-
ber, such as in “System V Release 3”.
.BT Set the page footer. Redefine this macro to get control of the
footer.
.DT Set tabs every 0.5 inches. Since this macro is always called
during a .TH macro, it makes sense to call it only if the tab
positions have been changed.
Use of this presentation-level macro is deprecated. It trans-
lates poorly to HTML, under which exact whitespace control and
tabbing are not readily available. Thus, information or dis-
tinctions that you use .DT to express are likely to be lost. If
you feel tempted to use it, you should probably be composing a
table using tbl(1) markup instead.
.HP [indent]
Set up a paragraph with a hanging left indentation. The indent
argument, if present, is handled as with .TP.
Use of this presentation-level macro is deprecated. While it is
universally portable to legacy Unix systems, a hanging indenta-
tion cannot be expressed naturally under HTML, and many HTML-
based manual viewers simply interpret it as a starter for a nor-
mal paragraph. Thus, any information or distinction you tried
to express with the indentation may be lost.
.PD [vertical-space]
Define the vertical space between paragraphs or (sub)sections.
The optional argument vertical-space specifies the amount of
space; the default scaling is ‘v’). Without an argument, the
spacing is reset to its default value; see “Horizontal and ver-
tical spacing” above.
Use of this presentation-level macro is deprecated. It trans-
lates poorly to HTML, under which exact control of inter-para-
graph spacing is not readily available. Thus, information or
distinctions that you use .PD to express are likely to be lost.
.PT Set the page header. Redefine this macro to get control of the
header.
.UC [version]
Alter the footer for use with BSD man pages, overriding any def-
inition of the footer-outside argument to .TH. This macro ex-
ists only for compatibility; don't use it.
The argument version can be:
3 3rd Berkeley Distribution (default)
4 4th Berkeley Distribution
5 4.2 Berkeley Distribution
6 4.3 Berkeley Distribution
7 4.4 Berkeley Distribution
History
According to its own man(7) page, Version 7 Unix (1979) supported all
of the macros described in this page not listed as GNU extensions, ex-
cept .P, .SB, .SS, and the deprecated .AT, .BT, .PT, and .UC. The only
string registers defined were R and S; no number registers were docu-
mented.
OPTIONS
The following groff options set number registers recognized and used by
the man macro package.
-rcR=1 Continuous rendering. Create a single, very long page instead
of multiple pages. This is the default in nroff mode. Use
-rcR=0 to disable it.
-rC1 Number pages continuously. If more than one man page is given
on the command line, number the pages continuously, rather than
starting each at 1.
-rD1 Enable double-sided printing. Footers for even and odd pages
are formatted differently; see the description of .TH in “Docu-
ment structure macros”, above.
-rFT=footer-distance
Set distance of the footer, relative to the bottom of the page
if negative or relative to the top if positive, to footer-dis-
tance. The default is -0.5i.
-rHY=flags
Set hyphenation flags. Permissible values of flags are docu-
mented in section “Hyphenation” of groff(7). The default is 4
if continuous rendering is enabled (-rcR=1 above), and 6 other-
wise.
-rIN=indent
Set the body text indentation (for normal paragraphs) to indent.
See “Horizontal and vertical spacing” above for the default in-
dentation value. For nroff, indent should always be an integer
multiple of unit ‘n’ to get consistent indentation.
-rLL=line-length
Set line length. If this option is not given, the line length
is set to respect any value set by a prior “.ll” request (which
must be in effect when the .TH macro is invoked), if this dif-
fers from the built-in default for the formatter; otherwise it
defaults to 78n in nroff mode and 6.5i in troff mode.
Note that the use of a “.ll” request to initialize the line
length is supported for backward compatibility with some ver-
sions of the man program; direct initialization of the LL regis-
ter should always be preferred to the use of such a request. In
particular, note that a “.ll 65n” request does not preserve the
normal nroff default line length (the man default initialization
to 78n prevails), whereas the -rLL=65n option, or an equivalent
“.nr LL 65n” request preceding the use of the .TH macro, does
set a line length of 65n.
-rLT=title-length
Set title length. If this option is not given, the title length
defaults to the line length.
-rPn Start enumeration of pages at n rather than 1.
-rSpoint-size
Use point-size as the base document font size. Acceptable val-
ues are 10, 11, or 12. See subsection “Font style macros” above
for the default.
-rSN=subsection-indent
Set subsection indentation to subsection-indent. See “Horizon-
tal and vertical spacing” above for the default indentation
value.
-rXp After page p, number pages as pa, pb, pc, and so forth. For ex-
ample, the option -rX2 produces the following page numbers: 1,
2, 2a, 2b, 2c, and so on.
FILES
/usr/share/groff/1.22.4/tmac/man.tmac
/usr/share/groff/1.22.4/tmac/an.tmac
These are wrapper files to call andoc.tmac.
/usr/share/groff/1.22.4/tmac/andoc.tmac
This brief groff program detects whether the man or mdoc macro
package is being used by a document and loads the correct macro
definitions, taking advantage of the fact that pages using them
must call .TH or .Dd, respectively, as their first macro. Be-
cause the wrappers above load this file, a man program or user
typing, for example, “groff -man page.1”, need not know which
package the file page.1 uses. Multiple man pages, in either
format, can be handled.
/usr/share/groff/1.22.4/tmac/an-old.tmac
Most man macros are contained in this file. It also loads the
GNU extensions from an-ext.tmac (see below).
/usr/share/groff/1.22.4/tmac/an-ext.tmac
The extension macro definitions for .SY, .OP, .YS, .TQ, .EX/.EE,
.UR/.UE, and .MT/.ME are contained in this file, which is writ-
ten in classic troff and permissively licensed—not copylefted.
Man page authors concerned about portability to legacy Unix sys-
tems are encouraged to copy these definitions into their pages,
and maintainers of troff implementations or work-alike systems
that format man pages are encouraged to re-use them.
Note that the definitions for these macros are read after the
call of .TH, so they will replace any macros of the same names
preceding it in your file. If you use your own implementations
of these macros, they must be defined after calling .TH to have
any effect.
/usr/share/groff/site-tmac/man.local
Local changes and customizations should be put into this file.
NOTES
Some tips on troubleshooting your man pages follow.
• .RS doesn't indent relative to my indented paragraph
The .RS macro sets the indentation relative to the amount of a
normal paragraph (.PP and its synonyms). The same default in-
dentation amount is used for .RS, .IP, .TP, and the deprecated
.HP. If you need to start an indent relative to an indented
paragraph, call .RS repeatedly until an acceptable indentation
is achieved, or give .RS an indentation argument that is at
least as much as the paragraph's indentation amount relative to
an adjacent .PP paragraph. See “Horizontal and vertical spac-
ing” above for the values.
• .RE doesn't reset the indent to the expected level
• warning: scale indicator invalid in this context
• warning: number register 'an-saved-marginn' not defined
• warning: number register 'an-saved-prevailing-indentn' not defined
The .RS macro takes an indentation amount as an argument; the
.RE macro's argument is a specific indentation level. .RE 1
goes to the level before any .RS macros were called, .RE 2 goes
to the level of the first .RS call you made, and so forth. If
you desire symmetry in your macro calls, simply issue one .RE
without an argument for each .RS that precedes it.
After calls to the .SH and .SS sectioning macros, all relative
indents are cleared and calls to .RE have no effect.
AUTHORS
The GNU version of the man macro package was written by James Clark and
contributors. The extension macros were written by Werner Lemberg ⟨wl@
gnu.org⟩ and Eric S. Raymond ⟨esr@thyrsus.com⟩.
This document was originally written for the Debian GNU/Linux system by
Susan G. Kleinmann ⟨sgk@debian.org⟩. It was corrected and updated by
Werner Lemberg and G. Branden Robinson. The extension macros were doc-
umented by Eric S. Raymond; he also originated the portability section,
to which Ingo Schwarze contributed most of the material on escape se-
quences.
SEE ALSO
Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
Lemberg, is the main groff documentation. You can browse it interac-
tively with “info groff”.
tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.
man(1) describes the man page formatter on your system.
groff_mdoc(7) describes the groff version of the BSD-originated alter-
native macro package for man pages.
groff(7), groff_char(7), man(7)
groff 1.22.4 7 March 2023 GROFF_MAN(7)
Generated by dwww version 1.15 on Sat Jun 1 21:20:50 CEST 2024.