[Doc-SIG] directives and reversiblity

David Goodger dgoodger@bigfoot.com
Fri, 10 Aug 2001 17:52:07 -0400

>>> 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 (!).

>> Yes, this is the plan.

> 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

By default, after parsing the above reStructuredText becomes::

    <directive data="arguments" type="a_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