Documentation/howto-usage-function.txt

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