[src/trunk]: src/bin/sh sh(1): improve getopts docs for optstring leading :

[lukem <lukem%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/4003d36fcbcf
branches:  trunk
changeset: 359457:4003d36fcbcf
user:      lukem <lukem%NetBSD.org@localhost>
date:      Fri Jan 07 05:30:30 2022 +0000

description:
sh(1): improve getopts docs for optstring leading :

getopts has different behaviour if the leading character
of optstring is `:', so describe in more detail:
- no errors are printed (already there)
- unknown options set var to `?' and OPTARG to the unknown option
- missing arguments set var to `:' and OPTARG to the option name

Slight rewording of other paragraphs for more clarity.

diffstat:

 bin/sh/sh.1 |  35 ++++++++++++++++++++++++++---------
 1 files changed, 26 insertions(+), 9 deletions(-)

diffs (64 lines):

diff -r b129d77e6abe -r 4003d36fcbcf bin/sh/sh.1
--- a/bin/sh/sh.1       Fri Jan 07 05:17:38 2022 +0000
+++ b/bin/sh/sh.1       Fri Jan 07 05:30:30 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sh.1,v 1.242 2022/01/07 05:10:30 lukem Exp $
+.\"    $NetBSD: sh.1,v 1.243 2022/01/07 05:30:30 lukem Exp $
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
@@ -2932,7 +2932,7 @@
 .Xr getopt 1 .
 .Pp
 The first argument should be a series of letters, each of which may be
-optionally followed by a colon to indicate that the option requires an
+optionally followed by a colon (:) to indicate that the option requires an
 argument.
 The variable specified is set to the parsed option.
 .Pp
@@ -2969,21 +2969,38 @@
 .Ar optstring
 is a string of recognized option letters (see
 .Xr getopt 3 ) .
-If a letter is followed by a colon, the option is expected to have an
-argument which may or may not be separated from it by whitespace.
+If a letter is followed by a colon (:), the option is expected to have an
+argument which may or may not be separated from the option by whitespace.
 If an option character is not found where expected,
 .Ic getopts
 will set the variable
 .Ar var
-to a
+to
 .Sq Li \&? ;
 .Ic getopts
 will then unset
 .Ev OPTARG
-and write output to standard error.
-By specifying a colon as the first character of
-.Ar optstring
-all errors will be ignored.
+and write an error to standard error.
+.Pp
+By specifying a colon (:) as the first character of
+.Ar optstring ,
+the error handling behavior changes:
+no errors will be written to standard error;
+unknown option characters will set
+.Ar var
+to
+.Sq Li \&?
+and set
+.Ev OPTARG
+to the unknown option character (instead of unset
+.Ev OPTARG Ns );
+and missing option arguments will set
+.Ar var
+to
+.Sq Li \&:
+and set
+.Ev OPTARG
+to the option character with the missing argument.
 .Pp
 A nonzero value is returned when the last option is reached.
 If there are no remaining arguments,