docs: add usage() howto for contributors

Style instructions to usage() writers. Discussion about this;
http://www.spinics.net/lists/util-linux-ng/index.html#04983

Signed-off-by: Sami Kerola <kerolasa@iki.fi>

1 files changed, 147 insertions, 0 deletions

diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt
new file mode 100644
index 000000000..f717293d9
--- /dev/null
+++ b/Documentation/howto-usage-function.txt
@@ -0,0 +1,147 @@
+Well-known options
+------------------
+
+Following options are well-known, and they should not be used to 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 followed by `Usage:', and on next line
+there synopsis begins. Synopsis, and all other lines which vary, are
+intended by one space (0x40).
+
+The synopsis line tells how to execute the command. Some times you may
+need multiple synopsis lines, this 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 is always wrote first followed by long option. Options are
+separated with comma and one space. Lonely short or long option does not
+affect where writing of the option begins.
+
+Bellow, 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 will 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. It is good idea to write
+options that are somehow related next to each other. Usually --help and
+--version, in this order, are last options in print out.
+
+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);
+
+The usage output should be split to manageable chunks, in practice one or
+few lines.
+
+
+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 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' or `ddate'
+  commands.
+- Option string used as an option argument. See `more' command and `-num'.
+- Short long option. See `setterm'.
+
+
+Example
+-------
+
+Command sys-utils/arch.c is a minimal example how to do write usage
+function, setup option parsing, version printing and so on.