Documentation/howto-usage-function.txt

   1 Well-known options
   2 ------------------
   3
   4 Following options are well-known, and they should not be used for any
   5 other purpose.
   6
   7  -h, --help     display usage and exit
   8  -V, --version  display version and exit
   9
  10 Rule of thumb with other options is that once they exist you may not
  11 change how they work, or remove them.
  12
  13 Notice that `-?' is not expected to be synonym of --help, but an unknown
  14 options resulting to a usage print out due getopt failure.
  15
  16
  17 How usage is supposed to look
  18 -----------------------------
  19
  20 The usage output begins with empty line followed by `Usage:' and synopsis
  21 beginning on the next line. Synopsis and all other lines which vary are
  22 indented by one space (0x40).
  23
  24 The synopsis line describes how to execute the command. Sometimes you may
  25 need multiple synopsis lines, this is documented separately under Synopsis
  26 title.
  27
  28 Notations; Diamond brackets markup an argument. Anything optional is
  29 marked with square brackets, such as optional command arguments, or
  30 optional option arguments. In the later case `=' character in front of
  31 the option argument, because one has to use it. Square brackets with
  32 three dots inside mean unlimited repetition of previous.
  33
  34 Short option are always written first followed by long option. Options are
  35 separated with comma and one space. Lonely short or long option do not
  36 affect where writing of the option begins.
  37
  38 Below, in between snips, is an example of how the usage output should
  39 look like.
  40
  41 -- snip
  42
  43 Usage:
  44  program [options] <file> [...]
  45
  46 Options:
  47
  48  -n, --no-argument       option does not use argument
  49  -o, --optional[=<arg>]  option argument is optional
  50  -r, --required <arg>    option requires an argument
  51  -z                      no long option
  52      --xyzzy             a long option only
  53  -e, --extremely-long-long-option
  54                          use next line for description when needed
  55  -l, --long-explanation  an example of very verbose, and chatty option
  56                            description on two, or multiple lines, where the
  57                            consecutive lines are intended by two spaces
  58  -f, --foobar            next option description resets indent
  59
  60  -h, --help     display this help and exit
  61  -V, --version  output version information and exit
  62
  63 For more details see program(1).
  64 -- snip
  65
  66 Notice that there are usage function definitions in c.h include file
  67 which you must use. Location of example is mentioned at the end of this
  68 file.
  69
  70
  71 Option description
  72 ------------------
  73
  74 Option description should not exceed width of 80 characters. If you need
  75 longer description use multiple lines and indentation.
  76
  77 The description begins from the point of longest option plus two spaces.
  78 In case adding a new option would cause a description re-indentation
  79 need it either has to be done, or the new option should begin description
  80 from next line. Usually the later is better. The --help and --version
  81 will not follow this rule, since they are defined as constants to ease
  82 translation work.
  83
  84 The argument, e.g. `arg', can be better. For example if an option is
  85 expecting number as argument a `num' is suitable argument description.
  86
  87 Order of the options has no special meaning, with a exception of --help and
  88 --version which are expected to be last ones of the list.
  89
  90 Last line of the usage print out is either empty, or a message informing
  91 about manual page. For example: `For more details see example(1).' In
  92 between man page message and options there is empty line.
  93
  94
  95 Usage function
  96 --------------
  97
  98 Standard usage function takes either stderr or stdout as an argument. The
  99 argument will determine whether the program will exit with error or
 100 success. Usage function will never return.
 101
 102 In the code all strings with options have to start at the same position. See
 103 bellow what that means.
 104
 105         fprintf(out, _(" -x[=<foo>]  default foo is %s"), x);
 106         fputs(       _(" -y          some text"), out);
 107
 108 Be nice to translators. One gettext entry should be one option, no more,
 109 no less. For example:
 110
 111         fputs(_(" --you-there  be nice\n"), out);
 112         fputs(_(" -2 <whom>    translators\n"), out);
 113         fputs(_(" -t, --hey    are doing job that we probably cannot,"
 114                 "                or how is your klingon?\n"), out);
 115
 116 When existing usage output is changed, and it happens to be one big
 117 output, split it to chunks size of an option.  The extra work for
 118 translators will pay off at the time of the next change when they do not
 119 need to search from fuzzy markup what has changed, where, how, and was it
 120 the only change.
 121
 122 Synopsis
 123 --------
 124
 125 You may need to use multiple synopsis lines to tell that a command does
 126 fundamentally different things depending on options and/or arguments. For
 127 example ionice either changes priority of a running command, or executes
 128 a program with a defined priority. Therefore it is reasonable to have two
 129 synopsis lines.
 130
 131  ionice [options] -p <pid> [...]
 132  ionice [options] <command> [<args>] [...]
 133
 134 Notice that the synopsis is not meant to be repetition of options segment.
 135 The fundamental difference in execution is a bit difficult to define
 136 other than usually command author, package maintainer or patch submitter
 137 will know when it should be done that way.
 138
 139
 140 Legacy options
 141 --------------
 142
 143 Some commands use peculiar options and arguments. These are supported,
 144 but such will not be accepted in future. See list bellow for a hint what
 145 are meant this.
 146
 147 - Other than `-' used to define an option. See `+' for `more'
 148   commands.
 149 - Option string used as an option argument. See `more' command and `-num'.
 150 - Short long option. See `setterm'.
 151
 152
 153 Example
 154 -------
 155
 156 Command disk-utils/delpart.c is a minimal example how to do write usage
 157 function, setup option parsing, version printing and so on.