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 /Documentation/howto-man-page.txt | |
| 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>
Diffstat (limited to 'Documentation/howto-man-page.txt')
| -rw-r--r-- | Documentation/howto-man-page.txt | 22 |
1 files changed, 20 insertions, 2 deletions
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 |