Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 2146 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man7/groff_man.7 b/upstream/opensuse-tumbleweed/man7/groff_man.7
new file mode 100644
index 00000000..2c31d289
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man7/groff_man.7
@@ -0,0 +1,2146 @@
+'\" t
+.\" This page is generated by m4 from tmac/groff_man.7.man.in.
+.TH groff_man 7 "4 October 2023" "groff 1.23.0"
+.SH Name
+groff_man \- compose manual pages with GNU
+.I roff
+.
+.
+.\" ====================================================================
+.\" 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
+Man page authors and maintainers who are not already experienced
+.I groff
+users should consult
+.MR groff_man_style 7 ,
+an expanded version of this document,
+for additional explanations and advice.
+.
+It covers only those concepts required for man page document
+maintenance,
+and not the full breadth of the
+.I groff
+typesetting system.
+.
+.
+.P
+.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.
+.
+.
+.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
+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.
+.
+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.
+.
+The subject of the man page is
+.I topic
+and the section of the manual to which it belongs is
+.I section.
+.
+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
+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.
+.
+.
+.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 groff_man_style 7
+for suggestions and
+.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
+.\" 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 )
+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.
+.
+.
+.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.
+.
+.
+.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.
+.
+.
+.\" ====================================================================
+.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
+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.
+.
+.
+.\" ====================================================================
+.SS "Hyperlink macros"
+.\" ====================================================================
+.
+Man page cross references
+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.
+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].
+.
+.
+.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.
+.
+.
+.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.
+.
+.
+.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.
+.
+.
+.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.
+.
+.
+.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.
+.
+.
+.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.
+.
+.
+.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.
+.
+.
+.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.
+.
+.
+.
+.TP
+.BI .BI " bold-text italic-text "\c
+\&.\|.\|.\&
+Set each argument in bold and italics,
+alternately.
+.
+.
+.TP
+.BI .BR " bold-text roman-text "\c
+\&.\|.\|.\&
+Set each argument in bold and roman,
+alternately.
+.
+.
+.TP
+.BI .IB " italic-text bold-text "\c
+\&.\|.\|.\&
+Set each argument in italics and bold,
+alternately.
+.
+.
+.TP
+.BI .IR " italic-text roman-text "\c
+\&.\|.\|.\&
+Set each argument in italics and roman,
+alternately.
+.
+.
+.TP
+.BI .RB " roman-text bold-text "\c
+\&.\|.\|.\&
+Set each argument in roman and bold,
+alternately.
+.
+.
+.TP
+.BI .RI " roman-text italic-text "\c
+\&.\|.\|.\&
+Set each argument in roman and italics,
+alternately.
+.
+.
+.\" ====================================================================
+.SS "Horizontal and vertical spacing"
+.\" ====================================================================
+.
+The
+.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.
+.
+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
+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.
+.
+(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.
+.
+None of these is necessary in a contemporary man page;
+see
+.MR groff_man_style 7 .
+.
+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.
+.
+.
+.\" ====================================================================
+.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).
+.
+.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.
+.
+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 ).
+.
+.
+.
+.\" ====================================================================
+.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.
+.
+.
+.\" ====================================================================
+.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.
+.
+.
+.\" ====================================================================
+.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_style 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: