diff options
Diffstat (limited to 'Documentation/howto-usage-function.txt')
| -rw-r--r-- | Documentation/howto-usage-function.txt | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt new file mode 100644 index 0000000..c108bfc --- /dev/null +++ b/Documentation/howto-usage-function.txt @@ -0,0 +1,134 @@ + +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] <file> [...] + +Short program description, ideally one line only. + +Options: + -n, --no-argument option does not use argument + --optional[=<arg>] option argument is optional + -r, --required <arg> 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, '<num>' 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(<num>). 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[=<foo>] 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 <whom> 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 <pid> ... + ionice [options] <command> [<arg> ...] + +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. + + |