--- getopt/trunk/getopt.1	2014/11/20 19:09:47	364
+++ getopt/trunk/getopt.1	2014/11/20 20:15:01	365
@@ -1,8 +1,8 @@
-.TH GETOPT 1 "May 31, 1997" Linux ""
+.TH GETOPT "1" "June 2012" "Linux" "User Commands"
 .SH NAME
 getopt \- parse command options (enhanced)
 .SH SYNOPSIS
-.B getopt
+.BI getopt
 .I optstring parameters
 .br
 .B getopt
@@ -21,62 +21,60 @@
 .B getopt
 is used to break up
 .RI ( parse )
-options in command lines for easy parsing by
-shell procedures, and to check for legal options.
-It uses the
+options in command lines for easy parsing by shell procedures, and to
+check for legal options.  It uses the
 .SM GNU
 .BR getopt (3)
 routines to do this.
-
+.PP
 The parameters
 .B getopt
-is called with can be divided into two parts: options
-which modify the way getopt will parse
-.RI ( options
-and
-.BR \-o | \-\-options
+is called with can be divided into two parts: options which modify
+the way
+.B getopt
+will do the parsing
+.RI "(the " options
+and the
 .I optstring
 in the
 .BR SYNOPSIS ),
-and the parameters which are to be
-parsed
+and the parameters which are to be parsed
 .RI ( parameters
 in the
 .BR SYNOPSIS ).
-The second part will start at the first non\-option parameter
-that is not an option argument, or after the first occurrence of
-.RB ` \-\- '.
+The second part will start at the first non\-option parameter that is
+not an option argument, or after the first occurrence of
+.RB ' \-\- '.
 If no
-.RB ` \-o '
+.RB ' \-o '
 or
-.RB ` \-\-options '
-option is found in the first part, the first
-parameter of the second part is used as the short options string.
-
+.RB ' \-\-options '
+option is found in the first part, the first parameter of the second
+part is used as the short options string.
+.PP
 If the environment variable
 .B GETOPT_COMPATIBLE
-is set, or if its first parameter
-is not an option (does not start with a
-.RB ` \- ',
-this is the first format in the
+is set, or if the first \fIparameter\fR is not an option (does not start
+with a
+.RB ' \- ',
+the first format in the
 .BR SYNOPSIS ),
 .B getopt
 will generate output that is compatible with that of other versions of
 .BR getopt (1).
-It will still do parameter shuffling and recognize optional
-arguments (see section
+It will still do parameter shuffling and recognize optional arguments
+(see section
 .B COMPATIBILITY
 for more information).
-
+.PP
 Traditional implementations of
 .BR getopt (1)
-are unable to cope with whitespace and other (shell\-specific) special characters
-in arguments and non\-option parameters. To solve this problem, this
-implementation can generate
-quoted output which must once again be interpreted by the shell (usually
-by using the
+are unable to cope with whitespace and other (shell\-specific)
+special characters in arguments and non\-option parameters.  To solve
+this problem, this implementation can generate quoted output which
+must once again be interpreted by the shell (usually by using the
 .B eval
-command). This has the effect of preserving those characters, but
+command).  This has the effect of preserving those characters, but
 you must call
 .B getopt
 in a way that is no longer compatible with other versions (the second
@@ -91,49 +89,45 @@
 .TP
 .BR \-a , " \-\-alternative"
 Allow long options to start with a single
-.RB ` \- '.
+.RB ' \- '.
 .TP
 .BR \-h , " \-\-help"
-Output a small usage guide and exit successfully. No other output is generated.
+Display help text and exit.  No other output is generated.
 .TP
 .BR \-l , " \-\-longoptions \fIlongopts\fP"
-The long (multi\-character) options to be recognized.
-More than one option name
-may be specified at once, by separating the names with commas. This option
-may be given more than once, the
+The long (multi\-character) options to be recognized.  More than one
+option name may be specified at once, by separating the names with
+commas.  This option may be given more than once, the
 .I longopts
-are cumulative.
-Each long option name
-in
+are cumulative.  Each long option name in
 .I longopts
-may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument.
+may be followed by one colon to indicate it has a required argument,
+and by two colons to indicate it has an optional argument.
 .TP
 .BR \-n , " \-\-name \fIprogname\fP"
 The name that will be used by the
 .BR getopt (3)
-routines when it reports errors. Note that errors of
+routines when it reports errors.  Note that errors of
 .BR getopt (1)
 are still reported as coming from getopt.
 .TP
 .BR \-o , " \-\-options \fIshortopts\fP"
-The short (one\-character) options to be recognized. If this option is not
-found, the first parameter of
+The short (one\-character) options to be recognized.  If this option
+is not found, the first parameter of
 .B getopt
-that does not start with
-a
-.RB ` \- '
+that does not start with a
+.RB ' \- '
 (and is not an option argument) is used as the short options string.
-Each short option character
-in
+Each short option character in
 .I shortopts
 may be followed by one colon to indicate it has a required argument,
-and by two colons to indicate it has an optional argument.
-The first character of shortopts may be
-.RB ` + '
+and by two colons to indicate it has an optional argument.  The first
+character of shortopts may be
+.RB ' + '
 or
-.RB ` \- '
-to influence the way
-options are parsed and output is generated (see section
+.RB ' \- '
+to influence the way options are parsed and output is generated (see
+section
 .B SCANNING MODES
 for details).
 .TP
@@ -141,45 +135,46 @@
 Disable error reporting by getopt(3).
 .TP
 .BR  \-Q , " \-\-quiet\-output"
-Do not generate normal output. Errors are still reported by
+Do not generate normal output.  Errors are still reported by
 .BR getopt (3),
 unless you also use
-.IR \-q .
+.BR \-q .
 .TP
 .BR \-s , " \-\-shell \fIshell\fP"
-Set quoting conventions to those of shell. If no \-s argument is found,
-the
+Set quoting conventions to those of \fIshell\fR.
+If the \fB\-s\fR option is not given, the
 .SM BASH
-conventions are used. Valid arguments are currently
-.RB ` sh '
-.RB ` bash ',
-.RB ` csh ',
+conventions are used.  Valid arguments are currently
+.RB ' sh '
+.RB ' bash ',
+.RB ' csh ',
 and
-.RB ` tcsh '.
+.RB ' tcsh '.
 .TP
 .BR \-u , " \-\-unquoted"
-Do not quote the output. Note that whitespace and special (shell\-dependent)
-characters can cause havoc in this mode (like they do with other
+Do not quote the output.  Note that whitespace and special
+(shell\-dependent) characters can cause havoc in this mode (like they
+do with other
 .BR getopt (1)
 implementations).
 .TP
 .BR \-T , " \-\-test"
 Test if your
 .BR getopt (1)
-is this enhanced version or an old version. This generates no output,
-and sets the error status to 4. Other implementations of
+is this enhanced version or an old version.  This generates no
+output, and sets the error status to 4.  Other implementations of
 .BR getopt (1),
 and this version if the environment variable
 .B GETOPT_COMPATIBLE
-is set,
-will return
-.RB ` \-\- '
+is set, will return
+.RB ' \-\- '
 and error status 0.
 .TP
 .BR \-V , " \-\-version"
-Output version information and exit successfully. No other output is generated.
+Display version information and exit.  No other output is generated.
 .SH PARSING
-This section specifies the format of the second part of the parameters of
+This section specifies the format of the second part of the
+parameters of
 .B getopt
 (the
 .I parameters
@@ -187,223 +182,219 @@
 .BR SYNOPSIS ).
 The next section
 .RB ( OUTPUT )
-describes the output that is
-generated. These parameters were typically the parameters a shell function
-was called with.
-Care must be taken that each parameter the shell function was
-called with corresponds to exactly one parameter in the parameter list of
+describes the output that is generated.  These parameters were
+typically the parameters a shell function was called with.  Care must
+be taken that each parameter the shell function was called with
+corresponds to exactly one parameter in the parameter list of
 .B getopt
 (see the
 .BR EXAMPLES ).
 All parsing is done by the GNU
 .BR getopt (3)
 routines.
-
-The parameters are parsed from left to right. Each parameter is classified as a
-short option, a long option, an argument to an option,
-or a non\-option parameter.
-
+.PP
+The parameters are parsed from left to right.  Each parameter is
+classified as a short option, a long option, an argument to an
+option, or a non\-option parameter.
+.PP
 A simple short option is a
-.RB ` \- '
-followed by a short option character. If
-the option has a required argument, it may be written directly after the option
-character or as the next parameter (ie. separated by whitespace on the
-command line). If the
-option has an optional argument, it must be written directly after the
-option character if present.
-
+.RB ' \- '
+followed by a short option character.  If the option has a required
+argument, it may be written directly after the option character or as
+the next parameter (i.e. separated by whitespace on the command
+line).  If the option has an optional argument, it must be written
+directly after the option character if present.
+.PP
 It is possible to specify several short options after one
-.RB ` \- ',
-as long as all (except possibly the last) do not have required or optional
-arguments.
-
+.RB ' \- ',
+as long as all (except possibly the last) do not have required or
+optional arguments.
+.PP
 A long option normally begins with
-.RB ` \-\- '
-followed by the long option name.
-If the option has a required argument, it may be written directly after
-the long option name, separated by
-.RB ` = ',
-or as the next argument (ie. separated by whitespace on the command line).
-If the option has an optional argument, it must
-be written directly after the long option name, separated by
-.RB ` = ',
+.RB ' \-\- '
+followed by the long option name.  If the option has a required
+argument, it may be written directly after the long option name,
+separated by
+.RB ' = ',
+or as the next argument (i.e. separated by whitespace on the command
+line).  If the option has an optional argument, it must be written
+directly after the long option name, separated by
+.RB ' = ',
 if present (if you add the
-.RB ` = '
-but nothing behind it, it is interpreted
-as if no argument was present; this is a slight bug, see the
+.RB ' = '
+but nothing behind it, it is interpreted as if no argument was
+present; this is a slight bug, see the
 .BR BUGS ).
 Long options may be abbreviated, as long as the abbreviation is not
 ambiguous.
-
+.PP
 Each parameter not starting with a
-.RB ` \- ',
-and not a required argument of
-a previous option, is a non\-option parameter. Each parameter after
-a
-.RB ` \-\- '
-parameter is always interpreted as a non\-option parameter.
-If the environment variable
+.RB ' \- ',
+and not a required argument of a previous option, is a non\-option
+parameter.  Each parameter after a
+.RB ' \-\- '
+parameter is always interpreted as a non\-option parameter.  If the
+environment variable
 .B POSIXLY_CORRECT
-is set, or if the short
-option string started with a
-.RB ` + ',
-all remaining parameters are interpreted
-as non\-option parameters as soon as the first non\-option parameter is
-found.
+is set, or if the short option string started with a
+.RB ' + ',
+all remaining parameters are interpreted as non\-option parameters as
+soon as the first non\-option parameter is found.
 .SH OUTPUT
-Output is generated for each element described in the previous section.
-Output is done
-in the same order as the elements are specified in the input, except
-for non\-option parameters. Output can be done in
+Output is generated for each element described in the previous
+section.  Output is done in the same order as the elements are
+specified in the input, except for non\-option parameters.  Output
+can be done in
 .I compatible
 .RI ( unquoted )
-mode, or in such way that whitespace and other special characters within
-arguments and non\-option parameters are preserved (see
+mode, or in such way that whitespace and other special characters
+within arguments and non\-option parameters are preserved (see
 .BR QUOTING ).
 When the output is processed in the shell script, it will seem to be
-composed of distinct elements that can be processed one by one (by using the
-shift command in most shell languages). This is imperfect in unquoted mode,
-as elements can be split at unexpected places if they contain whitespace
-or special characters.
-
+composed of distinct elements that can be processed one by one (by
+using the shift command in most shell languages).  This is imperfect
+in unquoted mode, as elements can be split at unexpected places if
+they contain whitespace or special characters.
+.PP
 If there are problems parsing the parameters, for example because a
-required argument is not found or an option is not recognized, an error
-will be reported on stderr, there will be no output for the offending
-element, and a non\-zero error status is returned.
-
+required argument is not found or an option is not recognized, an
+error will be reported on stderr, there will be no output for the
+offending element, and a non\-zero error status is returned.
+.PP
 For a short option, a single
-.RB ` \- '
-and the option character are generated
-as one parameter. If the option has an argument, the next
-parameter will be the argument. If the option takes an optional argument,
-but none was found, the next parameter will be generated but be empty in
-quoting mode,
-but no second parameter will be generated in unquoted (compatible) mode.
+.RB ' \- '
+and the option character are generated as one parameter.  If the
+option has an argument, the next parameter will be the argument.  If
+the option takes an optional argument, but none was found, the next
+parameter will be generated but be empty in quoting mode, but no
+second parameter will be generated in unquoted (compatible) mode.
 Note that many other
 .BR getopt (1)
 implementations do not support optional arguments.
-
+.PP
 If several short options were specified after a single
-.RB ` \- ',
+.RB ' \- ',
 each will be present in the output as a separate parameter.
-
+.PP
 For a long option,
-.RB ` \-\- '
-and the full option name are generated as one
-parameter. This is done regardless whether the option was abbreviated or
-specified with a single
-.RB ` \- '
-in the input. Arguments are handled as with short options.
-
-Normally, no non\-option parameters output is generated until all options
-and their arguments have been generated. Then
-.RB ` \-\- '
-is generated as a
-single parameter, and after it the non\-option parameters in the order
-they were found, each as a separate parameter.
-Only if the first character of the short options string was a
-.RB ` \- ',
-non\-option parameter output is generated at the place they are found in the
-input (this is not supported if the first format of the
+.RB ' \-\- '
+and the full option name are generated as one parameter.  This is
+done regardless whether the option was abbreviated or specified with
+a single
+.RB ' \- '
+in the input.  Arguments are handled as with short options.
+.PP
+Normally, no non\-option parameters output is generated until all
+options and their arguments have been generated.  Then
+.RB ' \-\- '
+is generated as a single parameter, and after it the non\-option
+parameters in the order they were found, each as a separate
+parameter.  Only if the first character of the short options string
+was a
+.RB ' \- ',
+non\-option parameter output is generated at the place they are found
+in the input (this is not supported if the first format of the
 .B SYNOPSIS
 is used; in that case all preceding occurrences of
-.RB ` \- '
+.RB ' \- '
 and
-.RB ` + '
+.RB ' + '
 are ignored).
 .SH QUOTING
-In compatible mode, whitespace or 'special' characters in arguments or
-non\-option parameters are not handled correctly. As the output is
-fed to the shell script, the script does not know how it is supposed to break
-the output into separate parameters.  To circumvent this
-problem, this implementation offers quoting. The idea is that output
-is generated with quotes around each parameter. When this output is once
-again fed to the shell (usually by a shell
+In compatible mode, whitespace or 'special' characters in arguments
+or non\-option parameters are not handled correctly.  As the output
+is fed to the shell script, the script does not know how it is
+supposed to break the output into separate parameters.  To circumvent
+this problem, this implementation offers quoting.  The idea is that
+output is generated with quotes around each parameter.  When this
+output is once again fed to the shell (usually by a shell
 .B eval
 command), it is split correctly into separate parameters.
-
+.PP
 Quoting is not enabled if the environment variable
 .B GETOPT_COMPATIBLE
 is set, if the first form of the
 .B SYNOPSIS
 is used, or if the option
-.RB ` \-u '
+.RB ' \-u '
 is found.
-
-Different shells use different quoting conventions. You can use the
-.RB ` \-s '
-option to select the shell you are using. The following shells are
+.PP
+Different shells use different quoting conventions.  You can use the
+.RB ' \-s '
+option to select the shell you are using.  The following shells are
 currently supported:
-.RB ` sh ',
-.RB ` bash ',
-.RB ` csh '
+.RB ' sh ',
+.RB ' bash ',
+.RB ' csh '
 and
-.RB ` tcsh '.
-Actually, only two `flavors' are distinguished: sh\-like quoting conventions
-and csh\-like quoting conventions. Chances are that if you use another shell
-script language, one of these flavors can still be used.
-
+.RB ' tcsh '.
+Actually, only two 'flavors' are distinguished: sh\-like quoting
+conventions and csh\-like quoting conventions.  Chances are that if
+you use another shell script language, one of these flavors can still
+be used.
 .SH "SCANNING MODES"
 The first character of the short options string may be a
-.RB ` \- '
+.RB ' \- '
 or a
-.RB ` + '
-to indicate a special scanning mode. If the first calling form
-in the
+.RB ' + '
+to indicate a special scanning mode.  If the first calling form in
+the
 .B SYNOPSIS
 is used they are ignored; the environment variable
 .B POSIXLY_CORRECT
 is still examined, though.
-
+.PP
 If the first character is
-.RB ` + ',
+.RB ' + ',
 or if the environment variable
 .B POSIXLY_CORRECT
 is set, parsing stops as soon as the first non\-option parameter
-(ie. a parameter that does not start with a
-.RB ` \- ')
-is found that
-is not an option argument. The remaining parameters are all interpreted as
-non\-option parameters.
-
+(i.e. a parameter that does not start with a
+.RB ' \- ')
+is found that is not an option argument.  The remaining parameters
+are all interpreted as non\-option parameters.
+.PP
 If the first character is a
-.RB ` \- ',
-non\-option parameters are outputted at the place where they are found; in normal
-operation, they are all collected at the end of output after a
-.RB ` \-\- '
-parameter has been generated. Note that this
-.RB ` \-\- '
-parameter is still generated, but it will always be the last parameter in
-this mode.
+.RB ' \- ',
+non\-option parameters are outputted at the place where they are
+found; in normal operation, they are all collected at the end of
+output after a
+.RB ' \-\- '
+parameter has been generated.  Note that this
+.RB ' \-\- '
+parameter is still generated, but it will always be the last
+parameter in this mode.
 .SH COMPATIBILITY
 This version of
 .BR getopt (1)
-is written to be as compatible as possible to
-other versions. Usually you can just replace them with this version
-without any modifications, and with some advantages.
-
+is written to be as compatible as possible to other versions.
+Usually you can just replace them with this version without any
+modifications, and with some advantages.
+.PP
 If the first character of the first parameter of getopt is not a
-.RB ` \- ',
-getopt goes into compatibility mode. It will interpret its first parameter as
-the string of short options, and all other arguments will be parsed. It
-will still do parameter shuffling (ie. all non\-option parameters are outputted
-at the end), unless the environment variable
+.RB ' \- ',
+.B getopt
+goes into compatibility mode.  It will interpret its first
+parameter as the string of short options, and all other arguments
+will be parsed.  It will still do parameter shuffling (i.e. all
+non\-option parameters are output at the end), unless the
+environment variable
 .B POSIXLY_CORRECT
 is set.
-
+.PP
 The environment variable
 .B GETOPT_COMPATIBLE
 forces
 .B getopt
-into compatibility mode. Setting both this environment variable and
+into compatibility mode.  Setting both this environment variable and
 .B POSIXLY_CORRECT
-offers 100% compatibility for `difficult' programs. Usually, though,
+offers 100% compatibility for 'difficult' programs.  Usually, though,
 neither is needed.
-
+.PP
 In compatibility mode, leading
-.RB ` \- '
+.RB ' \- '
 and
-.RB ` + '
+.RB ' + '
 characters in the short options string are ignored.
 .SH RETURN CODES
 .B getopt
@@ -425,20 +416,18 @@
 Example scripts for (ba)sh and (t)csh are provided with the
 .BR getopt (1)
 distribution, and are optionally installed in
-.B /usr/local/share/getopt
+.BR /usr/local/share/getopt/
 or
-.BR /usr/share/getopt .
-
+.BR /usr/share/getopt/ .
 .SH ENVIRONMENT
 .IP POSIXLY_CORRECT
 This environment variable is examined by the
 .BR getopt (3)
-routines.
-If it is set, parsing stops as soon as a parameter
-is found that is not an option or an option argument. All remaining
+routines.  If it is set, parsing stops as soon as a parameter is
+found that is not an option or an option argument.  All remaining
 parameters are also interpreted as non\-option parameters, regardless
 whether they start with a
-.RB ` \- '.
+.RB ' \- '.
 .IP GETOPT_COMPATIBLE
 Forces
 .B getopt
@@ -446,19 +435,29 @@
 .BR SYNOPSIS .
 .SH BUGS
 .BR getopt (3)
-can parse long options with optional arguments that are given an empty optional
-argument (but can not do this for short options). This
+can parse long options with optional arguments that are given an
+empty optional argument (but can not do this for short options).
+This
 .BR getopt (1)
 treats optional arguments that are empty as if they were not present.
-
+.PP
 The syntax if you do not want any short option variables at all is
 not very intuitive (you have to set them explicitly to the empty
 string).
-
 .SH AUTHOR
-Frodo Looijaard <frodo@frodo.looijaard.name>
+.MT frodo@frodo.looijaard.name
+Frodo Looijaard
+.ME
 .SH "SEE ALSO"
 .BR getopt (3),
 .BR bash (1),
 .BR tcsh (1).
-
+.SH AVAILABILITY
+You can download the latest getopt from
+.UR http://frodo.looijaard.name/project/getopt
+the author's home page
+.UE .
+It is also part of the util-linux package which is available from
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .