Re: [Docutils-develop] Option fields...

Adam Chodorowski wrote:
> The problem for reST is the fact that you don't *need* to have
> modifiers on the options, so it's very hard to distinguish. A
> typical description of the options in ASCII text looks like:
> 
> FILE/M/A    Two or more files to be joined.
> AS=TO/K/A    The destination file.

Given your much longer description, I'm now even less optimistic.  In
fact, I'd have to say that the syntax is not suitable for specialized
markup like option lists.

> Hmmm... How about this syntax:
> 
> FILE/M/A    : Two or more files to be joined.
> AS=TO/K/A    : The destination file.

I seem to recall...  Yes, here it is.  About a year ago on Doc-SIG,
Tony Ibbs and I were discussing option lists and definition lists, and
he proposed a similar syntax.  But I didn't go for it then, and I'm
not going for it now, sorry.  The reason being, option lists are
modeled after the --help output of Unixish command-line programs.

Also, in the case of this specific syntax, a multi-line option
description would make it look too much like a definition list::

    OPTION/A  : A multi-line option
                description.

    term : classifier
        definition

> I guess I should use definitionlists then, but it would be nicer
> with "real" option lists. :)

"Real" option lists are simply two-column lists, and are only possible
because of the distinctive option prefixes.  You don't have that
advantage, so you might want to look into alternatives, like the
existing definition list or table syntax, the proposed simple table
syntax (see http://docutils.sf.net/spec/rst/problems.html#tables,
alternatives 3-6), or the proposed "columns" directive (see
http://docutils.sf.net/spec/notes#body-columns).

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/