Adding upstream version 2.38.1.upstream/2.38.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 134 insertions, 0 deletions

diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt
new file mode 100644
index 0000000..c108bfc
--- /dev/null
+++ b/Documentation/howto-usage-function.txt
@@ -0,0 +1,134 @@
+
+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.
+
+