[Doc-SIG] reStructuredText Field Lists: Deciding on Syntax

[Tony J Ibbs (Tibs)]

Hmm - I had actually realised that the "missing blank line" problem
existed (I think I mentioned it) - to me it wasn't a problem (well,
maybe I'm in denial). But...

David Goodger wrote:
> The choices are:
>
> 1. Use syntax alternative 6, but accept the limitation that
>    there may not be a blank line between a field name and
>    field body.

I could happily live with this myself, on tacky pragmatic grounds, since
I like the look of this alternative more than that of the other. BUT my
"standards head" says that it is rather confusing to allow the "::" to
be overloaded like that, especially since one already has to remember
varieties of "::" use (e.g., preceded by space, etc.). Of course, in
this instance I don't want to *listen* to that head...

> 2. Use a different syntax for field lists, one that avoids the
>    similarities with literal blocks. Syntax alternative #5
>    (``:field name: body``) would be my next choice. It has the
>    advantage of being visually distinctive up-front, bracketing
>    the field name. By beginning with a colon, the field name
>    also looks more like a list item marker, making a field list
>    look like a list.

My initial response to this is, as ever, yuck. On the other hand, I find
it difficult to "look at it for the first time" - I'm too entrenched in
what I want to type from older arguments.

If this will allow us to have field lists that contain content - for
instance::

    :Some-name:

        And more than one...

        ...paragraph.

then I'd be willing to vote +0 on it. I think I'd have to vote -0
(argh - don't like doing that) on option 6.

I would, however, then vote that email and PEP modes have a
specialisation for the first block, which allows one to do "traditional"
email headers, without requiring the leading colons.

Tibs

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