Example file ------------ Refer to the ./boilerplate.c example file while reading this howto. How a usage text is supposed to look ------------------------------------ The usage() output format is: Usage section, command description one-liner, Options section (see below), special sections like 'Available columns', and the last line is either the man page reference or an empty line. The output begins with, and each of the above are separated by, one empty line. The Usage section contains the synopsis line that describes how to compose the command. Sometimes you may need multiple synopsis lines (see below). Only the synopsis and option lines are indented. Indent is one space (0x40). Option lines do not use line-ending punctuation. Other sentences do. Notations: diamond brackets are used to mark an argument to be filled in; square brackets are used to mark anything that is optional, such as optional command arguments, or optional option arguments. In the later case the '=' character is required in between the option and argument with no whitespace; three consecutive dots means the unlimited repetition of the preceding. The short option is always written first, followed by the long option. They are separated with a comma and one space. Lonely short or long options do not affect their alignment. That is, they must be in their respective column. Below, in between the snips, is an example of what the usage output should look like. -- snip Usage: program [options] [...] Short program description, ideally one line only. Options: -n, --no-argument option does not use argument --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 continuation lines are indented 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 Option descriptions ------------------- This information also applies to other option-like arguments. That is, arguments starting with '-'. Such as: functions, commands, and so forth. An option description should not exceed the width of 80 characters. If you need a longer description, use multiple lines and indentation. The description text begins from the point of the longest option plus two spaces. If adding a new option would necessitate a re-indentation of the descriptions, it either has to be done, or the new option should begin its description on the next line. Usually the later is better. An argument is preferably worded appropriately. For example, if an option expects a number as argument, '' is a suitable argument indicator. The order of the options has no special meaning, with the exception of --help and --version which are expected to be last ones in the list. Usage function -------------- The usage() function will never return. It must only be called by -h/--help. All other cases use errtryhelp(EXIT_FAILURE). Section headers, man page, version, help, and other components of usage() have string constants defined in 'include/c.h' which must be used. See the example file listed at the top of this document. The help and version options are combined into a single macro which takes an argument for the column that their descriptions will begin on: USAGE_HELP_OPTIONS(). This allows them to align properly with the other options. In the code, all option strings must start at the same position. See here what this means: printf(out, _(" -x[=] default foo is %s"), x); puts( _(" -y some text"), out); Be nice to translators. One gettext entry should be one option, no more, no less. For example: puts(_(" --you-there be nice\n"), out); puts(_(" -2 translators\n"), out); puts(_(" -t, --hey are doing a 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 text, split it into chunks the size of one option. The extra work this will entail for translators will pay off later; the next string change will not force a search of the long fuzzy text for what was changed, where, how, and whether it was the only change. Synopsis -------- You may need to use multiple synopsis lines to show that a command does fundamentally different things depending on the options and/or arguments. For example, ionice either changes the 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] [ ...] Note that the synopsis is not meant to be a repetition of the options section. The fundamental difference in execution is a bit difficult to define. The command author, package maintainer or patch submitter will usually know when it should be done that way.