Re: [Structuredtext-develop] option lists

[David G. <go...@us...>]

Alan Jaffray wrote:
> I don't see the value in the "dashes are implicit" behavior.  It loses
> the ability to document non-GNU-style option lists.  What does it gain?

Once an option has been parsed and encoded in the doctree, the thing we're
most interested in is the option name, not the punctuation that goes along
with it. If we keep the hyphens/slashes in the text, we'll have to reparse
whenever we want to extract the name. A trivial operation, perhaps, but
unnecessary. Allowing for variant syntaxes makes it less trivial.

> We don't want to spend complexity dealing with every weird option-parsing
> behavior out there, but we don't have to.  Just leave the dashes in, and
> people can use option lists no matter what style of parsing they use - or
> what style of parsing is used by whatever they're documenting, it's not
> necessarily a choice that the document author can make.

As I've designed the DTD, there are three types of option, the punctuation
for each is implicit and invariant::

    <!ELEMENT option
        ((short_option | long_option | vms_option), option_argument?)>

In order to support nonstandard options (i.e. options which don't conform to
the above), I'd rather introduce a fourth type, perhaps
``nonstandard_option`` which either keeps the punctuation in the text or in
an attribute: either ``<nonstandard_option>-long-option-with-one-hypen</>``
or ``<nonstandard_option marker="-">long-option-with-one-hyphen</>``. Is it
necessary?

> There's a huge amount of existing software that uses single-dash long
> options.

I wonder if any of that is a target audience for reStructuredText? ;-)

There's also a lot of existing software that uses "+option" and other
variants. I don't see the need for the reStructuredText parser to support
them, but the Docutils DTD could, via "nonstandard_option" above.

> In the DOS world, using a single slash before both short and
> long options is nearly universal.

Already supported; no distinction is made between long & short vms_options.

still-haven't-read-perl-getopt::long-ly yr's --David

-- 
David Goodger    go...@us...    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net