135 lines
5.2 KiB
Plaintext
135 lines
5.2 KiB
Plaintext
|
|
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.
|
|
|
|
|