reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes"

[Tony J Ibbs (Tibs)]

Garth T Kidd wrote:
> I suspect I'm currently leaning in the direction of parser-loaded
> directives having the ability to "hook" the parser to alter the way it
> interprets the input [examples]_, but not affecting the composition of
> the parser output in such a way that would make it impossible for an
> `OOB` reST engine to reverse-engineer from the XML or node tree some
> valid reST input that would create the same output.

I'm a bit worried that directives are being used for two different
purposes (and I *think* they may be getting confused).

The first, and traditional (by its name) purpose is to act as a pragma
that changes the behaviour of the text (or maybe just the text after
that point in the document stream). An example would be::

    .. mode:: HTML

which is attempting to enable the various extensions needed to prepare
an HTML document.

The second usage is as a way of adding new "commands" to reST - for
instance::

    .. newline::
    .. section:: Garth's section title

*One* of the uses of the pragma directives is to load definitions for
the command directives (the other example of a use for a pragma
directive is the "enable lazy indentation" one).

I think we need to distinguish these two usages - perhaps the names I've
used help.

For command directives, one clearly looks up the directive name to see
if there is a method defined for it. If there is, one executes that
method on the directive's body, and inserts the resultant data as a node
with its tag taken from the directive name. If there is not, one emits
the directive name and body as a <literal> - I think that is what David
proposes? Possibly flagged with a Warning. That works well in practise,
I think.

For instance::

    .. fred:: Some {funny} text.

might generate::

    <fred>
        <text>Some </text>
        <humour>funny</humour>
        <text> text.</text>
    </fred>

if recognised, but::

    <warning>
        <message>Unrecognised directive "fred"</message>
        <literal>Some {funny} text.</literal>
    </warning>

(erm - I haven't even *tried* to write sensible XML for those - but I
hope the idea is evident).

In the second case, regenerating the original text is clearly possible.

In the first, it's more of a problem, since we don't know how to reverse
map <humour>. Either we say "tough, if the directive understander loaded
didn't have a reverse mechanism, we can't do it", or we require people
to always provide a reverse engine. I'd opt for the optional route,
myself - if people are writing their own directive understanders, then
we can't really mandate that they should provide the reverse mechanism.

It does suggest to me that pragma directives must insert a node in the
DOM tree, though, so that one can *know* what engines one needs to use
to regenerate reST.

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

> .. _OOB: Out of the box, ie without any directives loaded. Now, how on
>    Earth do we render this link target, or any other non-URI
> link target
>    that hasn't been rescued by some directive? I'm using it as a
>    footnote. Hmmm.

Presumably one should not lose the footnote - it is still text, after
all. Emit it with a warning that it is not referenced?

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)