Provided by: groff_1.22.4-3_amd64 bug

NAME

       groff_man - GNU roff macro package for formatting man pages

SYNOPSIS

       groff -man [option ...] [input-file ...]
       groff -m man [option ...] [input-file ...]

DESCRIPTION

       The man macro package for groff is used to produce manual pages (“man pages”) like the one
       you are reading.  GNU roff's implementation was written by James Clark.

       This document presents the macros thematically to aid learners; for those needing  only  a
       quick  reference,  the following table lists them alphabetically, with cross-references to
       appropriate subsections below.

       Macro   Meaning                         Subsection
       ───────────────────────────────────────────────────────────────────
       .B      Bold                            Font style macros
       .BI     Bold, italic alternating        Font style macros
       .BR     Bold, roman alternating         Font style macros
       .EE     Example end                     Document structure macros
       .EX     Example begin                   Document structure macros
       .I      Italic                          Font style macros
       .IB     Italic, bold alternating        Font style macros
       .IP     Indented paragraph              Paragraph macros
       .IR     Italic, roman alternating       Font style macros
       .LP     (Left) paragraph                Paragraph macros
       .ME     Mail-to end                     Hyperlink and email macros
       .MT     Mail-to start                   Hyperlink and email macros
       .OP     (Command-line) option           Command synopsis macros
       .P      Paragraph                       Paragraph macros
       .PP     Paragraph                       Paragraph macros
       .RB     Roman, bold alternating         Font style macros
       .RE     Relative-indent end             Document structure macros
       .RI     Roman, italic alternating       Font style macros
       .RS     Relative-indent start           Document structure macros
       .SB     Small bold                      Font style macros
       .SH     Section heading                 Document structure macros
       .SM     Small                           Font style macros
       .SS     Subection heading               Document structure macros
       .SY     Synopsis start                  Command synopsis macros
       .TH     Title heading                   Document structure macros
       .TP     Tagged paragraph                Paragraph macros
       .TQ     Tagged paragraph continuation   Paragraph macros
       .UE     URL end                         Hyperlink and email macros
       .UR     URL start                       Hyperlink and email macros
       .YS     Synopsis end                    Command synopsis macros

       Macros whose use we discourage (.AT, .BT, .DT, .HP, .PD, .PT, and .UC)  are  described  in
       subsection “Deprecated features”, below.

   Macro reference preliminaries
       Each  macro  is  described in a tagged paragraph.  Closely related macros, such as .EX and
       .EE, are grouped together.

       Optional macro arguments are indicated by surrounding them with  square  brackets.   If  a
       macro  accepts  multiple  arguments, arguments containing whitespace must be double-quoted
       ("one two"), to be interpreted correctly.  Most macro arguments are strings that  will  be
       output as text; exceptions are noted.

       Bear   in  mind  that  groff  is  fundamentally  a  programming  system  for  typesetting.
       Consequently, the verb “to set” is frequently used below in the sense “to typeset”.

   Document structure macros
       The highest level of organization of a man page is determined by  this  group  of  macros.
       .TH (title heading) identifies the document as a man page and defines information enabling
       its indexing by mandb(8) or a similar tool.  Sections (.SH), one of which is mandatory and
       many  of  which  are  standardized,  facilitate quick location of relevant material by the
       reader and aid the man page  writer  to  discuss  all  essential  aspects  of  the  topic.
       Subsections  (.SS)  are  optional  and  permit  sections  that  grow  long to develop in a
       controlled way.  Many technical discussions require  examples;  lengthy  ones,  especially
       those  reflecting  multiple  lines  of  input  to  or output from the system, are usefully
       bracketed by .EX and .EE.  When none of the foregoing meets a structural demand, a section
       of the discussion can be manually indented within .RS and .RE macros.

       .TH title section
                [footer-middle] [footer-outside] [header-middle] Define the title of the man page
              as title and the section as section.  See man(1) for details on the section numbers
              and  suffixes applicable to your system.  title and section are positioned together
              at the left and right in the header line (with section in  parentheses  immediately
              appended  to title).  footer-middle is centered in the footer line.  footer-outside
              is positioned at the left in the footer line (or at the left on even pages  and  at
              the  right  on  odd  pages  if  double-sided printing is active).  header-middle is
              centered in the header line.  If section is  a  simple  integer  between  1  and  9
              (inclusive),  or  is  exactly  “3p”, there is no need to specify header-middle; the
              macro package will supply text for it.

              For HTML output, headers and footers are completely suppressed.

              Additionally, this macro starts a new page; the page number is reset to  1  (unless
              the  -rC1  option is given on the command line).  This feature is intended only for
              formatting multiple man pages.

              A man page should contain exactly one .TH call at or  near  the  beginning  of  the
              file, prior to any other macro calls.

              By  convention,  footer-middle is the most recent modification date of the man page
              source document, and footer-outside is the name  and  version  or  release  of  the
              project providing it.

       .SH [  heading-text] Set heading-text as a section heading flush left.  The text following
              .SH up to the end of the line, or the text on the next input line if .SH  is  given
              no  arguments,  is  set  in  bold (or the font specified by the string register HF)
              slightly larger than the  base  font  size.   Additionally,  the  left  margin  and
              indentation  affecting  subsequent text are reset to their default values.  Text on
              input lines after heading-text is set as a normal paragraph (.PP).

              The content of heading-text and ordering  of  sections  has  been  standardized  by
              common  practice,  as  has  much  of  the  layout of material within sections.  For
              example, a section called “Name” or “NAME” must exist, must be  the  first  section
              after the .TH call, and must contain only a line of the form
                     page-topic[, ...] \- summary-description
              for  a  man page to be properly indexed.  See man(7) for the conventions prevailing
              on your system.

       .SS [  subheading-text] Set subheading-text as a subsection heading indented (by  default)
              partway  between  a  section  heading and a normally-indented paragraph (.PP).  The
              text following .SS up to the end of the line, or the text on the next input line if
              .SS  is  given  no  arguments,  is set in bold (or the font specified by the string
              register HF) at the base font size.  Additionally, the left margin and  indentation
              affecting  subsequent  text are reset to their default values.  Text on input lines
              after subheading-text is set as a normal paragraph (.PP).

       .EX
       .EE    Begin and end example.  After .EX, filling  and  hyphenation  are  disabled  and  a
              constant-width  (monospaced)  font  is  selected.   Calling .EE enables filling and
              restores the previous hyphenation setting and font.

              Example regions are useful for formatting  code,  shell  sessions,  and  text  file
              contents.

              These  macros are defined on many (but not all) legacy Unix systems running classic
              troff.  To be certain your page will be  portable  to  those  systems,  copy  their
              definitions from the an-ext.tmac file of a groff installation.

       .RS [  indent] Move the left margin to the right by the value indent, if specified, and by
              a default amount otherwise; see subsection “Horizontal and vertical spacing” below.
              Calls to .RS can be nested; each call increments by 1 the indentation level used by
              .RE.  The indentation level prior to any .RS calls is 1.

       .RE [  level] Move the left margin back to that corresponding to indentation level  level.
              If no argument is given, move the left margin one level back.

   Paragraph macros
       A  typical paragraph (.PP) is set at the current left margin, which by default is indented
       from the left margin of the output device.  In man pages and other  technical  literature,
       definition  lists are frequently encountered; these can be set as “tagged paragraphs” (.TP
       and .TQ), which have one or more  leading  tags  followed  by  a  paragraph  that  has  an
       additional  left  indent.   The  indented  paragraph (.IP) macro is useful to continue the
       indented content of a narrative started with .TP, or to present  an  itemized  or  ordered
       list.

       .LP
       .PP
       .P     Begin  a new paragraph; these macros are synonymous.  They break the output line at
              the current position, followed by a vertical space downward  by  a  default  amount
              (which  can  be  changed by the deprecated .PD macro).  The font size and style are
              reset to defaults; see subsection “Font style macros”  below.   Finally,  the  left
              margin and indentation are reset to default values.

       .TP [  indent]  Set  a  tagged,  indented paragraph.  The input line following this macro,
              known as the tag, is printed at  the  current  left  margin.   Subsequent  text  is
              indented by indent, if specified, and by a default amount otherwise; see subsection
              “Horizontal and vertical spacing” below.

              If the tag is not as wide as the indentation, the paragraph starts on the same line
              as  the  tag,  at the applicable indentation, and continues on the following lines.
              Otherwise, the descriptive part of the paragraph begins on the line  following  the
              tag,  entirely indented.  The line containing the tag can include a macro call, for
              instance to set the tag in bold with .B.

              .TP was used to write the first paragraph of this description of .TP, and  .IP  the
              subsequent ones.

       .TQ    Set  an additional tag for a paragraph tagged with .TP.  The pending output line is
              broken.  The tag on the input line following this macro and  subsequent  lines  are
              handled as with .TP.

              This  macro  is  not  defined  on legacy Unix systems running classic troff.  To be
              certain your page will be portable to those systems, copy its definition  from  the
              an-ext.tmac file of a groff installation.

              The descriptions of .LP, .PP, and .P above were written using .TP and .TQ.

       .IP [  tag]  [indent]  Set an indented paragraph with an optional tag.  The tag and indent
              arguments, if present, are handled as with .TP, with the  exception  that  the  tag
              argument to .IP cannot include a macro call.

              Two convenient use cases for .IP are

                     (1) to  start  a new paragraph with the same indentation as the previous .IP
                         or .TP paragraph, if no indent argument is given; and

                     (2) to set a paragraph with a short tag that is not semantically  important,
                         such  as  a bullet (·)—obtained with the ‘\(bu’ character escape—or list
                         enumerator, as seen in this very paragraph.

   Command synopsis macros
       Command synopses are a staple of section 1 and 8 man  pages.   These  macros  aid  you  to
       construct one that has the classical Unix appearance.  Furthermore, some tools are able to
       interpret these macros semantically and treat them appropriately for  localization  and/or
       presentation.   A  command synopsis is wrapped in .SY/.YS calls, with command-line options
       of some formats indicated by .OP.

       These macros are not defined on legacy Unix systems running classic troff.  To be  certain
       your  page  will be portable to those systems, copy their definitions from the an-ext.tmac
       file of a groff installation.

       .SY command
              Begin synopsis.  Hyphenation is turned off.  The command argument is set  in  bold.
              The  output line is filled as normal, but if a break is required, subsequent output
              lines are indented by the width of command plus a space.

       .OP option-name
               [option-argument] Indicate an optional command parameter called option-name, which
              is  set  in bold.  If the option takes an argument, specify option-argument using a
              noun, abbreviation, or hyphenated noun  phrase.   If  present,  option-argument  is
              preceded  by  a space and set in italics.  Square brackets (in roman) surround both
              arguments.

       .YS    End synopsis.  Restore indentation and hyphenation to previous values.

       Multiple .SY/.YS blocks can be specified, for instance to distinguish differing  modes  of
       operation of a complex command like tar(1); each will be separated by a paragraph space.

       .SY  can also be repeated multiple times before a closing .YS, which is useful to indicate
       synonymous ways of invoking a particular mode of operation.

       For example,

              .SY groff
              .OP \-abcegiklpstzCEGNRSUVXZ
              .OP \-d cs
              .OP \-f fam
              .OP \-F dir
              .OP \-I dir
              .OP \-K arg
              .OP \-L arg
              .OP \-m name
              .OP \-M dir
              .OP \-n num
              .OP \-o list
              .OP \-P arg
              .OP \-r cn
              .OP \-T dev
              .OP \-w name
              .OP \-W name
              .RI [ file
              \&.\|.\|.\&]
              .YS
              .
              .SY groff
              .B \-h
              .SY groff
              .B \-\-help
              .YS

       produces the following output.

              groff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir] [-I dir] [-K arg]
                    [-L arg] [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn] [-T dev]
                    [-w name] [-W name] [file ...]

              groff -h
              groff --help

       Several features of the above example are of note.

       ·      The empty request (.), which does nothing, is used  for  vertical  spacing  in  the
              input file for readability by the document maintainer.  Do not put empty lines in a
              roff source document.

       ·      The command and option names are presented in bold to cue the user that they should
              be input literally.

       ·      Option  dashes  are  specified  with the ‘\-’ escape sequence; this is an important
              practice to make them clearly visible and  to  facilitate  cut-and-paste  from  the
              rendered man page to a shell prompt or text file.

       ·      Option  arguments and command operands are presented in italics (underlined on some
              output devices, such as terminals and emulators), to cue the user that they must be
              replaced with appropriate text.

       ·      Symbols  that  are  neither to be typed literally nor simply replaced appear in the
              roman style; brackets surround optional arguments, and an ellipsis  indicates  that
              the previous syntactical element may be repeated arbitrarily.

              Some  man  pages  use  a  brace-and-pipe  notation  such as “{--diff|--compare}” to
              indicate that one and only one of the ‘|’-separated items within the braces must be
              input.   If  this braced construct is furthermore surrounded by square brackets, it
              means that at most one of the items is accepted.

              Authors of man pages should note the use of the zero-width  space  escape  sequence
              ‘\&’  on  both sides of the ellipsis; this is a good practice to avoid surprises in
              the event the ellipsis gets refilled  in  your  text  editor.   See  “Portability”,
              below.  The morbidly curious may consult groff(7) regarding the narrow-space escape
              sequence ‘\|’.

   Hyperlink and email macros
       Email addresses are bracketed with .MT/.ME and URL hyperlinks with .UR/.UE.

       These macros are not defined on legacy Unix systems running classic troff.  To be  certain
       your  page  will be portable to those systems, copy their definitions from the an-ext.tmac
       file of a groff installation.

       .MT address
       .ME [  punctuation] Identify address as an RFC 6068 addr-spec for a “mailto:” URI with the
              text  between  the two macro calls as the link text.  A punctuation argument to .ME
              is placed at the end of the link text without intervening space.  Note that address
              may not be visible in the output text, particularly if the man page is being viewed
              as HTML.  On a device that is not a browser, address is set in angle brackets after
              the link text and before punctuation.

              When rendered by groff to a TTY or PostScript output device,

                     Contact
                     .MT fred.foonly@\:fubar.net
                     Fred Foonly
                     .ME
                     for more information.

              displays as: “Contact Fred Foonly ⟨fred.foonly@fubar.net⟩ for more information.”.

              The  use of ‘\:’ to insert hyphenless discretionary breaks is a groff extension and
              can be omitted.

       .UR URL
       .UE [  punctuation] Identify URL as an RFC 3986 URI hyperlink with the  text  between  the
              two  macro  calls as the link text.  A punctuation argument to .UE is placed at the
              end of the link text without intervening space.  Note that URL may not  be  visible
              in  the  output  text,  particularly if the man page is being viewed as HTML.  On a
              device that is not a browser, URL is set in angle brackets after the link text  and
              before punctuation.

              When rendered by groff to a TTY or PostScript output device,

                     The GNU Project of the Free Software Foundation hosts the
                     .UR https://\:www.gnu.org/\:software/\:groff/
                     Groff home page
                     .UE .

              displays  as: “The GNU Project of the Free Software Foundation hosts the Groff home
              page ⟨https://www.gnu.org/software/groff/⟩.”.

              The use of ‘\:’ to insert hyphenless discretionary breaks is a groff extension  and
              can be omitted.

   Font style macros
       The  man  macro  package  is limited in its font styling options, offering only bold (.B),
       italic (.I), and roman (the default).  Italic text is usually set underscored  instead  on
       terminals and other classical nroff-style output devices.  The .SM and .SB macros set text
       in roman or bold, respectively, at a  smaller  point  size;  these  differ  visually  from
       regular-sized roman or bold text only on troff-style output devices.  The foregoing macros
       cause word breaks before and after their arguments, but it is often necessary to set  text
       in  different  styles without intervening whitespace.  The macros .BI, .BR, .IB, .IR, .RB,
       and .RI, where ‘B’, ‘I’, and ‘R’ indicate bold, italic, and roman, respectively, set their
       odd-  and  even-numbered  arguments  in  alternating styles, with no whitespace separating
       them.

       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, in-line literals, and even man page cross-references.

       The default font size and family (for  troff  output  devices)  is  10-point  Times.   The
       default style is roman.

       .B [   text]  Set  text in bold.  If the macro is given no arguments, the text of the next
              input line is set in bold.

              Use bold for literal portions of  syntax  synopses,  for  command-line  options  in
              running  text,  and  for  literals  that  are  major  topics  of  the subject under
              discussion; for example, this page uses bold for  macro  and  register  names.   In
              .EX/.EE  examples  of interactive I/O (such as a shell session), set only the user-
              typed input in bold.

       .I [   text] Set text in italics.  If the macro is given no arguments,  the  text  of  the
              next input line is set in italics.

              Use  italics for file and path names, for environment variables, for enumeration or
              preprocessor constants in C, for  variable  (user-determined)  portions  of  syntax
              synopses,  for  the  first occurrence only of a technical concept being introduced,
              for names of works of software (including commands  and  functions,  but  excluding
              names  of  operating  systems or their kernels), and anywhere a parameter requiring
              replacement by the user is encountered.  An exception involves variable text  in  a
              context  that  is  already  marked  up  in italics, such as file or path names with
              variable  components;  in  such  cases,  follow  the  convention  of   mathematical
              typography:  set the file or path name in italics as usual (see .IR below), but use
              roman for the variable part, and italics again in running roman text when referring
              to the variable material.

       .SM [  text] Set text one point size smaller than the default size.  If the macro is given
              no arguments, the text of the next input line is set smaller.

              Note: nroff-style output devices, such as terminals, will render text at the normal
              font  size  instead.   Do  not  rely  upon  .SM to communicate semantic information
              distinct from using roman style at the normal size; it will be hidden from  readers
              using such devices.

       .SB [  text] Set text in bold, one point size smaller than the default size.  If the macro
              is given no arguments, the text of the next input line is set smaller and in bold.

              Note: nroff-style output devices, such as terminals, will render text  in  bold  at
              the  normal  font  size  instead.   Do  not  rely  upon .SB to communicate semantic
              information distinct from using bold style at the normal size; it  will  be  hidden
              from readers using such devices.

       Note  what  is  not prescribed for setting in bold or italics above: elements of “synopsis
       language” such as ellipses and brackets  around  options;  proper  names  and  adjectives;
       titles  of  anything other than works of literature or software; identifiers for standards
       documents or technical reports such as CSTR #54, RFC 1918, Unicode 11.0, or  POSIX.1-2017;
       acronyms;  and occurrences after the first of a technical term or piece of jargon.  Again,
       the names of operating systems and their kernels are, by practically universal convention,
       set in roman.

       Be  frugal  with  the  use of italics for emphasis, and particularly with the use of bold.
       Brief runs of literal text, such as references to individual characters or short  strings,
       including  section  and  subsection  headings  of  man  pages,  are  suitable  objects for
       quotation; see the ‘\(lq’, ‘\(rq’, ‘\(oq’, and ‘\(cq’ escapes in subsection  “Portability”
       below.

       Unlike  the  above  font  style  macros,  the  font  alternation  macros below accept only
       arguments on the same line as the macro call.  If whitespace is required within one of the
       arguments,  first  consider whether the same result could be achieved with as much clarity
       by using the single-style macros on separate input lines.  When it cannot, double-quote an
       argument  with  one or more embedded space characters.  Setting all three different styles
       within one whitespace-delimited word presents challenges; it is  possible  with  the  ‘\c’
       and/or ‘\f’ escapes, but see subsection “Portability” below for caveats.

       .BI bold-text italic-text
               ... Set each argument in bold and italics, alternately.

                     .BI \-r name = n

       .BR bold-text roman-text
               ... Set each argument in bold and roman, alternately.

                     Any such change becomes effective with the first use of
                     .BR .NH ,
                     .I after
                     the new alias is defined.

       .IB italic-text bold-text
               ... Set each argument in italics and bold, alternately.

                     All macro package files must be named
                     .IB name .tmac
                     to fully use the
                     .I tmac
                     mechanism.

       .IR italic-text roman-text
               ... Set each argument in italics and roman, alternately.

                     This is the first command of the
                     .IR prologue .

       .RB roman-text bold-text
               ... Set each argument in roman and bold, alternately.

                     Also, the statement
                     .RB \(oq "delim on" \(cq
                     is not handled specially.

       .RI roman-text italic-text
               ... Set each argument in roman and italics, alternately.

                     .RI [ file
                     \&.\|.\|.\&]

   Horizontal and vertical spacing
       The  indent argument accepted by .RS, .IP, .TP, and the deprecated .HP is a number plus an
       optional scaling indicator.  If no scaling indicator is given,  the  man  package  assumes
       ‘n’; that is, the width of a letter “n” in the font current when the macro is called.  See
       section “Numerical Expressions” in groff(7) for further details.  An indent specified in a
       call  to  .IP,  .TP,  or  the deprecated .HP persists until (1) another of these macros is
       called with an explicit indent argument, or (2) .SH,  .SS,  or  .PP  or  its  synonyms  is
       called; these clear the indent entirely.

       Indents set by .RS move the left margin and persist until .RS, .RE, .SH, or .SS is called.
       The default indentation, exhibited by  ordinary  .PP  paragraphs  not  within  an  .RS/.RE
       relative indent, is 7.2n in troff mode and 7n in nroff mode.  The HTML output device is an
       exception; it ignores  indentation  completely.   This  same  indentation  is  used  again
       (additively)  for the defaults of .IP, .TP, .RS, and the deprecated .HP.  Section headings
       (.SH) are set flush with the left margin of the output  device,  and  subsection  headings
       (.SS) are indented 3n.

       Resist  the temptation to mock up tabular or multi-column output with ASCII tab characters
       or the indentation arguments to .IP, .TP, .RS, or the deprecated .HP; the result  may  not
       render  comprehensibly on an output device you fail to check, or which is developed in the
       future.  The table preprocessor tbl(1) can likely meet your needs.

       The following macros cause a line break with the insertion of vertical  space:  .SH,  .SS,
       .TP,  .TQ, .PP (and its synonyms), .IP, and the deprecated .HP.  The default inter-section
       and inter-paragraph spacing is 1 line in  nroff  mode,  and  0.4v  in  troff  mode.   (The
       deprecated  macro  .PD can change this vertical spacing, but its use is discouraged.)  The
       macros .RS, .RE, .EX, and .EE also cause a break but no insertion of vertical space.

   Number registers
       Number registers are described in section “Options” below.

   String registers
       The following strings are defined.

       \*R    expands to the character  escape  for  the  “registered  sign”  glyph,  ‘\(rg’,  if
              available, and “(Reg.)” otherwise.

       \*S    expands to an escape setting the font size to the document default.

       \*(HF  expands to the font identifier used to print headings and subheadings.  The default
              is ‘B’.

       \*(lq
       \*(rq  expand to the character escapes for left and right double-quotation  marks,  ‘\(lq’
              and ‘\(rq’, respectively.

       \*(Tm  expands  to  the  character  escape  for  the  “trade  mark sign” glyph, ‘\(tm’, if
              available, and “(TM)” otherwise.

   Interaction with preprocessors
       When a preprocessor like tbl or eqn is needed, a  hint  can  be  given  to  the  man  page
       formatter by making the first line of a man page look like this:

              '\" word

       Note  that  the  line  starts  with  an apostrophe ('), not a dot, and that a single space
       character follows the double quote.  The word consists  of  one  letter  for  each  needed
       preprocessor:  ‘e’ for eqn, ‘r’ for refer, and ‘t’ for tbl.  Modern implementations of the
       man program interpret this first line and automatically call the right preprocessor(s).

       The usual tbl and eqn macros for table and equation inclusion, .TS,  .T&,  .TE,  .EQ,  and
       .EN,  may  be  used  freely.   Note  that  nroff  output  devices are extremely limited in
       presentation of mathematical equations.

   Portability
       The two major syntactical categories of roff languages are requests  and  escapes.   Since
       the  man  macros  are  implemented  in  terms  of  groff requests and escapes, one can, in
       principle, supplement the functionality of  man  with  these  lower-level  elements  where
       necessary.

       Note,  however, that using raw groff requests is likely to make your page render poorly on
       the class of viewers that transform it to HTML.  Some requests make  implicit  assumptions
       about things like character and page sizes that may not hold in an HTML environment; also,
       many of these viewers don't interpret the full groff vocabulary, a problem that  can  lead
       to portions of your text being silently dropped.

       For  portability to modern viewers, it is best to write your page entirely with the macros
       described in this page (except for the ones identified  as  deprecated,  which  should  be
       avoided).   The macros we have described as extensions (.EX/.EE, .SY/.OP/.YS, .UR/.UE, and
       .MT/.ME) should be used with caution, as they may not yet be built in to some viewer  that
       is  important to your audience.  If in doubt, copy the implementation into your page—after
       the .TH call and the “Name” section, to accommodate timid mandb implementations.

       Similar caveats apply to escapes.  Some escape sequences are however required for  correct
       typesetting even in man pages and usually do not cause portability problems:

       \"     Comment.   Everything  after  the  double-quote  to  the  end  of the input line is
              ignored.  Whole-line comments are frequently placed  immediately  after  the  empty
              request ‘.’.

       \newline
              Join  the  next  input line to the current one.  Except for the update of the input
              line counter (used for diagnostic messages and related purposes), a series of lines
              ending  in  backslash-newline  is  transparent  to groff.  Use this escape to break
              excessively input long lines for document maintenance.

       \~     Adjustable, non-breaking space character.  Use  this  escape  to  prevent  a  break
              inside  a  short  phrase  or  between  a  numerical  quantity and its corresponding
              unit(s).

                     Before starting the motor, set the output speed to\~1.
                     There are 1,024\~bytes in 1\~kiB.
                     CSTR\~#8 documents the B language.

       \&     Zero-width  space.   Append  to  an  input  line  to  prevent  an   end-of-sentence
              punctuation  sequence  from being recognized as such, or insert at the beginning of
              an input line to prevent  a  dot  or  apostrophe  from  being  interpreted  as  the
              beginning of a roff request.

       \(aq   ASCII  apostrophe.   Use  for syntax elements of programming languages because some
              output devices might replace unescaped  apostrophes  with  right  single  quotation
              marks.

       \(oq   Opening single quotation mark.
       \(cq   Closing single quotation mark.

              Use these for paired directional single quotes, ‘like this’.

       \(dq   ASCII   double-quote.    Sometimes   needed   after  macro  calls  to  prevent  the
              interpretation of the ASCII quotation mark character ‘"’ as the beginning or end of
              a macro argument.

       \(lq   Left double quotation mark.
       \(rq   Right double quotation mark.

              Use these for paired directional double quotes, “like this”.

       \(em   Em-dash.  Use for an interruption in a sentence—such as this one.

       \(en   En-dash.   Use  to separate the two ends of a range, in particular between numbers,
              for example: the digits 1–9.

       \(ga   ASCII grave accent.  Use for syntax elements of programming languages, for  example
              shell  command  substitutions,  because some output devices might replace unescaped
              grave accents with left single quotation marks.

       \(ha   ASCII circumflex accent.  Use for syntax elements of programming languages  because
              some  output  devices  might  replace  unescaped  circumflex accents with non-ASCII
              glyphs like the Unicode U+02C6 modifier letter circumflex.

       \(ti   ASCII tilde.  Use for syntax elements of programming languages because some  output
              devices  might  replace  unescaped  tildes  with  non-ASCII glyphs like the Unicode
              U+02DC small tilde.

       \-     Minus sign.  Also use this to  display  syntax  elements  that  require  the  ASCII
              hyphen-minus  character, for example command-line options and C language operators.
              The unescaped ‘-’ input character is not appropriate for these cases because it may
              render as a hyphen on some output devices.

       \c     If  this  escape  sequence  occurs  at  the end of an input line, no white space is
              inserted between the last glyph on it and the first glyph resulting from  the  next
              input line.  This is occasionally useful when three different fonts are needed in a
              single word.

                     Normally, the final output file should be named
                     .IB file .pdf\c
                     \&.

              Note that when using this trick with the .BI  or  .RI  macros,  you  will  need  to
              manually  add  an  italic  correction escape ‘\/’ before the ‘\c’ due to way macros
              expand their arguments.

                     Files processed with
                     .B groff \-mom
                     (or
                     .BI "\-m " mom\/\c
                     ) produce PostScript output by default.

              Alternatively, and perhaps with better portability, the ‘\f’ font  escape  sequence
              can  be used; see below.  Using ‘\c’ to include the output from more than one input
              line into the next-line argument of a .TP macro will render incorrectly with  groff
              1.22.3,  mandoc  1.14.1,  older  versions  of these programs, and perhaps with some
              other formatters.

       \e     Widely used in man pages to represent a backslash output glyph.  It works  reliably
              as long as the .ec request is not used, which should never happen in man pages, and
              it is slightly more portable than the more exact ‘\(rs’ (“reverse solidus”)  escape
              sequence.

       \fB, \fI, \fR, \fP
              Switch  to bold, italic, roman, or back to the previous font, respectively.  Either
              these or ‘\c’ is needed when  three  different  fonts  are  required  in  a  single
              whitespace-delimited word.

                     .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ]

                     .RB [ \-\-reference\-dictionary=\c
                     .IR name ]

              Font  escapes  may  be more portable than ‘\c’.  As shown above, it is up to you to
              account for italic corrections with ‘\/’  and  ‘\,’,  which  are  themselves  groff
              extensions, if desired and if supported by your implementation.

              Note  that  ‘\fP’  reliably  returns  to the style in use immediately preceding the
              previous ‘\f’ escape only if no sectioning, paragraph, or  font  face  macro  calls
              have intervened.

              As  long as only two fonts are needed in any single whitespace-delimited word, font
              alternation macros like .BI usually result in more readable source code  than  ‘\f’
              escapes do.

       For  maximum  portability,  escape  sequences  and special characters not listed above are
       better avoided in man pages.

   Deprecated features
       Use of the following is discouraged.

       .AT [  system [release]] Alter the footer for use with  AT&T  man  pages,  overriding  any
              definition  of  the  footer-outside  argument  to  .TH.  This macro exists only for
              compatibility; don't use it.

              The first argument system can be:

                     3      7th edition (default)

                     4      System III

                     5      System V

              The optional second argument release specifies  the  release  number,  such  as  in
              “System V Release 3”.

       .BT    Set the page footer.  Redefine this macro to get control of the footer.

       .DT    Set  tabs  every 0.5 inches.  Since this macro is always called during a .TH macro,
              it makes sense to call it only if the tab positions have been changed.

              Use of this presentation-level macro is deprecated.  It translates poorly to  HTML,
              under  which exact whitespace control and tabbing are not readily available.  Thus,
              information or distinctions that you use .DT to express are likely to be lost.   If
              you  feel  tempted to use it, you should probably be composing a table using tbl(1)
              markup instead.

       .HP [  indent] Set up a paragraph with a hanging left indentation.  The  indent  argument,
              if present, is handled as with .TP.

              Use  of  this  presentation-level  macro  is  deprecated.   While it is universally
              portable to  legacy  Unix  systems,  a  hanging  indentation  cannot  be  expressed
              naturally  under  HTML, and many HTML-based manual viewers simply interpret it as a
              starter for a normal paragraph.  Thus, any information or distinction you tried  to
              express with the indentation may be lost.

       .PD [  vertical-space] Define the vertical space between paragraphs or (sub)sections.  The
              optional argument vertical-space specifies the amount of space; the default scaling
              is  ‘v’).   Without  an  argument,  the  spacing is reset to its default value; see
              “Horizontal and vertical spacing” above.

              Use of this presentation-level 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 .PD to  express  are  likely  to  be
              lost.

       .PT    Set the page header.  Redefine this macro to get control of the header.

       .UC [  version]  Alter the footer for use with BSD man pages, overriding any definition of
              the footer-outside argument to .TH.  This  macro  exists  only  for  compatibility;
              don't use it.

              The argument version can be:

                     3      3rd Berkeley Distribution (default)

                     4      4th Berkeley Distribution

                     5      4.2 Berkeley Distribution

                     6      4.3 Berkeley Distribution

                     7      4.4 Berkeley Distribution

   History
       According  to  its  own  man(7)  page,  Version  7 Unix (1979) supported all of the macros
       described in this page not listed  as  GNU  extensions,  except  .P,  .SB,  .SS,  and  the
       deprecated  .AT,  .BT,  .PT,  and .UC.  The only string registers defined were R and S; no
       number registers were documented.

OPTIONS

       The following groff options set number registers recognized and  used  by  the  man  macro
       package.

       -rcR=1 Continuous  rendering.   Create a single, very long page instead of multiple pages.
              This is the default in nroff mode.  Use -rcR=0 to disable it.

       -rC1   Number pages continuously.  If more than one man page is given on the command line,
              number the pages continuously, rather than starting each at 1.

       -rD1   Enable  double-sided  printing.   Footers  for  even  and  odd  pages are formatted
              differently; see the description of .TH in “Document structure macros”, above.

       -rFT=footer-distance
              Set distance of the footer, relative to the bottom  of  the  page  if  negative  or
              relative to the top if positive, to footer-distance.  The default is -0.5i.

       -rHY=flags
              Set  hyphenation  flags.   Permissible  values  of  flags are documented in section
              “Hyphenation” of groff(7).  The default is 4 if  continuous  rendering  is  enabled
              (-rcR=1 above), and 6 otherwise.

       -rIN=indent
              Set  the  body text indentation (for normal paragraphs) to indent.  See “Horizontal
              and vertical spacing” above for the default indentation value.  For  nroff,  indent
              should always be an integer multiple of unit ‘n’ to get consistent indentation.

       -rLL=line-length
              Set  line  length.   If this option is not given, the line length is set to respect
              any value set by a prior “.ll” request (which must be in effect when the .TH  macro
              is invoked), if this differs from the built-in default for the formatter; otherwise
              it defaults to 78n in nroff mode and 6.5i in troff mode.

              Note that the use of a “.ll” request to initialize the line length is supported for
              backward compatibility with some versions of the man program; direct initialization
              of the LL register should always be preferred to the use of  such  a  request.   In
              particular,  note  that  a  “.ll  65n”  request  does not preserve the normal nroff
              default line length (the man default initialization to 78n prevails),  whereas  the
              -rLL=65n option, or an equivalent “.nr LL 65n” request preceding the use of the .TH
              macro, does set a line length of 65n.

       -rLT=title-length
              Set title length.  If this option is not given, the title length  defaults  to  the
              line length.

       -rPn   Start enumeration of pages at n rather than 1.

       -rSpoint-size
              Use  point-size  as  the base document font size.  Acceptable values are 10, 11, or
              12.  See subsection “Font style macros” above for the default.

       -rSN=subsection-indent
              Set subsection indentation to  subsection-indent.   See  “Horizontal  and  vertical
              spacing” above for the default indentation value.

       -rXp   After  page  p,  number pages as pa, pb, pc, and so forth.  For example, the option
              -rX2 produces the following page numbers: 1, 2, 2a, 2b, 2c, and so on.

FILES

       /usr/share/groff/1.22.4/tmac/man.tmac
       /usr/share/groff/1.22.4/tmac/an.tmac
              These are wrapper files to call andoc.tmac.

       /usr/share/groff/1.22.4/tmac/andoc.tmac
              This brief groff program detects whether the man or mdoc  macro  package  is  being
              used by a document and loads the correct macro definitions, taking advantage of the
              fact that pages using them must call .TH  or  .Dd,  respectively,  as  their  first
              macro.   Because  the  wrappers above load this file, a man program or user typing,
              for example, “groff -man page.1”, need not know which package the file page.1 uses.
              Multiple man pages, in either format, can be handled.

       /usr/share/groff/1.22.4/tmac/an-old.tmac
              Most  man macros are contained in this file.  It also loads the GNU extensions from
              an-ext.tmac (see below).

       /usr/share/groff/1.22.4/tmac/an-ext.tmac
              The extension macro definitions for .SY,  .OP,  .YS,  .TQ,  .EX/.EE,  .UR/.UE,  and
              .MT/.ME  are  contained  in  this  file,  which  is  written  in  classic troff and
              permissively licensed—not copylefted.  Man page authors concerned about portability
              to  legacy  Unix systems are encouraged to copy these definitions into their pages,
              and maintainers of troff implementations or  work-alike  systems  that  format  man
              pages are encouraged to re-use them.

              Note  that the definitions for these macros are read after the call of .TH, so they
              will replace any macros of the same names preceding it in your file.   If  you  use
              your own implementations of these macros, they must be defined after calling .TH to
              have any effect.

       /usr/share/groff/site-tmac/man.local
              Local changes and customizations should be put into this file.

NOTES

       Some tips on troubleshooting your man pages follow.

       · .RS doesn't indent relative to my indented paragraph
              The .RS macro sets the indentation relative to the amount  of  a  normal  paragraph
              (.PP  and its synonyms).  The same default indentation amount is used for .RS, .IP,
              .TP, and the deprecated .HP.  If you  need  to  start  an  indent  relative  to  an
              indented  paragraph,  call  .RS  repeatedly  until  an  acceptable  indentation  is
              achieved, or give .RS an indentation argument that is  at  least  as  much  as  the
              paragraph's  indentation  amount  relative  to  an  adjacent  .PP  paragraph.   See
              “Horizontal and vertical spacing” above for the values.

       · .RE doesn't reset the indent to the expected level
       · warning: scale indicator invalid in this context
       · warning: number register 'an-saved-margin
              n' not defined
       · warning: number register 'an-saved-prevailing-indent
              n' not defined The .RS macro takes an indentation amount as an  argument;  the  .RE
              macro's  argument  is a specific indentation level.  .RE 1 goes to the level before
              any .RS macros were called, .RE 2 goes to the level of the first .RS call you made,
              and  so  forth.   If  you desire symmetry in your macro calls, simply issue one .RE
              without an argument for each .RS that precedes it.

              After calls to the .SH and .SS sectioning macros, all relative indents are  cleared
              and calls to .RE have no effect.

AUTHORS

       The GNU version of the man macro package was written by James Clark and contributors.  The
       extension macros were written by Werner Lemberg ⟨wl@gnu.org⟩ and  Eric  S.  Raymond  ⟨esr@
       thyrsus.com⟩.

       This document was originally written for the Debian GNU/Linux system by Susan G. Kleinmann
       ⟨sgk@debian.org⟩.  It was corrected and updated by Werner Lemberg and G. Branden Robinson.
       The  extension  macros  were  documented  by  Eric  S.  Raymond;  he  also  originated the
       portability section, to which Ingo Schwarze contributed most of  the  material  on  escape
       sequences.

SEE ALSO

       Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the main
       groff documentation.  You can browse it interactively with “info groff”.

       tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.

       man(1) describes the man page formatter on your system.

       groff_mdoc(7) describes the groff version of the BSD-originated alternative macro  package
       for man pages.

       groff(7), groff_char(7), man(7)