Merge branch 'topic/po4a' of https://github.com/mariobl/util-linux

[thirdparty/util-linux.git] / Documentation / howto-usage-function.txt

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.