Well-known options ------------------ Following options are well-known, and they should not be used for any other purpose. -h, --help display usage and exit -V, --version display version and exit Rule of thumb with other options is that once they exist you may not change how they work, or remove them. Notice that `-?' is not expected to be synonym of --help, but an unknown options resulting to a usage print out due getopt failure. How usage is supposed to look ----------------------------- The usage output begins with empty line followed by `Usage:' and synopsis beginning on the next line. Synopsis and all other lines which vary are indented by one space (0x40). The synopsis line describes how to execute the command. Sometimes you may need multiple synopsis lines, this is documented separately under Synopsis title. Notations; Diamond brackets markup an argument. Anything optional is marked with square brackets, such as optional command arguments, or optional option arguments. In the later case `=' character in front of the option argument, because one has to use it. Square brackets with three dots inside mean unlimited repetition of previous. Short option are always written first followed by long option. Options are separated with comma and one space. Lonely short or long option do not affect where writing of the option begins. Below, in between snips, is an example of how the usage output should look like. -- snip Usage: program [options] [...] Options: -n, --no-argument option does not use argument -o, --optional[=] option argument is optional -r, --required option requires an argument -z no long option --xyzzy a long option only -e, --extremely-long-long-option use next line for description when needed -l, --long-explanation an example of very verbose, and chatty option description on two, or multiple lines, where the consecutive lines are intended by two spaces -f, --foobar next option description resets indent -h, --help display this help and exit -V, --version output version information and exit For more details see program(1). -- snip Notice that there are usage function definitions in c.h include file which you must use. Location of example is mentioned at the end of this file. Option description ------------------ Option description should not exceed width of 80 characters. If you need longer description use multiple lines and indentation. The description begins from the point of longest option plus two spaces. In case adding a new option would cause a description re-indentation need it either has to be done, or the new option should begin description from next line. Usually the later is better. The --help and --version will not follow this rule, since they are defined as constants to ease translation work. The argument, e.g. `arg', can be better. For example if an option is expecting number as argument a `num' is suitable argument description. Order of the options has no special meaning, with a exception of --help and --version which are expected to be last ones of the list. Last line of the usage print out is either empty, or a message informing about manual page. For example: `For more details see example(1).' In between man page message and options there is empty line. Usage function -------------- Standard usage function takes either stderr or stdout as an argument. The argument will determine whether the program will exit with error or success. Usage function will never return. In the code all strings with options have to start at the same position. See bellow what that means. fprintf(out, _(" -x[=] default foo is %s"), x); fputs( _(" -y some text"), out); Be nice to translators. One gettext entry should be one option, no more, no less. For example: fputs(_(" --you-there be nice\n"), out); fputs(_(" -2 translators\n"), out); fputs(_(" -t, --hey are doing job that we probably cannot," " or how is your klingon?\n"), out); When existing usage output is changed, and it happens to be one big output, split it to chunks size of an option. The extra work for translators will pay off at the time of the next change when they do not need to search from fuzzy markup what has changed, where, how, and was it the only change. Synopsis -------- You may need to use multiple synopsis lines to tell that a command does fundamentally different things depending on options and/or arguments. For example ionice either changes priority of a running command, or executes a program with a defined priority. Therefore it is reasonable to have two synopsis lines. ionice [options] -p [...] ionice [options] [] [...] Notice that the synopsis is not meant to be repetition of options segment. The fundamental difference in execution is a bit difficult to define other than usually command author, package maintainer or patch submitter will know when it should be done that way. Legacy options -------------- Some commands use peculiar options and arguments. These are supported, but such will not be accepted in future. See list bellow for a hint what are meant this. - Other than `-' used to define an option. See `+' for `more' commands. - Option string used as an option argument. See `more' command and `-num'. - Short long option. See `setterm'. Example ------- Command disk-utils/delpart.c is a minimal example how to do write usage function, setup option parsing, version printing and so on.