Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 4117 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man7/groff_man_style.7 b/upstream/opensuse-tumbleweed/man7/groff_man_style.7
new file mode 100644
index 00000000..94acc53c
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man7/groff_man_style.7
@@ -0,0 +1,4117 @@
+'\" t
+.\" This page is generated by m4 from tmac/groff_man.7.man.in.
+.TH groff_man_style 7 "4 October 2023" "groff 1.23.0"
+.SH Name
+groff_man_style \- GNU
+.I roff
+man page tutorial and style guide
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1999-2018, 2020-2021 Free Software Foundation, Inc.
+.\"
+.\" 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\~ .\|.\|.]
+.
+.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 produce manual pages
+.\" We use an unbreakable space \~ here to keep the phrase intact for
+.\" its introduction; in subsequent discussion, that is not important.
+(\(lqman\~pages\(rq)
+like the one you are reading.
+.
+.
+.P
+This document presents the macros thematically;
+for those needing only a quick reference,
+the following table lists them alphabetically,
+with cross references to appropriate subsections below.
+.
+.
+.P
+.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
+\&.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
+\&.SB	Small bold	Font style macros
+\&.SH	Section heading	Document structure macros
+\&.SM	Small	Font style macros
+\&.SS	Subsection heading	Document structure macros
+\&.SY	Synopsis start	Command 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	Command synopsis macros
+.TE
+.
+.
+.P
+We discuss other macros
+.RB ( .AT ,
+.BR .DT ,
+.BR .HP ,
+.BR .OP ,
+.BR .PD ,
+and
+.BR .UC )
+in subsection \(lqDeprecated features\(rq below.
+.
+.
+.P
+Throughout Unix documentation,
+a manual entry is referred to simply as a \(lqman page\(rq,
+regardless of its length,
+without gendered implication,
+and irrespective of the macro package selected for its composition.
+.
+.
+.\" ====================================================================
+.\" .SS "Input file format"
+.\" ====================================================================
+.P
+Man pages should be encoded using Unicode basic Latin code points
+exclusively,
+and employ the Unix line-ending convention
+(U+000A only).
+.\" What about rare English words that require diacritics, and
+.\" proper names that require more than basic Latin?
+.\"
+.\" sentence (including end-of-sentence detection)
+.\" The above distinction works well with filling.
+.\" Don't fill your input text yourself; let groff do the work.
+.\" Also good for diffs.
+.\" escape sequences--pretty much just "see Portability"
+.
+.\" ====================================================================
+.SS "Fundamental concepts"
+.\" ====================================================================
+.\" font (family, style [elsewhere known as face])
+.\" type size
+.\" typesetter (troff device, PostScript, PDF)
+.\" terminal (nroff device, emulator, typewriter, TTY)
+.I groff
+is a programming system for typesetting:
+we thus often use the verb \(lqto set\(rq in the sense
+\(lqto typeset\(rq.
+.
+The formatter
+.MR \%troff 1
+collects words from the input and
+.I fills
+output lines with as many as will 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.
+.
+When formatted,
+a word may be broken at hyphens,
+at
+.B \e%
+or
+.B \e:
+escape sequences
+(see subsection \(lqPortability\(rq below),
+or at predetermined locations
+if automatic hyphenation is enabled
+(see the
+.B \-rHY
+option in section \(lqOptions\(rq below).
+.
+An output line may be supplemented with
+.I inter-sentence space,
+and then optionally
+.I adjusted
+with more space to a consistent line length
+(see the
+.B \-dAD
+option).
+.
+.MR roff 7
+details these processes.
+.
+.
+.P
+An input line that starts with a dot (.\&)
+or neutral apostrophe (\(aq)
+is a
+.I control line.
+.
+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.
+.
+We refer to macros in this document using this leading dot.
+.
+Some macros interpret
+.I arguments,
+words that follow the macro name.
+.
+A newline,
+unless escaped
+(see subsection \(lqPortability\(rq below),
+marks the end of the macro call.
+.
+An input line consisting of a dot followed by a newline
+is called the
+.I empty request;
+it does nothing.
+.
+.I Text lines
+are input lines that are not control lines.
+.
+.
+.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
+.
+.
+.br
+.ne 6v
+.\" ====================================================================
+.SS "Macro reference preliminaries"
+.\" ====================================================================
+.
+A tagged paragraph describes each macro.
+.
+We present coupled pairs together,
+as with
+.B .EX
+and
+.BR .EE .
+.
+.
+.br
+.ne 2v
+.P
+Optional macro arguments are indicated by surrounding them with square
+brackets.
+.
+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.
+.
+An empty macro argument can be specified with a pair of double-quotes
+(""),
+but the
+.I man
+package is designed such that this should seldom be necessary.
+.
+See section \(lqNotes\(rq below for examples of cases where better
+alternatives to empty arguments in macro calls are available.
+.
+Most macro arguments will be formatted as text in the output;
+exceptions are noted.
+.
+.
+.\" ====================================================================
+.SS "Document structure macros"
+.\" ====================================================================
+.
+Document structure macros organize a man page's content.
+.
+All of them break the output line.
+.
+.B .TH
+(title heading)
+identifies the document as a man page and configures the page headers
+and footers.
+.
+Section headings
+.RB ( .SH ),
+one of which is mandatory and many of which are conventionally expected,
+facilitate location of material by the reader and aid the man page
+writer to discuss all essential aspects of the topic.
+.
+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 " topic section"\c
+.RI " [" footer-middle ]\c
+.RI " [" footer-inside ]\c
+.RI " [" header-middle ]
+Determine the contents of the page header and footer.
+.
+.I roff
+systems refer to these collectively as \(lqtitles\(rq.
+.
+The subject of the man page is
+.I topic
+and the section of the manual to which it belongs is
+.I section.
+.
+This use of \(lqsection\(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 topic
+and
+.I section
+are positioned together at the left and right in the header
+(with
+.I section
+in parentheses immediately appended to
+.IR topic ).
+.
+.I footer-middle
+is centered in the footer.
+.
+The arrangement of the rest of the footer depends on whether
+double-sided layout is enabled with the option
+.BR \-rD1 .
+.
+When disabled (the default),
+.I footer-inside
+is positioned at the bottom left.
+.
+Otherwise,
+.I footer-inside
+appears at the bottom left on recto (odd-numbered) pages,
+and at the bottom right on verso (even-numbered) pages.
+.
+The outside footer is the page number,
+except in the continuous-rendering mode enabled by the option
+.BR \-rcR=1 ,
+in which case it is the
+.I topic
+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
+will supply text for it.
+.
+The macro package may also abbreviate
+.I topic
+and
+.I footer-inside
+with ellipses
+.RB ( .\|.\|.\& )
+if they would overrun the space available in the header and footer,
+respectively.
+.
+For HTML output,
+headers and footers are suppressed.
+.
+.
+.IP
+Additionally,
+this macro breaks the page,
+resetting the number to\~1
+(unless the
+.B \-rC1
+option is given).
+.
+This feature is intended only for formatting multiple
+.I man
+documents in sequence.
+.
+.
+.IP
+A valid
+.I man
+document calls
+.B .TH
+once,
+early in the file,
+prior to any other macro calls.
+.
+.
+.IP
+By convention,
+.I footer-middle
+is the date of the most recent modification to the man page source
+document,
+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.
+.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line
+.\", which can be formatted with a macro, \" true but discouraged
+becomes
+.I heading-text.
+.
+The left margin is reset to zero to set the heading text in bold
+(or the font specified by the string
+.BR HF ),
+and,
+on typesetting devices,
+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,
+setting the left margin to the value of the
+.B IN \" TODO: future: BP or BI register ("base paragraph indentation")
+register.
+.
+Text after
+.I heading-text
+is 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 has much of the layout of material within sections.
+.
+For example,
+a section called \(lqName\(rq or \(lqNAME\(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
+.RB "].\|.\|.\& \e\- "\c
+.I summary-description
+.RE \" Move left margin back to .IP indentation.
+for a man page to be properly indexed.
+.
+See
+.MR man 7
+for the conventions prevailing on your system.
+.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 ).
+.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line
+.\", which can be formatted with a macro, \" true but discouraged
+becomes
+.I subheading-text.
+.
+The left margin is reset to the value of the
+.B SN
+register to set the heading text 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,
+setting the left margin to the value of the
+.B IN \" TODO: future: BP or BI register ("base paragraph indentation")
+register.
+.
+Text after
+.I subheading-text
+is set as an ordinary paragraph
+.RB ( .P ).
+.
+.
+.TP
+.B .EX
+.TQ
+.B .EE
+Begin and end example.
+.
+After
+.BR .EX ,
+filling is disabled and a constant-width (monospaced) font is selected.
+.
+Calling
+.B .EE
+enables filling and restores the previous font.
+.
+.
+.IP
+Example regions are useful for formatting code,
+shell sessions,
+and text file contents.
+.
+An example region is not
+a \(lqliteral 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
+.BR \(ti ,
+and sentence endings are still detected and additional inter-sentence
+space applied.
+.
+If the amount of additional 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
+.\" Also see subsection "History" below...
+These macros are extensions introduced in Ninth Edition Research Unix.
+.
+Systems running that
+.IR troff , \" AT&T Research Unix
+or those from
+Documenter's Workbench,
+Heirloom Doctools,
+or Plan\~9
+.I troff
+support them.
+.\" Solaris 10 troff does not support .EX/.EE.  Neatroff doesn't ship
+.\" (m)an macros.
+.
+To be certain your page will be portable to systems that do not,
+copy their definitions from the
+.I \%an\-ext.tmac
+file of a
+.I groff
+installation.
+.
+.
+.TP
+.BR .RS " ["\c
+.IR inset-amount ]
+Start a new relative inset level.
+.
+The position of the left margin is saved,
+then moved right by
+.I inset-amount,
+if specified,
+and by the amount of the
+.B IN
+register otherwise.
+.
+Calls to
+.B .RS
+can be nested;
+each increments by\~1
+the inset level used by
+.BR .RE .
+.
+The level prior to any
+.B .RS
+calls is\~1.
+.
+.
+.TP
+.BR .RE " ["\c
+.IR level ]
+End a relative inset.
+.
+The left margin corresponding to inset level
+.I level
+is restored.
+.
+If no argument is given,
+the inset level is reduced by\~1.
+.
+.
+.\" ====================================================================
+.SS "Paragraphing macros"
+.\" ====================================================================
+.
+An ordinary paragraph
+.RB ( .P )
+like this one
+is set without a first-line indentation at the current left margin.
+.
+In man pages and other technical literature,
+definition lists are frequently encountered;
+these can be set as \(lqtagged paragraphs\(rq,
+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 is useful to continue the indented content of a narrative started
+with
+.BR .TP ,
+or to present an itemized or ordered list.
+.
+All of these macros break the output line.
+.
+If another paragraph macro has occurred since the previous
+.B .SH
+or
+.BR .SS ,
+they
+(except for
+.BR .TQ )
+follow the break with a default amount of vertical space,
+which can be changed by the deprecated
+.B .PD
+macro;
+see subsection \(lqHorizontal and vertical spacing\(rq below.
+.
+They also reset the type size and font style to defaults
+.RB ( .TQ
+again excepted);
+see subsection \(lqFont style macros\(rq below.
+.
+.
+.br
+.ne 4v
+.TP
+.B .P
+.TQ
+.B .LP
+.TQ
+.B .PP
+Begin a new paragraph;
+these macros are synonymous.
+.
+The indentation is reset to the default value;
+the left margin,
+as affected by
+.B .RS
+and
+.BR .RE ,
+is not.
+.
+.
+.TP
+.BR .TP " ["\c
+.IR indentation ]
+Set a paragraph with a leading tag,
+and the remainder of the paragraph indented.
+.
+A one-line input trap is planted;
+text on the next line,
+which can be formatted with a macro,
+becomes the tag,
+which is placed at the current left margin.
+.
+The tag can be extended with the
+.B \(rsc
+escape sequence.
+.
+Subsequent text is indented by
+.I indentation,
+if specified,
+and by the amount of the
+.B IN
+register otherwise.
+.
+If the tag is not as wide as the indentation,
+the paragraph starts on the same line as the tag,
+at the applicable indentation,
+and continues on the following lines.
+.
+Otherwise,
+the descriptive part of the paragraph begins on the line following 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 .
+.
+An input trap is planted as with
+.BR .TP .
+.
+.
+.IP
+This macro is a GNU extension not defined on systems running
+AT&T,
+Plan\~9,
+or
+Solaris
+.IR troff ;
+see
+.I \%an\-ext.tmac
+in section \(lqFiles\(rq below.
+.
+.
+.IP
+The descriptions of
+.BR .P ,
+.BR .LP ,
+and
+.B .PP
+above were written using
+.B .TP
+and
+.BR .TQ .
+.
+.
+.TP
+.BR .IP " ["\c
+.IR tag "] "\c
+.RI [ indentation ]
+Set an indented paragraph with an optional tag.
+.
+The
+.I tag
+and
+.I indentation
+arguments,
+if present,
+are handled as with
+.BR .TP ,
+with the exception that the
+.I tag
+argument to
+.B .IP
+cannot include a macro call.
+.
+.
+.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) 4n
+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 tag
+that is not semantically important,
+such as a bullet (\(bu)\(emobtained with the
+.B \e(bu
+special character escape sequence\(emor 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 "Command synopsis macros"
+.\" ====================================================================
+.
+.B .SY
+and
+.B .YS
+aid you to construct a command synopsis that has the classical Unix
+appearance.
+.
+They break the output line.
+.
+.\" 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.
+.
+.
+.P
+These macros are GNU extensions not defined on systems running
+AT&T,
+Plan\~9,
+or
+Solaris
+.IR troff ;
+see
+.I \%an\-ext.tmac
+in section \(lqFiles\(rq below.
+.
+.
+.TP
+.BI .SY " command"
+Begin synopsis.
+.
+A new paragraph begins at the left margin
+(as with
+.BR .P )
+unless
+.B .SY
+has already been called without a corresponding
+.BR .YS ,
+in which case only a break is performed.
+.
+Adjustment and automatic hyphenation are disabled.
+.
+.I command
+is set in bold.
+.
+If a break is required,
+lines after the first are indented by the width of
+.I command
+plus a space.
+.
+.
+.TP
+.B .YS
+End synopsis.
+.
+Indentation,
+adjustment,
+and hyphenation
+are restored to their previous states.
+.
+.
+.P
+Multiple
+.BR .SY / .YS
+blocks can be specified,
+for instance to distinguish differing modes of operation of a complex
+command like
+.MR tar 1 ;
+each will be vertically separated as paragraphs are.
+.
+.
+.P
+.B .SY
+can be repeated before
+.B .YS
+to indicate synonymous ways of invoking a particular mode of operation.
+.
+.
+.br
+.ne 2v
+.P
+.IR groff 's
+own command-line interface serves to illustrate most of the specimens
+of synopsis syntax one is likely to encounter.
+.
+.
+.IP
+.\" from src/roff/groff/groff.1.man
+.EX
+\&.SY groff
+\&.RB [ \e-abcCeEgGijklNpRsStUVXzZ ]
+\&.RB [ \e-d\e\(ti\ec
+\&.IR cs ]
+\&.RB [ \e-d\e\(ti\ec
+\&.IB name =\ec
+\&.IR string ]
+\&.RB [ \e-D\e\(ti\ec
+\&.IR enc ]
+.EE
+.
+.I (and so on similarly)
+.
+.EX
+\&.RI [ file\e\(ti .\e|.\e|.]
+\&.YS
+\&.
+\&.
+\&.SY groff
+\&.B \e-h
+\&.
+\&.SY groff
+\&.B \e-\e-help
+\&.YS
+\&.
+\&.
+\&.SY groff
+\&.B \e-v
+\&.RI [ option\e\(ti .\e|.\e|.\e&]
+\&.RI [ file\e\(ti .\e|.\e|.]
+\&.
+\&.SY groff
+\&.B \e-\e-version
+\&.RI [ option\e\(ti .\e|.\e|.\e&]
+\&.RI [ file\e\(ti .\e|.\e|.]
+\&.YS
+.EE
+.
+.
+.P
+produces the following output.
+.
+.
+.RS
+.SY groff
+.RB [ \-abcCeEgGijklNpRsStUVXzZ ]
+.RB [ \-d\~\c
+.IR cs ]
+.RB [ \-d\~\c
+.IB name =\c
+.IR string ]
+.RB [ \-D\~\c
+.IR enc ]
+.RB [ \-f\~\c
+.IR fam ]
+.RB [ \-F\~\c
+.IR dir ]
+.RB [ \-I\~\c
+.IR dir ]
+.RB [ \-K\~\c
+.IR enc ]
+.RB [ \-L\~\c
+.IR arg ]
+.RB [ \-m\~\c
+.IR name ]
+.RB [ \-M\~\c
+.IR dir ]
+.RB [ \-n\~\c
+.IR num ]
+.RB [ \-o\~\c
+.IR list ]
+.RB [ \-P\~\c
+.IR arg ]
+.RB [ \-r\~\c
+.IR cn ]
+.RB [ \-r\~\c
+.IB reg =\c
+.IR expr ]
+.RB [ \-T\~\c
+.IR dev ]
+.RB [ \-w\~\c
+.IR name ]
+.RB [ \-W\~\c
+.IR name ]
+.RI [ file\~ .\|.\|.]
+.YS
+.
+.
+.SY groff
+.B \-h
+.
+.SY groff
+.B \-\-help
+.YS
+.
+.
+.SY groff
+.B \-v
+.RI [ option\~ .\|.\|.\&]
+.RI [ file\~ .\|.\|.]
+.
+.SY groff
+.B \-\-version
+.RI [ option\~ .\|.\|.\&]
+.RI [ file\~ .\|.\|.]
+.YS
+.RE
+.
+.
+.P
+Several features of the above example are of note.
+.
+.
+.IP \(bu 2n
+The empty request (.),
+which does nothing,
+is used to vertically space the input file for readability by the
+document maintainer.
+.
+Do not put blank (empty) lines in a man page source document.
+.
+.
+.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 \(lqFont style macros\(rq below regarding terminals)
+to cue the user that they must be replaced with appropriate text.
+.
+.
+.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 syntactical element may be
+repeated arbitrarily.
+.
+.
+.IP \(bu
+The non-breaking adjustable space escape sequence
+.B \e\(ti
+is used to prevent the output line from being broken within the option
+brackets;
+see subsection \(lqPortability\(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 \(lqPortability\(rq below.
+.
+.
+.IP \(bu
+The dummy character escape sequence
+.B \e&
+follows the ellipsis when further text will 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 a newline...
+and causing additional inter-sentence space to be placed after it.
+.
+See subsection \(lqPortability\(rq below.
+.
+.
+.\" ====================================================================
+.SS "Hyperlink macros"
+.\" ====================================================================
+.
+Man page cross references
+like
+.MR ls 1
+are best presented with
+.BR .MR .
+.
+Text may be hyperlinked to email addresses with
+.BR .MT / .ME
+or other URIs with
+.BR .UR / .UE .
+.
+Hyperlinked text is supported on HTML
+.\", PDF,
+and terminal output devices;
+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),
+.B .MT
+and
+.B .UR
+URIs are rendered between angle brackets after the linked text.
+.
+.
+.P
+.BR .MT ,
+.BR .ME ,
+.BR .UR ,
+and
+.B .UE
+are GNU extensions not defined on systems running
+AT&T,
+Plan\~9,
+or
+Solaris
+.IR troff ; \" Solaris
+see
+.I \%an\-ext.tmac
+in section \(lqFiles\(rq below.
+.
+Plan\~9 from User Space's
+.I troff \" plan9port
+implements
+.BR .MR .
+.
+.
+.P
+The arguments to
+.BR .MR ,
+.BR .MT ,
+and
+.B .UR
+should be prepared for typesetting since they can appear in the
+output.
+.
+Use special character escape sequences to encode Unicode basic Latin
+characters where necessary,
+particularly the hyphen-minus.
+.
+(See section \[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 a hyperlink 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.
+.
+The formatter removes
+.B \e:
+escape sequences from hyperlinks when supplying device control commands
+to output drivers.
+.
+.
+.TP
+.BI .MR "\~topic manual-section"\c
+.RI \~[ 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 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.
+.
+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 \(lqmailto:\(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.
+.
+.
+.br
+.ne 6v
+.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
+displays as \(lqContact Fred Foonly \(lafred\:.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.
+.
+.
+.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
+displays as \(lqThe GNU Project of the Free Software Foundation hosts
+the
+.I groff
+home page
+\(lahttps://\:www\:.gnu\:.org/\:software/\:groff/\(ra.\(rq.
+.
+.
+.P
+The hyperlinking of
+.B .TP
+paragraph tags with
+.BR .UR / .UE
+and
+.BR .MT / .ME
+is not yet supported;
+if attempted,
+the hyperlink will be typeset at the beginning of the indented paragraph
+even on hyperlink-supporting devices.
+.
+.
+.\" ====================================================================
+.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 is usually set underscored instead on terminal devices.
+.
+The
+.B .SM
+and
+.B .SB
+macros set text in roman or bold,
+respectively,
+at a smaller type size;
+these differ visually from regular-sized roman or bold text only on
+typesetting devices.
+.
+It is often necessary to set text in different styles without
+intervening space.
+.
+The macros
+.BR .BI ,
+.BR .BR ,
+.BR .IB ,
+.BR .IR ,
+.BR .RB ,
+and
+.BR .RI ,
+where \(lqB\(rq,
+\(lqI\(rq,
+and \(lqR\(rq indicate bold,
+italic,
+and roman,
+respectively,
+set their odd- and even-numbered arguments in alternating styles,
+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.
+.
+.
+.br
+.ne 2v
+.P
+The default type size and family for typesetting devices 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.
+.
+If no argument is given,
+a one-line input trap is planted;
+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.
+.
+If no argument is given,
+a one-line input trap is planted;
+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 typesetting devices.
+.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line,
+which can be further formatted with a macro,
+is set smaller.
+.
+.
+.IP
+.I Note:
+terminals will 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 will be hidden from readers using such devices.
+.
+.
+.TP
+.BR .SB \~[\c
+.IR text ]
+Set
+.I text
+in bold and
+(on typesetting devices)
+one point smaller than the default type size.
+.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line,
+which can be further formatted with a macro,
+is set smaller and in bold.
+.
+This macro is an extension introduced in SunOS\~4.0.
+.
+.
+.IP
+.I Note:
+terminals will 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 will be hidden from readers using such devices.
+.
+.
+.P
+Observe what is
+.I not
+prescribed for setting in bold or italics above:
+elements of \(lqsynopsis 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\~13.0,
+or
+POSIX.1-2017;
+acronyms;
+and occurrences after the first of a technical term.
+.
+.
+.P
+Be frugal with italics for emphasis,
+and particularly with bold.
+.
+Article titles and brief runs of literal text,
+such as references to individual characters or short strings,
+including section and subsection headings of man pages,
+are suitable objects for quotation;
+see the
+.BR \e(lq ,
+.BR \e(rq ,
+.BR \e(oq ,
+and
+.B \e(cq
+escape sequences in subsection \(lqPortability\(rq below.
+.
+.
+.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.
+.
+Italic corrections are applied 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 \(lqPortability\(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\~ register = numeric-expression
+.EE
+.RE
+.
+.
+.TP
+.BI .BR " bold-text roman-text "\c
+\&.\|.\|.\&
+Set each argument in bold and roman,
+alternately.
+.
+.
+.RS
+.IP
+.\" from tmac/groff_ms.7.man
+.EX
+After
+\&.B .NH
+is called,
+.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/preproc/pic/pic.1.man
+.EX
+if
+\&.I file
+is
+\&.RB \[rs][lq] \[rs]\- \[rs][rq],
+the standard input stream is read.
+.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
+.I indentation
+argument accepted by
+.BR .IP ,
+.BR .TP ,
+and the deprecated
+.B .HP
+is a number plus an optional scaling unit,
+as is
+.BR .RS 's
+.IR inset-amount .
+.
+If no scaling unit is given,
+the
+.I man
+package assumes \(lqn\(rq;
+that is,
+the width of a letter \(lqn\(rq in the font current when the macro is
+called
+(see section \(lqMeasurements\(rq in
+.MR groff 7 ).
+.
+An indentation specified in a call to
+.BR .IP ,
+.BR .TP ,
+or the deprecated
+.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.
+.
+.
+.P
+The left margin used by ordinary paragraphs set with
+.B .P
+(and its synonyms)
+not within an
+.BR .RS / .RE
+relative inset
+.\" TODO: future: BP or BI register ("base paragraph indentation")
+is 7.2n for typesetting devices
+and 7n for terminal devices
+(but see the
+.B \-rIN
+option).
+.
+Headers,
+footers
+(both set with
+.BR .TH ),
+and section headings
+.RB ( .SH )
+are set at the page offset
+(see
+.MR groff 7 )
+and subsection headings
+.RB ( .SS )
+indented from it by 3n
+(but see the
+.B \-rSN
+option).
+.
+.\" XXX: This is not true, but they do handle it badly.
+.\" HTML output devices ignore indentation.
+.
+.
+.P
+It may be helpful to think of the left margin and indentation as related
+but distinct concepts;
+.IR groff 's
+implementation of the
+.I man
+macro package tracks them separately.
+.
+The left margin 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 deprecated
+.B .HP
+macros,
+and cancelled by
+.B .P
+and its synonyms.
+.
+An extensive example follows.
+.
+.
+.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
+(in other words,
+moved the left margin)
+with
+.B .RS
+and started another ordinary paragraph with
+.BR .P .
+.
+.
+.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 ,
+will appear 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.
+.
+This paragraph is affected both by the moved left margin
+.RB ( .RS )
+and indentation
+.RB ( .IP ).
+.
+.TS
+box;
+l.
+This table is affected both by
+the left margin and indentation.
+.TE
+.
+.
+.IP \(bu
+This indented paragraph has a bullet for a tag,
+making it more obvious that the left margin and indentation are
+distinct;
+only the former affects the tag,
+but both affect the text of the paragraph.
+.
+.
+.br
+.ne 3v
+.P
+This ordinary
+.RB ( .P )
+paragraph resets the indentation,
+but the left margin is still inset.
+.
+.TS
+box;
+l.
+This table is affected only
+by the left margin.
+.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 reset the left margin to the default.
+.
+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 the deprecated
+.BR .HP ;
+the result may not render comprehensibly on an output device you fail to
+check,
+or which is developed in the future.
+.
+The table preprocessor
+.MR \%tbl 1
+can likely meet your needs.
+.
+.
+.P
+Several macros insert vertical space:
+.BR .SH ,
+.BR .SS ,
+.BR .TP ,
+.B .P
+(and its synonyms),
+.BR .IP ,
+and the deprecated
+.BR .HP .
+.
+The default inter-section and inter-paragraph spacing is
+is 1v for terminal devices
+and 0.4v for typesetting devices
+(\(lqv\(rq is a unit of vertical distance,
+where 1v is the distance between adjacent text baselines in a
+single-spaced document).
+.
+(The deprecated macro
+.B .PD
+can change this vertical spacing,
+but its use is discouraged.)
+.
+Between
+.B .EX
+and
+.B .EE
+calls,
+the inter-paragraph spacing is 1v regardless of output
+device.
+.
+.
+.\" ====================================================================
+.SS Registers
+.\" ====================================================================
+.
+Registers are described in section \(lqOptions\(rq below.
+.
+They can be set not only on the command line but in the site
+.I man.local
+file as well;
+see section \(lqFiles\(rq below.
+.
+.
+.br
+.ne 7v
+.\" ====================================================================
+.SS Strings
+.\" ====================================================================
+.
+The following strings are defined for use in man pages.
+.
+.
+Others are supported for configuration of rendering parameters;
+see section \(lqOptions\(rq below.
+.
+.
+.TP
+.B \e*R
+interpolates a special character escape sequence for the \(lqregistered
+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 \(lqtrade mark
+sign\(rq glyph,
+.BR \e(tm ,
+if available,
+and \(lq(TM)\(rq otherwise.
+.
+.
+.P
+None of the above is necessary in a contemporary man page.
+.
+.B \e*S
+is superfluous,
+since type size changes are invisible on terminal devices 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 a man page author is aiming for a pathological level of
+portability,
+such as the composition of pages for consumption on simulators of 1980s
+Unix systems
+(or Solaris
+.IR troff ,
+though even it supports
+.BR \(rs(rg ),
+the above strings should be avoided.
+.
+.
+.\" ====================================================================
+.SS Portability
+.\" ====================================================================
+.
+It is wise to quote 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.
+.
+A similar restriction applied to the
+.BR .B ,
+.BR .I ,
+.BR .SM ,
+and font style alternation macros.
+.
+.
+.P
+The two major syntactical categories for formatting control in the
+.I roff
+language are requests and escape sequences.
+.
+Since the
+.I man
+macros are implemented in terms of
+.I groff
+requests and escape sequences,
+one can,
+in principle,
+supplement the functionality of
+.I man
+with these lower-level elements where necessary.
+.
+.
+.br
+.ne 2v
+.P
+However,
+using raw
+.I groff
+requests
+(apart from the empty request
+.RB \(lq . \(rq)\&
+is likely to make your page render poorly when processed by other tools;
+many of these attempt to interpret page sources directly for conversion
+to HTML.
+.
+Some requests make implicit assumptions about things like character
+and page sizes that may not hold in an HTML environment;
+also,
+many of these viewers don't interpret the full
+.I groff
+vocabulary,
+a problem that can lead to portions of your text being omitted
+or presented incomprehensibly.
+.
+.
+.P
+For portability to modern viewers,
+it is best to write your page solely with the macros described in this
+page
+(except for the ones identified as deprecated,
+which should be avoided).
+.
+The macros we have described as extensions
+.RB ( .EX / .EE ,
+.BR .SY / .YS ,
+.BR .TQ ,
+.BR .UR / .UE ,
+.BR .MT / .ME ,
+.BR .MR ,
+and
+.BR .SB )
+should be used with caution,
+as they may not be built in to some viewer that is important to your
+audience.
+.
+See
+.I \%an\-ext.tmac
+in section \(lqFiles\(rq below.
+.
+.
+.P
+Similar caveats apply to escape sequences.
+.
+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+0000\(enU+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
+syntactically\(emnamely,
+any of the set
+.B \(aq \- \(rs \(ha \(ga \(ti
+(apostrophe,
+dash or minus,
+backslash,
+caret,
+grave accent,
+tilde).
+.
+.
+.br
+.ne 2v
+.TP
+.B \e\(dq
+Comment.
+.
+Everything after the double-quote to the end of the input line is
+ignored.
+.
+Whole-line comments should be placed 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.
+.
+Use this escape sequence to split excessively long input lines for
+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.
+.
+This escape sequence is an input word boundary,
+so the remainder of the word is subject to hyphenation as normal.
+.
+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
+This escape sequence is a
+.I groff
+extension also supported by Heirloom Doctools
+.I troff \" Heirloom
+050915 (September 2005),
+.I mandoc
+1.14.5 (2019-03-10),
+and
+.I neatroff
+(commit 399a4936,
+2014-02-17),
+but not by Plan\~9,
+Solaris,
+or Documenter's Workbench
+.IR troff s. \" Plan 9, Solaris, DWB
+.\" 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\(ti1.
+There are 1,024\e\(tibytes in 1\e\(tiKiB.
+CSTR\e\(ti#8 documents the B\e\(tilanguage.
+.EE
+.RE
+.
+.
+.\" BEGIN Keep in sync with groff.texi node "Other Differences" and
+.\" groff_diff(7).
+.IP
+This escape sequence is a
+.I groff
+extension also supported by Heirloom Doctools
+.I troff \" Heirloom
+050915 (September 2005),
+.I mandoc
+1.9.5 (2009-09-21),
+.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 Solaris
+or Documenter's Workbench
+.IR troff s. \" Solaris, DWB
+.\" 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.
+.
+Insert at the beginning of an input line to prevent a dot or apostrophe
+from being interpreted as beginning a
+.I roff
+control line.
+.
+Append 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 typesetting devices like
+.BR dvi ,
+.BR pdf ,
+and
+.BR ps .
+.
+.
+.TP
+.B \ec
+End a text line without inserting space or attempting a break.
+.
+.\" TODO: When we explain what a "sentence" is, move this parenthetical
+.\" there.
+Normally,
+if filling is enabled,
+the end of a text line is treated like a space;
+.\" end-of-sentence detection is performed, and...
+an output line
+.I may
+be broken there
+(if not,
+an adjustable space is inserted);
+if filling is disabled,
+the line
+.I will
+be broken there,
+as in
+.BR .EX / .EE
+examples.
+.
+The next line is interpreted as usual and can include a macro call
+(contrast with
+.BI \e newline\/\c
+).
+.
+.B \(rsc
+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
+.
+.
+.IP
+It also helps when changing font styles in
+.BR .EX / .EE
+examples,
+since they are not filled.
+.
+.
+.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
+Alternatively,
+and perhaps with better portability,
+the
+.B \ef
+font selection escape sequence can be used;
+see below.
+.
+Using
+.B \ec
+to continue a
+.B .TP
+paragraph tag across multiple input lines will render 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 current 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
+(\(lqreverse 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,
+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 Plan\~9 or Solaris
+.IR troff , \" 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 .
+.
+.
+.TP
+.B \e\-
+Minus sign or basic Latin hyphen-minus.
+.
+This escape sequence produces the Unix command-line option dash in the
+output.
+.
+.RB \(lq \- \(rq
+is a hyphen in the
+.I roff
+language;
+some output devices replace it with U+2010
+(hyphen)
+or similar.
+.
+.
+.TP
+.B \e(aq
+Basic Latin neutral apostrophe.
+.
+Some output devices format
+.RB \(lq\| \(aq \|\(rq
+as a right single quotation mark.
+.
+.
+.br
+.ne 3v
+.TP
+.B \e(oq
+.TQ
+.B \e(cq
+Opening (left) and closing (right) single quotation marks.
+.
+Use these for paired directional single quotes,
+\(oqlike this\(cq.
+.
+.
+.TP
+.B \e(dq
+Basic Latin quotation mark
+(double quote).
+.
+Use in macro calls to prevent
+.\" This page prefers double quotes, but not here because they are more
+.\" confusing to the eye when another double quote is what is quoted!
+.RB \(oq\| \(dq \|\(rq
+.\" AT&T: .RB  """
+from being interpreted as beginning a quoted argument,
+or simply for readability.
+.
+.
+.RS
+.IP
+.\" from src/preproc/eqn/eqn.1.man
+.EX
+\&.TP
+\&.BI \(dqsplit \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,
+\(lqlike this\(rq.
+.
+.
+.TP
+.B \e(em
+Em-dash.
+.
+Use for an interruption\(emsuch as this one\(emin a sentence.
+.
+.
+.TP
+.B \e(en
+En-dash.
+.
+Use to separate the ends of a range,
+particularly between numbers;
+for example,
+\(lqthe digits 1\(en9\(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
+(\(lqhat\(rq).
+.
+Some output devices format
+.RB \(lq \(ha \(rq
+as U+02C6
+(modifier letter circumflex accent)
+or similar.
+.
+.
+.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)
+or similar.
+.
+.
+.P
+For maximum portability,
+escape sequences and special characters not listed above are better
+avoided in man pages.
+.
+.
+.\" ====================================================================
+.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 \(lqFiles\(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 will likely consist of \[lq].sp\[rq] and
+\[lq].tl\[rq] requests.
+.
+They must also increase the page length with \[lq].pl\[rq] requests in
+continuous rendering mode;
+.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
+(\(lqbottom trap\(rq).
+.
+.
+.TP
+.B .PT
+Set the page header text
+(\(lqpage 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
+.I system
+can be any of the following.
+.
+.
+.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 \(lqSystem\~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 is desirable to restore them,
+you should probably be composing a table using
+.MR \%tbl 1
+instead.
+.
+.
+.TP
+.BR .HP " ["\c
+.IR indentation ]
+Set up a paragraph with a hanging left indentation.
+.
+The
+.I indentation
+argument,
+if present,
+is handled as with
+.BR .TP .
+.
+.
+.IP
+Use of this presentation-oriented macro is deprecated.
+.
+A hanging indentation cannot be expressed naturally under HTML,
+and
+.RI non- roff -based
+man page interpreters may treat
+.B .HP
+as an ordinary paragraph.
+.
+Thus,
+information or distinctions you mean to express with indentation may be
+lost.
+.
+.
+.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 originating in Documenter's Workbench
+.IR troff ,\" DWB
+is deprecated.
+.
+It cannot 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 it is preferable to use font style alternation macros,
+which afford greater flexibility.
+.
+.
+.TP
+.BR .PD " ["\c
+.IR vertical-space ]
+Define the vertical space between paragraphs or (sub)sections.
+.
+The optional argument
+.I vertical-space
+specifies the amount;
+the default scaling unit is \(lqv\(rq.
+.
+Without an argument,
+the spacing is reset to its default value;
+see subsection \(lqHorizontal 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 .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
+.I version
+can be any of the following.
+.
+.
+.RS \" Invisibly move left margin to current .IP indentation.
+.RS \" Now indent further, visibly.
+.TP
+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.
+.
+.
+.\" ====================================================================
+.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 the first volume of its
+.IR "Programmer's Manual" ,
+a compilation of all man pages supplied by the system.
+.
+That
+.I man
+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 .
+.
+The only strings defined were
+.B R
+and
+.BR S ;
+no registers were documented.
+.
+.
+.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 Research Unix (1986) introduced
+.B .EX
+and
+.BR .EE .
+.
+SunOS\~4.0 (1988) added
+.BR .SB .
+.
+.
+.P
+The foregoing features were what James Clark implemented in early
+versions of
+.IR groff .
+.
+.
+Later,
+.I groff
+1.20 (2009) originated
+.BR .SY / .YS ,
+.BR .TQ ,
+.BR .MT / .ME ,
+and
+.BR .UR / .UE .
+.\" ...along with implementations of OP, EX, and EE.
+.
+Plan\~9 from User Space's
+.I troff \" plan9port
+introduced
+.B .MR
+in 2020.
+.\" https://github.com/9fans/plan9port/commit/\
+.\"  977b25a76ae8263e53fb4eb1abfc395769f23e3d
+.\"  d32deab17bfffa5bffc5fab3e6577558e40888c5
+.\"  36cd4c58c1346375b98f517fb8568be5bb47618d
+.
+.
+.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
+.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
+.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 terminal devices;
+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
+.B \-rCS=1
+Set section headings
+(the argument(s) to
+.BR .SH )
+in full capitals.
+.
+This transformation is off by default because it discards case
+distinction information.
+.
+.
+.TP
+.B \-rCT=1
+Set the man page topic
+(the first argument to
+.BR .TH )
+in full capitals in headers and footers.
+.
+This transformation is off by default because it discards case
+distinction information.
+.
+.
+.TP
+.B \-rD1
+Enable double-sided layout,
+formatting footers for even and odd pages differently;
+see the description of
+.B .TH
+in subsection \(lqDocument 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 \-0.5i.
+.
+.
+.TP
+.BI \-dHF= heading-font
+Set 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 amount of indentation used for ordinary paragraphs
+.RB ( .P
+and its synonyms)
+and the default indentation amount used by
+.BR .IP ,
+.BR .RS ,
+.BR .TP ,
+.\" .TQ inherits its indentation from the preceding .TP.
+and the deprecated
+.BR .HP .
+.
+See subsection \(lqHorizontal and vertical spacing\(rq above for the
+default.
+.
+For
+terminal devices,
+.I standard-indentation
+should always be an integer multiple of unit \(lqn\(rq to get consistent
+indentation.
+.
+.
+.TP
+.BI \-rLL= line-length
+Set line length;
+the default is 78n for terminal devices
+and 6.5i for typesetting devices.
+.
+.
+.TP
+.BI \-rLT= title-length
+Set the line length for titles.
+.
+(\(lqTitles\(rq is the
+.I roff
+term for headers and footers.)
+.
+By default,
+it is set to the line length
+(see
+.B \-rLL
+above).
+.
+.
+.TP
+.BI \-dMF= man-page-topic-font
+Set the font used for man page topics named in
+.B .TH
+and
+.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],
+it is assumed to be an oblique typeface,
+and italic corrections are applied before and after man page topics.
+.
+.
+.TP
+.BI \-rP n
+Start enumeration of pages at
+.IR n .
+.
+The default is\~1.
+.
+.
+.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 \(lqFont style macros\(rq above for the default.
+.
+.
+.TP
+.BI \-rSN= subsection-indentation
+Set indentation of subsection headings to
+.I subsection-indentation.
+.
+See subsection \(lqHorizontal and vertical spacing\(rq above for the
+default.
+.
+.
+.br
+.ne 4v
+.TP
+.B \-rU1
+Enable generation of URI hyperlinks in the
+.I grohtml
+and
+.I grotty
+output drivers.
+.
+.I grohtml
+enables them by default;
+.I grotty
+does not,
+pending more widespread pager support for OSC\~8 escape sequences.
+.
+Use
+.B \-rU0
+to disable hyperlinks;
+this will make the arguments to
+.B MT
+and
+.B UR
+calls visible in the document text produced by link-capable drivers.
+.
+.
+.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 \(lqa\(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.
+.
+.
+.\" ====================================================================
+.SH Files
+.\" ====================================================================
+.
+.TP
+.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%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.23.0/\:\%tmac/\:\%andoc\:.tmac
+This brief
+.I groff
+program detects whether the
+.I man
+or
+.I mdoc
+macro package is being used by a document and loads the correct macro
+definitions,
+taking advantage of the fact that pages using them must call
+.B .TH
+or
+.BR .Dd ,
+respectively,
+before any other macros.
+.
+A
+.I man
+program or 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.
+.
+.
+.TP
+.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%an\-ext\:.tmac
+Except for
+.BR .SB ,
+definitions of macros described above as extensions
+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\(emnot 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.
+.
+.
+.IP
+The definitions for these macros are read after a page calls
+.BR .TH ,
+so they will replace any macros of the same names preceding it in your
+file.
+.
+If you use your own implementations of these macros,
+they must be defined after
+.B .TH
+is called to have any effect.
+.
+Furthermore,
+it is wise to define such page-local macros
+(if at all)
+after the \(lqName\(rq section to accommodate timid
+.I makewhatis
+or
+.I mandb
+implementations that may give up their scan for indexing material early.
+.
+.
+.TP
+.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:man\:.tmac
+This is a wrapper that loads
+.IR an.tmac .
+.
+.
+.TP
+.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%mandoc\:.tmac
+This is a wrapper that loads
+.IR \%andoc.tmac .
+.
+.
+.TP
+.I /usr/\:\%share/\:\%groff/\:\%site\-tmac/\:\%man\:\%.local
+Put site-local changes and customizations into this file.
+.
+.
+.RS
+.RS
+.P
+.EX
+\&.\e" Use narrower indentation on terminals and similar.
+\&.if n .nr IN 4n
+\&.\e" Put only one space after the end of a sentence.
+\&.ss 12 0 \e" See groff(7).
+\&.\e" Keep pages narrow even on wide terminals.
+\&.if n .if \(rsn[LL]>78n .nr LL 78n
+\&.\e" Ensure hyperlinks are enabled for terminals.
+\&.nr U 1
+.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.
+.
+.br
+.ne 3v
+.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 troubleshooting your man pages follow.
+.
+.
+.TP
+\(bu Some ASCII characters look funny or copy and paste wrong.
+.
+On devices with large glyph repertoires,
+like UTF-8-capable terminals and PDF,
+several keyboard glyphs are mapped to code points outside the Unicode
+basic Latin range 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
+c c
+rfCB lfCB.
+To get a \(lqliteral\(rq.\|.\|.	.\|.\|.should be input.
+_
+\(aq	\(rs(aq
+\-	\(rs\-
+\(rs	\(rs(rs
+\(ha	\(rs(ha
+\(ga	\(rs(ga
+\(ti	\(rs(ti
+_
+.TE
+.
+.
+.IP
+Additionally,
+if a neutral double quote (") is needed in a macro argument,
+you can use
+.B \(rs(dq
+to get it.
+.
+You should
+.I not
+use
+.B \(rs(aq
+for an ordinary apostrophe
+(as in \(lqcan't\(rq)
+or
+.B \(rs\-
+for an ordinary hyphen
+(as in \(lqword-aligned\(rq).
+.
+Review subsection \(lqPortability\(rq above.
+.
+.
+.TP
+\(bu Do I ever need to use an empty macro argument ("")?
+.
+Probably not.
+.
+When this seems necessary,
+often a shorter or clearer alternative is available.
+.
+.
+.IP
+.if t .ne 10v
+.if n .ne 16v \" account for horizontal rules
+.TS
+c c
+lfCB lfCB.
+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 \(dqfoo 1.2.3\(dq	.TH foo 1 \
+\f(CIyyyy\fP-\f(CImm\fP-\f(CIdd\fP \(dqfoo 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
+.
+.
+.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 will keep both up to date.
+.
+.
+.IP
+.B .IP
+is sometimes ill-understood and misused,
+especially when no marker argument is supplied\(eman 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 \(lqtwo\(rq and \(lqthree\(rq\(embut
+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.
+.
+.
+.TP
+.RB \(bu " .RS" " doesn't indent relative to my indented paragraph."
+.
+The
+.B .RS
+macro sets the left margin;
+that is,
+the position at which an
+.I ordinary
+paragraph
+.RB ( .P
+and its synonyms)
+will be set.
+.
+.BR .IP ,
+.BR .TP ,
+and the deprecated
+.B .HP
+use the same default indentation.
+.
+If not given an argument,
+.B .RS
+moves the left margin by this same amount.
+.
+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
+.B .P
+paragraph.
+.
+See subsection \(lqHorizontal and vertical spacing\(rq above for the
+values.
+.
+.
+.IP
+Another approach you can use with tagged paragraphs is to place an
+.B .RS
+call immediately after the paragraph tag;
+this will also force a break regardless of the width of the tag,
+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).
+.
+.
+.TP
+.RB \(bu " .RE" " doesn't move the inset back to the expected level."
+.TQ
+\(bu warning: scaling unit invalid in context
+.TQ
+\(bu warning: register \(aqan\-saved\-margin\c
+.IR n "\(aq not defined"
+.TQ
+\(bu warning: register \(aqan\-saved\-prevailing\-indent\c
+.IR n "\(aq not defined"
+.
+The
+.B .RS
+macro takes an
+.I indentation amount
+as an argument;
+the
+.B .RE
+macro's argument is a specific
+.I inset level.
+.
+.B .RE\~1
+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
+After calls to the
+.B .SH
+and
+.B .SS
+sectioning macros,
+all relative insets are cleared and calls to
+.B .RE
+have no effect until
+.B .RS
+is used again.
+.
+.
+.TP
+\(bu Do I need to keep typing the indentation in a series of \c
+.BR .IP " calls?"
+.
+Not if you don't want to change it.
+.
+Review subsection \(lqHorizontal and vertical spacing\(rq above.
+.
+.
+.IP
+.if t .ne 5v
+.if n .ne 7v \" account for horizontal rules
+.TS
+c c
+lfCB lfCB.
+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
+.
+.
+.TP
+\(bu Why doesn't the package provide a string to insert an ellipsis?
+.
+Examples of ellipsis usage are shown above,
+in subsection \[lq]Command 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
+C C
+LfCB LfCB.
+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
+There is an ellipsis code point in Unicode,
+and some fonts have an ellipsis glyph,
+which some man pages have accessed in a non-portable way with the
+font-dependent
+.B \[rs]N
+escape sequence.
+.
+We discourage the use of these;
+on terminals,
+they may crowd the dots into a half-width character cell,
+and will not render at all if the output device doesn't have the glyph.
+.
+In syntax synopses,
+missing ellipses can cause great confusion.
+.
+Dots and space are universally supported.
+.\" XXX: Does an unconditional _preceding_ dummy character cause
+.\" problems?
+.
+.
+.\" ====================================================================
+.SH Authors
+.\" ====================================================================
+.
+The initial GNU implementation of the
+.I man
+macro package was written by James Clark. \" 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.
+.
+.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. \" all 1.23
+.
+.
+Except for
+.BR .SB , \" Clark, as noted above
+the extension macros were written by
+Lemberg,
+.MT esr@\:thyrsus\:.com
+Eric S.\& Raymond
+.ME ,
+and
+Robinson. \" 1.23: MR
+.
+.
+.br
+.ne 3v
+.P
+This document was originally written for the Debian GNU/Linux system by
+.MT sgk@\:debian\:.org
+Susan G.\& Kleinmann
+.ME .
+.
+It was corrected and updated by Lemberg and Robinson.
+.
+The extension macros were documented by Raymond and Robinson.
+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 the BSD-originated alternative macro package for man pages.
+.
+.
+.P
+.MR groff_man 7 ,
+.MR groff 7 ,
+.MR groff_char 7 ,
+.MR man 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: