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

[David Goodger]

I've added Tibs' suggestion of double-colon syntax for field lists, as
alternative #6 in reStructuredText.txt:

    6. Use double colons::

           Author:: Me
           Version:: 1

       Advantages: unambiguous, obvious? (*almost* RFC822-compliant),
       flexible, similar to syntax already used for literal blocks and
       directives. Disadvantage: no precedent, not quite
       RFC822-compliant, similar to syntax already used for literal
       blocks and directives.

Choosing this as the best of the alternatives, I started working on the
implementation, and realized that the similarity to literal block syntax may
be more significant that I'd thought. In the simple case, it's no problem::

    field name:: field body

But for long field names or field bodies containing multiple body elements,
I'd like to be able to start the field body on another line::

    field name::
        field body

There is a problem if people try to put a blank line between the field name
and body::

    field name::

        field body

The "field body" above *is* a literal block.

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.

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.

Hmm. I'm starting to reconsider my choice of alternative #6 in favour of
alternative #5.

Opinions?

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