[Doc-SIG] Field lists and label blocks

Thu, 09 Aug 2001 23:07:15 -0400

Tony J Ibbs (Tibs) <tony@lsl.co.uk> wrote on 2001-08-09 5:31 AM:
> Markup versus meaning
> =====================
> Almost all of reST is dealing with markup - presentation.

I would disagree. It deals with extracting structure from
presentation. Admittedly, the amount of structure gleanable from
plaintext is meager, and its level is quite low for the most part.
Field lists are potentially higher-level structure.

(I thought of another name for field lists: "label lists"; whaddya
think? Oh, I see that Tony already had "label blocks"; similar.)

> But field lists are a different kettle of fish. They're for a
> different purpose, and require a separate justification.

I don't see why they should be excluded.

> All of the examples show the <body> as being confined to the rest of
> the line - that is, no line breaks allowed.

That's an accident. I actually intend::

    <name>: <body>

            The <body> consists of
            one or more body elements>

            Including nested field lists!

One-liners are merely a degenerate form. Even in email RFC822 headers,
you often end up with multi-line (but single "paragraph") bodies.

Indentation is all that's needed to determine if a field list item is
a one-liner or multi-liner. In some modes' contexts, such as email
headers, even indentation isn't necessary.

> Label blocks
> ============
...
> Label blocks have some implementation details, though:
> 
> 1. A paragraph is only a label block if <name> is found
>    in a dictionary of valid names, otherwise it's just
>    a normal paragraph (maybe with a Warning being issued).

When working on the concept for field lists in reStructuredText, I
thought about this as well. I rejected it as too limiting (somebody is
always going to want a new field name). It's feasible in limited
contexts, such as bibliographic fields, PEP headers, or email headers.
And even in those contexts, unknown fields will not trigger an error,
but will be shown as a simple field list instead.

> 2. The "definition" associated with a name indicates
>    whether <body> is restricted to the rest-of-line,
>    or whether it may be longer (technically, whether
>    its DOM tree node may have children). Specific
>    examples would be::
> 
>         Author: Guido van Rossum
> 
>         Authors:
>             * Guido van Rossum
>             * Tim Peters
> 
> 3. The "definition" also indicates which forms of DOM
>    node the children may be - for instance, bullet list,
>    paragraph, etc.

We may put this kind of checking ability into the DPS, or perhaps the
output formatter, but the parser needn't know about it.

> In an reST context, I would replace the single colon by two,

Added as syntax alternative 6. It's got potential.

> and I would add a rule that if children are allowed and present,
> then a blank line is not allowed after the <name> - i.e., as in
> cells within a table, the <name> line prepares one for a new block.

I don't follow. If this still applies after reading my explanation
of body elements in field list item bodies, above, please explain.

> When do we want these ideas?
> ============================
> Field lists and label blocks are both about being able to extract
> *meaning* from a document stream, rather than just presentation.
> 
> I would contend that they do not, thus, belong in the base document
> format at all, but in the particular modes where they are useful.
> Note that making this decision means we can get reST *itself* out
> the door faster, that we get a simpler reST document (a Good Thing),
> and that the decisions about how to do such things can be
> application dependent, and thus easier to design and reach agreement
> on.

Implementing the *interpretation* of field lists may be tricky, but
their *parsing* is not a big deal (once the syntax is decided on; I
like either #5 [":field: body"] or the new #6 ["field:: body"]).

The interpretation of field lists will not be done by the parser
anyhow. It's the DPS itself, or an output formatter, or an
intermediate transformation component, that will do the
interpretation.

(BTW, the introduction of the concept of "modes" has helped me to gel
some ideas I had about the DPS framework. We need mode-specific
modules as middleware between the input parser and output formatters.)

> Why field lists aren't enough
> =============================

I think this is addressed by my explanation above of multiple body
elements in each field list item?

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