docs: optinal option arguments should be long-only

Deprecate adding new short optional option arguments.  They are problematic.

Proposed-by: Ruediger Meier <sweet_f_a@gmx.de>
Acked-by: Karel Zak <kzak@redhat.com>
Reviewed-by: Benno Schulenberg <bensberg@justemail.net>
Reference: https://lists.gnu.org/archive/html/coreutils/2012-11/msg00004.html
Reference: http://marc.info/?l=util-linux-ng&m=146062997618853&w=2
Signed-off-by: Sami Kerola <kerolasa@iki.fi>

Documentation/boilerplate.c

@@ -35,7 +35,7 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fprintf(out, _(" %s [options] file...\n"), program_invocation_short_name);
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -n, --no-argument       option does not use argument\n"), out);
-	fputs(_(" -o, --optional[=<arg>]  option argument is optional\n"), out);
+	fputs(_("     --optional[=<arg>]  option argument is optional\n"), out);
 	fputs(_(" -r, --required <arg>    option requires an argument\n"), out);
 	fputs(_(" -z                      no long option\n"), out);
 	fputs(_("     --xyzzy             a long option only\n"), out);
@@ -57,11 +57,11 @@ int main(int argc, char **argv)
 	int c;
 
 	enum {
-		OPT_XYZZY = CHAR_MAX + 1
+		OPT_XYZZY = CHAR_MAX + 1,
+		OPT_OPTIONAL	/* see howto-man-page.txt about short option */
 	};
 	static const struct option longopts[] = {
 		{"no-argument", no_argument, NULL, 'n'},
-		{"optional", optional_argument, NULL, 'o'},
 		{"required", required_argument, NULL, 'r'},
 		{"xyzzy", no_argument, NULL, OPT_XYZZY},
 		{"extremely-long-long-option", no_argument, NULL, 'e'},
@@ -77,10 +77,10 @@ int main(int argc, char **argv)
 	textdomain(PACKAGE);
 	atexit(close_stdout);
 
-	while ((c = getopt_long(argc, argv, "no::r:elfVh", longopts, NULL)) != -1)
+	while ((c = getopt_long(argc, argv, "nr:elfVh", longopts, NULL)) != -1)
 		switch (c) {
 		case 'n':
-		case 'o':
+		case OPT_OPTIONAL:
 		case 'r':
 		case OPT_XYZZY:
 		case 'e':

Documentation/howto-man-page.txt

@@ -18,7 +18,7 @@
 .\"
 .\" Please read `man 7 groff_man' to see how to use the various macros.
 .\"
-.TH EXAMPLE "1" "July 2014" "util-linux" "User Commands"
+.TH EXAMPLE "1" "April 2016" "util-linux" "User Commands"
 .SH NAME
 example \- a util-linux man-page howto
 .SH SYNOPSIS
@@ -33,7 +33,7 @@ Write such here.
 \fB\-n\fR, \fB\-\-no\-argument\fR
 This option does not use an argument.
 .TP
-\fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
+\fB\-\-optional\fR[\fI=argument\fR]
 Tell in this description that the
 .I argument
 is optional, and what happens when it is or is not given.  Notice that the word
@@ -43,6 +43,24 @@ usage text uses the argument
 .IR num ,
 the manual page should say
 .IR number .
+.IP
+Notice that after release v2.28 it was decided that introducing new options
+taking optional arguments should be limited to long-only options.  This is
+done primarily to avoid problematic behaviour of short options.  Imagine for
+example normal option
+.B \-n
+and optional option
+.BR \-o .
+One will expect
+.B command \ \-no
+and
+.B command \ \-on
+to be the same, but in fact the former is two separate options while the
+later will use
+.B n
+as option argument of
+.BR -o .
+So it is best to avoid short forms of optional options altogether.
 .TP
 \fB\-r\fR, \fB\-\-required\fR \fIargument\fR
 Tell in this description that the

Documentation/howto-usage-function.txt

@@ -45,7 +45,7 @@ Usage:
 
 Options:
  -n, --no-argument       option does not use argument
- -o, --optional[=<arg>]  option argument is optional
+     --optional[=<arg>]  option argument is optional
  -r, --required <arg>    option requires an argument
  -z                      no long option
      --xyzzy             a long option only