diff options
author | Sami Kerola | 2016-04-16 16:30:39 +0200 |
---|---|---|
committer | Sami Kerola | 2016-04-17 00:08:18 +0200 |
commit | 326c5c93b917a623f346155c8b3438b379d9fd60 (patch) | |
tree | 9c47cbdf3125b3a18b9fabcade84645a60de2690 | |
parent | libmount: make kernel_fs_postparse() more robust (diff) | |
download | kernel-qcow2-util-linux-326c5c93b917a623f346155c8b3438b379d9fd60.tar.gz kernel-qcow2-util-linux-326c5c93b917a623f346155c8b3438b379d9fd60.tar.xz kernel-qcow2-util-linux-326c5c93b917a623f346155c8b3438b379d9fd60.zip |
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>
-rw-r--r-- | Documentation/boilerplate.c | 10 | ||||
-rw-r--r-- | Documentation/howto-man-page.txt | 22 | ||||
-rw-r--r-- | Documentation/howto-usage-function.txt | 2 |
3 files changed, 26 insertions, 8 deletions
diff --git a/Documentation/boilerplate.c b/Documentation/boilerplate.c index 3ee7d7bed..fe2fc13ac 100644 --- 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 ee3cb4e2f..28a1e3450 100644 --- 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 dd1f4eded..54d3084cb 100644 --- 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 |