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  conven­
       tions 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 ver­
       sions 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, recom­
       mended, 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  con­
                        trol.

              source    The source of the command.

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

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


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

              manual    The title of the manual (e.g., Linux Pro­
                        grammer's Manual).

       Note that BSD mdoc-formatted pages begin with the Dd  com­
       mand, 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 Macro packages and conventions
                        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 docu­
                        mentation   that   exists   is   outdated
                        already.  There  are  better  sources  of
                        information for kernel developers.

       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, 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 eas­
       ier 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 com­
       mand descriptions for the whatis(1)  and  apropos(1)  com­
       mands.

       Some  other  traditional  sections have the following con­
       tents:

       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  ([]) sur­
                     round 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  decla­
                     ration.

       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 stan­
                     dard  error.  Omit internals and implementa­
                     tion 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  subcom­
                     mands,  consider  describing them in a sepa­
                     rate  USAGE  section  (and  just  place   an


       RETURN VALUE  gives  a list of the values the library rou­
                     tine will return to the caller and the  con­
                     ditions   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  pro­
                     gram and how they change its behavior.

       USAGE         describes  the  grammar  of  any sublanguage
                     this implements.

       FILES         lists the  files  the  program  or  function
                     uses,  such  as configuration files, startup
                     files, and files the program directly  oper­
                     ates  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 exe­
                     cution 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, espe­
                     cially if they aren't  obvious.   Discussing
                     security  in a separate section isn't neces­
                     sary; 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.


       BUGS          lists limitations, known defects or inconve­
                     niences, and other questionable  activities.

       AUTHOR        lists  authors  of the documentation or pro­
                     gram 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  sec­
              tion,  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 sub­
              ject 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


       .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 defini­
       tions 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  pre­
                vailing  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.

                vious 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 para­
                graph's lines are indented).

       .IP x i  Indented paragraph with optional hanging tag.  If
                the  tag x is omitted, the entire following para­
                graph is indented by i.  If the  tag  x  is  pro­
                vided,  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 sim­
                plifies 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
       .UR u    Begins  a  hypertext  link to the URI (URL) u; it
                will end with the corresponding UE command.  When
                generating  HTML  this  should translate into the
                HTML command <A HREF="u">.  There  is  an  excep­
                tion:  if  u  is  the  special value ":", then no
                hypertext link of  any  kind  will  be  generated
                until  after  the  closing  UE (this permits dis­
                abling hypertext links in  phrases  like  LALR(1)
                when  linking  is not appropriate).  These hyper­
                text link "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.

       .UE      Ends the corresponding UR command; when  generat­
                ing HTML this should translate into </A>.

       .UN u    Creates  a  named  hypertext location named u; do
                not include a  corresponding  UE  command.   When
                generating  HTML  this  should translate into the
                HTML command <A NAME="u"  id="u">&nbsp;</A>  (the
                &nbsp;  is  optional  if  support  for  Mosaic is
                unneeded).

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

       .IX ...  Inserts index information (for a search system or
                printed index list).  Index  information  is  not
                normally  displayed  in the page itself.  If fol­
                lowed by a single  parameter,  the  parameter  is
                added as a standalone index term pointing to this
                location in the man page.  If  it's  two  parame­
                ters,  it's  probably in Perl manpage format; the
                first parameter identifies the type of name  (one
                of  Name, Title, Header, Subsection, or Item) and
                the  second  parameter  the  name  itself  to  be
                indexed.   Otherwise, it's in the long index for­
                mat: each parameter gives an index term, subordi­
                nate  index  term, subsubordinate index term, and
                so on until terminated  by  an  empty  parameter,
                then  a  parameter  with the name of the program,
                \em, and short description; this may be  followed
                by  another  empty parameter and possibly by page
                control messages (e.g. PAGE START).   An  example
                of  this  would  be "programming tools" "make" ""
                "\fLmake\fP \(em build programs".

       .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: (TM)

       \*(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 abil­
       ities 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.

       formats.  The following troff macros are  believed  to  be
       safe  (though in many cases they will be ignored by trans­
       lators): \", ., 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 neg­
       ative  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
       UR macro to identify links to related information.  If you
       include  URLs, use the full URL (e.g., <http://www.kernel­
       notes.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  pre­
       processed.     For   portability's   sake   to   non-troff

       other  than  tbl(1),  and  Linux can detect that automati­
       cally.  However, you might want to include  this  informa­
       tion  so your man page can be handled by other (less capa­
       ble) systems.  Here are the definitions of the  preproces­
       sors 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 consis­
       tent 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),



Man(1) output converted with man2html