optparse: clarify option concatenation in docs

[ajs]

BPO	5555
Nosy	@birkenfeld

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2009-07-01.17:29:06.582>
created_at = <Date 2009-03-24.18:01:13.944>
labels = ['type-bug', 'docs']
title = 'optparse: clarify option concatenation in docs'
updated_at = <Date 2009-07-01.17:29:06.580>
user = 'https://bugs.python.org/ajs'

bugs.python.org fields:

activity = <Date 2009-07-01.17:29:06.580>
actor = 'ajs'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2009-07-01.17:29:06.582>
closer = 'ajs'
components = ['Documentation']
creation = <Date 2009-03-24.18:01:13.944>
creator = 'ajs'
dependencies = []
files = []
hgrepos = []
issue_num = 5555
keywords = []
message_count = 3.0
messages = ['84103', '89960', '89993']
nosy_count = 3.0
nosy_names = ['gward', 'georg.brandl', 'ajs']
pr_nums = []
priority = 'low'
resolution = None
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue5555'
versions = ['Python 2.6', 'Python 3.0']

[ajs]

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.

[gward]

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"?

[ajs]

I'm closing this out, as the previous poster was correct: the module
does the right thing, and I misread the documentation. Thanks!