NAME

       "LaTeXML::Post::MathML" - Post-Processing modules for converting math to MathML.

SYNOPSIS

       "LaTeXML::Post::MathML" is the abstract base class for the MathML Postprocessor;
       "LaTeXML::Post::MathML::Presentation" and "LaTeXML::Post::MathML::Content" convert XMath
       to either Presentation or Content MathML, or with that format as the principle branch for
       Parallel markup.

DESCRIPTION

       The conversion is carried out primarly by a tree walk of the "XMath" expression;
       appropriate handlers are selected and called depending on the operators and forms
       encountered.  Handlers can be defined on applications of operators, or on tokens; when a
       token is applied, it's application handler takes precedence over it's token handler

   "DefMathML($key,$presentation,$content);"
       Defines presentation and content handlers for $key.  $key is of the form
       "TYPE:ROLE:MEANING", where

         TYPE    : is one either C<Token> or C<Apply> (or C<Hint> ?)
         ROLE    : is a grammatical role (on XMath tokens)
         MEANING : is the meaning attribute (on XMath tokens)

       Any of these can be "?" to match any role or meaning; matches of both are preferred, then
       match of meaning or role, or neither.

       The subroutine handlers for presentation and content are given by $presentation and
       $content, respectively.  Either can be "undef", in which case some other matching handler
       will be invoked.

       For "Token" handlers, the arguments passed are the token node; for "Apply" handler, the
       arguments passed are the operator node and any arguments.

       However, it looks like some "TOKEN" handlers are being defined to take
       "$content,%attributes" being the string content of the token, and the token's attributes!

   Presentation Conversion Utilties
       "$mmlpost->pmml_top($node,$style);"
           This is the top-level converter applied to an "XMath" node.  It establishes a local
           context for font, style, size, etc.  It generally does the bulk of the work for a
           PresentationMathML's "translateNode", although the latter wraps the actual "m:math"
           element around it.  ("style" is display or text).

       "pmml($node)", "pmml_smaller($node)", "pmml_scriptsizsize($node)"
           Converts the "XMath" $node to Presentation MathML.  The latter two are used when the
           context calls for smaller (eg. fraction parts) or scriptsize (eg sub or superscript)
           size or style, so that the size encoded within $node will be properly accounted for.

       "pmml_mi($node,%attributes)", "pmml_mn($node,%attributes)", "pmml_mo($node,%attributes)"
           These are "Token" handlers, to create "m:mi", "m:mn" and "m:mo" elements,
           respectively.  When called as a handler, they will be supplied only with an "XMath"
           node (typically an "XMTok"). For convenient reuse, these functions may also be called
           on a 'virtual' token: with $node being a string (that would have been the text content
           of the "XMTok"), and the %attributes that would have been the token's attributes.

       "pmml_infix($op,@args)", "pmml_script($op,@args)", "pmml_bigop($op,@args)"
           These are "Apply" handlers, for handling general infix, sub or superscript, or bigop
           (eg. summations) constructs.  They are called with the operator token, followed by the
           arguments; all are "XMath" elements.

       "pmml_row(@items)"
           This wraps an "m:mrow" around the already converted @items if need; That is, if there
           is only a single item it is returned without the "m:mrow".

       "pmml_unrow($pmml)"
           This perverse utility takes something that has already been converted to Presentation
           MathML.  If the argument is an "m:mrow", it returns a list of the mathml elements
           within that row, otherwise it returns a list containing the single element $pmml.

       "pmml_parenthesize($item,$open,$close)"
           This utility parenthesizes the (already converted MathML) $item with the string
           delimiters $open and $close.  These are converted to an "m:mrow" with "m:mo" for the
           fences, unless the "usemfenced" switch is set, in which case "m:mfenced" is used.

       "pmml_punctuate($separators,@items) "
           This utility creates an "m:mrow" by interjecting the punctuation between suceessive
           items in the list of already converted @items.  If there are more than one character
           in $separators the first is used between the first pair, the next between the next
           pair; if the separators is exhausted, the last is repeated between remaining pairs.
           $separators defaults to (repeated) comma.

   Content Conversion Utilties
       "$mmlpost-"cmml_top($node); >
           This is the top-level converter applied to an "XMath" node.  It establishes a local
           context for font, style, size, etc (were it needed).  It generally does the bulk of
           the work for a ContentMathML's "translateNode", although the latter wraps the actual
           "m:math" element around it.

       "cmml($node)"
           Converts the "XMath" $node to Content MathML.

       "cmml_leaf($token)"
           Converts the "XMath" token to an "m:ci", "m:cn" or "m:csymbol", under appropriate
           circumstances.

       "cmml_decoratedSymbol($item)"
           Similar to "cmml_leaf", but used when an operator is itself, apparently, an
           application.  This converts $item to Presentation MathML to use for the content of the
           "m:ci".

       "cmml_not($arg)"
           Construct the not of the argument $arg.

       "cmml_synth_not($op,@args)"
           Synthesize an operator by applying "m:not" to another operator ($op) applied to its
           @args ("XMath" elements that will be converted to Content MathML).  This is useful to
           define a handler for, eg., c<not-approximately-equals> in terms of c<m:approx>.

       "cmml_synth_complement($op,@args)"
           Synthesize an operator by applying a complementary operator ($op) to the reverse of
           its @args ("XMath" elements that will be converted to Content MathML).  This is useful
           to define a handler for, eg. "superset-of-or-equals" using "m:subset".

       "cmml_or_compose($operators,@args)"
           Synthesize an operator that stands for the "or" of several other operators (eg.
           c<less-than-or-similar-to-or-approximately-equals>) by composing it of the "m:or" of
           applying each of "m:less" and "m:approx" to the arguments.  The first operator is
           applied to the converted arguments, while the rest are applied to "m:share" elements
           referring to the previous ones.

       "cmml_share($node)"
           Converts the "XMath" $node to Content MathML, after assuring that it has an id, so
           that it can be shared.

       "cmml_shared($node)"
           Generates a "m:share" element referting to $node, which should have an id (such as
           after calling "cmml_share").

Math Processors, Generally.

       We should probably formalize the idea of a Math Processor as an abstract class, but let
       this description provide a starting overview.  A MathProcessor follows the API of
       "LaTeXML::Post" processors, by handling "process", which invokes "processNode" on all
       "Math" nodes; That latter inserts the result of either "translateNode" or
       "translateParallel", applied to the "XMath" representation, into the "Math" node.

       Parallel translation is done whenever additional MathProcessors have been specified, via
       the "setParallel" method; these are simply other MathProcessors following the same API.