Documentation/howto-usage-function.txt

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.