[Doc-SIG] directives and reversiblity

[David Goodger]

[Tony]
>>> For pragma directives, if the directive is not recognised, I think
>>> that the directive *itself* should be emitted as a <literal> node,
>>> and that it should be flagged as an Error. That gives the user some
>>> hint of why their document looks odd (!).

[David]
>> Yes, this is the plan.

[Garth]
> I think we're better off spitting out the directive tag with some kind
> of "unrecognised" attribute, its argument as the argument attribute, and
> its *contents* as a literal block.

When I said, "this is the plan", this was what I meant. It's the default
case, what the parser does now. To clarify::

    .. a_directive:: arguments
       block

By default, after parsing the above reStructuredText becomes::

    <directive data="arguments" type="a_directive">
        <literal_block>
            block
        </literal_block>
    </directive>

An actually *implemented* directive may do something else, but it should
still be reversible. When we devise a directive that isn't inherently
reversible, we'll revisit this issue.

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