Screenshot instructions:
Windows
Mac
Red Hat Linux
Ubuntu
Click URL instructions:
Rightclick on ad, choose "Copy Link", then paste here →
(This may not be possible with some types of ads)
From: David Goodger <goodger@py...>  20080516 13:20:23

[Günter replied to me offlist by accident. Here's my reply, quoting with permission.] On Thu, May 15, 2008 at 11:54 AM, G. Milde <milde@...> wrote: > On 15.05.08, David Goodger wrote: >> [G. Milde  20080515 05:42] >>> We should care to differentiate between *input*, *internal*, and *output* >>> format. > >>> The basic question is which internal format should docutils >>> use. > >> The math input data should be stored in a "pending" node in the original >> input format. The Transform will convert that to something compatible >> with the target Writer. The internal format for math in the Docutils >> doctree is the input format (prior to the Transform running), and the >> output format (after the Transform runs). > >> I have no interest in making a generic mathdoctree; it would double the >> size of the doctree spec. As far as Docutils is concerned, math is a >> blob. And there is no reason to do a double conversion; it's imperfect. >> Let's just use a standard format internally: the input format, LaTeX. > > I see the light. This perspective makes everything so much easier. Great! > (But I would like to see other input formats too (at a later stage).) One challenge at a time. >>> However, some html writer variants (or options) would care for older >>> browsers not understanding MathML > ... >> I want the Transform to take care of these cases, not the Writers. The >> option will affect the Transform. > > So a realisation of this concept could be: > > * Define a "math" directive (rst syntax ``.. math::``) and role (rst > syntax :math:`2+3`) > > * The Parser stores the content in a pending "math" doctree node > (without parsing the content). > > * The Transform converts the content depending on configuration > settings (options), e.g. ``mathpass``, ``mathlatex``, ``mathml``, > ``mathpng``, ... That's possible, but I'd only do it as an override. The default would be as follows. Each Writer specifies a list of acceptable formats (initially for math, but it could be extended for other objects, like images). These would be in order of preference. For example, the HTML Writer might specify ["mathml", "png", "jpeg", "ascii"]. If the math output format is not specified explicitly (via the mathoutput option), the Transform would query the Writer for its preferences, and choose the first that matches its capability (with a fallback default of a literal block containing the math input). > We would have to decide on a set of options (like above) or one keyword > (say ``mathformat``) with a set of string values ("", "LaTeX", > "MathML", "PNG", ...) I'd have a single mathoutput option with arguments (autoconverted to lowercase; typing LaTeX is hard!). > Options can be set: > > * in the configuration file (generic or writerdependent) > with system defaults in the standard conf file. > > * from command line options > > * If the Transform cannot convert to the desired format, a warning is > issued and the content is put in a literal block (eventually > preceded by a helpfull message). > > * The writer inserts the content verbatim (but without wrapping it in a > verbatim container). Yes, that works. > Example > > :: > > a) There is no arguing that :math:`1 + 1 = 2`. > > b) However it is not clear whether > > .. math:: > > 0 * \infty = 3 > > > > With the mathlatex transformation, a) would become ``$1 + 1 = 2$`` > and b) would become:: > > \[ > 0 * \infty = 3 > \] > > (i.e. adding the math switches) while mathpass would leave the content > unprocessed. Not sure what you mean by mathpass. Passthrough, and format as a literal block / inline literal? >> No double conversion, please. > > To prevent e.g. a MathML > LaTeX > MathML conversion, > an option to the "math" directive could specify the input format. If multiple math input formats are supported, such an option would be necessary. But no doubleconversion would ever have to take place. Whatever the math input format is, that's what would be stored in the doctree for the Transform to process. > A ``.. mathinputformat::`` directive could be used to set the input > format for the whole document. Sure. Or for the whole document, from that point forward, until another such directive. > If not input format is specified, it could be guessed by the > Transform (e.g. telling MathML from LaTeX should be easy) Better to require that the format be specified. Explicit is better than implicit.  David Goodger <http://python.net/~goodger>; 