Well-known options ------------------ Following options are well-known, and they should not be used to 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 followed by `Usage:', and on next line there synopsis begins. Synopsis, and all other lines which vary, are intended by one space (0x40). The synopsis line tells how to execute the command. Some times you may need multiple synopsis lines, this 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 is always wrote first followed by long option. Options are separated with comma and one space. Lonely short or long option does not affect where writing of the option begins. Bellow, 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 will 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. It is good idea to write options that are somehow related next to each other. Usually --help and --version, in this order, are last options in print out. 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); The usage output should be split to manageable chunks, in practice one or few lines. 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 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' or `ddate' commands. - Option string used as an option argument. See `more' command and `-num'. - Short long option. See `setterm'. Example ------- Command sys-utils/arch.c is a minimal example how to do write usage function, setup option parsing, version printing and so on.