(help2man.info.gz) --help recommendations

 
 3 `--help' Recommendations
 **************************
 
 Here are some recommendations for what to include in your `--help'
 output.  Including these gives `help2man' the best chance at generating
 a respectable man page, as well as benefitting users directly.
 
     Command-Line Interfaces (GNU Coding Standards)Command-Line
 Interfaces, and  Man Pages (GNU Coding Standards)Man Pages, for
 the official GNU standards relating to `--help' and man pages.
 
    * A synopsis of how to invoke the program.  If different usages of
      the program have different invocations, then list them all.  For
      example (edited for brevity):
 
           Usage: cp [OPTION]... SOURCE DEST
             or:  cp [OPTION]... SOURCE... DIRECTORY
           ...
 
      Use `argv[0]' for the program name in these synopses, just as it
      is, with no directory stripping.  This is in contrast to the
      canonical (constant) name of the program which is used in
      `--version'.
 
    * A very brief explanation of what the program does, including
      default and/or typical behaviour.  For example, here is `cp''s:
 
           Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
 
    * A list of options, indented to column 2.  If the program supports
      one-character options, put those first, then the equivalent long
      option (if any).  If the option takes an argument, include that
      too, giving it a meaningful name.  Align the descriptions in a
      convenient column, if desired.  Note that to be correctly
      recognised by `help2man' the description must be separated from
      the options by at least two spaces and descriptions continued on
      subsequent lines must start at the same column.
 
      Here again is an (edited) excerpt from `cp', showing a short
      option with an equivalent long option, a long option only, and a
      short option only:
 
             -a, --archive                same as -dpR
                 --backup[=CONTROL]       make a backup of each ...
             -b                           like --backup but ...
 
      For programs that take many options, it may be desirable to split
      the option list into sections such as `Global', `Output control',
      or whatever makes sense in the particular case.  It is usually
      best to alphabetise (by short option name first, then long) within
      each section, or the entire list if there are no sections.
 
    * Any useful additional information about program behaviour, such as
      influential environment variables, further explanation of options,
      etc.  For example, `cp' discusses `VERSION_CONTROL' and sparse
      files.
 
    * A few examples of typical usage, at your discretion.  One good
      example is usually worth a thousand words of description, so this
      is highly recommended.
 
    * In closing, a line stating how to email bug reports.  Typically,
      MAILING-ADDRESS will be `bug-PROGRAM@gnu.org'; please use this
      form for GNU programs whenever possible.  It's also good to
      mention the home page of the program, other mailing lists, etc.
 
 
    The `argp' and `popt' programming interfaces let you specify option
 descriptions for `--help' in the same structure as the rest of the
 option definition; you may wish to consider using these routines for
 option parsing instead of `getopt'.
Info Catalog
(help2man.info.gz) Including text
(help2man.info.gz) Top
(help2man.info.gz) Makefile usage
automatically generated byinfo2html