unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

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



NAME
       man-pages - conventions for writing Linux man pages

SYNOPSIS
       man [section] title

DESCRIPTION
       This  page describes the conventions that should be employed when writ-
       ing man pages for the Linux man-pages project, which comprises Sections
       2, 3, 4, 5, and 7 of the Linux manual pages.  The conventions described
       on this page may also be useful for authors writing man pages for other
       projects.

   Sections of the Manual Pages
       The manual Sections are traditionally defined as follows:

       1 Commands (Programs)
                 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.

       4 Special files (devices)
                 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
                 Overviews of various topics, conventions and protocols, char-
                 acter set standards, and miscellaneous other things.

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

   Macro package
       New  manual  pages  should be marked up using the groff an.tmac package
       described in man(7).  This choice is mainly for consistency:  the  vast
       majority  of  existing  Linux  manual  pages  are marked up using these
       macros.

   Conventions for source file layout
       Please limit source code line length to no more than about  75  charac-
       ters  wherever  possible.   This helps avoid line-wrapping in some mail
       clients when patches are submitted inline.

       New sentences should be started on new lines.  This makes it easier  to
       see the effect of patches, which often operate at the level of individ-
       ual sentences.

   Title line
       The first command in a man page should be a TH command:

              .TH title section date source manual

       where:

              title     The title of the man page, written in all caps  (e.g.,
                        MAN-PAGES).

              section   The  section  number  in  which the man page should be
                        placed (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.  Dates should be written in the form YYYY-MM-
                        DD.

              source    The source of the command, function, or system call.

                        For those few man-pages pages in  Sections  1  and  8,
                        probably you just want to write GNU.

                        For system calls, just write Linux.  (An earlier prac-
                        tice was to write the version  number  of  the  kernel
                        from  which the manual page was being written/checked.
                        However, this was never done consistently, and so  was
                        probably  worse  than  including  no  version  number.
                        Henceforth, avoid including a version number.)

                        For library calls that are part of glibc or one of the
                        other  common  GNU  libraries, just use GNU C Library,
                        GNU, or an empty string.

                        For Section 4 pages, use Linux.

                        In cases of doubt, just write Linux, or GNU.

              manual    The title of the manual (e.g., for  Section  2  and  3
                        pages in the man-pages package, use Linux Programmer's
                        Manual).

   Sections within a manual page
       The list below shows conventional or suggested sections.   Most  manual
       pages  should include at least the highlighted sections.  Arrange a new
       manual page so that sections are placed in the order shown in the list.

            NAME
            SYNOPSIS
            CONFIGURATION      [Normally only in Section 4]
            DESCRIPTION
            OPTIONS            [Normally only in Sections 1, 8]
            EXIT STATUS        [Normally only in Sections 1, 8]
            RETURN VALUE       [Normally only in Sections 2, 3]
            ERRORS             [Typically only in Sections 2, 3]
            ENVIRONMENT
            FILES
            VERSIONS           [Normally only in Sections 2, 3]
            CONFORMING TO
            NOTES
            BUGS
            EXAMPLE
            SEE ALSO

       Where a traditional heading would apply, please use it;  this  kind  of
       consistency  can  make  the  information  easier to understand.  If you
       must, you can create your own headings if they make  things  easier  to
       understand  (this  can be especially useful for pages in Sections 4 and
       5).  However, before doing this, consider whether  you  could  use  the
       traditional  headings,  with  some  subsections (.SS) within those sec-
       tions.

       The following list elaborates on the contents of each of the above sec-
       tions.

       NAME          The  name  of this manual page.  See man(7) for important
                     details of the line(s) that should follow  the  .SH  NAME
                     command.

       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.

                     Where  a  feature  test macro must be defined in order to
                     obtain the declaration of a function (or a variable) from
                     a header file, then the SYNOPSIS should indicate this, as
                     described in feature_test_macros(7).

       CONFIGURATION Configuration details for a device.   This  section  nor-
                     mally only appears in Section 4 pages.

       DESCRIPTION   gives  an  explanation  of what the program, 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
                     command-line  options  of  a program use the OPTIONS sec-
                     tion.

       OPTIONS       describes the command-line options accepted by a  program
                     and  how  they  change its behavior.  This section should
                     only appear for Section 1 and 8 manual pages.

       EXIT STATUS   lists the possible exit status values of  a  program  and
                     the  conditions  that  cause these values to be returned.
                     This section should only appear for Section 1 and 8  man-
                     ual pages.

       RETURN VALUE  For  Section  2 and 3 pages, this section gives a list of
                     the values the library routine will return to the  caller
                     and   the  conditions  that  cause  these  values  to  be
                     returned.

       ERRORS        For Section 2 and 3 manual pages, this is a list  of  the
                     values  that  may  be  placed in errno in the event of an
                     error, along with information  about  the  cause  of  the
                     errors.  The error list should be in alphabetical order.

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

       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  pro-
                     grams,   the   default   installation   location   is  in
                     /usr/local,  so  your  base  manual   page   should   use
                     /usr/local as the base.

       VERSIONS      A  brief  summary  of  the Linux kernel or glibc versions
                     where a system call  or  library  function  appeared,  or
                     changed  significantly  in  its  operation.  As a general
                     rule, every new interface should include a VERSIONS  sec-
                     tion  in  its  manual page.  Unfortunately, many existing
                     manual pages don't include this information (since  there
                     was  no policy to do so when they were written).  Patches
                     to remedy this are welcome, but, from the perspective  of
                     programmers  writing  new code, this information probably
                     only matters in the case of kernel interfaces  that  have
                     been  added  in  Linux  2.4 or later (i.e., changes since
                     kernel 2.2), and library functions that have  been  added
                     to  glibc  since  version  2.1 (i.e., changes since glibc
                     2.0).

                     The syscalls(2) manual  page  also  provides  information
                     about kernel versions in which various system calls first
                     appeared.

       CONFORMING TO describes any standards or conventions that relate to the
                     function  or command described by the manual page.  For a
                     page in Section 2 or 3,  this  section  should  note  the
                     POSIX.1  version(s)  that  the call conforms to, and also
                     whether the call is specified in C99.  (Don't  worry  too
                     much  about  other standards like SUS, SUSv2, and XPG, or
                     the SVr4 and 4.xBSD implementation standards, unless  the
                     call  was  specified in those standards, but isn't in the
                     current version of POSIX.1.)  (See standards(7).)

                     If the call is not governed by any standards but commonly
                     exists  on  other  systems,  note  them.   If the call is
                     Linux-specific, note this.

                     If this section consists of  just  a  list  of  standards
                     (which  it  commonly  does),  terminate  the  list with a
                     period ('.').

       NOTES         provides miscellaneous notes.  For Section 2  and  3  man
                     pages  you may find it useful to include subsections (SS)
                     named Linux Notes and Glibc Notes.

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

       EXAMPLE       provides  one  or more examples describing how this func-
                     tion, file or command is used.  For  details  on  writing
                     example programs, see Example Programs below.

       AUTHORS       lists authors of the documentation or program.  Use of an
                     AUTHORS section is strongly discouraged.   Generally,  it
                     is  better not to clutter every page with a list of (over
                     time potentially numerous) authors; if you write or  sig-
                     nificantly amend a page, add a copyright notice as a com-
                     ment in the source file.  If you  are  the  author  of  a
                     device  driver and want to include an address for report-
                     ing bugs, place this under the BUGS section.

       SEE ALSO      provides a comma-seprated  list  of  related  man  pages,
                     ordered  by  section  number  and  then alphabetically by
                     name, possibly followed by other related pages  or  docu-
                     ments.  Do not terminate this with a period.

   Font conventions
       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);

       Variable names should, like argument names, be specified in italics.

       Filenames   (whether   pathnames,   or   references  to  files  in  the
       /usr/include directory) are always in italics (e.g., <stdio.h>), except
       in  the  SYNOPSIS  section,  where  included  files  are in bold (e.g.,
       #include <&lt;stdio.h>&gt;).  When referring to a standard include  file  under
       /usr/include,  specify the header file surrounded by angle brackets, in
       the usual C way (e.g., &lt;stdio.h&gt;).

       Special macros, which are usually in upper case,  are  in  bold  (e.g.,
       MAXINT).  Exception: don't boldface NULL.

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

       Complete commands should, if long, be written as in an indented line on
       their own, for example

           man 7 man-pages

       If the comamnd is short, then it can be included inline in the text, in
       italic format, for example, man 7 man-pages.  In this case, it  may  be
       worth  using  non-breaking spaces ("\ ") at suitable places in the com-
       mand.  Command options should be written in italics, e.g., -l.

       Expressions, if not written on a  separate  indented  line,  should  be
       specified  in  italics.   Again,  the use of non-breaking spaces may be
       appropriate if the expression is inlined with normal text.

       Any reference to the subject of the current manual page should be writ-
       ten with the name in bold.  If the subject is a function (i.e., this is
       a Section 2 or 3 page), then the name should be followed by a  pair  of
       parentheses  in  Roman (normal) font.  For example, in the fcntl(2) man
       page, references to the subject  of  the  page  would  be  written  as:
       fcntl().  The preferred way to write this in the source file is:

           .BR fcntl ()

       (Using  this format, rather than the use of "\fB...\fP()" makes it eas-
       ier to write tools that parse man page source files.)

       Any reference to another man page should be written with  the  name  in
       bold,  always  followed by the section number, formatted in Roman (nor-
       mal) font, without any separating spaces (e.g.,  intro(2)).   The  pre-
       ferred way to write this in the source file is:

           .BR intro (2)

       (Including  the  section  number  in  cross  references lets tools like
       man2html(1) create properly hyperlinked pages.)

   Spelling
       Starting with release 2.59, man-pages follows American spelling conven-
       tions;  please  write all new pages and patches according to these con-
       ventions.

   Example Programs
       Manual pages can include example programs demonstrating how  to  use  a
       system call or library function.  However, note the following:

       *  Example programs should be written in C.

       *  An  example  program is only necessary and useful if it demonstrates
          something beyond what can easily be provided in a  textual  descrip-
          tion  of  the interface.  An example program that does nothing other
          than call an interface usually serves little purpose.

       *  Example programs should be fairly short (preferably  less  than  100
          lines; ideally less than 50 lines).

       *  Example  programs  should  do  error checking after system calls and
          library function calls.

       *  Example programs should be complete, and  compile  without  warnings
          when compiled with cc -Wall.

       *  Where possible and appropriate, example programs should allow exper-
          imentation, by varying their behavior based on inputs (ideally  from
          command-line arguments, or alternatively, via input read by the pro-
          gram).

       *  Example programs should be  laid  out  according  to  Kernighan  and
          Ritchie  style, with 4-space indents.  (Avoid the use of TAB charac-
          ters in source code!)

       For some examples of  what  example  programs  should  look  like,  see
       wait(2) and pipe(2).

   Indentation of structure definitions, shell session logs, etc.
       When  structure  definitions,  shell session logs, etc. are included in
       running text, indent them by  4  spaces  (i.e.,  a  block  enclosed  by
       .in +4n and .in).

EXAMPLE
       For canonical examples of how man pages in the man-pages package should
       look, see pipe(2) and fcntl(2).

SEE ALSO
       man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)

COLOPHON
       This page is part of release 3.05 of the Linux  man-pages  project.   A
       description  of  the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.



Linux                             2008-06-12                      MAN-PAGES(7)