structuredtext-develop

[Structuredtext-develop] option lists

[Alan J. <ja...@po...>]

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?

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.

There's a huge amount of existing software that uses single-dash long
options.  In the DOS world, using a single slash before both short and
long options is nearly universal.

Alan

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

Re: [Structuredtext-develop] option lists

[Alan J. <ja...@po...>]

On Sat, 23 Feb 2002, David Goodger wrote:
> 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.

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.

Of course, that doesn't necessarily mean that the reStructuredText
parser is going to recognize "#$&foo" ("foo" martian-style) as part
of an option list. :)

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

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?

> > 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? ;-)

Possibly.  There's also a lot of new software that uses single-dash
long options.  Any new X program ought to support -geometry and -font.
There's also the situation of someone writing internal docs describing
a program for their users.

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

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

Alan

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