156 lines
5.9 KiB
Plaintext
156 lines
5.9 KiB
Plaintext
Well-known options
|
|
------------------
|
|
|
|
The following options are well-known, and should not be used for any
|
|
other purpose:
|
|
|
|
-h, --help display usage and exit
|
|
-V, --version display version and exit
|
|
|
|
The rule of thumb with other options is that once they exist, you may
|
|
not change them, nor change how they work, nor remove them.
|
|
|
|
Notice that '-?' is not expected to be a synonym of '--help', but is an
|
|
unknown option resulting in a usage print-out due to a getopt failure.
|
|
|
|
|
|
How a usage text is supposed to look
|
|
------------------------------------
|
|
|
|
The usage output begins with an empty line, followed by 'Usage:', and
|
|
then the synopsis on the line after that. The synopsis and option-
|
|
description lines are all indented by one space (0x40).
|
|
|
|
The synopsis line describes how to compose the command. Sometimes you
|
|
may need multiple synopsis lines -- this is documented separately in the
|
|
Synopsis section.
|
|
|
|
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 needed in front of the option argument, because one has to use
|
|
it. Three consecutive dots mean 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 where the writing of the option begins.
|
|
|
|
Below, in between the snips, is an example of what the usage output should
|
|
look like.
|
|
|
|
-- snip
|
|
|
|
Usage:
|
|
program [options] <file> [...]
|
|
|
|
Options:
|
|
-n, --no-argument option does not use argument
|
|
-o, --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
|
|
|
|
Note that there are usage-function definitions in the 'c.h' include file
|
|
which you must use. The location of an example file is mentioned at the
|
|
end of this text.
|
|
|
|
|
|
Option descriptions
|
|
-------------------
|
|
|
|
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. In case 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. The --help
|
|
and --version options do not follow this rule, since they are defined as
|
|
constants to ease translation work.
|
|
|
|
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.
|
|
|
|
The last line of the usage text is either empty, or a message informing
|
|
about the manual page. For example: 'For more details see example(1).'.
|
|
Between the options and the man-page message there is an empty line.
|
|
|
|
|
|
Usage function
|
|
--------------
|
|
|
|
The standard usage() function takes either stderr or stdout as an argument.
|
|
The argument will determine whether the program will exit with an error or
|
|
with success. The usage() function will never return.
|
|
|
|
In the code all the strings with options have to start at the same position.
|
|
See here what this means:
|
|
|
|
fprintf(out, _(" -x[=<foo>] default foo is %s"), x);
|
|
fputs( _(" -y some text"), out);
|
|
|
|
Be nice to translators. One gettext entry should be one option, no more,
|
|
no less. For example:
|
|
|
|
fputs(_(" --you-there be nice\n"), out);
|
|
fputs(_(" -2 <whom> translators\n"), out);
|
|
fputs(_(" -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, at the time of the next change,
|
|
when they will not need to search in the long fuzzy text 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 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
|
|
segment. The fundamental difference in execution is a bit difficult to
|
|
define other than that usually the 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 will continue
|
|
to be supported, but anything like them will not be accepted as new
|
|
additions. A short list of examples:
|
|
|
|
- Other characters than '-' to start an option. See '+' in 'more'.
|
|
- Using a number as an option argument. See '-<number>' in 'more'.
|
|
- Long options that start with a single '-'. See 'setterm'.
|
|
|
|
|
|
Example file
|
|
------------
|
|
|
|
The file disk-utils/delpart.c is a minimal example of how to write
|
|
a usage function, set up option parsing, version printing and so on.
|