Provided by: manpages_2.17-1_all bug

NAME

       man - macros to format man pages

SYNOPSIS

       groff -Tascii -man file ...

       groff -Tps -man file ...

       man [section] title

DESCRIPTION

       This manual page explains the groff tmac.an macro package (often called
       the man macro package) and  related  conventions  for  creating  manual
       (man)  pages.   This  macro  package  should be used by developers when
       writing or porting man pages for Linux.  It is fairly  compatible  with
       other  versions  of this macro package, so porting man pages should not
       be a major problem (exceptions include the  NET-2  BSD  release,  which
       uses a totally different macro package called mdoc; see mdoc(7)).

       Note  that  NET-2  BSD  mdoc man pages can be used with groff simply by
       specifying the -mdoc option instead of  the  -man  option.   Using  the
       -mandoc  option is, however, recommended, since this will automatically
       detect which macro package is in use.

PREAMBLE

       The first command in a man page (after comment lines) should be

              .TH title section date source manual,

       where:

              title     The title of the man page (e.g., MAN).

              section   The section number the man page should  be  placed  in
                        (e.g., 7).

              date      The  date of the last revision—remember to change this
                        every time a change is made to  the  man  page,  since
                        this is the most general way of doing version control.

              source    The source of the command.

                        For binaries, use  something  like:  GNU,  NET-2,  SLS
                        Distribution, MCC Distribution.

                        For  system  calls, use the version of the kernel that
                        you are currently looking at: Linux 0.99.11.

                        For library calls, use the  source  of  the  function:
                        GNU, 4.3BSD, Linux DLL 4.4.1.

              manual    The  title  of  the  manual  (e.g., Linux Programmers
                        Manual).

       Note that BSD mdoc-formatted pages begin with the Dd command,  not  the
       TH command.

       The manual sections are traditionally defined as follows:

              1 Commands
                        Those  commands  that can be executed by the user from
                        within a shell.

              2 System calls
                        Those functions which must be performed by the kernel.

              3 Library calls
                        Most of the libc functions, such as qsort(3).

              4 Special files
                        Files found in /dev.

              5 File formats and conventions
                        The  format  for  /etc/passwd and other human-readable
                        files.

              6 Games

              7 Conventions and miscellaneous
                        A description of  the  standard  file  system  layout,
                        network  protocols,  ASCII  and other character codes,
                        this man page, and other things.

              8 System management commands
                        Commands like mount(8), many of which  only  root  can
                        execute.

              9 Kernel routines
                        This  is  an  obsolete  manual  section.   Once it was
                        thought a good idea to document the Linux kernel here,
                        but  in  fact very little has been documented, and the
                        documentation that exists is outdated  already.  There
                        are   better   sources   of   information  for  kernel
                        developers.

SECTIONS

       Sections are started with .SH followed by the  heading  name.   If  the
       name  contains  spaces  and appears on the same line as .SH, then place
       the heading  in  double  quotes.   Traditional  or  suggested  headings
       include:  NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR
       HANDLING,  ERRORS,  OPTIONS,  USAGE,  EXAMPLES,   FILES,   ENVIRONMENT,
       DIAGNOSTICS,  SECURITY,  CONFORMING  TO,  NOTES,  BUGS, AUTHOR, and SEE
       ALSO.  Where a traditional heading would apply,  please  use  it;  this
       kind  of  consistency  can  make  the information easier to understand.
       However, feel free to create your own  headings  if  they  make  things
       easier  to understand.  The only required heading is NAME, which should
       be the first section and be followed on the next line  by  a  one  line
       description of the program:

              .SH NAME
              chess \- the game of chess

       It  is extremely important that this format is followed, and that there
       is a backslash before the single dash which follows the  command  name.
       This  syntax  is used by the makewhatis(8) program to create a database
       of  short  command  descriptions  for  the  whatis(1)  and   apropos(1)
       commands.

       Some other traditional sections have the following contents:

       SYNOPSIS      briefly  describes  the  command or function’s interface.
                     For commands, this shows the syntax of  the  command  and
                     its  arguments  (including options); boldface is used for
                     as-is text and italics are used to  indicate  replaceable
                     arguments.  Brackets  ([])  surround  optional arguments,
                     vertical bars (|) separate choices,  and  ellipses  (...)
                     can  be  repeated.   For functions, it shows any required
                     data declarations or #include directives, followed by the
                     function declaration.

       DESCRIPTION   gives  an  explanation  of what the command, function, or
                     format does.  Discuss how it  interacts  with  files  and
                     standard  input,  and what it produces on standard output
                     or standard error.   Omit  internals  and  implementation
                     details  unless  they’re  critical  for understanding the
                     interface.  Describe the usual case; for  information  on
                     options  use  the OPTIONS section.  If there is some kind
                     of input grammar or complex set of subcommands,  consider
                     describing  them  in  a  separate USAGE section (and just
                     place an overview in the DESCRIPTION section).

       RETURN VALUE  gives a list of  the  values  the  library  routine  will
                     return  to the caller and the conditions that cause these
                     values to be returned.

       EXIT STATUS   lists the possible exit status values or  a  program  and
                     the conditions that cause these values to be returned.

       OPTIONS       describes  the  options  accepted  by the program and how
                     they change its behavior.

       USAGE         describes the grammar of any sublanguage this implements.

       EXAMPLES      provides   one  or  more  examples  describing  how  this
                     function, file or command is used.

       FILES         lists the files the program or  function  uses,  such  as
                     configuration files, startup files, and files the program
                     directly operates on.  Give the full  pathname  of  these
                     files,  and  use  the  installation process to modify the
                     directory part  to  match  user  preferences.   For  many
                     programs,   the   default  installation  location  is  in
                     /usr/local,  so  your  base  manual   page   should   use
                     /usr/local as the base.

       ENVIRONMENT   lists  all environment variables that affect your program
                     or function and how they affect it.

       DIAGNOSTICS   gives an overview of the most common error  messages  and
                     how  to cope with them.  You don’t need to explain system
                     error messages or fatal signals that  can  appear  during
                     execution  of  any program unless they’re special in some
                     way to your program.

       SECURITY      discusses security issues and implications.   Warn  about
                     configurations  or  environments  that should be avoided,
                     commands that may have security implications, and so  on,
                     especially  if  they aren’t obvious.  Discussing security
                     in a separate section isn’t necessary; if it’s easier  to
                     understand,  place  security  information  in  the  other
                     sections (such as  the  DESCRIPTION  or  USAGE  section).
                     However, please include security information somewhere!

       CONFORMING TO describes any standards or conventions this implements.

       NOTES         provides miscellaneous notes.

       BUGS          lists  limitations,  known defects or inconveniences, and
                     other questionable activities.

       AUTHOR        lists authors of the documentation or program so you  can
                     mail in bug reports.

       SEE ALSO      lists  related  man pages in alphabetical order, possibly
                     followed   by   other   related   pages   or   documents.
                     Conventionally this is the last section.

FONTS

       Although there are many arbitrary conventions for man pages in the UNIX
       world, the  existence  of  several  hundred  Linux-specific  man  pages
       defines our font standards:

              For functions, the arguments are always specified using italics,
              even in the SYNOPSIS section, where the rest of the function  is
              specified in bold:
              int myfunction(int argc, char **argv);

              Filenames  are  always  in italics (e.g., /usr/include/stdio.h),
              except in the SYNOPSIS section, where included files are in bold
              (e.g., #include <stdio.h>).

              Special  macros,  which  are  usually in upper case, are in bold
              (e.g., MAXINT).

              When enumerating a list of error codes, the codes  are  in  bold
              (this list usually uses the .TP macro).

              Any  reference  to  another  man  page (or to the subject of the
              current man page) is in bold.  If the manual section  number  is
              given,  it  is  given in Roman (normal) font, without any spaces
              (e.g., man(7)).

       The commands to select the type face are:

       .B  Bold

       .BI Bold alternating  with  italics  (especially  useful  for  function
           specifications)

       .BR Bold  alternating  with  Roman  (especially useful for referring to
           other manual pages)

       .I  Italics

       .IB Italics alternating with bold

       .IR Italics alternating with Roman

       .RB Roman alternating with bold

       .RI Roman alternating with italics

       .SB Small alternating with bold

       .SM Small (useful for acronyms)

       Traditionally, each command can have up to six arguments, but  the  GNU
       implementation  removes  this limitation (you might still want to limit
       yourself  to  6  arguments  for  portability’s  sake).   Arguments  are
       delimited  by spaces.  Double quotes can be used to specify an argument
       which contains spaces.  All of the arguments will be  printed  next  to
       each  other  without intervening spaces, so that the .BR command can be
       used to specify a word in bold followed by a  mark  of  punctuation  in
       Roman.   If  no  arguments  are  given,  the  command is applied to the
       following line of text.

OTHER MACROS AND STRINGS

       Below are other relevant macros and predefined strings.   Unless  noted
       otherwise,  all  macros  cause  a break (end the current line of text).
       Many  of  these  macros  set  or  use  the  "prevailing  indent."   The
       "prevailing  indent"  value  is  set  by any macro with the parameter i
       below; macros may omit i in which case the  current  prevailing  indent
       will  be used.  As a result, successive indented paragraphs can use the
       same indent without re-specifying the indent  value.   A  normal  (non-
       indented)  paragraph  resets the prevailing indent value to its default
       value (0.5 inches).  By default a given indent is measured in ens;  try
       to  ens  or  ems  as  units for indents, since these will automatically
       adjust to font size changes.  The other key macro definitions are:

   Normal Paragraphs
       .LP      Same as .PP (begin a new paragraph).

       .P       Same as .PP (begin a new paragraph).

       .PP      Begin a new paragraph and reset prevailing indent.

   Relative Margin Indent
       .RS i    Start relative margin indent: moves the left margin i  to  the
                right  (if i is omitted, the prevailing indent value is used).
                A new prevailing indent is set to 0.5 inches.   As  a  result,
                all   following   paragraph(s)  will  be  indented  until  the
                corresponding .RE.

       .RE      End relative margin indent and restores the previous value  of
                the prevailing indent.

   Indented Paragraph Macros
       .HP i    Begin  paragraph  with a hanging indent (the first line of the
                paragraph is at the left margin of normal paragraphs, and  the
                rest of the paragraph’s lines are indented).

       .IP x i  Indented paragraph with optional hanging tag.  If the tag x is
                omitted, the entire following paragraph is indented by i.   If
                the  tag  x  is provided, it is hung at the left margin before
                the following indented paragraph (this is just like .TP except
                the  tag  is included with the command instead of being on the
                following line).  If the tag is too long, the text  after  the
                tag will be moved down to the next line (text will not be lost
                or garbled).  For bulleted lists, use  this  macro  with  \(bu
                (bullet) or \(em (em dash) as the tag, and for numbered lists,
                use the number or letter followed by a period as the tag; this
                simplifies translation to other formats.

       .TP i    Begin  paragraph  with  hanging  tag.  The tag is given on the
                next line, but its results are like those of the .IP  command.

   Hypertext Link Macros
       (Feature  supported  with  groff only.)  In order to use hypertext link
       macros, it is necessary to load the www.tmac macro  package.   Use  the
       request .mso www.tmac to do this.

       .URL url link trailer
                Inserts  a  hypertext  link to the URI (URL) url, with link as
                the text of the link.  The trailer will be printed immediately
                afterwards.   When  generating HTML this should translate into
                the HTML command <A HREF="url">link</A>trailer.

                This and other related macros are new, and many tools won’t do
                anything  with  them,  but  since many tools (including troff)
                will simply ignore undefined macros (or at worst insert  their
                text) these are safe to insert.

                It  can be useful to define your own URL macro in manual pages
                for the benefit of those viewing it with a roff  viewer  other
                than  groff.   That  way, the URL, link text, and trailer text
                (if any) are still visible.

                Here’s an example:
                      .de URL
                      \\$2 \(laURL: \\$1 \(ra\\$3
                      ..
                      .if \n[.g] .mso www.tmac
                      .TH ...
                      (later in the page)
                      This software comes from the
                      .URL "http://www.gnu.org/" "GNU Project" " of the"
                      .URL "http://www.fsf.org/" "Free Software Foundation"  .

                In  the  above,  if  groff  is  being used, the www.tmac macro
                package’s definition of  the  URL  macro  will  supersede  the
                locally defined one.

       A number of other link macros are available.  See groff_www(7) for more
       details.

   Miscellaneous Macros
       .DT      Reset tabs to default tab values (every 0.5 inches); does  not
                cause a break.

       .PD d    Set  inter-paragraph  vertical  distance  to  d  (if  omitted,
                d=0.4v); does not cause a break.

       .SS t    Subheading t (like .SH, but used for  a  subsection  inside  a
                section).

   Predefined Strings
       The man package has the following predefined strings:

       \*R    Registration Symbol: ®

       \*S    Change to default font size

       \*(Tm  Trademark Symbol: ™

       \*(lq  Left angled doublequote: “

       \*(rq  Right angled doublequote: ”

SAFE SUBSET

       Although  technically  man is a troff macro package, in reality a large
       number of other tools process man page files that don’t  implement  all
       of  troff’s  abilities.   Thus, it’s best to avoid some of troff’s more
       exotic abilities where possible to permit these  other  tools  to  work
       correctly.   Avoid  using the various troff preprocessors (if you must,
       go ahead and use tbl(1), but try to use the IP and TP commands  instead
       for  two-column  tables).   Avoid  using computations; most other tools
       can’t process them.  Use simple commands that are easy to translate  to
       other  formats.   The  following  troff  macros are believed to be safe
       (though in many cases they will be ignored by translators): \", .,  ad,
       bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps,
       so, sp, ti, tr.

       You may also use many troff escape sequences (those sequences beginning
       with  \).   When  you need to include the backslash character as normal
       text, use \e.  Other sequences you may use,  where  x  or  xx  are  any
       characters  and  N  is any digit, include: \’, \‘, \-, \., \", \%, \*x,
       \*(xx, \(xx, \$N, \nx, \n(xx, \fx, and \f(xx.  Avoid using  the  escape
       sequences for drawing graphics.

       Do  not  use  the  optional  parameter  for  bp (break page).  Use only
       positive values for sp (vertical space).  Don’t  define  a  macro  (de)
       with  the same name as a macro in this or the mdoc macro package with a
       different meaning; it’s likely that such redefinitions will be ignored.
       Every  positive  indent  (in) should be paired with a matching negative
       indent (although you should be using the RS  and  RE  macros  instead).
       The  condition  test  (if,ie)  should  only  have  ’t’  or  ’n’  as the
       condition.  Only translations (tr) that can be ignored should be  used.
       Font  changes  (ft  and  the  \f  escape sequence) should only have the
       values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also  have  no
       parameters).

       If  you  use  capabilities beyond these, check the results carefully on
       several tools.  Once you’ve confirmed that the additional capability is
       safe,  let  the maintainer of this document know about the safe command
       or sequence that should be added to this list.

NOTES

       By all means include full URLs (or URIs) in the text itself; some tools
       such  as  man2html(1) can automatically turn them into hypertext links.
       You can also use the  new  URL  macro  to  identify  links  to  related
       information.    If   you   include   URLs,  use  the  full  URL  (e.g.,
       <http://www.kernelnotes.org>) to ensure that  tools  can  automatically
       find the URLs.

       Tools processing these files should open the file and examine the first
       non-whitespace character. A period (.)  or  single  quote  (’)  at  the
       beginning of a line indicates a troff-based file (such as man or mdoc).
       A left angle bracket (<) indicates an SGML/XML-based file (such as HTML
       or Docbook). Anything else suggests simple ASCII text (e.g., a "catman"
       result).

       Many man pages begin with ’\"  followed  by  a  space  and  a  list  of
       characters,  indicating  how  the  page  is  to  be  preprocessed.  For
       portability’s sake to non-troff translators we recommend that you avoid
       using   anything   other   than  tbl(1),  and  Linux  can  detect  that
       automatically.  However, you might want to include this information  so
       your man page can be handled by other (less capable) systems.  Here are
       the definitions of the preprocessors invoked by these characters:

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)

FILES

       /usr/share/groff/[*/]tmac/tmac.an
       /usr/man/whatis

BUGS

       Most of the macros describe formatting (e.g., font  type  and  spacing)
       instead  of marking semantic content (e.g., this text is a reference to
       another page), compared to formats like mdoc and DocBook (even HTML has
       more  semantic  markings).   This situation makes it harder to vary the
       man format for different media, to make the formatting consistent for a
       given media, and to automatically insert cross-references.  By sticking
       to the safe subset described above, it should  be  easier  to  automate
       transitioning to a different reference page format in the future.

       The Sun macro TX is not implemented.

AUTHORS

       —  James  Clark  (jjc@jclark.com) wrote the implementation of the macro
          package.

       —  Rickard E. Faith (faith@cs.unc.edu) wrote  the  initial  version  of
          this manual page.

       —  Jens  Schweikhardt  (schweikh@noc.fdn.de)  wrote  the Linux Man-Page
          Mini-HOWTO (which influenced this manual page).

       —  David A. Wheeler (dwheeler@ida.org)  heavily  modified  this  manual
          page, such as adding detailed information on sections and macros.

SEE ALSO

       apropos(1),  groff(1),  man(1),  man2html(1), mdoc(7), mdoc.samples(7),
       groff_www(7), whatis(1)