From: David G. <go...@py...> - 2008-05-16 14:38:42
|
[G. Milde - 2008-05-16 02:33] > On 15.05.08, David Goodger wrote: >> On Thu, May 15, 2008 at 11:54 AM, G. Milde wrote: > >>>>> However, some html writer variants (or options) would care for older >>>>> browsers not understanding Math-ML >>> ... >>>> 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 > ... >> 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 --math-output 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). > > :literal: would explicitly ask for the literal block (or string, > in case of a math role), while > :raw: would pass-through the content and insert like a raw node. Why have "raw" math at all? We already have a "raw" directive. Wouldn't they do exactly the same thing? >> I'd have a single --math-output option with arguments >> (auto-converted to lowercase; typing LaTeX is hard!). > >>> Options can be set: >>> >>> + in the configuration file (generic or writer-dependent) >>> 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 warning and message can be suppressed by explicitly asking > for --math-output literal (or a supported format, of course). Yes. >>> * The writer inserts the content > like a "raw" node content. > > > Should the Transform store the converted math in a raw node? > > + writers will do "the right thing" without changes, > > - information is lost. This might matter if > > a) a transformed doctree is stored for later use, Not a problem. A stored doctree will still have the "pending" node. When processing to a doctree (using docutils.core.publish_doctree), the "null" writer is used. The math Transform will not process the pending node in this case, but leave it for a later processing run (when a concrete Writer is specified). > b) a writer wants to add e.g. some class info to math nodes. The Transform could add a "math" class to the raw node. The alternative is to add a "math" node to Docutils. Problem there is that there are many options for the math output: raw, image, literal block, maybe others. I think a "math" class is sufficient. >>> Example >>> >>> :: >>> >>> a) There is no arguing that :math:`1 + 1 = 2`. >>> >>> b) However it is not clear whether >>> >>> .. math:: >>> >>> 0 * \infty = 3 >>> >>> >>> >>> With the math-latex transformation, a) would become ``$1 + 1 = 2$`` >>> and b) would become:: >>> >>> \[ >>> 0 * \infty = 3 >>> \] >>> >>> (i.e. adding the math switches) > while math-output literal would leave the content unprocessed. > > >>> To prevent e.g. a Math-ML -> LaTeX -> Math-ML 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 double-conversion 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 ``.. math-input-format::`` directive could be used to set the input >>> format 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. > > Then, math-input-format == "auto" could be used to explicitly ask > for auto-determination by the Transform. If we ever have more than one supported math input format, we can revisit this issue. It is premature now, as we have none and someone may be working on one. > BTW: how would I specify the math-input-format in case of a role > (i.e. for inline math)? Again, if this ever becomes necessary, we'll revisit it. Possibilities: * :math-latex:`...`, :math-ml:`...`, etc. * .. math-input-format:: ... followed by :math:`...` > Would it help, if I started writing a specification (in the line of > ref/rst/directives.txt)? Yes. > Should this be a sandbox project (math-directive) or modify the > main documentation? I suggest a branch, since it touches the entire codebase. /branches/mathsupport or /branches/math would be fine. -- David Goodger <http://python.net/~goodger> |