Provided by: manpages_3.35-0.1ubuntu1_all bug

NAME

       man-pages - conventions for writing Linux man pages

SYNOPSIS

       man [section] title

DESCRIPTION

       This page describes the conventions that should be employed when writing 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, character 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 characters 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 individual 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 practice 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 sections.

       The following list elaborates on the contents of each of the above sections.

       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 normally 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 section.

       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 manual 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  programs,  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 section  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 function, 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
                     significantly  amend  a  page,  add  a  copyright notice as a comment in the
                     source file.  If you are the author of a device driver and want  to  include
                     an address for reporting bugs, place this under the BUGS section.

       SEE ALSO      provides  a  comma-separated  list  of related man pages, ordered by section
                     number and then alphabetically by name, possibly followed by  other  related
                     pages or documents.  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 <stdio.h>).  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., <stdio.h>).

       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 command 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 nonbreaking  spaces  ("\ ")
       at  suitable  places  in the command.  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 nonbreaking spaces may be appropriate if the expression is inlined with
       normal text.

       Any reference to the subject of the current manual page should be written 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 easier  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 (normal) font,  without  any  separating  spaces
       (e.g., intro(2)).  The preferred 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 conventions; please  write
       all new pages and patches according to these conventions.

   Example Programs and Shell Sessions
       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 description 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 experimentation, by
          varying their behavior  based  on  inputs  (ideally  from  command-line  arguments,  or
          alternatively, via input read by the program).

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

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

       If you include a shell session demonstrating the use of a program or other system feature,
       boldface the user input text, to distinguish it from output produced by the system.

   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.35 of the Linux man-pages project.  A description of the
       project, and information about reporting bugs, can be found at  http://man7.org/linux/man-
       pages/.