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>

diff --git a/Documentation/boilerplate.c b/Documentation/boilerplate.c
index 3ee7d7bedd0f423dffbb85b4c73f29a4936ea5b0..fe2fc13ac158b04434be4812bebd90448f5a72cb 100644 (file)
--- a/Documentation/boilerplate.c
+++ b/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':

diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt
index ee3cb4e2fe0d83bbfe8692e59c2930c965770593..28a1e34506fdf156fc00eeca974510df349c78f7 100644 (file)
--- a/Documentation/howto-man-page.txt
+++ b/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

diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt
index dd1f4ededd4628e71f9b0c5adeb429926413bef1..54d3084cbc8e0032b4893dcb0db7c914f65b74d2 100644 (file)
--- a/Documentation/howto-usage-function.txt
+++ b/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