| |
| 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. |
| |
| |