[Doc-SIG] Re: reST: Option lists and descriptive lists

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> Rather than trying to shoehorn option lists into
> definition/descriptive lists, I'm trying to provide for them in a
> natural way. Lists of command-line options, such as found in man pages
> and '--help' usage output, are not the same as definition lists.

Well, we obviously differ. But, on the other hand, *you* are the one
with final decisions, and I'm the one who has to come up with a
convincing argument.

> > At which point we need to stand back and think again. And the way to
> > do *that* is to take lots of examples and to look for commonality.
>
> That's what I have done. I've looked at a lot of man pages and
> '--help' usage output, and I see option lists as described in the
> spec.

I'm still uncomfortable with the Unix specificity of that.

So, trying to worry in a more specific manner, you currently propose::

    -a    Output all
    -b    Output both (this description is
          quite long)

Would you also allow::

    /a    Output all
    /b    Output both (this description is
          quite long)

which is more natural on Windows and VMS? (if I'm producing software
that *will* only be used on Windows, it doesn't make sense to stick with
Unix conventions for switches).

On my worriting about descriptive lists:
> So come up with a better, unambiguous alternative, and fame & fortune
> will be yours. (Well, maybe not fortune. Not much fame either, I'm
> afraid. A bit of egoboo is all we open-sourcers can expect.)

Heh, don't denigrate egoboo - people run N-thousand people conventions
just for the egoboo of it!

> The option list construct is convenient and unambiguous,
> and (AFAICT, not having implemented it yet) ought to
> work well. Why all the resistance?

I wish I could explain - if I could it would probably encapsulate the
solution(!) - but it undoubtedly stems back to my discomfort with
descriptive lists, and *that* ties back to the "naturalness" of Guido's
example. Hmm - maybe *I'm* overgeneralising - would we accept a Python
extension that allowed me to do, for instance::

    :Arguments:
        `arg1` -- not a very informative example.
        `arg2` -- and it is *very* restricted in what
                  goes at the front - it *must* be a
                  Python thingy in quotes.

since it is the arguments case that particularly bugs me? Is *that*
worth it? (maybe not).

On the other hand, given three choices:

1. Get a working reST/DPS with descriptive lists
   as they are now.
2. Get a working reST/DPS without descriptive lists
   at all.
3. Continue arguing about this forever.

option 3 is the only one I *wouldn't* choose.

Tibs (colour me happy except for some minor polka dots that I can ignore
if I really have to)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)