158 lines
5.5 KiB
Plaintext
158 lines
5.5 KiB
Plaintext
Well-known options
|
|
------------------
|
|
|
|
Following options are well-known, and they should not be used for any
|
|
other purpose.
|
|
|
|
-h, --help display usage and exit
|
|
-V, --version display version and exit
|
|
|
|
Rule of thumb with other options is that once they exist you may not
|
|
change how they work, or remove them.
|
|
|
|
Notice that `-?' is not expected to be synonym of --help, but an unknown
|
|
options resulting to a usage print out due getopt failure.
|
|
|
|
|
|
How usage is supposed to look
|
|
-----------------------------
|
|
|
|
The usage output begins with empty line followed by `Usage:' and synopsis
|
|
beginning on the next line. Synopsis and all other lines which vary are
|
|
indented by one space (0x40).
|
|
|
|
The synopsis line describes how to execute the command. Sometimes you may
|
|
need multiple synopsis lines, this is documented separately under Synopsis
|
|
title.
|
|
|
|
Notations; Diamond brackets markup an argument. Anything optional is
|
|
marked with square brackets, such as optional command arguments, or
|
|
optional option arguments. In the later case `=' character in front of
|
|
the option argument, because one has to use it. Square brackets with
|
|
three dots inside mean unlimited repetition of previous.
|
|
|
|
Short option are always written first followed by long option. Options are
|
|
separated with comma and one space. Lonely short or long option do not
|
|
affect where writing of the option begins.
|
|
|
|
Below, in between snips, is an example of how 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
|
|
consecutive lines are intended 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
|
|
|
|
Notice that there are usage function definitions in c.h include file
|
|
which you must use. Location of example is mentioned at the end of this
|
|
file.
|
|
|
|
|
|
Option description
|
|
------------------
|
|
|
|
Option description should not exceed width of 80 characters. If you need
|
|
longer description use multiple lines and indentation.
|
|
|
|
The description begins from the point of longest option plus two spaces.
|
|
In case adding a new option would cause a description re-indentation
|
|
need it either has to be done, or the new option should begin description
|
|
from next line. Usually the later is better. The --help and --version
|
|
will not follow this rule, since they are defined as constants to ease
|
|
translation work.
|
|
|
|
The argument, e.g. `arg', can be better. For example if an option is
|
|
expecting number as argument a `num' is suitable argument description.
|
|
|
|
Order of the options has no special meaning, with a exception of --help and
|
|
--version which are expected to be last ones of the list.
|
|
|
|
Last line of the usage print out is either empty, or a message informing
|
|
about manual page. For example: `For more details see example(1).' In
|
|
between man page message and options there is empty line.
|
|
|
|
|
|
Usage function
|
|
--------------
|
|
|
|
Standard usage function takes either stderr or stdout as an argument. The
|
|
argument will determine whether the program will exit with error or
|
|
success. Usage function will never return.
|
|
|
|
In the code all strings with options have to start at the same position. See
|
|
bellow what that 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 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
|
|
output, split it to chunks size of an option. The extra work for
|
|
translators will pay off at the time of the next change when they do not
|
|
need to search from fuzzy markup what has changed, where, how, and was it
|
|
the only change.
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
You may need to use multiple synopsis lines to tell that a command does
|
|
fundamentally different things depending on options and/or arguments. For
|
|
example ionice either changes 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> [<args>] [...]
|
|
|
|
Notice that the synopsis is not meant to be repetition of options segment.
|
|
The fundamental difference in execution is a bit difficult to define
|
|
other than usually 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 are supported,
|
|
but such will not be accepted in future. See list bellow for a hint what
|
|
are meant this.
|
|
|
|
- Other than `-' used to define an option. See `+' for `more'
|
|
commands.
|
|
- Option string used as an option argument. See `more' command and `-num'.
|
|
- Short long option. See `setterm'.
|
|
|
|
|
|
Example
|
|
-------
|
|
|
|
Command disk-utils/delpart.c is a minimal example how to do write usage
|
|
function, setup option parsing, version printing and so on.
|