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

David Goodger dgoodger@bigfoot.com
Thu, 09 Aug 2001 23:07:13 -0400


Tony J Ibbs (Tibs) <tony@lsl.co.uk> wrote on 2001-08-08 5:39 AM:
> 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.

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.

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

Sure, one unified form could be used for both options and arguments,
but that's not what *is* being used. If there's a perfectly good and
unambiguous model out there, why not use it?

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

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

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

I don't see how we can.

[example omitted]
> 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

Please note that I've removed the "two or more elements" rule. If it
looks like an enumerated list item, it is one.

> 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

Nothing wrong with it. And until option lists (in whatever form) are
implemented, that's all that *is* available. The option list construct
is convenient and unambiguous, and (AFAICT, not having implemented it
yet) ought to work well. Why all the resistance?

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