[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