Documentation/howto-usage-function.txt

   1
   2 Example file
   3 ------------
   4
   5 Refer to the ./boilerplate.c example file while reading this howto.
   6
   7
   8 How a usage text is supposed to look
   9 ------------------------------------
  10
  11 The usage() output format is: Usage section, command description one-liner,
  12 Options section (see below), special sections like 'Available columns', and
  13 the last line is either the man page reference or an empty line. The output
  14 begins with, and each of the above are separated by, one empty line.
  15
  16 The Usage section contains the synopsis line that describes how to compose
  17 the command. Sometimes you may need multiple synopsis lines (see below).
  18
  19 Only the synopsis and option lines are indented. Indent is one space (0x40).
  20 Option lines do not use line-ending punctuation. Other sentences do.
  21
  22 Notations: diamond brackets are used to mark an argument to be filled in;
  23 square brackets are used to mark anything that is optional, such as optional
  24 command arguments, or optional option arguments. In the later case the '='
  25 character is required in between the option and argument with no whitespace;
  26 three consecutive dots means the unlimited repetition of the preceding.
  27
  28 The short option is always written first, followed by the long option.  They
  29 are separated with a comma and one space.  Lonely short or long options do
  30 not affect their alignment. That is, they must be in their respective column.
  31
  32 Below, in between the snips, is an example of what the usage output should
  33 look like.
  34
  35 -- snip
  36
  37 Usage:
  38  program [options] <file> [...]
  39
  40 Short program description, ideally one line only.
  41
  42 Options:
  43  -n, --no-argument       option does not use argument
  44      --optional[=<arg>]  option argument is optional
  45  -r, --required <arg>    option requires an argument
  46  -z                      no long option
  47      --xyzzy             a long option only
  48  -e, --extremely-long-long-option
  49                          use next line for description when needed
  50  -l, --long-explanation  an example of very verbose, and chatty option
  51                            description on two, or multiple lines, where the
  52                            continuation lines are indented by two spaces
  53  -f, --foobar            next option description resets indent
  54
  55  -h, --help     display this help and exit
  56  -V, --version  output version information and exit
  57
  58 For more details see program(1).
  59 -- snip
  60
  61
  62 Option descriptions
  63 -------------------
  64
  65 This information also applies to other option-like arguments. That is,
  66 arguments starting with '-'. Such as: functions, commands, and so forth.
  67
  68 An option description should not exceed the width of 80 characters.  If
  69 you need a longer description, use multiple lines and indentation.
  70
  71 The description text begins from the point of the longest option plus two
  72 spaces. If adding a new option would necessitate a re-indentation of the
  73 descriptions, it either has to be done, or the new option should begin its
  74 description on the next line.  Usually the later is better.
  75
  76 An argument is preferably worded appropriately.  For example, if an option
  77 expects a number as argument, '<num>' is a suitable argument indicator.
  78
  79 The order of the options has no special meaning, with the exception of
  80 --help and --version which are expected to be last ones in the list.
  81
  82
  83 Usage function
  84 --------------
  85
  86 The usage() function will never return. It must only be called by -h/--help.
  87 All other cases use errtryhelp(EXIT_FAILURE).
  88
  89 Section headers, man page, version, help, and other components of usage()
  90 have string constants defined in 'include/c.h' which must be used. See the
  91 example file listed at the top of this document. The help and version options
  92 are combined into a single macro which takes an argument for the column that
  93 their descriptions will begin on: USAGE_HELP_OPTIONS(<num>).  This allows
  94 them to align properly with the other options.
  95
  96 In the code, all option strings must start at the same position.
  97 See here what this means:
  98
  99         printf(out, _(" -x[=<foo>]  default foo is %s"), x);
 100         puts(       _(" -y          some text"), out);
 101
 102 Be nice to translators.  One gettext entry should be one option, no more,
 103 no less.  For example:
 104
 105         puts(_(" --you-there  be nice\n"), out);
 106         puts(_(" -2 <whom>    translators\n"), out);
 107         puts(_(" -t, --hey    are doing a job that we probably cannot,"
 108                 "                or how is your klingon?\n"), out);
 109
 110 When existing usage output is changed, and it happens to be one big text,
 111 split it into chunks the size of one option. The extra work this will entail
 112 for translators will pay off later; the next string change will not force a
 113 search of the long fuzzy text for what was changed, where, how, and whether
 114 it was the only change.
 115
 116
 117 Synopsis
 118 --------
 119
 120 You may need to use multiple synopsis lines to show that a command does
 121 fundamentally different things depending on the options and/or arguments.
 122 For example, ionice either changes the priority of a running command, or
 123 executes a program with a defined priority.  Therefore it is reasonable
 124 to have two synopsis lines:
 125
 126  ionice [options] -p <pid> ...
 127  ionice [options] <command> [<arg> ...]
 128
 129 Note that the synopsis is not meant to be a repetition of the options
 130 section. The fundamental difference in execution is a bit difficult to
 131 define. The command author, package maintainer or patch submitter will
 132 usually know when it should be done that way.
 133
 134