Re: [Structuredtext-develop] option lists

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

Thanks for the counter-examples. Always useful in disproving a
theory. The practical trumps the ideal. ;-)

[Tony]
> I'm not entirely sure that we should be aiming to support every
> weird and wonderful command line that someone can come up with

I suppose that if we don't at least attempt to cover the more common
variants, there will be no end to the debate. If we want successful
option lists, and not simply revert to literal blocks, we ought to
support actual usage.

[Alan]
> In my mind, the name of a command line option is "-a" or "--force",
> not "a" or "force".  Likewise for "-geom" (not "geom" X-style),
> "/release" (not "release" DOS-style), or "co" (not "co" cvs-style).
> Hyphens never get stripped, and there's no parsing involved, let
> alone reparsing.

Fair enough. Since supporting every conceivable variant would be
difficult, it's reasonable to simply support a single abstract
"option" and leave the details in the element's content. (If you
check the CVS history, you'll see that that's how it was at one
point, before I "fixed" it.)

[David]
> 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`` ... Is it necessary?

[Alan]
> I think it's at least desirable; but then, once it's created, I
> don't understand the need for the other options.  When does one need
> to know whether a given option is short, long, trapezoidal, or
> whatever?

I suppose from a document's point of view, we don't. The DPS/Docutils
is a documentation system. If there's ever an application that does
need to know, it can figure it out easily enough. Not our job.

Rethinking the whole thing, I realize that I'd been trying to come up
with a perfect model for option lists, but in order to achieve it I
had to limit their scope. The role of a documentation system is to
allow authors sufficient flexibility to describe their subject, not
for the tool to prescribe any restrictive forms, and certainly not to
proscribe. A successful documentation system is rich, flexible, and
doesn't get in the way. So let's loosen up the model.

Here's my idea for a new model to replace the current one (irrelevant
attribute lists omitted)::

    <!ELEMENT option_list (option_list_item+)>
    
    <!ELEMENT option_list_item (option_group, description)>
    
    <!ELEMENT option_group (option, option_argument*)+>
    
    <!ELEMENT option (#PCDATA)>
    
    <!ELEMENT option_argument (#PCDATA)>
    <!ATTLIST option_argument
        %basic.atts;
        delimiter  CDATA    #IMPLIED>
    
    <!ELEMENT description (%body.elements;)+>

There are no longer separate option types for long/short/vms options.
The "delimiter" attribute on "option_argument" contains the delimiter
(typically either " " or "=") between the "option" and the
"option_argument". If there are multiple option arguments [#]_,
"delimiter" contains the delimiter between them (typically either " "
or ",").

.. [#] I don't know if I'll support multiple option arguments in the
   parser, but the DTD ought to.

[Tony]
> Thinking-out-loud-again,

That's what mailing lists are for. :-) Please continue.

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

[Alan] 
> I didn't expect you would.  I've never managed to make it all the
> way through myself. :-)

Scanned it today. Not too hairy, was expecting worse. Perhaps my bias
is showing, ex-Perler that I am. Luckily for me, Python was waiting
when I gave up after only two and a half years of Perl. Could've been
worse.

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