I'm going to jump in here...I've been following this thread, and I am
the author/maintainer of latexwiki. I would like to get my latex code
into docutils as a plugin/extension. Right now latexwiki will only do
latex with stx because it can be placed in-line without too much
trouble. But I would like a reST + LaTeX mode as well, and much code
can be shared. My code generates in-line images for HTML output and
aligns them, and also interfaces with itex for MathML output.
What work is being done on this, and by whom, and is there any test code
I can use as a starting point?
Please forgive my ignorance of the inner workings of docutils...reST is
my weak point in this discussion. ;)
Beni Cherniavsky [cben@...] wrote:
> Let's hash out the extension(s) <-> plugin(s) relationships on math
> support, assuming it'll be done entirely with plugins:
> - We want multiple input formats (LaTeX, asciimath, Lout, etc.). Each
> will have a directive and a role to write it.
Do we really want asciimath or Lout? There is exactly one
well-understood, widely used syntax for math, and that is LaTeX. Lout
appears to have near-zero usage, and I'd be happy to give you a long
list of what is wrong with the asciimath syntax from a mathematical
> - Each format can be translated to multiple formats. There can be
> implementations for a single output format (e.g. LaTeX can be converted to
> MathML or to images for HTML output).
This is not really a "translation" but rather a function of the output.
I don't see how a plugin/extension could possibly be required to know
about all possible output formats. Yes, xml, html, latex, output can be
handled, but what about when someone writes a pdf or svg output target?
Such a "plugin" is fundamentally intertwined with the output module.
> Consulting PEP 258, the output of the directive/role should probably be a
> custom math node, recording the input format either in the node type or as
> an attribute of the node. These custom nodes can be handled by
> writer-dependent transforms, outputting raw nodes.
I think 'math' should be a node.
> A reST document containg latex-math should certainly not indicate that it
> needs a transform that e.g. outputs raw html nodes containing MathML. It
> should only ``.. require latex-math`` and be processable to any format with
> many plugins.
At the input document level, this is an extension of the reST input
syntax, and we can parse it (especially if we require exactly one math
syntax) into the document tree, ignorant of whether the output module
can actually deal with it. The output plugins should therefore be of
math->html4.0 + gif
math->xhtml + png
math->xhtml + gif
math->xml + mathml
e.g. they are output-only and there are many, for each possible type of
output. (and as mentioned before, whether you use png's or gif's should
be configured in a config file or as a command line option that gets
passed to the writer -- not part of the input document)
> But somebody must indicate which transform gets it. For different output
> formats, plugins could not install themselves unless the writer is correct.
Does it do any harm to parse the math input directive into the document
tree? Can the output simply generate a warning: "don't know what to do
with node 'math'...skipping".
> For multiple implementations of the same format, this seems a perfect job
> for a config file.
Or command line options to rest2html. ;)
> BTW, I asked in another mail whether we need plugin names separate from the
> extension they implement. It is now clear to me that we do.
Yes, see the above list of math transforms. I could have the
math->xml+mathml output-plugin installed, but not the others.
> Should each competing plugin should implement the same ``latex-math``
> directive and role with redudant code? Apperently they have to, because
> each should be self-contained and we cannot assume all plugins translate it
> to the same node type. What happens if two plugins implementing the same
> directive are enabled simultaneosly? I think this should signal an error -
> the user must select which one he wants.
I think a 'math' directive should be part of the base docutils, the
plugins should only provide the output side. Or perhaps latex-input and
mathml-output can be two separate plugins, the latter depending on the
Of course if you insist on alternative math input syntaxes then the
input and output plugins must be separated. But again I think latex is
the only reasonable one to implement. Note that computer algebra
systems (the other major source of mathematical content) can all
generate latex output.
This whole discussion is stretching my abstract-discussion abilities. I
need something to hack on to understand it better...
Bob McElrath [Univ. of California at Davis, Department of Physics]
"It's not the people who vote that count. It's the people who count the
votes." -- Joseph Stalin