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

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> By "by other means", do you mean such as the example you gave, below?
> I think that option lists are common enough (some form is in most
> every command-line program I've ever written), and I'd like to keep
> them. Unless there's something *problematic* about parsing them, I
> don't see the problem having them available. Of course, anyone who
> wants to use alternatives (tables, bullet lists, definition lists), is
> free to do so.

Hmm. I think that if you can't use descriptive lists to represent option
lists naturally, then that is a signal that descriptive lists are wrong.
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.

[Of course, below I take two examples and stand on top of them. Oh
well.]

> >     Alternatively, try defining a new syntax for "tabbed tables"
> >     (something like the facilities available in LaTeX) - something
> >     that looks like::
> >
> >         .. -a        :: Output all
> >         .. -b        :: Output both (this description
> >                       is quite long)
>
> Excuse me, but, ugh.

Well, yes, but it's a quickly typed in first suggestion, and anyway
those colons should have been dots (typo).

So, the examples we have are things like::

    -a            Output them all
    -b or -both   Output just two

and things like::

    first  -- the first argument
    second -- the second argument

and we need to make sure that they read well in the "raw text".

*I* would contend that the first can be phrased like the second and
still look OK - that is, as::

    -a          -- Output them all
    -b or -both -- Output just two

is that contentious? (i.e., do we agree that one unified form would
serve for both, whatever that form might be).

I *still* don't know the solution for descriptive lists, but I do feel
that::

    name
        description

is one of the worse ways of presenting them, in generality - although it
does have its uses sometimes. But its use of screen estate vertically is
Not a Good Thing.

I do agree (by now) that ``--`` is sensible within text as well - but
that doesn't mean we have to discard its use for descriptive lists
(where it is fairly natural) if we can discern (reasonably)
unambiguously that that is what we are doing.

Hmm - a strawman (in itself a bit yucky proposal) for such
disambiguation...

Let us consider what happens if a block (paragraph) starts with a single
"word" followed by a double hyphen, where a "word" is one of a word (!),
or a single inline markup entity. So we would have::

    word -- the simple case

    *emphasised text* -- counts as one "word"

    `some non-emphasised text` -- some grouped text

    `even a link`_ -- 'cos it's still one "word"

It *does* seem to require blank lines to be unambigous, but by the "a
list has to have at least two elements rule" (which I think you give for
enumerated lists) I think this *could* work - whether it is too horrible
for words is another matter...

Hmm - I'm still not happy with that. More thought needed...

On the other hand, for the case of parameter lists which are *mainly*
meant for interpretation by the command line user, what's wrong with
just allowing a user who wants that to do::

    Usage::

        fred.py  <switches>

        -a           all
        -b or -both  just the two

Does what is primarily wanted, and doesn't require an extra construct...

Tibs (sure he could argue things better, unsure of where he's going, but
uncomfortable with where we started...)

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