'\" t
.\" This page is generated by m4 from tmac/groff_man.7.man.in.
.TH groff_man 7 "2026-03-15" "groff 1.24.1"
.SH Name
groff_man \- compose manual pages with GNU
.I roff
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
.\" Copyright 1999-2017 Free Software Foundation, Inc.
.\"           2017      Ingo Schwarze
.\"           2017-2025 G. Branden Robinson
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of
.\" this manual under the conditions for verbatim copying, provided that
.\" the entire resulting derived work is distributed under the terms of
.\" a permission notice identical to this one.
.\"
.\" Permission is granted to copy and distribute translations of this
.\" manual into another language, under the above conditions for
.\" modified versions, except that this permission notice may be
.\" included in translations approved by the Free Software Foundation
.\" instead of in the original English.
.
.
.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
.do nr *groff_groff_man_7_man_C \n[.cp]
.cp 0
.
.\" Define fallback for groff 1.23's MR macro if the system lacks it.
.nr do-fallback 0
.if !\n(.f           .nr do-fallback 1 \" mandoc
.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
.if \n[do-fallback]  \{\
.  de MR
.    ie \\n(.$=1 \
.      I \%\\$1
.    el \
.      IR \%\\$1 (\\$2)\\$3
.  .
.\}
.rr do-fallback
.
.
.\" ====================================================================
.SH Synopsis
.\" ====================================================================
.
.SY "groff \-man"
.RI [ option\~ .\|.\|.\&]
.RI [ file\~ .\|.\|.]
.YS
.
.SY "groff \-m man"
.RI [ option\~ .\|.\|.\&]
.RI [ file\~ .\|.\|.]
.YS
.
.
.\" ====================================================================
.SH Description
.\" ====================================================================
.
The GNU implementation of the
.I man
macro package is part of the
.I groff
document formatting system.
.
It is used to compose manual pages
.\" We use an unbreakable space \~ here to keep the phrase intact for
.\" its introduction; in subsequent discussion, that is not important.
(\[lq]man\~pages\[rq])
like the one you are reading.
.
This document presents the macros thematically;
for those needing only a quick reference,
the following table lists them alphabetically,
with references to appropriate subsections below.
.
.
.P
Readers who are not already experienced
.I groff
users should consult
.MR groff_man_style 7 ,
an expanded version of this document,
for additional explanations and advice.
.
It covers only those concepts required for man page document
maintenance,
and not the full breadth of the
.I groff
typesetting system.
.
.
.P
.if t .vs 11.75p \" begin hideous cheat for U.S. letter paper
.if n .if \n[LL]<68n .RS -3n \" begin shameless cheat for slim terminals
.TS
l l l.
Macro	Meaning	Subsection
.T&
lB l l.
_
\&.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
\&.HP	Begin hanging paragraph	Paragraphing macros
\&.I	Italic	Font style macros
\&.IB	Italic, bold alternating	Font style macros
\&.IP	Indented paragraph	Paragraphing macros
\&.IR	Italic, roman alternating	Font style macros
\&.LP	Begin paragraph	Paragraphing macros
\&.ME	Mail-to end	Hyperlink macros
\&.MR	Man page cross reference	Hyperlink macros
\&.MT	Mail-to start	Hyperlink macros
\&.P	Begin paragraph	Paragraphing macros
\&.PP	Begin paragraph	Paragraphing macros
\&.RB	Roman, bold alternating	Font style macros
\&.RE	Relative inset end	Document structure macros
\&.RI	Roman, italic alternating	Font style macros
\&.RS	Relative inset start	Document structure macros
\&.SH	Section heading	Document structure macros
\&.SM	Small	Font style macros
\&.SS	Subsection heading	Document structure macros
\&.SY	Synopsis start	Synopsis macros
\&.TH	Title heading	Document structure macros
\&.TP	Tagged paragraph	Paragraphing macros
\&.TQ	Supplemental paragraph tag	Paragraphing macros
\&.UE	URI end	Hyperlink macros
\&.UR	URI start	Hyperlink macros
\&.YS	Synopsis end	Synopsis macros
.TE
.if n .if \n[LL]<68n .RE \" end shameless cheat for slim terminals
.if t .vs \" end hideous cheat for U.S. letter paper
.
.
.P
We discuss other macros
.RB ( AT ,
.BR DT ,
.BR OP ,
.BR PD ,
.BR SB ,
and
.BR UC )
in subsection \[lq]Deprecated features\[rq] below.
.
.
.P
Throughout Unix documentation,
a manual entry is referred to simply as a \[lq]man page\[rq],
regardless of its length,
without gendered implication,
and irrespective of the macro package selected for its composition.
.\" ====================================================================
.SS "Macro reference preliminaries"
.\" ====================================================================
.
A tagged paragraph describes each macro.
.
We present coupled pairs together,
as with
.B EX
and
.BR EE .
.
If you require an empty macro argument,
specify it as a pair of neutral double quotes
.RB ( \[dq]\^\[dq] ).
.
Most macro arguments are formatted as text in the output;
exceptions are noted.
.
.
.
.\" ====================================================================
.SS "Document structure macros"
.\" ====================================================================
.
Document structure macros organize a man page's content.
.
All of them break the output line.
.
.B TH
(title heading)
identifies the document as a man page and configures the page headers
and footers.
.
Section headings
.RB ( SH ),
one of which is mandatory and many of which are conventionally expected,
facilitate location of material by the reader and aid the man page
writer to discuss all essential aspects of the topics presented.
.
Subsection headings
.RB ( SS )
are optional and permit sections that grow long to develop in a
controlled way.
.
Many technical discussions benefit from examples;
lengthy ones,
especially those reflecting multiple lines of input to or output from
the system,
are usefully bracketed by
.B EX
and
.BR EE .
.
When none of the foregoing meets a structural demand,
use
.BR RS / RE
to inset a region within a (sub)section.
.
.
.TP
.BI .TH " identifier section"\~\c
.RI [ footer-middle \~\c
.RI [ footer-inside \~\c
.RI [ header-middle ]]]
Break the page,
reset the page number to\~1
(unless the
.B \-rC1
option is given),
and use the arguments to populate the page header and footer.
.
Together,
.I identifier
and the
.I section
of the manual to which it belongs
can uniquely identify a
.I man
document on the system.
.
See
.MR man 1
or
.MR intro 1
for the manual sectioning applicable to your system.
.
.I identifier
and
.I section
are positioned at the left and right in the header;
the latter is set after the former,
in parentheses and without space.
.
.I footer-middle
is centered in the footer.
.
By default,
.I footer-inside
is positioned at the bottom left.
.
Use of the double-sided layout option
.B \-rD1
places
.I footer-inside
at the bottom left on recto (odd-numbered) pages,
and the bottom right on verso (even-numbered) pages.
.
By default,
the outside footer is the page number.
.
Use of the continuous-rendering option
.B \-rcR=1
replaces it with
.I identifier
and
.I section,
as in the header.
.
.I header-middle
is centered in the header.
.
If
.I section
is an integer between 1 and\~9 (inclusive),
there is no need to specify
.I header-middle;
.I an.tmac
supplies text for it.
.
If
.I identifier
or
.I footer-inside
would overrun the space available in the header and/or footer,
this package may abbreviate them with
ellipses.
.
.I "groff man"
suppresses headers and footers in HTML output.
.
.\" Does anyone try to do anything different?  GBR hasn't seen it.
.\" This feature is intended only for formatting multiple
.\" .I man
.\" documents in sequence.
.
.
.IP
A valid
.I man
document calls
.B TH
only once,
early in the file,
prior to any other macro calls.
.
.
.TP
.BR .SH " ["\c
.IR heading-text ]
Set
.I heading-text
as a section heading.
.
Given no argument,
.B SH
plants a one-line input trap;
text on the next line
.\", which can be formatted with a macro, \" true but discouraged
becomes
.I heading-text.
.
The heading text is set in bold
(or the font specified by the string
.BR HF ),
and,
on typesetters,
slightly larger than the base type size.
.
If the heading font
.B \[rs]*[HF]
is bold,
use of an italic style in
.I heading-text
is mapped to the bold-italic style if available in the font family.
.
The inset level is reset to 1;
see subsection \[lq]Horizontal and vertical spacing\[rq] below.
.
Text lines after the call are set as an ordinary paragraph
.RB ( P ).
.
.
.IP
The content of
.I heading-text
and ordering of sections follows a set of common practices,
as does much of the layout of material within sections.
.
For example,
a section called \[lq]Name\[rq] or \[lq]NAME\[rq] must exist,
must be the first section after the
.B TH
call,
and must contain only text of the form
.RS \" Invisibly move left margin to current IP indentation.
.RS \" Now indent further, visibly.
.IR topic [\c
.BI , " another-topic"\c
].\|.\|.\& \e\-
.I summary-description
.RE \" Move left margin back to IP indentation.
for tools like
.MR makewhatis 8
or
.MR mandb 8
to index them.
.RE \" Move left margin back to standard position.
.
.
.TP
.BR .SS " ["\c
.IR subheading-text ]
Set
.I subheading-text
as a subsection heading indented between a section heading and an
ordinary paragraph
.RB ( P ).
.
Given no argument,
.B SS
plants a one-line input trap;
text on the next line
.\", which can be formatted with a macro, \" true but discouraged
becomes
.I subheading-text.
.
The subheading text is set in bold
(or the font specified by the string
.BR HF ).
.
If the heading font
.B \[rs]*[HF]
is bold,
use of an italic style in
.I subheading-text
is mapped to the bold-italic style if available in the font family.
.
The inset level is reset to 1;
see subsection \[lq]Horizontal and vertical spacing\[rq] below.
.
Text lines after the call are set as an ordinary paragraph
.RB ( P ).
.
.
.TP
.B .EX
.TQ
.B .EE
Begin and end example.
.
After
.BR EX ,
filling is disabled
(and,
on typesetters,
a monospaced font family is selected).
.
Calling
.B EE
enables filling
(and restores the previous family).
.
.
.IP
Ninth Edition Unix introduced the
.\" Also see subsection "History" below...
.B EX
and
.B EE
extensions.
.
Documenter's Workbench (DWB),
Heirloom Doctools,
and
Plan\~9
.IR troff s, \" DWB, Heirloom, Plan 9
and
.I mandoc
(since 1.12.2)
support them.
.
Solaris
.I troff \" Solaris
does not.
.\" Neatroff doesn't ship (m)an macros.
.
.
.TP
.BR .RS " ["\c
.IR inset-amount ]
Start new relative inset.
.
.I man
saves any current inset amount
and moves right by:
.I inset-amount,
if specified;
the
.I indentation
amount of the preceding
.BR IP ,
.BR TP ,
or
.B HP
macro call if no (sub-)sectioning or ordinary paragraphing macro has
intervened;
or the amount of the
.B IN
register.
.
.B RS
calls can nest;
each increments by\~1 the
.I level
used by
.BR RE .
.
The level prior to any
.B RS
call is\~1.
.
.
.TP
.BR .RE " ["\c
.IR inset-level ]
End a relative inset,
reducing it to that of
.I inset-level
(or by\~1 if not specified)
and restoring the corresponding inset amount.
.
.
.\" ====================================================================
.SS "Paragraphing macros"
.\" ====================================================================
.
These macros break the output line.
.
An
.I ordinary
paragraph
.RB ( P )
indents all output lines by the same amount.
.
A hanging paragraph
.RB ( HP )
is a cosmetic variant of
.B P
with a hanging indent.
.
Definition lists frequently occur in man pages;
these can be set as
.I "tagged paragraphs,"
which have one
.RB ( TP )
or more
.RB ( TQ )
leading tags followed by a paragraph that has an additional indentation.
.
The indented paragraph
.RB ( IP )
macro
can continue the indented content of a narrative started
with
.BR TP ,
or present an itemized or ordered list.
.
If a paragraphing macro has been called since
.B SH
or
.BR SS ,
all except
.B TQ
follow the break with vertical space
(in an amount configured by the deprecated
.B PD
macro);
see subsection \[lq]Horizontal and vertical spacing\[rq] below.
.
Except for
.BR TQ ,
these macros
reset the type size,
hyphenation,
and adjustment to (configured) defaults,
and the font style to roman.
.\" slack wording for managing stranded lines in PS/PDF output
.\" [end previous text line with semicolon, not period]
.\"see subsections \[lq]Font style macros\[rq] and \[lq]Options\[rq]
.\"below.
.
.
.br
.ne 4v
.TP
.B .P
.TQ
.B .LP
.TQ
.B .PP
Begin a new paragraph;
these macros are synonymous.
.
Any indentation from use of
.BR IP ,
.BR TP ,
or
.B HP
is cleared.
.
The inset amount,
as affected by
.B RS
and
.BR RE ,
is not.
.
.
.TP
.BR .HP " ["\c
.IR indentation ]
Set a paragraph with a hanging indentation.
.
Text on output lines after the first is indented by
.I indentation,
if specified,
and by the amount of the
.B IN
register otherwise.
.
.
.IP
.I Caution:
A hanging indentation cannot be expressed naturally in (pure) HTML,
a hanging paragraph is not distinguishable from an ordinary one if it
formats on only one output line,
and
.RI non- roff -based
man page interpreters may treat
.B HP
as an ordinary paragraph anyway.
.
Thus,
information or distinctions you mean to express with indentation may be
lost.
.
.
.TP
.BR .TP " ["\c
.IR indentation ]
Set an indented paragraph with a leading unindented tag.
.
The macro plants a one-line input trap that honors the
.B \[rs]c
escape sequence;
text on the next line becomes the tag,
set without indentation.
.
Text on subsequent lines is indented by
.I indentation,
if specified,
and by the amount of the
.B IN
register otherwise.
.
If the tag,
plus the \[lq]tag spacing\[rq] stored in the
.B TS
register
(see section \[lq]Options\[rq] below)
is wider than the indentation,
the package breaks the line after the tag.
.
.
.TP
.B .TQ
Set an additional tag for a paragraph tagged with
.BR TP ,
planting a one-line input trap as with
.BR TP .
.
.
.IP
.B TQ
is a GNU extension supported by
Heirloom Doctools
.I troff \" Heirloom
.\" commit 5e4181af2a1562c542caaa3b2cc129e40e3e76e5
(since Git snapshot 151218)
and
.I mandoc
(since 1.14.5)
but not by
DWB,
Plan\~9,
or
Solaris
.IR troff s. \" DWB, Plan 9, Solaris
.
.
.TP
.BR .IP\~ [\c
.IR mark \~\c
.RI [ indentation ]]
Set an indented paragraph with an optional mark.
.
Arguments,
if present,
are handled as with
.BR TP ,
except that the
.I mark
argument to
.B IP
cannot include a macro call,
and the tag separation amount stored in the
.B TS
register is not enforced.
.
.
.\" ====================================================================
.SS "Synopsis macros"
.\" ====================================================================
.
Use
.B SY
and
.B YS
to summarize syntax using familiar Unix conventions.
.
.\" TODO: Determine whether this (is still? was ever?) true.
.\" Furthermore,
.\" some tools are able to interpret these macros semantically and treat
.\" them appropriately for localization and/or presentation.
.
Heirloom Doctools
.I troff \" Heirloom
.\" commit 5e4181af2a1562c542caaa3b2cc129e40e3e76e5
(since Git snapshot 151218)
and
.I mandoc
(since 1.14.5)
support these GNU extensions;
DWB,
Plan\~9,
and
Solaris
.IR troff s \" DWB, Plan 9, Solaris
do not.
.
.
.TP
.BI .SY\~ keyword\~\c
.RI [ suffix ]
Begin synopsis.
.
Adjustment and automatic hyphenation are disabled.
.
If
.B SY
has already been called without a corresponding
.BR YS ,
a break is performed.
.
.I keyword
and any
.I suffix
are set in bold.
.
When
.I suffix
is present,
the package
sets the next word after it without intervening space.
.
If a break is required in subsequent text
(up to a paragraphing,
sectioning,
or
.B YS
macro call),
lines after the first are indented.
.
Unless the previous synopsis's indentation is reused
(see
.B YS
below),
output lines after the first
indent by the width of the pending output line up to the end of
.I keyword
plus a space,
if
.I keyword
is the only argument,
and up to the end of
.I suffix
otherwise.
.
.
.br
.ne 4v
.TP
.BR .YS\~ [\c
.IR reuse-indentation ]
End synopsis,
breaking the line and restoring
indentation,
adjustment,
and hyphenation
to their previous states.
.
If an argument is given,
the indentation corresponding to the previous
.B SY
call is reused by the next
.B SY
call instead of being computed.
.
.
.\" ====================================================================
.SS "Hyperlink macros"
.\" ====================================================================
.
Man page cross references
are best presented with
.BR MR .
.
Mark email addresses with
.BR MT / ME
and other sorts of URI with
.BR UR / UE .
.
To hyperlink text,
terminals and pager programs must support ECMA-48 OSC\~8 escape
sequences
(see
.MR grotty 1 ).
.
When device support is unavailable or disabled with the
.B U
register
(see section \[lq]Options\[rq] below),
.I "groff man"
renders these URIs between angle brackets
.RB ( \[la]\~\[ra] )
after the linked text.
.
.
.P
.BR MT ,
.BR ME ,
.BR UR ,
and
.B UE
are GNU extensions supported by
Heirloom Doctools
.I troff \" Heirloom
.\" commit 5e4181af2a1562c542caaa3b2cc129e40e3e76e5
(since Git snapshot 151218)
and
.I mandoc
.RB ( UR / UE
since 1.12.3;
.BR MT / ME
since 1.14.2)
but not by
DWB,
Plan\~9 (original),
or
Solaris
.IR troff s. \" DWB, Plan 9, Solaris
.
Plan\~9 from User Space's
.I troff \" plan9port
implements
.BR MR .
.
.
.br
.ne 2v
.P
Prepare arguments to
.BR MR ,
.BR MT ,
and
.B UR
for typesetting;
they can appear in the output.
.
Use special character escape sequences to encode Unicode basic Latin
characters where necessary,
particularly the hyphen-minus.
.\" XXX: We don't need to say this, do we?  It shouldn't be the man(7)
.\" user's problem.
.\" The formatter removes
.\" .B \e:
.\" escape sequences from hyperlinks when supplying
.\" device extension command arguments to output drivers.
.
.
.TP
.BI .MR \~topic\c
.RI \~[ manual-section \~[ trailing-text ]]
.IR (since\~ groff \~1.23) \" TODO: remove note once novelty dies down
Set a man page cross reference as
\[lq]\c
.IB topic ( manual-section )\c
\[rq].
.
If
.I manual-section
is absent,
the package omits the surrounding parentheses.
.
If
.I trailing-text
(typically punctuation)
is specified,
it follows the closing parenthesis without intervening space.
.
Hyphenation is disabled while the cross reference is set.
.
.I topic
is set in the font specified by the
.B MF
string.
.
If
.I manual-section
is present,
the cross reference hyperlinks to a URI of the form
.RB \[lq] man:\c
.IR topic ( manual-section )\[rq].
.
.
.TP
.BI .MT " address"
.TQ
.BR .ME " ["\c
.IR trailing-text ]
Identify
.I address
as an RFC 6068
.I addr-spec
for a \[lq]mailto:\[rq] URI with the text between the two macro
calls as the link text.
.
An argument to
.B ME
is placed after the link text without intervening space.
.
.I address
may not be visible in the rendered document if hyperlinks are enabled
and supported by the output driver.
.
If they are not,
.I address
is set in angle brackets after the link text and before
.I trailing-text.
.
If hyperlinking is enabled but there is no link text,
.I address
is formatted and hyperlinked
.I without
angle brackets,
except when
.I address
appears as a
.B TP
paragraph tag.
.
.
.TP
.BI .UR " uri"
.TQ
.BR .UE " ["\c
.IR trailing-text ]
Identify
.I uri
as an RFC 3986 URI hyperlink with the text between the two macro calls
as the link text.
.
An argument to
.B UE
is placed after the link text without intervening space.
.
.I uri
may not be visible in the rendered document if hyperlinks are enabled
and supported by the output driver.
.
If they are not,
.I uri
is set in angle brackets after the link text and before
.I trailing-text.
.
If hyperlinking is enabled but there is no link text,
.I uri
is formatted and hyperlinked
.I without
angle brackets,
except when
.I uri
appears as a
.B TP
paragraph tag.
.
.
.P
If a
.BR UR / UE
or
.BR MT / ME
pair occurs in a
.B TP
tag
and hyperlinking is unavailable,
.I "groff man"
sets the link target at the beginning
of the indented paragraph,
not as part of the tag,
unless there is no link text.
.
.
.\" ====================================================================
.SS "Font style macros"
.\" ====================================================================
.
The
.I man
macro package is limited in its font styling options,
offering only
.BR bold \~( B ),
.I italic\c
.RB \~( I ),
and roman.
.
Italic text may instead render underscored on terminals.
.
.B SM
sets text at a smaller type size,
which differs visually from regular-sized text only on typesetters.
.
The macros
.BR BI ,
.BR BR ,
.BR IB ,
.BR IR ,
.BR RB ,
and
.B RI
set their odd- and even-numbered arguments
as text in the alternating styles their names indicate,
with no space separating them.
.
.
.P
The default type size and family for typesetters is 10-point Times,
except on the
.B \%X75\-12
and
.B \%X100\-12
devices where the type size is 12 points.
.
The default style is roman.
.
.
.TP
.BR .B \~[\c
.IR text ]
Set
.I text
in bold.
.
Given no argument,
.B B
plants a one-line input trap;
text on the next line,
which can be further formatted with a macro,
is set in bold.
.
.
.TP
.BR .I \~[\c
.IR text ]
Set
.I text
in an italic or oblique face.
.
Given no argument,
.B I
plants a one-line input trap;
text on the next line,
which can be further formatted with a macro,
is set in an italic or oblique face.
.
.
.TP
.BR .SM \~[\c
.IR text ]
Set
.I text
one point smaller than the default type size on typesetters.
.
Given no argument,
.B SM
plants a one-line input trap;
text on the next line,
which can be further formatted with a macro,
is set smaller.
.
.
.br
.ne 2v
.P
Unlike the above font style macros,
the font style alternation macros below set no input traps;
they must be given arguments to have effect.
.
They apply italic corrections as appropriate.
.
.
.
.TP
.BI .BI " bold-text italic-text "\c
\&.\|.\|.\&
Set each argument in bold and italics,
alternately.
.
.
.TP
.BI .BR " bold-text roman-text "\c
\&.\|.\|.\&
Set each argument in bold and roman,
alternately.
.
.
.TP
.BI .IB " italic-text bold-text "\c
\&.\|.\|.\&
Set each argument in italics and bold,
alternately.
.
.
.TP
.BI .IR " italic-text roman-text "\c
\&.\|.\|.\&
Set each argument in italics and roman,
alternately.
.
.
.TP
.BI .RB " roman-text bold-text "\c
\&.\|.\|.\&
Set each argument in roman and bold,
alternately.
.
.
.TP
.BI .RI " roman-text italic-text "\c
\&.\|.\|.\&
Set each argument in roman and italics,
alternately.
.
.
.\" ====================================================================
.SS "Horizontal and vertical spacing"
.\" ====================================================================
.
The package sets all text inboard of the left edge of the output medium
by the amount of the
.I "page offset;"
see register
.B PO
in section \[lq]Options\[rq] below.
.
Headers,
footers
(both set with
.BR TH ),
and section headings
.RB ( SH )
lie at the page offset.
.
.I groff
.I man
indents
subsection headings
.RB ( SS )
by the amount in the
.B SN
register.
.
.
.P
Ordinary paragraphs not within an
.BR RS / RE
inset region are inset by the amount stored in the
.B BP
register;
see section \[lq]Options\[rq] below.
.
The
.B IN
register configures the default indentation amount used by
.B RS
(as the
.IR inset-amount ),
.BR IP ,
.BR TP ,
and
.BR HP ;
an overriding argument
is a number plus an optional scaling unit.
.
If no scaling unit is given,
the
.I man
package assumes \[lq]n\[rq].
.
An indentation specified in a call to
.BR IP ,
.BR TP ,
or
.B HP
persists until
(1) another of these macros is called with an
.I indentation
argument,
or
(2)
.BR SH ,
.BR SS ,
or
.B P
or its synonyms is called;
these clear the indentation entirely.
.\" XXX: This is not true, but they do handle it badly.
.\"
.\" HTML output devices ignore indentation.
.
.
.P
Several macros insert vertical space:
.BR SH ,
.BR SS ,
.BR TP ,
.B P
(and its synonyms),
.BR IP ,
and
.BR HP .
.
They then enable
.I "no-space mode;"
see
.MR groff 7 .
.
The default inter-section and inter-paragraph spacing
is 1v for terminals and 0.4v for typesetters.
.
(The deprecated macro
.B PD
can change this vertical spacing,
but we discourage its use.)
.
Between
.B EX
and
.B EE
calls,
the inter-paragraph spacing is 1v regardless of output
device.
.
.
.\" ====================================================================
.SS Registers
.\" ====================================================================
.
Registers are described in section \[lq]Options\[rq] below.
.
They can be set not only on the command line but in the site
.I man.local
file as well;
see section \[lq]Files\[rq] below.
.
.
.\" ====================================================================
.SS Strings
.\" ====================================================================
.
The following strings are defined for use in man pages.
.
None of these is necessary in a contemporary man page;
see
.MR groff_man_style 7 .
.
.I "groff man"
supports others for configuration of rendering parameters;
see section \[lq]Options\[rq] below.
.
.
.\" In the rest of this section, we retain use of legacy AT&T syntax;
.\" there seems little point in illustrating groff syntax for features
.\" of man(7) that users of groff don't need, and should avoid.
.\"
.\" Special characters named here are not in AT&T's repertoire.
.TP 8n \" accommodate "\e*(Tm", hand-tuned for PDF
.B \e*R
interpolates a special character escape sequence for the \[lq]registered
sign\[rq] glyph,
.BR \e(rg ,
if available,
and \[lq](Reg.)\[rq] otherwise.
.
.
.
.TP
.B \e*S
interpolates an escape sequence setting the type size to the document
default.
.
.
.TP
.B \e*(lq
.TQ
.B \e*(rq
interpolate special character escape sequences for left and right
double-quotation marks,
.B \e(lq
and
.BR \e(rq ,
respectively.
.
.
.TP
.B \e*(Tm
interpolates a special character escape sequence for the \[lq]trade mark
sign\[rq] glyph,
.BR \e(tm ,
if available,
and \[lq](TM)\[rq] otherwise.
.
.
.\" ====================================================================
.SS Hooks
.\" ====================================================================
.
Two macros,
both GNU extensions,\" from groff 1.19
are called internally by the
.I "groff man"
package to format page headers and footers and can be redefined by the
administrator in a site's
.I man.local
file
(see section \[lq]Files\[rq] below).
.
The presentation of
.B TH
above describes the default headers and footers.
.
Because these macros are hooks for
.I "groff man"
internals,
man pages have no reason to call them.
.
Such hook definitions typically consist of \[lq]sp\[rq] and
\[lq]tl\[rq] requests.
.
.B PT
furthermore has the responsibility of emitting a PDF bookmark after
writing the first page header in a document.
.
Consult the existing implementations in
.I an.tmac
when drafting replacements.
.
.
.TP
.B .BT
Set the page footer text
(\[lq]bottom trap\[rq]).
.
.
.TP
.B .PT
Set the page header text
(\[lq]page trap\[rq]).
.
.
.P
To remove a page header or footer entirely,
define the appropriate macro as empty rather than deleting it.
.
.
.\" ====================================================================
.SS "Deprecated features"
.\" ====================================================================
.
Use of the following in man pages for public distribution is
discouraged.
.
.
.TP
.BR .AT " ["\c
.IR system " [" release ]]
Alter the footer for use with legacy AT&T man pages,
overriding any definition of the
.I footer-inside
argument to
.BR TH .
.
This macro exists only to render man pages from historical systems.
.
.
.IP
The inside footer is populated per the value of
.I system.
.
.
.RS \" Invisibly move left margin to current IP indentation.
.RS \" Now indent further, visibly.
.TP
3
7th edition
.I (default)
.
.
.TP
4
System III
.
.
.TP
5
System V
.RE \" Move left margin back to IP indentation.
.RE \" Move left margin back to standard position.
.
.
.IP
The optional
.I release
argument specifies the release number,
as in \[lq]System\~V Release\~3\[rq].
.
.
.TP
.B .DT
Reset tab stops to the default
(every 0.5i).
.
.IP
Use of this presentation-oriented macro is deprecated.
.
It translates poorly to HTML,
under which exact space control and tabulation are not readily
available.
.
Thus,
information or distinctions that you use tab stops to express are likely
to be lost.
.
If you feel tempted to change the tab stops such that calling this macro
later to restore them is desirable,
consider composing a table using
.MR \%tbl 1
instead.
.
.
.br
.ne 5v
.TP
.BI .OP " option-name"\/\c
.RI " [" option-argument ]
Indicate an optional command parameter called
.IR option-name ,
which is set in bold.
.
If the option takes an argument,
specify
.I option-argument
using a noun,
abbreviation,
or hyphenated noun phrase.
.
If present,
.I option-argument
is preceded by a space and set in italics.
.
Square brackets in roman surround both arguments.
.
.
.IP
Use of this quasi-semantic macro,
.\" https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/an.sr#L37
an extension whose name originated in DWB
.IR troff ,\" DWB
is deprecated;
.IR groff 's
interface differs.
.
Neither can easily be used to annotate options
that take optional arguments
or options whose arguments have internal structure
(such as a mixture of literal and variable components).
.
One could work around these limitations
with font selection escape sequences,
but font style alternation macros are preferable;
they are more flexible and perform italic corrections on typesetters.
.
.
.TP
.BR .PD " ["\c
.IR vertical-space ]
Configure the amount of vertical space between paragraphs or
(sub)sections.
.
The optional argument
.I vertical-space
specifies the amount;
the default scaling unit is \[lq]v\[rq].
.
Without an argument,
inter-paragraph spacing resets to its default value;
see subsection \[lq]Horizontal and vertical spacing\[rq] above.
.
.
.IP
Use of this presentation-oriented macro is deprecated.
.
It translates poorly to HTML,
under which exact control of inter-paragraph spacing is not readily
available.
.
Thus,
information or distinctions that you use
.B PD
to express are likely to be lost.
.
.
.TP
.BR .SB \~[\c
.IR text ]
Set
.I text
in bold and
(on typesetters)
one point smaller than the default type size.
.
Given no argument,
.B SB
plants a one-line input trap;
text on the next line,
which can be further formatted with a macro,
is set smaller and in bold.
.
Use of this macro,
an extension originating in SunOS\~4.0
.IR troff ,\" SunOS
.\" ...and which Clark included in groff man(7) from 1.01 or earlier...
is deprecated.
.
.B SM
without an argument,
followed immediately by
.RB \[lq] B
.IR text \[rq],
produces the same output more portably.
.
The macros' order is interchangeable;
put
.I text
with the latter.
.
.
.TP
.BR .UC " ["\c
.IR version ]
Alter the footer for use with legacy BSD man pages,
overriding any definition of the
.I footer-inside
argument to
.BR TH .
.
This macro exists only to render man pages from historical systems.
.
.
.IP
The inside footer is populated per the value of
.I version.
.
.
.RS \" Invisibly move left margin to current IP indentation.
.RS \" Now indent further, visibly.
.TP
.if t \{\
.  \" begin hideous cheat for U.S. letter paper
.  do nr saved-PD \n[PD]
.  do nr PD 0.25v
.\}
3
3rd Berkeley Distribution
.I (default)
.
.
.TP
4
4th Berkeley Distribution
.
.
.TP
5
4.2 Berkeley Distribution
.
.
.TP
6
4.3 Berkeley Distribution
.
.
.TP
7
4.4 Berkeley Distribution
.RE \" Move left margin back to IP indentation.
.RE \" Move left margin back to standard position.
.if t \{\
.  \" end hideous cheat for U.S. letter paper
.  do nr PD \n[saved-PD]u
.  do rr saved-PD
.\}
.
.
.\" ====================================================================
.SS History
.\" ====================================================================
.
.MT m.douglas.mcilroy@dartmouth.edu
M.\& Douglas McIlroy
.ME
designed,
implemented,
and documented the AT&T
.I man
macros
for
Unix Version\~7 (1979) and employed them
to edit Volume\~1 of its
.IR "Programmer's Manual" ,
a compilation of all man pages supplied by the system.
.
The package supported the macros listed in this page
not described as extensions,
except
.B P
.\" SS was implemented in tmac.an but not documented in man(7).
and the deprecated
.B AT
and
.BR UC .
.
It documented no registers and defined only
.B R
and
.B S
strings.
.
.
.P
.B UC
appeared in 3BSD (1980).
.
.\" per https://archive.org/details/\
.\" bitsavers_attunixSysalRelease3Jun80_33886798
Unix System\~III (1980) introduced
.B P
.\" ...and de-documented LP...
and exposed the registers
.B IN
and
.BR LL ,
.\" ...as well as \n[PD], which we implement but don't expose.
which had been internal to Seventh Edition Unix
.IR man .
.
.\" This inference is based on RCS idents of "PWB Manual Entry Macros"
.\" from various forms of "an.src" distributed with System III (an.src
.\" 1.35, dated 5/6/80, lacks the Tm string), Research Unix Version 10
.\" (1.36, dated 11/11/80, has it), Ultrix 3.1 (1.37, dated 12/19/80,
.\" retains it) and "pdp11v" (also 1.37).  One source (S. S. Pirzada)
.\" says PWB 2.0 was released in June 1979.  I found no record of later
.\" releases and cannot account for the discrepancy (field updates?).
.\" -- GBR
PWB/Unix 2.0 (1980) added the
.B Tm
string.
.
4BSD (1980) added
.\" undocumented VS and VE macros to mark regions with 12-point box
.\" rules (\[br]) as margin characters, as well as...
.B lq
and
.B rq
strings.
.
.\" The SunOS inferences here and below are based on inspection of SunOS
.\" 2.0 (May 1985), 3.2 (September 1986), 3.5 (January 1988), and 4.0
.\" (December 1988) tape archives (only).
SunOS\~2.0 (1985) recognized
.BR C ,
.BR D ,
.BR P ,
and
.B X
registers.
.
4.3BSD (1986) added
.\" undocumented DS and DE macros for "displays", which are RS/RE
.\" wrappers with filling disabled and vertical space of 1v before and
.\" .5v after, as well as...
.B AT
and
.BR P .
.
.\" Per Doug McIlroy in
.\" <https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html>...
Ninth Edition Unix (1986) introduced
.B EX
and
.BR EE .
.\" DWB added EX/EE support, albeit slightly incompatibly.*  It
.\" was in 3.3 (1992) but could have appeared as early as 2.0 (1986)
.\" given its relationship to Research Unix.
.\"
.\" * See <https://lists.gnu.org/archive/html/bug-ncurses/2024-03/\
.\" msg00173.html>.
.
SunOS\~4.0 (1988) added
.BR SB .
.
Unix System\~V (1988) incorporated the
.B lq
and
.B rq
strings.
.\" ...whereas DWB 2.0 (1984) apparently did not.
.\" https://lists.gnu.org/archive/html/groff/2025-09/msg00079.html
.\" Going by the SCCS header, DWB had incorporated them by 3.2 (1991?).
.\" https://github.com/n-t-roff/DWB3.3/blob/\
.\"   562bb8615116f46077ca03e8561323cc7a89673e/macros/man/an.sr#L20
.
.
.P
Except for
.BR EX / EE ,
James Clark implemented the foregoing features in early versions of
.I groff.
.
Later,
.I groff
1.20 (2009) resurrected
.BR EX / EE
and originated
.BR SY / YS ,
.BR TQ ,
.BR MT / ME ,
and
.BR UR / UE .
.\" ...along with implementations of OP, EX, and EE.
.\"
.\" It's not clear exactly when OP showed up in DWB troff.  It wasn't
.\" in 1.0 (1984), but was by the time of the 3.3 release (1992).  Scans
.\" of DWB manuals online suggest that AT&T did not bother to document
.\" DWB's man(7) implementation in printed matter (nor its ms(7)).
.
Plan\~9 from User Space's
.I troff \" plan9port
introduced
.B MR
in 2020,
.\" https://github.com/9fans/plan9port/commit/\
.\"  977b25a76ae8263e53fb4eb1abfc395769f23e3d
.\"  d32deab17bfffa5bffc5fab3e6577558e40888c5
.\"  36cd4c58c1346375b98f517fb8568be5bb47618d
and incorporated the
.B lq
and
.B rq
strings in 2025.
.\" https://github.com/9fans/plan9port/commit/\
.\"  e5b5757e640371974d2e70144c8e59c6a5b613f6
.
.
.br
.ne 4v
.\" ====================================================================
.SH Options
.\" ====================================================================
.
The following
.I groff
options set registers
(with
.BR \-r )
and strings
(with
.BR \-d )
recognized and used by the
.I man
macro package.
.
To ensure rendering consistent with output device capabilities and
reader preferences,
man pages should never manipulate them.
.
.
.TP 9.25n \" "-rHY=0" + 2n + hand-tuned for PDF
.BI \-dAD= adjustment-mode
Set line adjustment to
.I adjustment-mode,
which is typically
.RB \[lq] b \[rq]
for adjustment to both margins
(the default),
or
.RB \[lq] l \[rq]
for left alignment
(ragged right margin).
.
Any valid argument to
.IR groff 's
\[lq]ad\[rq] request may be used.
.
See
.MR groff 7
for less-common choices.
.
.
.TP
.BI \-rBP= base-paragraph-inset
Set the inset amount for ordinary paragraphs not within an
.BR RS / RE
inset.
.
The default is\~5n.
.
.
.TP
.B \-rcR=1
Enable continuous rendering.
.
Output is not paginated;
instead,
one
(potentially very long)
page is produced.
.
This is the default for terminal and HTML devices.
.
Use
.B \-rcR=0
to disable it on terminals;
on HTML devices,
it cannot be disabled.
.
.
.TP
.B \-rC1
Number output pages consecutively,
in strictly increasing sequence,
rather than resetting the page number to\~1
(or the value of register
.BR P )
with each new
.I man
document.
.
.
.TP
.BI \-rCHECKSTYLE= n
Report problems with usage of this macro package exhibited by the input
at verbosity level
.IR n ,
where
.I n
is an integer in the range 0\[en]3,
inclusive;
.B 0
disables the messages and is the default.
.
This feature is a development and debugging aid
for man page maintainers;
the problems diagnosed,
and range and meanings of the supported levels,
are subject to change.
.
.
.TP
.B \-rCS=1
Set section headings
(the argument(s) to
.BR SH )
in full capitals.
.
This transformation is off by default because it discards lettercase
distinctions.
.
.
.TP
.B \-rCT=1
Set the man page identifier
(the first argument to
.BR TH )
in full capitals in headers and footers.
.
This transformation is off by default because it discards lettercase
distinctions.
.
.
.TP
.B \-rD1
Enable double-sided layout,
formatting footers for even and odd pages differently;
see the description of
.B TH
in subsection \[lq]Document structure macros\[rq] above.
.
.
.TP
.BI \-rFT= footer-distance
Set distance of the footer relative to the bottom of the page to
.I footer-distance;
this amount is always negative.
.
At one half-inch above this location,
the page text is broken before writing the footer.
.
Ignored if continuous rendering is enabled.
.
The default is \[lq]\-0.5i\~\-\~1v\[rq].
.
.
.TP
.BI \-dHF= heading-font
Select the font used for section and subsection headings;
the default is
.RB \[lq] B \[rq]
(bold style of the default family).
.
Any valid argument to
.IR groff 's
\[lq]ft\[rq] request may be used.
.
See
.MR groff 7 .
.
.
.TP
.B \-rHY=0
Disable automatic hyphenation.
.
Normally,
it is enabled\~(1).
.
The hyphenation mode is determined by the
.I groff
locale;
see section \[lq]Localization\[lq] of
.MR groff 7 .
.
.
.TP
.BI \-rIN= standard-indentation
Set the default indentation amount used by
.BR IP ,
.BR TP ,
.\" TQ inherits its indentation from the preceding TP.
and
.BR HP ,
and the inset amount used by
.BR RS .
.
The default is 7n on terminals and 7.2n on typesetters.
.
Use only integer multiples of unit \[lq]n\[rq] on terminals for consistent
indentation.
.
.
.TP
.BI \-rLL= line-length
Set line length;
the default is 80n on terminals
and 6.5i on typesetters.
.
.
.TP
.BI \-rLT= title-length
Set the line length for titles.
.
By default,
it is set to the line length
(see
.B \-rLL
above).
.
.
.br
.ne 5v
.TP
.BI \-dMF= man-page-topic-font
Select the font used for man page identifiers in
.B TH
calls and topics named in
.B MR
calls;
the default is
.RB \[lq] I \[rq]
(italic style of the default family).
.
Any valid argument to
.IR groff 's
\[lq]ft\[rq] request may be used.
.
If the
.B MF
string ends in \[lq]I\[rq],
the package assumes it to be an oblique typeface,
and applies italic corrections before and after man page topics and
identifiers.
.
.
.TP
.BI \-rP n
Start enumeration of pages at
.IR n .
.
The default is\~1.
.
.
.TP
.BI \-rPO= page-offset
Set page offset;
the default is 0 on terminals
and 1i on typesetters.
.
.
.TP
.BI \-rS type-size
Use
.I type-size
for the document's body text;
acceptable values are 10,
11,
or 12 points.
.
See subsection \[lq]Font style macros\[rq] above for the default.
.
.
.TP
.BI \-rSN= subsection-indentation
Set indentation of subsection headings to
.I subsection-indentation.
.
The default is\~3n.
.
.
.TP
.BI \-rTS= separation
Require the given
.I separation
between a
.B TP
paragraph's tag and its body.
.
The default is\~2n.
.
.
.TP
.B \-rU0
Disable generation of URI hyperlinks in output drivers capable of them,
making the arguments to
.B MT
and
.B UR
calls visible as formatted text.
.
.MR grohtml 1 ,
.MR gropdf 1 ,
and
.MR grotty 1
enable hyperlinks by default
(the last only if not in its legacy output mode).
.
.
.TP
.BI \-rX p
Number successors of
.RI page\~ p
as
.IR p a,
.IR p b,
.IR p c,
and so forth.
.
The register tracking the suffixed page letter uses format \[lq]a\[rq]
(see the \[lq]af\[rq] request in
.MR groff 7 ).
.
.
.
.br
.if n .ne 3v
.if t .ne 4v \" section headings are taller on typesetters
.\" ====================================================================
.SH Files
.\" ====================================================================
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:an\:.tmac
Most
.I man
macros are defined in this file.
.
It also loads extensions from
.I \%an\-ext.tmac
(see below).
.
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:\%andoc\:.tmac
This brief
.I groff
program detects whether the
.I man
or
.I mdoc
macro package is used by a document
and loads the correct macro definitions,
taking advantage of the fact that pages using them must call
.B TH
or
.BR Dd ,
respectively,
before any other macros.
.
A
.I man
program or a user typing,
for example,
.RB \[lq] "groff \-mandoc page.1" \[rq],
need not know which package the file
.I page.1
uses.
.
Multiple man pages,
in either format,
can be handled;
.I \%andoc
reloads each macro package as necessary.
.
Page-local redefinitions of names used by the
.I man
or
.I mdoc
packages prior to
.B TH
or
.B Dd
calls are \[lq]clobbered\[rq] by the reloading process.
.
If you want to provide your own definition of an extension macro to
ensure its availability,
the
.I \%an\-ext\:.tmac
entry below offers advice.
.
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:\%an\-ext\:.tmac
Definitions of macros described above as extensions
(and not deprecated)
are contained in this file;
in some cases,
they are simpler versions of definitions appearing in
.IR an.tmac ,
and are ignored if the formatter is GNU
.IR troff .\" GNU
.
They are written to be compatible with AT&T
.I troff \" AT&T
and permissively licensed\[em]not copylefted.
.
To reduce the risk of name space collisions,
string and register names begin only with
.RB \[lq] m \[rq].
.
We encourage man page authors
who are concerned about portability to legacy Unix systems
to copy these definitions into their pages,
and maintainers of
.I troff \" generic
implementations or work-alike systems that format man pages
to re-use them.
.
To ensure reliable rendering,
define them after your page calls
.BR TH ;
see the discussion of
.I \%andoc\:.tmac
above.
.
Further,
it is wise to define such page-local macros
(if at all)
after the \[lq]Name\[rq] section to accommodate timid
.MR makewhatis 8
or
.MR mandb 8
implementations that easily give up scanning for indexing material.
.
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:man\:.tmac
is a wrapper enabling the package to be loaded with the option
.RB \[lq] "\-m man" \[rq].
.
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:\%mandoc\:.tmac
is a wrapper enabling
.I \&andoc.tmac
to be loaded with the option
.RB \[lq] "\-m mandoc" \[rq].
.
.
.TP
.I /usr/\:\%share/\:\%groff/\:\%site\-tmac/\:\%man\:\%.local
Put site-local changes and customizations into this file.
.
.
.\" ====================================================================
.SH Authors
.\" ====================================================================
.
James Clark wrote the initial GNU implementation of the
.I man
macro package.  \" by 1.01
.
Later,
.MT wl@\:gnu\:.org
Werner Lemberg
.ME
supplied the
.BR S , \" 1.16
.BR LT , \" 1.18
and
.B cR \" 1.17
registers,
the last a 4.3BSD-Reno
.IR mdoc (7)
feature.
.\" "Assume nroff on crt's [sic] only if cR==1"
.\" https://minnie.tuhs.org/cgi-bin/utree.pl
.\"   ?file=4.3BSD-Reno/share/tmac/tmac.doc
.
.MT kollar@\:alltel\:.net
Larry Kollar
.ME
added the
.BR FT ,
.BR HY ,
and
.B SN
registers;
the
.B HF
string;
and the
.B PT
and
.B BT
macros in
.I groff
1.19 (2003).
.
Lemberg and
.MT esr@\:thyrsus\:.com
Eric S.\& Raymond
.ME
contributed
.BR EX / EE ,
.BR MT / ME ,
.BR UR / UE ,
.BR TQ ,
and an early version of the
.BR SY / YS
macros to
.I groff
1.20 (2009).
.
.MT g.branden\:.robinson@\:gmail\:.com
G.\& Branden Robinson
.ME
implemented the
.B AD
and
.B MF
strings;
.BR CS ,
.BR CT ,
and
.B U
registers;
and the
.B MR
macro for
.I groff
1.23 (2023),
and the
.BR BP ,
.BR PO ,
and
.B TS
registers
and a revised implementation of the
.BR SY / YS
macros for
.I groff
1.24 (2026).
.
.
.P
.MT sgk@\:debian\:.org
Susan G.\& Kleinmann
.ME
wrote the initial version of this document
for the Debian GNU/Linux system.
.
Lemberg imported it to
.I groff.
He and Robinson revised and updated it.
.
Raymond and Robinson documented the extension macros.
.
.
.\" ====================================================================
.SH "See also"
.\" ====================================================================
.
.MR \%tbl 1 ,
.MR \%eqn 1 ,
and
.MR \%refer 1
are preprocessors used with man pages.
.
.MR man 1
describes the man page librarian on your system.
.
.MR groff_mdoc 7
details the
.I groff
version of BSD's alternative macro package for man pages.
.
.
.P
.MR groff_man_style 7 ,
.MR groff 7 ,
.MR groff_char 7
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_groff_man_7_man_C]
.do rr *groff_groff_man_7_man_C
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=groff textwidth=72: