util-linux/Documentation/howto-usage-function.txt

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.