From 326c5c93b917a623f346155c8b3438b379d9fd60 Mon Sep 17 00:00:00 2001 From: Sami Kerola Date: Sat, 16 Apr 2016 15:30:39 +0100 Subject: docs: optinal option arguments should be long-only Deprecate adding new short optional option arguments. They are problematic. Proposed-by: Ruediger Meier Acked-by: Karel Zak Reviewed-by: Benno Schulenberg 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 --- Documentation/howto-man-page.txt | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) (limited to 'Documentation/howto-man-page.txt') 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 -- cgit v1.2.3-55-g7522