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

Garth T Kidd
Tue, 7 Aug 2001 15:32:18 +1000

> > David, it just occurred to me that [most? all?] directives
> > should simply be parsed and embedded in the output for the
> > application to handle.
> Depends on the directive. [...] For example, I'm thinking of a
> set of "admonition" directives. You could write::
>     .. Caution:: Mad scientist at work!

Excellent example.

Implementation wise, I'm thinking the application hands the parser a
dictionary of directives mapping directive identifiers to functions (or
otherwise callable objects). The parser calls the function with the
argument string (currently ``::`` to end of line), the block it just
pulled out of the text, and the parent node. The function returns either
a node or None. Finally, the parser either inserts the new node or a
directive element.

A short-cut: if the directive identifier maps to a string, the parser
parses the contents and inserts an element with the string as the
element name. If the directive identifier maps to None, use the
directive identifier as the element name. I can see that being handy for

An extension: the application might instead hand the parser a function
which takes as arguments the directive type, arguments, and block, and
return either a node, None, or a string as per the short-cut above.
That'd support the [cheeky] "cheat and use userids as directive types
for annotations" idea nicely. It'd also let me do pull quotes in two
lines of code (!).

That said, I still have no idea how the ~2500-3000 lines of parser code
work, so maybe that's the World's Most Broken Idea, in which case deem
requests for thrown lines included. :)

> For directives which require further processing later on, the
> "directive" element could be used; it which can contain any body
> elements. This is how unrecognized directives will be handled.

Currently, directives always contain literal blocks. Are you planning to
change that?