man - macros to format man pages


     groff -Tascii -man file ...

     groff -Tps -man file ...

     man [section] title


     This manual page explains the groff  macro  package.
     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

     Note that NET-2 BSD 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


     The first command in a man page should be

          .TH title section date source manual,


          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,

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

                  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
                  Programmer'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

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

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

          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)


     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 section,
          where  included  files  are  in  bold  (e.g.,  #include

          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 sec-
          tion 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.  Argu-
     ments are delimited by spaces.  Double quotes can be used to
     specify an argument which contains spaces.  All of the argu-
     ments 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 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,
     required  heading  is  NAME, which should 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 fol-
     lows  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.


     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




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