Merge branch '170622' of github.com:jwpi/util-linux
* '170622' of github.com:jwpi/util-linux: Docs: move option naming to howto-contribute.txt Docs: update howto-usage-function.txt Docs: add a comment for constants to boilerplate.c include/c.h: add USAGE_COMMANDS and USAGE_COLUMNS
This commit is contained in:
commit
d6ec64e824
|
@ -29,6 +29,11 @@
|
|||
#include "closestream.h"
|
||||
#include "nls.h"
|
||||
|
||||
/*
|
||||
* FIXME: remove this comment.
|
||||
* Other usage() constants that are not demonstrated below:
|
||||
* USAGE_FUNCTIONS USAGE_COMMANDS USAGE_COLUMNS
|
||||
*/
|
||||
static void __attribute__((__noreturn__)) usage(FILE *out)
|
||||
{
|
||||
fputs(USAGE_HEADER, out);
|
||||
|
@ -37,9 +42,6 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
|
|||
fputs(USAGE_SEPARATOR, out);
|
||||
fputs(_("Short program description.\n"), out);
|
||||
|
||||
fputs(USAGE_FUNCTIONS, out);
|
||||
fputs(_(" -s, --do-something some specific task\n"), out);
|
||||
fputs(_(" -o, --do-other some different task\n"), out);
|
||||
fputs(USAGE_OPTIONS, out);
|
||||
fputs(_(" -n, --no-argument option does not use argument\n"), out);
|
||||
fputs(_(" --optional[=<arg>] option argument is optional\n"), out);
|
||||
|
|
|
@ -3,6 +3,7 @@ CONTENTS
|
|||
Patching Process
|
||||
Email Format
|
||||
Coding Style
|
||||
Options
|
||||
Various Notes
|
||||
Standards Compliance
|
||||
|
||||
|
@ -155,6 +156,30 @@ Coding Style
|
|||
multiple lines. In case the shorthand does not look good on one line
|
||||
use the normal "if () else" syntax.
|
||||
|
||||
Options
|
||||
|
||||
* The rule of thumb for options is that once they exist, you may not
|
||||
change them, nor change how they work, nor remove them.
|
||||
|
||||
* 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
|
||||
|
||||
* 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:
|
||||
|
||||
Characters other than '-' to start an option. See '+' in 'more'.
|
||||
|
||||
Using a number as an option. See '-<number>' in 'more'.
|
||||
|
||||
Long options that start with a single '-'. See 'setterm'.
|
||||
|
||||
'-?' is not a synonym for '--help', but is an unknown option
|
||||
resulting in a suggestion to try --help due to a getopt failure.
|
||||
|
||||
Various Notes
|
||||
|
||||
* util-linux does not use kernel headers for file system super
|
||||
|
|
|
@ -1,34 +1,29 @@
|
|||
Well-known options
|
||||
------------------
|
||||
|
||||
The following options are well-known, and should not be used for any
|
||||
other purpose:
|
||||
Example file
|
||||
------------
|
||||
|
||||
-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.
|
||||
|
||||
See Legacy options below.
|
||||
Refer to the ./boilerplate.c example file while reading this howto.
|
||||
|
||||
|
||||
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 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 and empty line. The output
|
||||
begins with, and each of the above are separated by, one empty line.
|
||||
|
||||
The synopsis line describes how to compose the command. Sometimes you
|
||||
may need multiple synopsis lines -- this is documented separately in the
|
||||
Synopsis section.
|
||||
The Usage section contains the synopsis line that describes how to compose
|
||||
the command. Sometimes you may need multiple synopsis lines (see below).
|
||||
|
||||
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.
|
||||
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
|
||||
|
@ -63,22 +58,21 @@ Options:
|
|||
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
|
||||
-------------------
|
||||
|
||||
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. 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
|
||||
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. 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
|
||||
|
@ -87,10 +81,6 @@ 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
|
||||
--------------
|
||||
|
@ -99,6 +89,10 @@ 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.
|
||||
|
||||
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.
|
||||
|
||||
In the code all the strings with options have to start at the same position.
|
||||
See here what this means:
|
||||
|
||||
|
@ -114,17 +108,17 @@ no less. For example:
|
|||
" 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.
|
||||
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 options and/or arguments.
|
||||
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:
|
||||
|
@ -133,27 +127,8 @@ to have two synopsis lines:
|
|||
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.
|
||||
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.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
- Characters other than '-' to start an option. See '+' in 'more'.
|
||||
- Using a number as an option. See '-<number>' in 'more'.
|
||||
- Long options that start with a single '-'. See 'setterm'.
|
||||
- '-?' is not expected to be a synonym of '--help', but is an unknown
|
||||
option resulting in a suggestion to try --help due to a getopt failure.
|
||||
|
||||
|
||||
Example file
|
||||
------------
|
||||
|
||||
The file ./boilerplate.c is a minimal example of how to write
|
||||
a usage function, set up option parsing, version printing and so on.
|
||||
|
|
|
@ -1850,7 +1850,7 @@ static void __attribute__ ((__noreturn__)) usage(FILE *out)
|
|||
fputs(USAGE_SEPARATOR, out);
|
||||
fputs(_("Display or manipulate a disk partition table.\n"), out);
|
||||
|
||||
fputs(_("\nCommands:\n"), out);
|
||||
fputs(USAGE_COMMANDS, out);
|
||||
fputs(_(" -A, --activate <dev> [<part> ...] list or set bootable MBR partitions\n"), out);
|
||||
fputs(_(" -d, --dump <dev> dump partition table (usable for later input)\n"), out);
|
||||
fputs(_(" -J, --json <dev> dump partition table in JSON format\n"), out);
|
||||
|
|
|
@ -307,11 +307,13 @@ static inline int xusleep(useconds_t usec)
|
|||
|
||||
/*
|
||||
* Constant strings for usage() functions. For more info see
|
||||
* Documentation/howto-usage-function.txt and disk-utils/delpart.c
|
||||
* Documentation/{howto-usage-function.txt,boilerplate.c}
|
||||
*/
|
||||
#define USAGE_HEADER _("\nUsage:\n")
|
||||
#define USAGE_OPTIONS _("\nOptions:\n")
|
||||
#define USAGE_FUNCTIONS _("\nFunctions:\n")
|
||||
#define USAGE_COMMANDS _("\nCommands:\n")
|
||||
#define USAGE_COLUMNS _("\nAvailable columns:\n")
|
||||
#define USAGE_SEPARATOR "\n"
|
||||
#define USAGE_HELP _(" -h, --help display help information and exit\n")
|
||||
#define USAGE_VERSION _(" -V, --version display version information and exit\n")
|
||||
|
|
|
@ -1255,11 +1255,9 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
|
|||
fputs(USAGE_HELP, out);
|
||||
fputs(USAGE_VERSION, out);
|
||||
|
||||
fprintf(out, _("\nAvailable columns:\n"));
|
||||
|
||||
fputs(USAGE_COLUMNS, out);
|
||||
for (i = 0; i < ARRAY_SIZE(coldescs); i++)
|
||||
fprintf(out, " %14s %s\n", coldescs[i].name,
|
||||
_(coldescs[i].help));
|
||||
fprintf(out, " %14s %s\n", coldescs[i].name, _(coldescs[i].help));
|
||||
|
||||
fprintf(out, USAGE_MAN_TAIL("lslogins(1)"));
|
||||
|
||||
|
|
|
@ -1248,8 +1248,7 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
|
|||
fputs(USAGE_HELP, out);
|
||||
fputs(USAGE_VERSION, out);
|
||||
|
||||
fprintf(out, _("\nAvailable columns:\n"));
|
||||
|
||||
fputs(USAGE_COLUMNS, out);
|
||||
for (i = 0; i < ARRAY_SIZE(infos); i++)
|
||||
fprintf(out, " %11s %s\n", infos[i].name, _(infos[i].help));
|
||||
|
||||
|
|
|
@ -300,7 +300,7 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
|
|||
fputs(USAGE_SEPARATOR, out);
|
||||
fputs(_("Run zone command on the given block device.\n"), out);
|
||||
|
||||
fputs(_("\nCommands:\n"), out);
|
||||
fputs(USAGE_COMMANDS, out);
|
||||
for (i = 0; i < ARRAY_SIZE(commands); i++)
|
||||
fprintf(out, " %-11s %s\n", commands[i].name, _(commands[i].help));
|
||||
|
||||
|
|
|
@ -2068,8 +2068,7 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
|
|||
fputs(USAGE_HELP, out);
|
||||
fputs(USAGE_VERSION, out);
|
||||
|
||||
fprintf(out, _("\nAvailable columns:\n"));
|
||||
|
||||
fputs(USAGE_COLUMNS, out);
|
||||
for (i = 0; i < ARRAY_SIZE(coldescs); i++)
|
||||
fprintf(out, " %13s %s\n", coldescs[i].name, _(coldescs[i].help));
|
||||
|
||||
|
|
|
@ -388,10 +388,9 @@ static void __attribute__((__noreturn__)) lsmem_usage(FILE *out)
|
|||
fputs(USAGE_HELP, out);
|
||||
fputs(USAGE_VERSION, out);
|
||||
|
||||
fputs(_("\nAvailable columns:\n"), out);
|
||||
|
||||
fputs(USAGE_COLUMNS, out);
|
||||
for (i = 0; i < ARRAY_SIZE(coldescs); i++)
|
||||
fprintf(out, " %10s %s\n", coldescs[i].name, coldescs[i].help);
|
||||
fprintf(out, " %10s %s\n", coldescs[i].name, _(coldescs[i].help));
|
||||
|
||||
fprintf(out, USAGE_MAN_TAIL("lsmem(1)"));
|
||||
|
||||
|
|
|
@ -194,9 +194,8 @@ static void __attribute__ ((__noreturn__)) usage(FILE *out)
|
|||
fputs(USAGE_SEPARATOR, out);
|
||||
|
||||
fprintf(out, _("The default device is %s.\n"), _PATH_WATCHDOG_DEV);
|
||||
fputs(USAGE_SEPARATOR, out);
|
||||
|
||||
fputs(_("Available columns:\n"), out);
|
||||
fputs(USAGE_COLUMNS, out);
|
||||
for (i = 0; i < ARRAY_SIZE(infos); i++)
|
||||
fprintf(out, " %13s %s\n", infos[i].name, _(infos[i].help));
|
||||
|
||||
|
|
Loading…
Reference in New Issue