[Docutils-develop] new "class" directive behaviour

[David G. <go...@py...>]

I am preparing to implement the "class" directive.  Here is the text
I'm working on for the entry in spec/rst/directives.txt:

 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

The "class" directive sets a "class" attribute value on an element.
For details of the "class" attribute, see `its entry`__ in `The
Docutils Document Tree`_.

There are three possibilities for the directive content:

1. If there is no directive content, the "class" attribute is set on
    the container element immediately enclosing the directive.  Note
    that the "class" directive may appear at any point; it is not
    restricted to the beginning of the container only.  For example,
    this input::

        paragraph text

            .. class:: one

            Block quote contents

    becomes this doctree fragment::

        <paragraph>
            paragraph text
        <block_quote class="one">
            <paragraph>
                Block quote contents

2. If the directive content is a single (possibly container)
    first-level element, the "class" attribute value is set on that
    element.  For example, this input::

        .. class:: two

           paragraph text

    becomes this doctree fragment::

        <paragraph class="two">
            paragraph text

3. If the directive content consists of multiple first-level elements,
    it is interpreted as a block quote and its "class" attribute value
    is set.  For example, this input::

        .. class:: three

           a paragraph

           another paragraph

    becomes this doctree fragment::

        <block_quote class="three">
            <paragraph>
                a paragraph
            <paragraph>
                another paragraph

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

My question: Is case 3 useful enough to keep, or should it be dropped
as confusing?  As shown in the examples above, case 3 can also be
handled by case 1.  Should case 3 be allowed?  Or should multiple
first-level elements be forbidden, and cause an error?  There is
precedent for this: the contents of the "replace" directive are
limited to single paragraphs only.

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv