Provided by: groff_1.22.2-5_amd64 bug

NAME

       groff_man - groff `man' macros to support generation of man pages

SYNOPSIS

       groff -man [options ...] [files ...]
       groff -m man [options ...] [files ...]

DESCRIPTION

       The man macros used to generate man pages with groff were written by James Clark.  This document provides
       a brief summary of the use of each macro in that package.

OPTIONS

       The man macros understand the following command line options (which define various registers).

       -rcR=1 This option (the default if in nroff mode) creates a single, very long page  instead  of  multiple
              pages.  Say -rcR=0 to disable it.

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

       -rD1   Double-sided printing.  Footers for even and odd pages are formatted differently.

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

       -rHY=flags
              Set  hyphenation  flags.   Possible  values  are  1  to  hyphenate  without restrictions, 2 to not
              hyphenate the last word on a page, 4 to not hyphenate the last two characters of a word, and 8  to
              not hyphenate the first two characters of a word.  These values are additive; the default is 14.

       -rIN=width
              Set body text indentation to width.  The default is 7n for nroff, 7.2n for troff.  For nroff, this
              value 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.

       -rPnnn Enumeration of pages start with nnn rather than with 1.

       -rSxx  Base document font size is xx points (xx can be 10, 11, or 12) rather than 10 points.

       -rSN=width
              Set sub-subheading indentation to width.  The default is 3n.

       -rXnnn After page nnn, number pages as nnna, nnnb, nnnc, etc.  For example, the  option  `-rX2'  produces
              the following page numbers: 1, 2, 2a, 2b, 2c, etc.

USAGE

       This  section describes the available macros for manual pages.  For further customization, put additional
       macros and requests into the file man.local which is loaded immediately after the man package.

       .TH title section [extra1] [extra2] [extra3]
              Set the title of the man page to title and the section to section, which  must  take  on  a  value
              between  1  and  8.   The value section may also have a string appended, e.g. `.pm', to indicate a
              specific subsection of the man pages.  Both title and section are positioned at the left and right
              in  the  header  line  (with  section  in  parentheses  immediately  appended to title.  extra1 is
              positioned in the middle of the footer line.  extra2 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).
              extra3 is centered in the header line.

              For HTML output, headers and footers are completely suppressed.

              Additionally, this macro starts a new page; the new line number is 1 again (except if  the  `-rC1'
              option  is  given  on  the  command line) -- this feature is intended only for formatting multiple
              man pages; a single man page should contain exactly one TH macro at the beginning of the file.

       .SH [text for a heading]
              Set up an unnumbered section heading sticking out to the left.  Prints out all the text  following
              SH up to the end of the line (or the text in the next input line if there is no argument to SH) in
              bold face (or the font specified by the string HF), one size larger than the base  document  size.
              Additionally,  the  left margin and the indentation for the following text is reset to the default
              values.

       .SS [text for a heading]
              Set up a secondary, unnumbered section heading.  Prints out all the text following SS  up  to  the
              end  of  the  line (or the text in the next input line if there is no argument to SS) in bold face
              (or the font specified  by  the  string  HF),  at  the  same  size  as  the  base  document  size.
              Additionally,  the  left margin and the indentation for the following text is reset to the default
              values.

       .TP [nnn]
              Set up an indented paragraph with label.  The indentation is  set  to  nnn  if  that  argument  is
              supplied  (the  default  unit  is `n' if omitted), otherwise it is set to the previous indentation
              value specified with TP, IP, or HP (or to the default value if none of them have been used yet).

              The first input line of text following this macro is interpreted as a string to be printed  flush-
              left, as it is appropriate for a label.  It is not interpreted as part of a paragraph, so there is
              no attempt to fill the first line with text from the following input lines.  Nevertheless, if  the
              label  is  not  as  wide  as the indentation the paragraph starts at the same line (but indented),
              continuing on the following lines.  If the label is wider than  the  indentation  the  descriptive
              part  of  the  paragraph  begins  on  the  line following the label, entirely indented.  Note that
              neither font shape nor font size of the label is set to a default value; on the  other  hand,  the
              rest of the text has default font settings.

              The TP macro is the macro used for the explanations you are just reading.

       .TQ    The TQ macro sets up header continuation for a .TP macro.  With it, you can stack up any number of
              labels (such as in a glossary, or list of commands) before beginning the indented paragraph.   For
              an example, look just past the next paragraph.

              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.

       .LP
       .PP
       .P     These  macros  are  mutual  aliases.   Any  of  them  causes a line break at the current position,
              followed by a vertical space downwards by the amount specified by the PD macro.  The font size and
              shape  are reset to the default value (normally 10pt Roman).  Finally, the current left margin and
              the indentation is reset to the default values.

       .IP [designator] [nnn]
              Set up an indented paragraph, using designator as a tag to mark its beginning.  The indentation is
              set  to nnn if that argument is supplied (the default unit is `n' if omitted), otherwise it is set
              to the previous indentation value specified with TP, IP, or HP (or to the default value if none of
              them  have been used yet).  Font size and face of the paragraph (but not the designator) are reset
              to its default values.

              To start an indented paragraph with a particular indentation but without a  designator,  use  `""'
              (two doublequotes) as the second argument.

              For  example,  the  following  paragraphs  were  all  set up with bullets as the designator, using
              `.IP \(bu 4'.  The whole block has been enclosed with `.RS' and  `.RE'  to  set  the  left  margin
              temporarily to the current indentation value.

              •   IP is one of the three macros used in the man package to format lists.

              •   HP is another.  This macro produces a paragraph with a left hanging indentation.

              •   TP is another.  This macro produces an unindented label followed by an indented paragraph.

       .HP [nnn]
              Set  up a paragraph with hanging left indentation.  The indentation is set to nnn if that argument
              is supplied (the default unit is `n' if omitted), otherwise it is set to the previous  indentation
              value  specified  with TP, IP, or HP (or to the default value if none of them have been used yet).
              Font size and face are reset to its default  values.   The  following  paragraph  illustrates  the
              effect  of  this  macro with hanging indentation set to 4 (enclosed by .RS and .RE to set the left
              margin temporarily to the current indentation):

              This is a paragraph following an invocation of the HP macro.   As  you  can  see,  it  produces  a
                  paragraph where all lines but the first are indented.

              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.

       .RS [nnn]
              This macro moves the left margin to the right by the value nnn if specified (default unit is `n');
              otherwise  it  is  set  to  the previous indentation value specified with TP, IP, or HP (or to the
              default value if none of them have been used yet).  The indentation  value  is  then  set  to  the
              default.

              Calls to the RS macro can be nested.

       .RE [nnn]
              This  macro  moves  the  left margin back to level nnn, restoring the previous left margin.  If no
              argument is given, it moves one level back.  The first  level  (i.e.,  no  call  to  RS  yet)  has
              number 1, and each call to RS increases the level by 1.

       .EX
       .EE    Example/End  Example.   After EX, filling is disabled and the font is set to constant-width.  This
              is useful for formatting code, command, and configuration-file examples.  The  EE  macro  restores
              filling and restores the previous font.

              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.

       To  summarize, the following macros cause a line break with the insertion of vertical space (which amount
       can be changed with the PD macro): SH, SS, TP, TQ, LP (PP, P), IP, and HP.  The macros RS, RE, EX, and EE
       also cause a break but no insertion of vertical space.

MACROS TO SET FONTS

       The standard font is Roman; the default text size is 10 point.

       .SM [text]
              Causes  the  text  on the same line or the text on the next input line to appear in a font that is
              one point size smaller than the default font.

       .SB [text]
              Causes the text on the same line or the text on the next input line to appear  in  boldface  font,
              one point size smaller than the default font.

       .BI text
              Causes  text  on the same line to appear alternately in bold face and italic.  The text must be on
              the same line as the macro call.  Thus

                     .BI this "word and" that

              would cause `this' and `that' to appear in bold face, while `word and' appears in italics.

       .IB text
              Causes text to appear alternately in italic and bold face.  The text must be on the same  line  as
              the macro call.

       .RI text
              Causes  text  on the same line to appear alternately in roman and italic.  The text must be on the
              same line as the macro call.

       .IR text
              Causes text on the same line to appear alternately in italic and roman.  The text must be  on  the
              same line as the macro call.

       .BR text
              Causes  text  on  the same line to appear alternately in bold face and roman.  The text must be on
              the same line as the macro call.

       .RB text
              Causes text on the same line to appear alternately in roman and bold face.  The text  must  be  on
              the same line as the macro call.

       .B [text]
              Causes  text  to appear in bold face.  If no text is present on the line where the macro is called
              the text of the next input line appears in bold face.

       .I [text]
              Causes text to appear in italic.  If no text is present on the line where the macro is called  the
              text of the next input line appears in italic.

MACROS TO DESCRIBE HYPERLINKS AND EMAIL ADDRESSES

       The  following  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.

       Using these macros helps ensure that you get hyperlinks when your manual page is rendered in a browser or
       other program that is Web-enabled.

       .UR URL
       .UE [punctuation]
              Wrap a World Wide Web hyperlink.  The argument to UR is the URL; thereafter, lines  until  UE  are
              collected  and  used  as  the link text.  Any argument to the UE macro is pasted to the end of the
              text.  On a device that is not a browser,

                     this is a link to
                     .UR http://\:randomsite.org/\:fubar
                     some random site
                     .UE ,
                     given as an example

              usually displays like this: “this is a link to  some  random  site  <http://randomsite.org/fubar>,
              given as an example”.

              The use of \: to insert hyphenless breakpoints is a groff extension and can be omitted.

       .MT address
       .ME [punctuation]
              Wrap  an email address.  The argument of MT is the address; text following, until ME, is a name to
              be associated with the address.  Any argument to the ME macro is pasted to the  end  of  the  link
              text.  On a device that is not a browser,

                     contact
                     .UR fred.foonly@\:fubar.net
                     Fred Foonly
                     .UE
                     for more information

              usually displays like this: “contact Fred Foonly <fred.foonly@fubar.net> for more information”.

              The use of \: to insert hyphenless breakpoints is a groff extension and can be omitted.

MACROS TO DESCRIBE COMMAND SYNOPSES

       The  following  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.

       These  macros  are  a  convenience  for  authors.   They also assist automated translation tools and help
       browsers in recognizing command synopses and treating them differently from running text.

       .SY command
              Begin synopsis.  Takes a single argument, the name of a command.  Text following, until closed  by
              YS,  is  set with a hanging indentation with the width of command plus a space.  This produces the
              traditional look of a Unix command synopsis.

       .OP key value
              Describe an optional command argument.  The arguments of this macro are set surrounded  by  option
              braces in the default Roman font; the first argument is printed with a bold face, while the second
              argument is typeset as italic.

       .YS    This macro restores normal indentation at the end of a command synopsis.

       Here is a real 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
              .IR .\|.\|. ]
              .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 ...]

       If  necessary,  you  might  use br requests to control line breaking.  You can insert plain text as well;
       this looks like the traditional (unornamented) syntax for a required command argument or filename.

MISCELLANEOUS

       The default indentation is 7.2n in troff mode and 7n in nroff  mode  except  for  grohtml  which  ignores
       indentation.

       .DT    Set  tabs every 0.5 inches.  Since this macro is always called during a TH request, 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.

       .PD [nnn]
              Adjust  the empty space before a new paragraph or section.  The optional argument gives the amount
              of space (default unit is `v'); without parameter, the value is reset to its default value (1 line
              in  nroff mode, 0.4v otherwise).  This affects the macros SH, SS, TP, LP (resp. PP and P), IP, and
              HP.

              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.

       .AT [system [release]]
              Alter the footer for use with AT&T man pages.  This command exists only for  compatibility;  don't
              use it.  See the groff info manual for more.

       .UC [version]
              Alter  the  footer  for use with BSD man pages.  This command exists only for compatibility; don't
              use it.  See the groff info manual for more.

       .PT    Print the header string.  Redefine this macro to get control of the header.

       .BT    Print the footer string.  Redefine this macro to get control of the footer.

       The following strings are defined:

       \*S    Switch back to the default font size.

       \*R    The `registered' sign.

       \*(Tm  The `trademark' sign.

       \*(lq
       \*(rq  Left and right quote.  This is equal to `\(lq' and `\(rq', respectively.

       \*(HF  The typeface used to print headings and subheadings.  The default is `B'.

       If a preprocessor like tbl or eqn is needed, it has become common to make the first line of the man  page
       look like this:

              '\" word

       Note  the  single  space  character  after  the  double  quote.   word consists of letters for the needed
       preprocessors: `e' for eqn, `r' for refer, and `t' for tbl.  Modern implementations of  the  man  program
       read this first line and automatically call the right preprocessor(s).

PORTABILITY AND TROFF REQUESTS

       Since  the  man  macros  consist  of  groups  of  groff  requests,  one can, in principle, supplement the
       functionality of the man macros with individual groff requests where necessary.  See the groff info pages
       for a complete reference of all requests.

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

       For  portability  to  modern viewers, it is best to write your page entirely in the requests described on
       this page.  Further, it is best to completely avoid those we have described as `presentation-level'  (HP,
       PD, and DT).

       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 onto your page.

FILES

       man.tmac
       an.tmac
              These are wrapper files to call andoc.tmac.

       andoc.tmac
              Use  this  file  in case you don't know whether the man macros or the mdoc package should be used.
              Multiple man pages (in either format) can be handled.

       an-old.tmac
              Most man macros are contained in this file.

       an-ext.tmac
              The extension macro definitions for  .SY,  .OP,  .YS,  .TQ,  .EX/.EE,  .UR/.UE,  and  .MT/.ME  are
              contained  in  this  file.   It is written in classic troff, and released for free re-use, and not
              copylefted; manual page authors concerned about portability to legacy Unix systems are  encouraged
              to  copy  these  definitions  into  their  pages,  and  maintainers of troff or its workalikes are
              encouraged to re-use them.

              Note that the definitions for these macros are read after the call of TH,  so  they  will  replace
              macros  of  the  same  names  given  at  the  beginning  of  your  file.  If you must use your own
              definitions for these macros, they must be given after calling TH.

       man.local
              Local changes and customizations should be put into this file.

SEE ALSO

       tbl(1), eqn(1), refer(1), man(1), man(7), groff_mdoc(7)

AUTHORS

       This manual page  was  originally  written  for  the  Debian  GNU/Linux  system  by  Susan  G.  Kleinmann
       ⟨sgk@debian.org⟩.   It  was  corrected  and updated by Werner Lemberg ⟨wl@gnu.org⟩.  The extension macros
       were documented (and partly designed) by Eric S. Raymond ⟨esr@thyrsus.com⟩; he also wrote the portability
       advice.