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) will
              create 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 com­
              mand line, number the  pages  continuously,  rather
              than starting each at 1.

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

       -rPnnn Enumeration of pages will  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.

       -rXnnn After page nnn, number pages as nnna,  nnnb,  nnnc,
              etc.   For  example, the option `-rX2' will produce
              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 will be loaded
       immediately after the man package.

       .TH title section [extra1] [extra2] [extra3]
              Sets 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  sec­
              tion  are  positioned  at the left and right in the
              header line (with section  in  parentheses  immedi­
              ately appended to title.  extra1 will be positioned
              in the middle of the footer line.  extra2  will  be

              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
              supressed.

              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]
              Sets up an unnumbered section heading sticking  out
              to  the left.  Prints out all the text following SH
              up to the end of the line (resp. the  text  in  the
              next  line  if  there is no argument to SH) in bold
              face, one size larger than the base document  size.
              Additionally,  the  left  margin  for the following
              text is reset to its default value.

       .SS [text for a heading]
              Sets up an secondary, unnumbered  section  heading.
              Prints  out all the text following SS up to the end
              of the line (resp. the text in  the  next  line  if
              there  is  no  argument to SS) in bold face, at the
              same size as the base document size.  Additionally,
              the  left margin for the following text is reset to
              its default value.

       .TP [nnn]
              Sets up an  indented  paragraph  with  label.   The
              indentation  is set to nnn if that argument is sup­
              plied (the default unit is `n' if omitted),  other­
              wise  it  is  set to the default indentation value.
              The first 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 inter­
              preted  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, then  the  para­
              graph  starts at the same line (but indented), con­
              tinuing on the following lines.  If  the  label  is
              wider  than  the  indentation, then 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 will have default font settings.  The TP macro
              is the macro used for the explanations you are just


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

       .IP [designator] [nnn]
              Sets  up an indented paragraph, using designator as
              a tag to mark its beginning.   The  indentation  is
              set  to  nnn  if that argument is supplied (default
              unit is `n'),  otherwise  the  default  indentation
              value is used.  Font size and face of the paragraph
              (but not the designator) are reset to  its  default
              values.  To start an indented paragraph with a par­
              ticular 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':

              ·   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 unin­
                  dented label followed by an indented paragraph.

       .HP [nnn]
              Sets  up a paragraph with hanging left indentation.
              The indentation is set to nnn if that  argument  is
              supplied  (default  unit  is  `n'),  otherwise  the
              default indentation value is used.  Font  size  and
              face  are reset to its default values.  The follow­
              ing paragraph illustrates the effect of this  macro
              with hanging indentation set to 4:

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

       .RS [nnn]
              This macro moves the left margin to  the  right  by
              the  value  nnn if specified (default unit is `n');
              otherwise the default indentation  value  is  used.
              Calls to the RS macro can be nested.

              This macro moves the left margin back to level nnn;
              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.

       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, LP (PP, P), IP,
       and HP.  The macros RS and RE 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  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  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

              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.

       .R [text]
              Causes text to appear in roman font.  If no text is
              present on the line where the macro is called, then
              the  text  of the next line appears in roman.  This
              is the default font to which text  is  returned  at
              the end of processing of the other macros.

       .B [text]
              Causes  text to appear in bold face.  If no text is
              present on the line where the macro is called, then
              the text of the next 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, then
              the text of the next line appears in italic.


MISCELLANEOUS

       The  default  indentation  is  7.2n for all output devices
       except for grohtml which ignores indentation.

       .DT    Sets 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.

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

       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.

       usage  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 implemen­
       tations  of the man program read this first line and auto­
       matically call the right preprocessor(s).


FILES

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

       andoc.tmac
              This file checks whether the man macros or the mdoc
              package should be used.

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

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


SEE ALSO

       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.
       A  complete list of these requests is available on the WWW
       at

         http://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html

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


AUTHOR

       This manual page was originally  written  for  the  Debian
       GNU/Linux  system  by Susan G. Kleinmann <sgk@debian.org>,
       corrected and updated by Werner Lemberg <wl@gnu.org>,  and
       is now part of the GNU troff distribution.


Man(1) output converted with man2html