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

[David Goodger]

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

I see from quick_reST.html 0.3 that you assumed the ':field-name:'
syntax would win out. You assumed correctly. Over the weekend, I
implemented field lists, option lists, and tables (temporarily, as
literal blocks; a full implementation will be a Significant Effort).

(Implementing option lists was a bit of a pain, because of a
time-consuming red herring: I'd made a simple logic error but failed
to track it down, thinking it was a regex problem instead. However,
implementing field lists was a pleasure. I made some test cases,
worked out the regex, put in the transition code for the first field
[copied & modified from bullet lists], and made a new state for fields
2 and up. This all took about a half hour. Ran it. Worked, first time, no
errors. "Cool!" I said, with a big grin on my face. Thank Guido for
Python!)

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

Agreed. For this purpose, I'll include an 'rfc822' syntax in the
parser, which is normally disabled but can be enabled by email & PEP
modes.

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