1 files changed, 34 insertions, 10 deletions

diff --git a/usr.bin/getopt/getopt.1 b/usr.bin/getopt/getopt.1
index ebf1c653e715..e3a0742f4a42 100644
--- a/usr.bin/getopt/getopt.1
+++ b/usr.bin/getopt/getopt.1
@@ -1,11 +1,12 @@
-.Dd June 21, 1993
+.Dd April 3, 1999
 .Dt GETOPT 1
 .Os
 .Sh NAME
 .Nm getopt
 .Nd parse command options
 .Sh SYNOPSIS
-.Nm set \-\- \`getopt Ar optstring $*\`
+.Nm args=\`getopt Ar optstring $*\`
+; errcode=$?; set \-\- $args
 .Sh DESCRIPTION
 .Nm Getopt
 is used to break up options in command lines for easy parsing by
@@ -42,24 +43,34 @@ and the option
 which requires an argument.
 .Pp
 .Bd -literal -offset indent
-set \-\- \`getopt abo: $*\`
-if test $? != 0
+args=\`getopt abo: $*\`
+# you should not use \`getopt abo: "$@"\` since that would parse
+# the arguments differently from what the set command below does.
+if [ $? != 0 ]
 then
 	echo 'Usage: ...'
 	exit 2
 fi
+set \-\- $args
+# You cannot use the set command with a backquoted getopt directly,
+# since the exit code from getopt would be shadowed by those of set, 
+# which is zero by definition.
 for i
 do
 	case "$i"
 	in
 		\-a|\-b)
-			flag=$i; shift;;
+			echo flag $i set; sflags="${i#-}$sflags"; 
+			shift;;
 		\-o)
-			oarg=$2; shift; shift;;
+			echo oarg is "'"$2"'"; oarg="$2"; shift;
+			shift;;
 		\-\-)
 			shift; break;;
 	esac
 done
+echo single-char flags: "'"$sflags"'"
+echo oarg is "'"$oarg"'"
 .Ed
 .Pp
 This code will accept any of the following as equivalent:
@@ -69,25 +80,33 @@ cmd \-aoarg file file
 cmd \-a \-o arg file file
 cmd \-oarg -a file file
 cmd \-a \-oarg \-\- file file
+.Pp
 .Ed
 .Sh SEE ALSO
 .Xr sh 1 ,
 .Xr getopt 3
 .Sh DIAGNOSTICS
 .Nm Getopt
-prints an error message on the standard error output when it
-encounters an option letter not included in
+prints an error message on the standard error output and exits with
+status > 0 when it encounters an option letter not included in
 .Ar optstring .
 .Sh HISTORY
 Written by Henry Spencer, working from a Bell Labs manual page.
-Behavior believed identical to the Bell version.
+Behavior believed identical to the Bell version. Example changed in
+.Fx
+version 3.2 and 4.0.
 .Sh BUGS
 Whatever
 .Xr getopt 3
 has.
 .Pp
 Arguments containing white space or embedded shell metacharacters
-generally will not survive intact;  this looks easy to fix but isn't.
+generally will not survive intact;  this looks easy to fix but
+isn't. People trying to fix 
+.Nm getopt
+or the example in this manpage should check the history of this file
+in
+.Fx .
 .Pp
 The error message for an invalid option is identified as coming
 from
@@ -101,3 +120,8 @@ The precise best way to use the
 .Nm set
 command to set the arguments without disrupting the value(s) of
 shell options varies from one shell version to another.
+.Pp
+Each shellscript has to carry complex code to parse arguments halfway
+correcty (like the example presented here). A better getopt-like tool
+would move much of the complexity into the tool and keep the client
+shell scripts simpler.