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

11 files changed, 78 insertions, 80 deletions

diff --git a/Documentation/boilerplate.c b/Documentation/boilerplate.c
index 5b2e59b8a..b70955d54 100644
--- a/Documentation/boilerplate.c
+++ b/Documentation/boilerplate.c
@@ -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);
diff --git a/Documentation/howto-contribute.txt b/Documentation/howto-contribute.txt
index 245f9ab93..e63d390c4 100644
--- a/Documentation/howto-contribute.txt
+++ b/Documentation/howto-contribute.txt
@@ -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
diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt
index 3496b4914..a666d44fa 100644
--- a/Documentation/howto-usage-function.txt
+++ b/Documentation/howto-usage-function.txt
@@ -1,34 +1,29 @@
-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.
+Example file
+------------
 
-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 Usage section contains the synopsis line that describes how to compose
+the command. Sometimes you may need multiple synopsis lines (see below).
 
-The synopsis line describes how to compose the command.  Sometimes you
-may need multiple synopsis lines -- this is documented separately in the
-Synopsis section.
+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 needed in front of the option argument, because one has to use
-it.  Three consecutive dots mean the unlimited repetition of the preceding.
+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.
diff --git a/disk-utils/sfdisk.c b/disk-utils/sfdisk.c
index 2ac8cef02..2a75190f5 100644
--- a/disk-utils/sfdisk.c
+++ b/disk-utils/sfdisk.c
@@ -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);
diff --git a/include/c.h b/include/c.h
index 8cf54cbe4..9c676ff04 100644
--- a/include/c.h
+++ b/include/c.h
@@ -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")
diff --git a/login-utils/lslogins.c b/login-utils/lslogins.c
index 1e89d2703..c6c849e14 100644
--- a/login-utils/lslogins.c
+++ b/login-utils/lslogins.c
@@ -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)"));
 
diff --git a/misc-utils/findmnt.c b/misc-utils/findmnt.c
index 93c0e90ef..7acc60a26 100644
--- a/misc-utils/findmnt.c
+++ b/misc-utils/findmnt.c
@@ -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));
 
diff --git a/sys-utils/blkzone.c b/sys-utils/blkzone.c
index 7713ff3b2..8fd55c066 100644
--- a/sys-utils/blkzone.c
+++ b/sys-utils/blkzone.c
@@ -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));
 
diff --git a/sys-utils/lscpu.c b/sys-utils/lscpu.c
index 3b549a7a0..2871f7131 100644
--- a/sys-utils/lscpu.c
+++ b/sys-utils/lscpu.c
@@ -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));
 
diff --git a/sys-utils/lsmem.c b/sys-utils/lsmem.c
index 0c8adb829..891be36f7 100644
--- a/sys-utils/lsmem.c
+++ b/sys-utils/lsmem.c
@@ -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)"));
 
diff --git a/sys-utils/wdctl.c b/sys-utils/wdctl.c
index e47fc70e9..1790e8993 100644
--- a/sys-utils/wdctl.c
+++ b/sys-utils/wdctl.c
@@ -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));