MAN(7)              Linux Programmer's Manual              MAN(7)

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.
       This macro package should be used by developers when writ-
       ing or porting man pages for Linux.  It is fairly compati-
       ble 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  dif-
       ferent macro package).

       Note  that NET-2 BSD man pages can be used with groff sim-
       ply 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 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  gen-
                      eral 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, BSD 4.3, Linux DLL 4.4.1.

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

       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
                      sort(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, this man page, and other things.

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

              9 Kernel routines
                      This  is  a non-standard manual section and
                      is included because the source code to  the
                      Linux  kernel is freely available under the
                      GNU Public  License  and  many  people  are
                      working on changes to the kernel)

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 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, without any spaces (e.g., man(7)).

              The commands to select  the  type  face  are  given
              below:

       .B      Bold

       .BI     Bold alternating with italics

       .BR     Bold alternating with Roman

       .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

       Traditionally,  each command can have up to six arguments,
       but the GNU  version  seems  to  remove  this  limitation.
       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.

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 headings include: NAME, SYNOPSIS, DESCRIPTION,
       OPTIONS, FILES, SEE ALSO, DIAGNOSTICS, BUGS,  and  AUTHOR.
       The  only  required  heading is NAME, which should be fol-
       lowed 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.

OTHER MACROS
       Other macros include the following:

       .DT    Default tabs

       .HP    Begin hanging indent

       .IP    Begin paragraph with hanging tag.  This is the same
              as  .TP,  except the tag is given on the same line,
              not on the following line.

       .LP    Same as .PP

       .PD    Set interparagraph distance to argument

       .PP    Begin a new paragraph

       .RE    End relative indent (indented paragraph)

       .RS    Start relative indent (indented paragraph)

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

       .TP    Begin paragraph with hanging tag.  The tag is given
              on the next line.  This command is similar to .IP

FILES
       /usr/local/lib/groff/tmac/tmac.an
       /usr/man/whatis

SEE ALSO
       groff(1), man(1), whatis(1), apropos(1), makewhatis(8)

Linux                      25 July 1993                         1