classification
Title: optparse: clarify option concatenation in docs
Type: behavior Stage:
Components: Documentation Versions: Python 3.0, Python 2.6
process
Status: closed Resolution:
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: ajs, georg.brandl, gward
Priority: low Keywords:

Created on 2009-03-24 18:01 by ajs, last changed 2009-07-01 17:29 by ajs. This issue is now closed.

Messages (3)
msg84103 - (view) Author: Aaron Sherman (ajs) Date: 2009-03-24 18:01
First off, I want to be clear that this isn't a request for changes to
functionality, nor for debate over decisions which have already been
made. This is purely a request for correction to mis-statements about
the nature and origins of optparse's handling in its documentation.

This is an edited-down excerpt form the optparse documentation from:

http://docs.python.org/library/optparse.html

"... the traditional Unix syntax is a hyphen (“-“) followed by a single
letter [...] Some other option syntaxes that the world has seen include:
    * a hyphen followed by a few letters, e.g. "-pf" [...]
[...] These option syntaxes are not supported by optparse, and they
never will be. This is deliberate: the first three are non-standard on
any environment[...]"

While, obviously, optparse is free to choose whatever model of option
parsing the developers like, the above text should be removed or
corrected. Traditional Unix command-line usage is detailed in the POSIX
specification's definition of various utilities and the optparse C
function as documented here:

http://www.opengroup.org/onlinepubs/009695399/functions/getopt.html

which lays out this example:

"This code accepts any of the following as equivalent:
cmd -ao arg path path
cmd -a -o arg path path"

Note that the concatenation of single-character arguments is, in fact,
in conformance to the POSIX standard, GNU coding conventions, and Unix
best-practices since at least the mid-1980s. This clearly contradicts
the statement from Python's documentation. For further reference, see:

any Unix or Unix-like system's "man 3 getopt"
http://www.faqs.org/docs/artu/ch10s05.html
http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces
(which refers back to the "POSIX guidelines for the command-line options
of a program")
any Unix or Unix-like system's man pages for a plethora of core
utilities such as rm(1), ls(1), sh(1), cp(1), etc.

A more accurate statement would be:

"optparse has chosen to implement a subset of the GNU coding standard's
command line interface guidelines, allowing for both long and short
options, but not the POSIX-style concatenation of short options."

A rationale for that decision may or may not be included, but I won't
presume to write it since I'm not actually privy to that decision-making
process.
msg89960 - (view) Author: Greg Ward (gward) (Python committer) Date: 2009-07-01 00:43
> This is an edited-down excerpt form the optparse documentation from:
> 
> http://docs.python.org/library/optparse.html
> 
> "... the traditional Unix syntax is a hyphen (“-“) followed by a 
> single letter [...] Some other option syntaxes that the world has seen
include:
>    * a hyphen followed by a few letters, e.g. "-pf" [...]

Note that the second "[...]" expands to "(this is *not* the same as
multiple options merged into a single argument)".  Which means:

1) optparse *does* implement the traditional Unix option-munging that
has been around since at least the mid-1980s
2) the proposed statement "optparse has chosen to implement a subset of
the GNU coding standard's command line interface guidelines, allowing
for both long and short options, but not the POSIX-style concatenation
of short options." is false

Offhand, I don't see a way for the documentation to be any clearer. 
Maybe an example of "-a" and "-b" munged to "-ab"?
msg89993 - (view) Author: Aaron Sherman (ajs) Date: 2009-07-01 17:29
I'm closing this out, as the previous poster was correct: the module
does the right thing, and I misread the documentation. Thanks!
History
Date User Action Args
2009-07-01 17:29:06ajssetstatus: open -> closed

messages: + msg89993
2009-07-01 00:44:53gwardsettitle: optparse -> optparse: clarify option concatenation in docs
2009-07-01 00:43:56gwardsetmessages: + msg89960
2009-06-27 23:57:50ezio.melottisetpriority: low
nosy: + gward
2009-03-24 18:01:13ajscreate