'\" t
.\" This page is generated by m4 from tmac/groff_man.7.man.in.
.TH groff_man_style 7 "2026-03-15" "groff 1.24.1"
.SH Name
groff_man_style \- GNU
.I roff
man page tutorial and style guide
.
.
.\" ====================================================================
.\" 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.
Experienced
.I man
authors may prefer
.MR groff_man 7 .
.
.
.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.
.
.
.P
A man page employs the Unix line-ending convention
(U+000A only).
.
Some basic Latin characters have special meaning to
.I roff;
see subsection \[lq]Portability\[rq] below.
.
.
.\" ====================================================================
.SS "Fundamental concepts"
.\" ====================================================================
.
.I groff
is a programming system for typesetting:
we thus often use the verb \[lq]to set\[rq] in the sense
\[lq]to typeset\[rq].
.
The formatter
.MR \%troff 1
collects words from the input and
.I fills
output lines with as many as can fit.
.
.I Words
are separated by spaces and newlines.
.\" Also tabs and leaders, but let's not discuss those in man(7).
.
A transition to a new output line is called a
.I break.
.
Breaks can occur at explicit hyphens,
at
.B \e%
or
.B \e:
escape sequences
(see subsection \[lq]Portability\[rq] below),
or at predetermined locations in a word
if automatic hyphenation is enabled
(see the
.B \-rHY
option in section \[lq]Options\[rq] below).
.
An output line may be supplemented with
.I "inter-sentence space,"
then potentially
.I adjusted
with more space to a consistent length
(see the
.B \-dAD
option).
.
.MR roff 7
details these processes.
.
The formatter prepares output for
.I terminals
or for more capable
.I typesetters
that can change the type size and font family.
.
.
.P
A
.I roff
document can contain
.I "control lines,"
which start with a dot
.RB ( .\& )
or neutral apostrophe
.RB ( \[aq] ).
.
All other input lines are
.I "text lines"
to be formatted.
.
A
.I macro
collects control and/or text lines
to ease document composition.
.
.I man
is a
.I "macro package."
.
To call a macro,
put its name after a dot on a control line.
.\" You never need to indent macro calls in man(7), or call them with
.\" the no-break control character.
.
Some macros interpret
.I arguments,
words that follow its name.
.
A newline,
unless escaped
(see subsection \[lq]Portability\[rq] below),
marks the end of the macro call.
.
A control line with no macro name on it is called an
.I "empty request;"
it does nothing.
.
.
.P
We describe below several
.I man
macros that plant one-line
.I "input traps:"
the next input line that directly produces formatted output is treated
specially.
.
For
.I man
documents that follow the advice in section
\[lq]Portability\[rq] below,
this means that control lines using the empty request
and uncommented input lines ending with an escaped newline
do not spring the trap;
anything else does
(but see the
.B TP
macro description).
.
.
.\" ====================================================================
.\" .SS "Why have a tutorial and style guide?"
.\" ====================================================================
.\" the processing pipeline in brief
.\"   preprocessors, roff itself, various output devices
.\" Things that aren't groff--why you want the man page language to be
.\" small (mandoc, Kerrisk's man7.org, manpages.debian.org, non-expert
.\" humans).
.\" possibly exhibit a horrorshow docbook-to-man example
.
.
.\" ====================================================================
.SS "Macro reference preliminaries"
.\" ====================================================================
.
A tagged paragraph describes each macro.
.
We present coupled pairs together,
as with
.B EX
and
.BR EE .
.
Square brackets surround optional macro arguments.
.
If a macro accepts multiple arguments,
those containing space \" or tab (in Plan 9 troff [only?])
characters must be double-quoted to be interpreted correctly.
.
If you require an empty macro argument,
specify it as a pair of neutral double quotes
.RB ( \[dq]\^\[dq] ).
.
See section \[lq]Notes\[rq] below for examples of cases where better
alternatives to empty arguments in macro calls are available.
.
Most macro arguments are formatted as text in the output;
exceptions are noted.
.
We identify some macros as
.I extensions
to the set originally implemented.
.
They are not supported everywhere;
see subsection \[lq]Use of extensions\[rq]
below.
.
.
.\" ====================================================================
.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.
.
.I roff
systems refer to these collectively as \[lq]titles\[rq].
.
Together,
.I identifier
and the
.I section
of the manual to which it belongs
can uniquely identify a
.I man
document on the system.
.
This use of \[lq]section\[rq] has nothing to do with the section headings
otherwise discussed in this page;
it arises from the organizational scheme of printed and bound Unix
manuals.
.
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
.RB ( .\|.\|.\& ).
.
.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.
.
By convention,
.I footer-middle
is the date of the most recent modification to the source document,
in ISO\~8601 format
.RI ( YYYY - MM - DD ),
and
.I footer-inside
is the name and version or release of the project providing it.
.
.
.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
Example regions are useful for formatting code,
shell sessions,
and text file contents.
.
An example region is not
a \[lq]literal mode\[rq]
of any sort:
special character escape sequences must still be used to produce correct
glyphs for
.BR \[aq] ,
.BR \- ,
.BR \[rs] ,
.BR \[ha] ,
.BR \[ga] ,
and
.B \[ti]
(see subsection \[lq]Portability\[rq] below).
.
Sentence endings are still detected
and supplemental inter-sentence space applied.
.
If the amount of supplemental inter-sentence spacing is altered,
the rendering of,
for instance,
regular expressions using
.B .\&
or
.B ?\&
followed by multiple spaces can change.
.
Use the dummy character escape sequence
.B \[rs]&
before the spaces.
.
.
.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 )
like this one
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.
.
.
.IP
The line containing the tag can include a macro call,
for instance to set the tag in bold with
.BR B .
.
.B TP
was used to write the first paragraph of this description of
.BR TP ,
and
.B IP
the subsequent one.
.
.
.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
.
.
.IP
The description of
.BR P ,
.BR LP ,
and
.B PP
above was written using
.B TP
and
.BR TQ .
.
.
.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.
.
.
.IP
Two convenient uses for
.B IP
are
.
.
.RS \" Invisibly move left margin to current IP indentation.
.RS 4n \" Now indent further, visibly.
.IP (1) 5n \" "(1)" + 3n
to start a new paragraph with the same indentation as an immediately
preceding
.B IP
or
.B TP
paragraph,
if no
.I indentation
argument is given;
and
.
.
.IP (2)
to set a paragraph with a short
.I mark
that is not semantically important,
such as a bullet (\[bu])\[em]obtained with the
.B \e[bu]
special character escape sequence\[em]or list enumerator,
as seen in this very paragraph.
.RE \" Move left margin back to IP indentation.
.RE \" Move left margin back to standard position.
.
.
.\" ====================================================================
.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.
.
.
.P
Interleave multiple
.BR SY / YS
blocks with paragraphing macros to distinguish differing modes of
operation of a complex command like
.MR tar 1 .
.
Omit the paragraphing macro to indicate synonymous ways of invoking a
particular mode of operation.
.
Paragraphing macros can similarly manage grouping of function synopses.
.
.
.br
.ne 4v
.P
.IR groff 's
own command-line interface illustrates most specimens
of synopsis syntax one may encounter.
.
.
.IP
.\" from src/roff/groff/groff.1.man
.EX
\&.SY groff
\&.RB [ \e\-abcCeEgGijklNpRsStUVXzZ ]
\&.RB [ \e\-d\e\[ti]\ec
\&.IR ctext ]
\&.RB [ \e\-d\e\[ti]\ec
\&.IB string =\ec
\&.IR text ]
\&.RB [ \e\-D\e\[ti]\ec
\&.IR fallback\-encoding ]
.EE
.
.I "(and so on similarly)"
.
.EX
\&.RI [ file\e\[ti] .\e|.\e|.]
\&.YS
\&.
\&.
\&.P
\&.SY groff
\&.B \e\-h
\&.YS
\&.
\&.SY groff
\&.B \e\-\e\-help
\&.YS
\&.
\&.
\&.P
\&.SY groff
\&.B \e\-v
\&.RI [ option\e\[ti] .\e|.\e|.\e&]
\&.RI [ file\e\[ti] .\e|.\e|.]
\&.YS
\&.
\&.SY groff
\&.B \e\-\e\-version
\&.RI [ option\e\[ti] .\e|.\e|.\e&]
\&.RI [ file\e\[ti] .\e|.\e|.]
\&.YS
.EE
.
.
.P
Given the foregoing input,
.I "groff man"
produces the following output.
.
.
.P
.RS
.SY groff
.RB [ \-abcCeEgGijklNpRsStUVXzZ ]
.RB [ \-d\~\c
.IR ctext ]
.RB [ \-d\~\c
.IB string =\c
.IR text ]
.RB [ \-D\~\c
.IR fallback-encoding ]
.RB [ \-f\~\c
.IR font-family ]
.RB [ \-F\~\c
.IR font-directory ]
.RB [ \-I\~\c
.IR inclusion-directory ]
.RB [ \-K\~\c
.IR input-encoding ]
.RB [ \-L\~\c
.IR spooler-argument ]
.RB [ \-m\~\c
.IR macro-package ]
.RB [ \-M\~\c
.IR macro-directory ]
.RB [ \-n\~\c
.IR page-number ]
.RB [ \-o\~\c
.IR page-list ]
.RB [ \-P\~\c
.IR postprocessor-argument ]
.RB [ \-r\~\c
.IR cnumeric-expression ]
.RB [ \-r\~\c
.IB register =\c
.IR numeric-expression ]
.RB [ \-T\~\c
.IR output-device ]
.RB [ \-w\~\c
.IR warning-category ]
.RB [ \-W\~\c
.IR warning-category ]
.RI [ file\~ .\|.\|.]
.YS
.
.
.br
.ne 2v
.P
.SY groff
.B \-h
.YS
.
.SY groff
.B \-\-help
.YS
.
.
.P
.SY groff
.B \-v
.RI [ option\~ .\|.\|.\&]
.RI [ file\~ .\|.\|.]
.YS
.
.SY groff
.B \%\-\-version
.RI [ option\~ .\|.\|.\&]
.RI [ file\~ .\|.\|.]
.YS
.RE
.
.
.P
Several features of the above example are of note.
.
.
.IP \[bu] 3n
The empty request (.),
which does nothing,
vertically spaces the input file for readability by the document
maintainer;
see subsection \[lq]Portability\[rq] below regarding blank lines.
.
.
.IP \[bu]
Command and option names are presented in
.B bold
to cue the user that they should be input literally.
.
.
.IP \[bu]
Option dashes are specified with the
.B \e\-
escape sequence;
this is an important practice to make them clearly visible and to
facilitate copy-and-paste from the rendered man page to a shell prompt
or text file.
.
.
.IP \[bu]
Option arguments and command operands are presented in
.I italics
(but see subsection \[lq]Font style macros\[rq] below regarding terminals)
to cue the user that they must be replaced with appropriate input.
.
.
.IP \[bu]
Symbols that are neither to be typed literally nor replaced at the
user's discretion appear in the roman style;
brackets surround optional arguments,
and an ellipsis indicates that the previous syntactic element may be
repeated arbitrarily.
.
Where whitespace separates optional arguments,
a space precedes the ellipsis.
.
.
.IP \[bu]
The non-breaking adjustable space escape sequence
.B \e\[ti]
prevents the output line from breaking within the option brackets;
see subsection \[lq]Portability\[rq] below.
.
.
.IP \[bu]
The output line continuation escape sequence
.B \ec
is used with font style alternation macros to allow all three font
styles to be set without (breakable) space among them;
see subsection \[lq]Portability\[rq] below.
.
.
.IP \[bu]
The dummy character escape sequence
.B \e&
follows the ellipsis when further text is to follow after space on the
output line,
keeping its last period from being interpreted as the end of a
sentence
because it is followed by characters that are transparent to
end-of-sentence detection,
and/or a newline,
which would in turn normally cause the formatter
to place supplemental inter-sentence space after it.
.
See subsection \[lq]Portability\[rq] below.
.
.
.P
We might synopsize the standard C library function
.MR bsearch 3
as follows.
.
.
.P
.RS
.EX
\&.P
\&.B void *\[rs]c
\&.SY bsearch (
\&.BI const\[rs]\[ti]void\[rs]\[ti]* key ,
\&.BI const\[rs]\[ti]void\[rs]\[ti]* base ,
\&.BI size_t\[rs]\[ti] nmemb ,
\&.BI int\[rs]\[ti](* compar )\[rs]c
\&.B (const\[rs]\[ti]void\[rs]\[ti]*, const\[rs]\[ti]void\[rs]\[ti]*));
\&.YS
.EE
.RE
.
.
.P
.I "groff man"
produces the following result.
.
.
.RS
.P
.B void *\c
.SY bsearch (
.BI const\~void\~* key ,
.BI const\~void\~* base ,
.BI size_t\~ nmemb ,
.BI int\~(* compar )\c
.B (const\~void\~*, const\~void\~*));
.YS
.RE
.
.
.\" ====================================================================
.SS "Hyperlink macros"
.\" ====================================================================
.
Man page cross references
like
.MR ls 1
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.
.
(See subsection \[lq]Portability\[rq] below.)
.
URIs can be lengthy;
rendering them can result in jarring adjustment or variations in line
length,
or
.I \%troff
warnings when one is longer than an output line.
.
The application of non-printing break point escape sequences
.B \e:
after each slash
(or series thereof),
and before each dot
(or series thereof)
is recommended as a rule of thumb.
.
The former practice avoids forcing a trailing slash in a URI onto a
separate output line,
and the latter helps the reader to avoid mistakenly interpreting a dot
at the end of a line as a period
(or multiple dots as an ellipsis).
.
Thus,
.RS
.EX
\&.UR http://\e:example\e:.com/\e:fb8afcfbaebc74e\e:.cc
.EE
.RE
has several potential break points in the URI shown.
.
Consider adding break points before or after at signs in email
addresses,
and question marks,
ampersands,
and number signs in HTTP(S) URIs.
.
.\" 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].
.
.
.RS
.IP
.EX
The output driver
\&.MR grops 1
produces PostScript from
\&.I troff
output.
\&.
The Ghostscript program (\[rs]c
\&.MR gs 1 )
interprets PostScript and PDF.
.EE
.RE
.
.
.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.
.
.
.IP
When rendered by
.I groff
to a PostScript device,
.RS
.IP
.EX
Contact
\&.MT fred\e:.foonly@\e:fubar\e:.net
Fred Foonly
\&.ME
for more information.
.EE
.RE
.
.
.IP
formats as
\[lq]Contact Fred Foonly \[la]fred\:.foonly@\:fubar\:.net\[ra]
for more information.\[rq].
.
.
.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.
.
.
.br
.ne 2v
.IP
When rendered by
.I groff
to a PostScript device,
.RS
.IP
.EX
The GNU Project of the Free Software Foundation
hosts the
\&.UR https://\e:www\e:.gnu\e:.org/\e:software/\e:groff/
\&.I groff
home page
\&.UE .
.EE
.RE
.
.
.IP
formats as \[lq]The GNU Project of the Free Software Foundation hosts
the
.I groff
home page
\[la]https://\:www\:.gnu\:.org/\:software/\:groff/\[ra].\[rq].
.
.
.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
Because font styles are presentational rather than semantic,
conflicting traditions have arisen regarding which font styles should be
used to mark file or path names,
environment variables,
and inlined literals.
.
.
.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.
.
.
.IP
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,
string,
and register names.
.
In an
.BR EX / EE
example of interactive I/O
(such as a shell session),
set only user input 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.
.
.
.IP
Use italics
for file and path names,
for environment variables,
for C data types,
for enumeration or preprocessor constants in C,
for variant (user-replaceable) portions of syntax synopses,
for the first occurrence (only) of a technical concept being introduced,
for names of journals and of literary works longer than an article,
and anywhere a parameter requiring replacement by the user is
encountered.
.
An exception involves variant text in a context already typeset in
italics,
such as file or path names with replaceable components;
in such cases,
follow the convention of mathematical typography:
set the file or path name in italics as usual
but use roman for the variant part
(see
.B IR
and
.B RI
below),
and italics again in running roman text when referring to the variant
material.
.
.
.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.
.
.
.IP
.I Note:
terminals render
.I text
at normal size instead.
.
Do not rely upon
.B SM
to communicate semantic information distinct from using roman style at
normal size;
it is hidden from readers using such devices.
.
.
.P
Observe what is
.I not
prescribed for setting in bold or italics above:
elements of \[lq]synopsis language\[rq] such as ellipses and brackets
around options;
proper names and adjectives;
titles of anything other than major works of literature;
identifiers for standards documents or technical reports such as
CSTR\~#54,
RFC\~1918,
Unicode\~16,
or
POSIX.1-2024;
acronyms;
and occurrences after the first of a technical term.
.
.
.P
Use italics for emphasis rarely,
and bold almost never.
.
Brief specimens of literal text,
such as article titles,
inline examples,
mentions of individual characters or short strings,
and (sub)section headings in man pages,
are suitable for quotation;
see the
.BR \e[lq] ,
.BR \e[rq] ,
.BR \e[oq] ,
and
.B \e[cq]
escape sequences in subsection \[lq]Portability\[rq] below.
.
.
.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.
.
If a space is required within an argument,
first consider whether the same result could be achieved with as much
clarity by using single-style macros on separate input lines.
.
When it cannot,
double-quote an argument containing embedded space characters.
.
Setting all three different styles within a word
presents challenges;
it is possible with the
.B \ec
and/or
.B \ef
escape sequences.
.
See subsection \[lq]Portability\[rq]
below for approaches.
.
.
.TP
.BI .BI " bold-text italic-text "\c
\&.\|.\|.\&
Set each argument in bold and italics,
alternately.
.
.
.RS
.IP
.\" from src/roff/troff/troff.1.man
.EX
\&.BI \-r\e\[ti] register = numeric-expression
.EE
.RE
.
.
.TP
.BI .BR " bold-text roman-text "\c
\&.\|.\|.\&
Set each argument in bold and roman,
alternately.
.
.
.RS
.IP
.\" from src/preproc/eqn/eqn.1.man
.EX
Set an ellipsis on the math axis with the GNU extension macro
\&.BR cdots .
.EE
.RE
.
.
.TP
.BI .IB " italic-text bold-text "\c
\&.\|.\|.\&
Set each argument in italics and bold,
alternately.
.
.
.RS
.IP
.\" from src/preproc/pic/pic.1.man
.EX
In places where
\&.IB n th
is allowed,
.EE
.RE
.
.
.TP
.BI .IR " italic-text roman-text "\c
\&.\|.\|.\&
Set each argument in italics and roman,
alternately.
.
.
.RS
.IP
.\" from src/preproc/pic/pic.1.man
.EX
Use GNU
\&.IR pic \[aq]s
\&.B figname
command to change the name of the vbox.
.EE
.RE
.
.
.TP
.BI .RB " roman-text bold-text "\c
\&.\|.\|.\&
Set each argument in roman and bold,
alternately.
.
.
.RS
.IP
.\" from src/roff/groff/groff.1.man
.EX
\&.I file
is
\&.RB \[rs][lq] \[rs]\- \[rs][rq],
\&.I groff
reads the standard input stream.
.RE
.EE
.
.
.TP
.BI .RI " roman-text italic-text "\c
\&.\|.\|.\&
Set each argument in roman and italics,
alternately.
.
.
.RS
.IP
.\" from src/preproc/pic/pic.1.man
.EX
\&.RI ( tpic
was a fork of AT&T
\&.I pic \" AT&T
by Tim Morgan of the University of California at Irvine
.EE
.RE
.
.
.\" ====================================================================
.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];
that is,
roughly the width of a letter \[lq]n\[rq] in the font current when the
macro is called\[em]see section \[lq]Measurements\[rq] in
.MR groff 7 .
.
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
The inset amount and indentation are related but distinct parameters
with the same defaults.
.
The former is manipulated by
.B RS
and
.B RE
(and by
.\".BR TH ,\" True but not to be encouraged within a document.
.B SH
and
.BR SS ,
which reset it to the default).
.
Indentation is controlled by the paragraphing macros
(though,
again,
.\".BR TH ,
.B SH
and
.B SS
reset it);
it is imposed by the
.BR TP ,
.BR IP ,
and
.B HP
macros,
and cancelled by
.B P
and its synonyms.
.
An extensive example follows.
.
.
.br
.ne 2v
.P
This ordinary
.RB ( P )
paragraph is not in a relative inset nor does it possess an indentation.
.
.
.RS
.P
Now we have created a relative inset with
.B RS
and started another ordinary paragraph with
.BR P .
.
We observe that all of its lines are inset and indented the same;
contrast with a first-line indentation.
.
.
.TP
.B tag
This tagged paragraph,
set with
.BR TP ,
is still within the
.B RS
region,
but lines after the first have a supplementary indentation that the
tag lacks.
.
.
.IP
A paragraph like this one,
set with
.BR IP ,
appears to the reader as also associated with the tag above,
because
.B IP
re-uses the previous paragraph's indentation unless given an argument
to change it.
.
Both the inset amount
.RB ( RS )
and indentation
.RB ( IP )
affect this paragraph.
.
.TS
box;
l.
This table is affected both by
the inset amount and indentation.
.TE
.
.
.IP \[bu]
This indented paragraph is marked with a bullet,
contrasting the inset amount and the indentation;
only the former affects the mark,
but both affect the text of the paragraph.
.
.
.P
This ordinary
.RB ( P )
paragraph resets the indentation,
but the inset amount is unchanged.
.
.TS
box;
l.
This table is affected only
by the inset amount.
.TE
.RE
.
.
.P
Finally,
we have ended the relative inset by using
.BR RE ,
which
(because we used only one
.BR RS / RE
pair)
has restored the inset amount to its initial value.
.
This is an ordinary
.B P
paragraph.
.
.
.P
Resist the temptation to mock up tabular or multi-column output with
tab characters or the indentation arguments to
.BR IP ,
.BR TP ,
.BR RS ,
or
.BR HP ;
the result may not be comprehensible on an output device you fail to
check,
or which is developed in the future.
.
Consider the table preprocessor
.MR \%tbl 1
instead.
.
.
.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.
\[lq]v\[rq] is a unit of vertical distance,
where 1v is the distance between adjacent text baselines.
.
(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.
.
.
.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.
.
.
.P
A contemporary man page needs none of the above.
.
.B \e*S
is superfluous;
type size changes are invisible on terminals,
and macros that change it restore its original value afterward.
.
Better alternatives exist for the rest;
simply use the
.BR \[rs][rg] , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9, Solaris
.BR \[rs][lq] , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
.BR \[rs][rq] , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
and
.B \[rs][tm] \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
special character escape sequences directly.
.
Unless you are aiming for a pathological level of portability\[em]\
perhaps composing a man page
for consumption on simulators of 1980s Unix systems
(or Solaris
.IR troff ,
though even it supports
.RB \[lq]\^ \[rs](rg \[rq])\[em]\c
avoid using the above strings.
.
.
.\" ====================================================================
.SS "Use of extensions"
.\" ====================================================================
.
To ensure that your man page formats reliably on a wide variety of
viewers,
write it solely with the macros described in this page
(except for the ones identified as deprecated,
which you should avoid).
.
Macros described as extensions might be unsupported by a formatter that
is important to your audience.
.
Nevertheless,
.IR groff 's
extensions are present because they perform tasks that are otherwise
difficult or tedious to achieve portably.
.
If you require an extension but expect your man page to be rendered
on a system that doesn't support it,
write a configuration test to measure a property of the system,
and use
.MR m4 1 ,
.MR sed 1 ,
or a similar tool to generate a
.I .man
file from a
.I .man.in
file,
defining page-local versions of extension macros only where necessary.
.
You can copy extension macro definitions from
.IR groff ;
see
.I \%an\-ext.tmac
in section \[lq]Files\[rq] below.
.
.
.P
For example,
we might put a line
.
.RS
.EX
@DEFINE_MR@
.EE
.RE
.
in our
.I man
document at the end of the \[lq]Name\[rq] section,
test a system for the availability of the
.I "groff man"
.B MR
macro,
remove the line if the macro is present,
and \[lq]inline\[rq] a definition otherwise,
as follows.
.
(This version is slightly simplified and does not attempt to disable
hyphenation when setting arguments to
.BR MR .)
.
.RS
.EX
have_MR=$(echo .pm | troff \-man 2>&1 | grep \[aq]MR[[:space:]]\[aq])
if [ \-n "$have_MR" ]
then
  sed \[aq]/@DEFINE_MR@/d\[aq] myprog.man.in > myprog.man
else
  sed \[aq]s/@DEFINE_MR@/.de MR\e
\&.  ie \e\e\e\en(.$=1 .I \e\e\e\e$1\e
\&.  el .IR \e\e\e\e$1 (\e\e\e\e$2)\e\e\e\e$3\e
\&../\[aq] myprog.man.in > myprog.man
fi
.EE
.RE
.
(The profusion of backslashes is due to its status as an escape
character in both
.I roff
and
.IR sed .)
.
.
.\" XXX: too preachy?
.P
If the foregoing method is too much trouble,
you could apply the radical technique of reading your man page using
every formatter of interest,
confirming satisfactory output from each.
.
Test documentation for syntactic validity and semantic correctness,
just as you would test code.
.
.
.\" ====================================================================
.SS Portability
.\" ====================================================================
.
GNU
.I troff \" GNU
expects its input to contain Unicode basic Latin code points
exclusively.
.
One can
.I maintain
it in a more convenient encoding,
using
.MR preconv 1 ,
as with
.MR groff 1 's
.B \-k
option,
to generate a basic Latin version
that employs special character escape sequences
to access other glyphs.
.
.
.P
AT&T
.IR troff 's \" AT&T
.I man
package and those of many of its descendants format man pages
using a line length of 65 ens
(character cells)
on terminals,
whereas
.I "groff man"
uses 80 ens
(and
.MR mandoc 1
78).
.
Readers with low vision may also benefit from the narrower line length.
.
Inspect your documents with
.RB \[lq] "nroff \-t \-r LL=65n \-man" \[rq]
to ensure that their output lines don't overrun.
.
.
.P
In
.I roff
systems,
elemental functions called
.I requests
and
.I "escape sequences"
control formatting operations.
.
A request appears on a control line.
.
An escape sequence starts with a backslash
.RB ( \[rs] )
and can appear almost anywhere.
.
However,
use of
.I roff
requests
(apart from the empty request
.RB \[lq] . \[rq])\&
risks poor rendering when a page is processed by
.RI non- roff
formatters that attempt to interpret page sources.
.
(Historically,
this was commonly attempted for HTML conversion.)
.
Many of these programs don't interpret the full
.I roff
language
(let alone extensions):
they may be incapable of handling numeric expressions,
control structures,
or register,
string,
and macro definitions,
causing a document's contents
to be presented incomprehensibly
or omitted entirely.
.
If your document uses formatter requests,
or escape sequences not shown below,
it accepts responsibility for restoring
formatter state to what the
.I man
macro package expects.
.
.
.P
Do not put blank (empty) lines in a man page source document.
.
They can produce excessive space in the output,
or less than is attempted;
some
.MR man 1
programs \[lq]squeeze\[rq] multiple blank output lines into one.
.
.
.P
The wise
.I man
author
quotes multi-word section and subsection headings;
the
.B SH
and
.B SS
macros of
.MR man 7
implementations descended from Seventh Edition Unix supported six
arguments at most.
.
This restriction also applied to the
.BR B ,
.BR I ,
.BR SM ,
and font style alternation macros.
.
.
.P
Exercise restraint with escape sequences as with requests.
.
Some escape sequences are however required for correct typesetting
even in man pages and usually do not cause portability problems.
.
Several of these render glyphs corresponding to punctuation code points
in the Unicode basic Latin range
(U+0020\[en]U+007F)
that are handled specially in
.I roff
input;
the escape sequences below must be used to render them correctly and
portably when documenting material that uses them
as literals\[em]namely,
any of the set
.B \[aq] \- \[rs] \[ha] \[ga] \[ti]
(apostrophe,
dash or hyphen-minus,
backslash,
caret,
grave accent,
tilde).
.
.
.if n .TP 10n \" "\newline" + 2n
.if t .TP 9n \" we can get away with less on typesetters
.B \e\[dq]
Comment.
.
The formatter ignores everything after the double quote to the end of
the input line.
.
Place whole-line comments on a control line
immediately after the empty request
.RB (\[lq] . \[rq]).
.
.
.TP
.BI \e newline
Join the next input line to the current one.
.
Except for the update of the input line counter
(used for diagnostic messages and related purposes),
a series of lines ending in backslash-newline appears to
.I groff
as a single input line.
.
Splitting excessively long input lines can ease document maintenance.
.
.
.TP
.B \e%
Control hyphenation.
.
The location of this escape sequence within a word marks a hyphenation
point,
supplementing
.IR groff 's
automatic hyphenation patterns.
.
At the beginning of a word,
it suppresses any hyphenation breaks within
.I except
those specified with
.BR \e% .
.
.
.TP
.B \e:
Insert a non-printing break point.
.
A word can break at such a point,
but a hyphen glyph is not written to the output if it does.
.
The remainder of the word is subject to hyphenation as normal.
.\" XXX: That's a bug; see Savannah #65549, because GNU troff doesn't
.\" stick a hyphenation suppression node at the beginning of the new
.\" output line.  Worse, there's no portability here anyway.
.\" See <https://lists.gnu.org/archive/html/groff/2024-04/msg00000.html>
.\" and the thread generally.
.
You can use
.B \e:
and
.B \e%
in combination to control breaking of a file name or URI or to permit
hyphenation only after certain explicit hyphens within a word.
.
See subsection \[lq]Hyperlink macros\[rq] above for an example.
.
.
.IP
.B \e:
is a GNU extension also supported by Heirloom Doctools
.I troff \" Heirloom
050915 (September 2005),
.I mandoc
1.13.1 (2014-08-10),
and
.I neatroff
(commit 399a4936,
2014-02-17),
but not by
DWB,
Plan\~9,
or
Solaris
.IR troff s. \" DWB, Plan 9, Solaris
.\" as of this writing, 2022-08-13
.
.
.TP
.B \e\[ti]
Adjustable non-breaking space.
.
Use this escape sequence to prevent a break inside a short phrase or
between a numerical quantity and its corresponding unit(s).
.
.
.RS
.IP
.EX
Before starting the motor,
set the output speed to\e\[ti]1.
There are 1,024\e\[ti]bytes in 1\e\[ti]KiB.
CSTR\e\[ti]#8 documents the B\e\[ti]language.
.EE
.RE
.
.
.IP
.B \e\[ti]
is a GNU extension
.\" BEGIN Keep in sync with groff.texi node "Other Differences" and
.\" groff_diff(7).
also supported by Heirloom Doctools
.I troff \" Heirloom
050915 (September 2005),
.I mandoc
1.9.14 (2009-11-16),
.I neatroff
(commit 1c6ab0f6e,
2016-09-13),
and
Plan\~9 from User Space
.I troff \" Plan 9
(commit 93f8143600,
2022-08-12),
but not by
DWB
or
Solaris
.IR troff s. \" DWB, Solaris
.\" as of this writing, 2022-08-13
.\" END Keep in sync with groff.texi node "Other Differences" and
.\" groff_diff(7).
.
.
.TP
.B \e&
Dummy character.
.
Prefix an input line with it
to prevent a dot or apostrophe
from being interpreted as beginning a
.I roff
control line.
.
Append
.B \e&
to an end-of-sentence punctuation sequence
to keep it from being recognized as such.
.
.
.TP
.B \e|
Thin space
(one-sixth em on typesetters,
zero-width on terminals);
a non-breaking space.
.
Used primarily in ellipses
(\[lq].\e|.\e|.\[rq])\&
to space the dots more pleasantly on typesetters.
.
.
.TP
.B \ec
End a text line without inserting space or attempting a break.
.
Nothing on the input line after this escape sequence is formatted.
.
.B \[rs]c
is useful when three font styles are
needed in a single word,
as in a command synopsis.
.
.
.RS
.IP
.\" from contrib/pdfmark/pdfroff.1.man
.EX
\&.RB [ \e\-\e\-stylesheet=\ec
\&.IR name ]
.EE
.RE
.
.
.br
.ne 4v
.IP
.B \ec
also helps when changing font styles in
.BR EX / EE
examples,
since they are not filled.
.
.
.br
.ne 6v
.RS
.IP
.\" from src/devices/grotty/grotty.1.man
.EX
\&.EX
$ \ec
\&.B groff \e\-T utf8 \e\-Z \ec
\&.I file \ec
\&.B | grotty \e\-i
\&.EE
.EE
.RE
.
.
.IP
.\" TODO: When we explain what a "sentence" is, move this pargraph
.\" there.
Normally,
if filling is enabled,
the formatter treats the end of a text line like a space.
.
It checks for the end of a sentence,
and
.I may
break the output line
(if not,
it inserts an adjustable space).
.
If filling is disabled,
the formatter
.I will
break the output line,
as in
.BR EX / EE
examples.
.
The formatter interprets the next input line as usual,
recognizing control lines,
including macro calls
(contrast with
.BI \e newline\/\c
).
.
.
.\" We once warned of \f possibly having "better portability" than \c;
.\" after several years of looking, GBR finds no evidence that this is
.\" the case.  However, po4a is confused by \c and refuses to process
.\" documents using it.  https://github.com/mquinson/po4a/issues/527
.IP
The
.B \ef
font selection escape sequence is an alternative to
.BR \ec ;
see below.
.
Using
.B \ec
to continue a
.B TP
paragraph tag across multiple input lines renders incorrectly with
.I groff
1.22.3,
.I mandoc
1.14.1,
older versions of these programs,
and perhaps with some other formatters.
.
.
.TP
.B \ee
Format the
.I roff
escape character on the output;
widely used in man pages to render a backslash glyph.
.
.\" Don't bold the ec request in this discussion; it's not a major
.\" topic of _this_ page as it would be in groff(7).  Also, we don't
.\" want to encourage people to mess with this old kludge by drawing
.\" attention to it.
It works reliably as long as the \[lq]ec\[rq] request is not used,
which should never happen in man pages,
and it is slightly more portable than the more explicit
.B \e[rs]
(\[lq]reverse solidus\[rq]) special character escape sequence.
.
.
.TP
.BR \efB ,\~ \efI ,\~ \efR ,\~ \efP
Switch to bold,
italic,
roman,
or back to the previous style,
respectively.
.
Either
.B \ef
or
.B \ec
is needed when three different font styles are required in a word.
.
.
.RS
.IP
.\" second example from contrib/pdfmark/pdfroff.1.man
.EX
\&.RB [ \e\-\e\-reference\e\-dictionary=\efI\e,name\e/\efP ]
.IP
\&.RB [ \e\-\e\-reference\e\-dictionary=\ec
\&.IR name ]
.EE
.RE
.
.
.IP
Style escape sequences may be more portable than
.BR \ec .
.
As shown above,
it is up to you to account for italic corrections with
.\" Normally we don't quote escape sequences, but these use
.\" potentially-confusing prose punctuation.
.RB \[lq] \^\e\|/\^ \[rq]
and
.RB \[lq] \^\e\^, \[rq],
which are themselves GNU extensions,
if desired and if supported by your implementation.
.
.
.IP
.B \efP
reliably returns to the style in use immediately preceding the
previous
.B \ef
escape sequence only if no
sectioning,
paragraph,
example,
or style macro calls have intervened.
.
.
.IP
As long as at most two styles are needed in a word,
style macros like
.B B
and
.B BI
usually result in more readable
.I roff
source than
.B \ef
escape sequences do.
.
.
.P
Several special characters are also widely portable.
.\" meaning: groff, Heirloom Doctools troff, neatroff, mandoc
.
Except for
.BR \[rs]\- ,
.BR \[rs][em] ,
and
.BR \[rs][ga] ,
AT&T
.I troff
did not consistently define the characters listed below,
.\" Only \-, \[em], and \[ga] were documented in CSTR #54 (1976).  CSTR
.\" #54 (1992) offers no _comprehensive_ list but shows \[en] in its
.\" PostScript DESC file example.  In DWB 3.3, \[aq] was supported by the
.\" "post" device, and \[dq] by "pcl" and "Latin1".
but its descendants,
like
DWB,
Plan\~9,
or
Solaris
.IR troff , \" DWB, Plan 9, Solaris
can be made to support them by defining them in font description files,
making them aliases of existing glyphs if necessary;
see
.MR groff_font 5 .
.
.IR groff 's
extended notation for special characters,
.BI \e[ xx ]\c
,
is also supported by
.MR mandoc 1 ,
Heirloom Doctools
.IR troff , \" Heirloom Doctools
and
.IR neatroff ,
but not
DWB,
Plan\~9,
or
Solaris
.IR troff s. \" DWB, Plan 9, Solaris
.
.
.TP
.B \e\-
Minus sign.
.
.B \e\-
produces the basic Latin hyphen-minus (U+002D) specifying Unix
command-line options and frequently used in file names.
.
.RB \[lq] \- \[rq]
is a hyphen in
.IR roff ;
some output devices format it as U+2010
(hyphen).
.
.
.TP
.B \e[aq]
Basic Latin neutral apostrophe.
.
Some output devices format
.RB \[lq]\| \[aq] \|\[rq]
as a right single quotation mark.
.
.
.TP
.B \e[oq]
.TQ
.B \e[cq]
Opening (left) and closing (right) single quotation marks.
.
Use these for paired directional single quotes,
\[oq]like this\[cq].
.
.
.TP
.B \e[dq]
Basic Latin quotation mark
(double quote).
.
Employ it in macro calls to work around interpretation of
.RB \[oq]\| \[dq] \|\[cq]
as an argument delimiter.
.\" This page prefers double quotes, but not here because they are more
.\" confusing to the eye when another double quote is what is quoted!
.\" AT&T: .RB  """
.
.
.RS
.IP
.\" from src/preproc/eqn/eqn.1.man
.EX
\&.TP
\&.BI \[dq]split \e[dq]\[dq] text \e[dq]
.EE
.RE
.
.
.br
.\" XXX: We need only 2v, but 2v more are necessary due to bad
.\" interaction with TP's own use of the ne request.
.ne 4v
.TP
.B \e[lq]
.TQ
.B \e[rq]
Left and right double quotation marks.
.
Use these for paired directional double quotes,
\[lq]like this\[rq].
.
.
.TP
.B \e[em]
Em dash.
.
Use for an interruption\[em]such as this one\[em]in a sentence.
.
.
.TP
.B \e[en]
En dash.
.
Use to separate the ends of a range,
as between numbers;
for example,
\[lq]the digits 1\[en]9\[rq].
.
.
.TP
.B \e[ga]
Basic Latin grave accent.
.
Some output devices format
.RB \[lq]\| \[ga] \|\[rq]
as a left single quotation mark.
.
.
.TP
.B \e[ha]
Basic Latin circumflex accent
(\[lq]hat\[rq]).
.
Some output devices format
.RB \[lq] \[ha] \[rq]
as U+02C6
(modifier letter circumflex accent).
.
.
.TP
.B \e[rs]
Reverse solidus
(backslash).
.
The backslash is the default escape character in the
.I roff
language,
so it does not represent itself in output.
.
Also see
.B \ee
above.
.
.
.TP
.B \e[ti]
Basic Latin tilde.
.
Some output devices format
.RB \[lq] \[ti] \[rq]
as U+02DC
(small tilde).
.
.
.P
For maximum portability,
avoid escape sequences
(including special characters) not listed above.
.
.
.\" ====================================================================
.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 [inches]).
.
.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.
.
.
.IP
.I Note:
terminals render
.I text
in bold at the normal size instead.
.
Do not rely upon
.B SB
to communicate semantic information distinct from using bold style at
normal size;
it is hidden from readers using such devices.
.
.
.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.
.
(\[lq]Titles\[rq] is the
.I roff
term for headers and footers.)
.
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 ).
.
For example,
the option
.B \-rX2
produces the following page
numbers: 1,
2,
2a,
2b,
\&.\|.\|.\|,
2aa,
2ab,
and so on.
.
.
.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.
.
.
.RS
.RS
.P
.EX
.ne 2v
\&.\e" Put only one space after the end of a sentence.
\&.ss 12 0 \e" See groff(7).
.ne 2v
\&.\e" Keep pages narrow even on wide terminals.
\&.if n .if \en[LL]>80n .nr LL 80n
.EE
.RE
.RE
.
.
.IP
On multi-user systems,
it is more considerate to users whose preferences may differ from the
administrator's to be less aggressive with such settings,
or to permit their override with a user-specific
.I man.local
file.
.
Place the requests below at the end of the site-local file to
manifest courtesy.
.
.RS
.RS
.EX
\&.soquiet \eV[XDG_CONFIG_HOME]/man.local
\&.soquiet \eV[HOME]/.man.local
.EE
.RE
.
However,
a security-sandboxed
.MR man 1 \" such as man-db 2.8.5
program may lack permission to open such files.
.RE
.
.
.\" ====================================================================
.SH Notes
.\" ====================================================================
.
Some tips on composing and troubleshooting your man pages follow.
.
.
.IP \[bu] 2n
What's the difference between a man page topic and identifier?
.
.
.IP
A single man page may document several related but distinct topics.
For example,
.MR printf 3
and
.MR fprintf 3
are often presented together.
.
Moreover,
multiple programming languages have functions named \[lq]printf\[rq],
and may document these in a man page.
.
The identifier is intended to
(with the section)
uniquely identify a page on the system;
it may furthermore correspond closely to the file name of the document.
.
.
.IP
The
.MR man 1
librarian makes access to man pages convenient by resolving topics to
man page identifiers.
.
Thus,
you can type
.RB \[lq] "man fprintf" \|\[rq],
and other pages can refer to it,
without knowing whether the installed document uses
\[lq]printf\|\[rq],
\[lq]fprintf\|\[rq],
or even \[lq]c_printf\|\[rq]
as its identifier.
.
.
.IP \[bu] 2n
Some ASCII characters look funny or copy and paste wrong.
.
.
.IP
On devices with large glyph repertoires,
like UTF-8-capable terminals and PDF,
GNU
.IR troff , \" GNU
like AT&T
.I troff \" AT&T
before it,
maps several keycaps to code points
outside the Unicode basic Latin range
(historically \[lq]ASCII\[rq])
because that usually results in better typography in the general case.
.
When documenting GNU/Linux command or C language syntax,
however,
this translation is sometimes not desirable.
.
.
.IP
.if t .ne 2v
.if n .ne 3v \" account for horizontal rule
.TS
Cb   Cb
RfCR LfCR.
To get a \[lq]literal\[rq].\|.\|.	.\|.\|.should be input.
_
\[aq]	\[rs][aq]
\-	\[rs]\-
\[rs]	\[rs][rs]
\[ha]	\[rs][ha]
\[ga]	\[rs][ga]
\[ti]	\[rs][ti]
_
.TE
.
.
.IP
If a neutral double quote (") is needed in a macro argument,
you can use
.B \[rs][dq]
to get it.
.
Do
.I not
use
.B \[rs][aq]
for an ordinary apostrophe
(as in \[lq]can't\[rq])
or
.B \[rs]\-
for an ordinary hyphen
(as in \[lq]word-aligned\[rq]).
.
.\" slack wording for managing stranded lines in PS/PDF output
.\"Review subsection \[lq]Portability\[rq] above.
.
.
.IP \[bu]
Do I ever need to use an empty macro argument ("")?
.
.
.IP
Probably not.
.
When this seems necessary,
often a shorter or clearer alternative is available.
.
.
.IP
.if n .if \n[LL]<72n .RS -4n \" begin shameless cheat for slim terminals
.if t .ne 10v
.if n .ne 16v \" account for horizontal rules
.TS
Cb   Cb
LfCR LfCR.
Instead of.\|.\|.\&	\&.\|.\|.should be considered.
_
\&.TP \[dq]\[dq]	.TP
_
\&.BI \[dq]\[dq] \fIitalic-text bold-text	.IB \fIitalic-text bold-text
_
\&.TH foo 1 \[dq]\[dq] \[dq]foo 1.2.3\[dq]	.TH foo 1 \
\f(CIyyyy\fP-\f(CImm\fP-\f(CIdd\fP \[dq]foo 1.2.3\[dq]
_
\&.IP \[dq]\[dq] 4n	.IP
_
\&.IP \[dq]\[dq] 4n	.RS 4n
\fIparagraph	.P
\fR.\|.\|.	\fIparagraph
\fR.\|.\|.	.RE
_
\&.B one two \[dq]\[dq] three	.B one two three
.TE
.if n .if \n[LL]<68n .RE \" end shameless cheat for slim terminals
.
.
.IP
In the title heading
.RB ( TH ),
the date of the page's last revision is more important than packaging
information;
it should not be omitted.
.
Ideally,
a page maintainer keeps both up to date.
.
.
.IP
.B IP
is sometimes ill-understood and misused,
especially when no mark argument is supplied\[em]an indentation argument
is not required.
.
By setting an explicit indentation,
you may be overriding the reader's preference as set with the
.B \-rIN
option.
.
If your page renders adequately without one,
use the simpler form.
.
If you need to indent multiple (unmarked) paragraphs,
consider setting an inset region with
.B RS
and
.B RE
instead.
.
.
.IP
In the last example,
the empty argument does have a subtly different effect than its
suggested replacement:
the empty argument causes an additional space character to be
interpolated between the arguments \[lq]two\[rq] and \[lq]three\[rq]\[em]but
it is a regular breaking space,
so it can be discarded at the end of an output line.
.
It is better not to be subtle,
particularly with space,
which can be overlooked in source and rendered forms.
.
.
.IP \[bu]
.B RS
doesn't indent relative to my indented paragraph.
.
.
.IP
The
.B RS
macro determines the
.I "inset amount,"
the position at which an
.I ordinary
paragraph
.RB ( P
and its synonyms)
is set;
the value of the
.B IN
register determines its default amount.
.
This register also determines
the default indentation used by
.BR IP ,
.BR TP ,
and
.BR HP .
.
To create an inset relative to an indented paragraph,
call
.B RS
repeatedly until an acceptable indentation is achieved,
or give
.B RS
an indentation argument that is at least as much as the paragraph's
indentation amount relative to an adjacent ordinary
.RB ( P )
paragraph.
.
.
.IP
Another approach to tagged paragraphs places an
.B RS
call immediately after the tag;
this also forces a break regardless of the tag's width,
which some authors prefer.
.
Follow-up paragraphs under the tag can then be set with
.B P
instead of
.BR IP .
.
Remember to use
.B RE
to end the indented region before starting the next tagged paragraph
(at the appropriate nesting level).
.
.
.IP \[bu]
.B RE
doesn't move the inset back to the expected level.
.
.
.IP
.B RE
takes an inset
.I level
as an argument,
unlike
.BR RS 's
inset
.I amount.
.
.RB \[lq] .RE\~1 \[rq]
goes to the level before any
.B RS
macros were called,
.B RE\~2
goes to the level of the first
.B RS
call you made,
and so forth.
.
If you desire symmetry in your macro calls,
simply issue one
.B RE
without an argument
for each
.B RS
that precedes it.
.
.
.IP
The
.B SH
and
.B SS
sectioning macros clear relative insets;
.B RE
calls have no effect until
.B RS
is used again.
.
.
.IP \[bu]
Do I need to keep typing the indentation in a series of
.B IP
calls?
.
.
.IP
Not if you don't want to change it.
.
Review subsection \[lq]Horizontal and vertical spacing\[rq] above.
.
.
.IP
.if t .ne 5v
.if n .ne 7v \" account for horizontal rules
.TS
Cb   Cb
LfCR LfCR.
Instead of.\|.\|.	.\|.\|.should be considered.
_
\&.IP \[rs][bu] 4n	.IP \[rs][bu] 4n
\fIparagraph	\fIparagraph
\&.IP \[rs][bu] 4n	.IP \[rs][bu]
\fIanother-paragraph	\fIanother-paragraph
_
.TE
.
.
.IP \[bu]
Why doesn't the package provide a string to insert an ellipsis?
.
.
.IP
Examples of ellipsis usage are shown above,
in subsection \[lq]Synopsis macros\[rq].
.
The idiomatic
.I roff
ellipsis is three dots (periods)
with thin space escape sequences
.B \[rs]|
internally separating them.
.
Since dots both begin control lines and are candidate end-of-sentence
characters,
however,
it is sometimes necessary to prefix and/or suffix an ellipsis with the
dummy character escape sequence
.BR \[rs]& .
.
That fact stands even if a string is defined to contain the sequence;
further,
if the string ends with
.BR \[rs]& ,
end-of-sentence detection is defeated when you use the string at the end
of an actual sentence.
.
(Ending a sentence with an ellipsis is often poor style,
but not always.)
.
A hypothetical string
.B EL
that contained an ellipsis,
but not the trailing dummy character
.BR \[rs]& ,
would then need to be suffixed with the latter
when not ending a sentence.
.
.
.IP
.if t .ne 5v
.if n .ne 7v \" account for horizontal rules
.TS
Cb   Cb
LfCR LfCR.
Instead of.\|.\|.\&	\&.\|.\|.do this.
_
\&.ds EL \[rs]&.\[rs]|.\[rs]|.	Arguments are
Arguments are	.IR src-file\[rs]\[ti] .\[rs]|.\[rs]|.\[rs]&
\&.IR src-file\[rs]\[ti] \[rs]*(EL\[rs]&	.IR dest-dir .
\&.IR dest-dir .
_
.TE
.
.
.IP
The first column practices a false economy;
the savings in typing is offset by the cost of obscuring even the
suggestion of an ellipsis to a casual reader of the source document,
and reduced portability to
.RI non- roff
man page formatters that cannot handle string definitions.
.
.
.IP
Unicode defines an ellipsis code point,
and some fonts have an ellipsis glyph,
which some man pages have accessed non-portably with the font-dependent
.B \[rs]N
escape sequence.
.
We discourage their use;
on terminals,
they may crowd the dots into a half-width character cell,
and do not render at all if the output device lacks the glyph.
.
In synopses,
missing ellipses can mislead the reader.
.
Dots and space are universally supported.
.\" XXX: Does an unconditional _preceding_ dummy character cause
.\" problems?
.
.
.br
.ne 4v
.IP \[bu]
When and how should I use quotation marks?
.
.
.IP
As noted above in subsection \[lq]Font style macros\[rq],
apply quotation marks to
\[lq]brief specimens of literal text,
such as article titles,
inline examples,
mentions of individual characters or short strings,
and (sub)section headings in man pages\[rq].
.
Multi-word literals,
such as Unix commands with arguments,
when set inline
(as opposed to displayed between
.B EX
and
.BR EE ),
should be quoted
to ensure that the boundaries of the literal
are clear even when the material is stripped of font styling
by,
for example,
copy-and-paste operations.
.
.IR groff ,
Heirloom Doctools
.IR troff , \" Heirloom
.IR neatroff ,
and
.I mandoc
support all of the special characters
.BR \[rs][oq] ,
.BR \[rs][cq] ,
.BR \[rs][lq] ,
.BR \[rs][rq] ,
.BR \[rs][aq] ,
and
.B \[rs][dq]
described in subsection \[lq]Portability\[rq] above.
.
DWB,
Plan\~9,
and
Solaris
.IR troff s \" DWB, Plan 9, Solaris
do not.
.
Interpolating the strings
.B \e*(lq
and
.B \e*(rq
portably yields directional double quotation marks,
if available,
in all these formatters
.\" including plan9port/Plan 9 from User Space as of commit e5b5757e64,
.\" 10 October 2025
(though
.I neatroff
does not supply a
.I man
macro package),
but they cannot reliably be used in macro arguments.
.
.
.IP
Obtaining directional single quotation marks is more of a challenge.
.
Historically,
man pages used
.B \[ga]
and
.B \[aq],
which
.I troff \" generic
rendered on typesetters
as \[oq] and \[cq],
exclusively for them.
.
However,
in recent years,
some distributors of
.I groff
have chosen to override the meanings of these characters in man pages,
remapping them to their Unicode Basic Latin code points.
.
Unfortunately,
.B \[ga]
and
.B \[aq]
are the
.I only
reliable means of obtaining directional single quotation marks in AT&T
.IR troff ; \" AT&T
in that implementation,
often no special character escape sequences exist to obtain them.
.
Further,
AT&T
.IR troff 's \" troff
special character identifiers,
like its font names,
were device-specific.
.
To achieve quotation portably in man pages rendered both by
AT&T and more modern
.IR troff s, \" generic
consider adding a preamble to your page after the
.B TH
call as follows.
.
.
.RS
.P
.RS
.EX
\&.ie \[rs]n(.g \[rs]{\[rs]
\&.  ds oq \[rs][oq]\[rs]"
\&.  ds cq \[rs][cq]\[rs]"
\&.\[rs]}
\&.el \[rs]{\[rs]
\&.  ds oq \[ga]\[rs]"
\&.  ds cq \[aq]\[rs]"
\&.\[rs]}
.EE
.RE
.
.
.P
You must then use the
.B \[rs]*
escape sequence to interpolate the quotation mark strings.
.
.
.P
.\" begin shameless cheat for slim terminals
.ds Indent \" empty
.if n .if \n[LL]<68n .ds Indent 2n
.RS \*[Indent]
.rm Indent
.\" end shameless cheat for slim terminals
.EX
The command
\&.RB \[rs]*(oq "while !\[rs]& git pull; do sleep 10; done" \[rs]*(cq
retries an update from the repository until it succeeds.
.EE
.RE
.
.P
If this procedure seems complex,
petition your distributor to revert their remapping of the
\[ga] and \[aq] characters.
.RE
.
.
.IP \[bu]
Escape sequences of the form
.BI \[rs][ xx ]
don't format correctly.
.
.
.IP
The
.BI \[rs][ xx ]
special character escape sequence is a
GNU
.I troff
extension also supported by
.I mandoc,
Heirloom Doctools
.I troff,
and
.I neatroff.
.
DWB,
Plan\~9,
and
Solaris
.IR troff s \" DWB, Plan 9, Solaris
don't implement it.
.
If your man page requires portability to these formatters,
spell such escape sequences as
.RB \[lq]\^ \[rs](\c
.IR xx \[rq];
no closing parenthesis is used.
.
.I xx
must be exactly two characters;
.MR groff_char 7
lists portable special character identifiers.
.
.
.\" ====================================================================
.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.
Raymond also originated the portability section,
to which
.MT schwarze@\:usta\:.de
Ingo Schwarze
.ME
contributed most of the material on escape sequences.
.
.
.\" ====================================================================
.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 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: