NAME

       "LaTeXML::Definition"  - Control sequence definitions.

DESCRIPTION

       These represent the various executables corresponding to control sequences.  See
       LaTeXML::Package for the most convenient means to create them.

       "LaTeXML::Expandable"
           represents macros and other expandable control sequences that are carried out in the
           Gullet during expansion. The results of invoking an "LaTeXML::Expandable" should be a
           list of "LaTeXML::Token"s.

       "LaTeXML::Primitive"
           represents primitive control sequences that are primarily carried out for side effect
           during digestion in the LaTeXML::Stomach and for changing the LaTeXML::State.  The
           results of invoking a "LaTeXML::Primitive", if any, should be a list of digested items
           ("LaTeXML::Box", "LaTeXML::List" or "LaTeXML::Whatsit").

       "LaTeXML::Register"
           is set up as a speciallized primitive with a getter and setter to access and store
           values in the Stomach.

       "LaTeXML::CharDef"
           represents a further specialized Register for chardef.

       "LaTeXML::Constructor"
           represents control sequences that contribute arbitrary XML fragments to the document
           tree.  During digestion, a "LaTeXML::Constuctor" records the arguments used in the
           invokation to produce a LaTeXML::Whatsit.  The resulting LaTeXML::Whatsit (usually)
           generates an XML document fragment when absorbed by an instance of LaTeXML::Document.
           Additionally, a "LaTeXML::Constructor" may have beforeDigest and afterDigest daemons
           defined which are executed for side effect, or for adding additional boxes to the
           output.

       More documentation needed, but see LaTeXML::Package for the main user access to these.

   Methods in general
       "$token = $defn->getCS;"
           Returns the (main) token that is bound to this definition.

       "$string = $defn->getCSName;"
           Returns the string form of the token bound to this definition, taking into account any
           alias for this definition.

       "$defn->readArguments($gullet);"
           Reads the arguments for this $defn from the $gullet, returning a list of
           LaTeXML::Tokens.

       "$parameters = $defn->getParameters;"
           Return the "LaTeXML::Parameters" object representing the formal parameters of the
           definition.

       "@tokens = $defn->invocation(@args);"
           Return the tokens that would invoke the given definition with the provided arguments.
           This is used to recreate the TeX code (or it's equivalent).

       "$defn->invoke;"
           Invoke the action of the $defn.  For expandable definitions, this is done in the
           Gullet, and returns a list of LaTeXML::Tokens.  For primitives, it is carried out in
           the Stomach, and returns a list of LaTeXML::Boxes.  For a constructor, it is also
           carried out by the Stomach, and returns a LaTeXML::Whatsit.  That whatsit will be
           responsible for constructing the XML document fragment, when the LaTeXML::Document
           invokes "$whatsit-"beAbsorbed($document);>.

           Primitives and Constructors also support before and after daemons, lists of
           subroutines that are executed before and after digestion.  These can be useful for
           changing modes, etc.

   More about Primitives
       Primitive definitions may have lists of daemon subroutines, "beforeDigest" and
       "afterDigest", that are executed before (and before the arguments are read) and after
       digestion.  These should either end with "return;", "()", or return a list of digested
       objects (LaTeXML::Box, etc) that will be contributed to the current list.

   More about Registers
       Registers generally store some value in the current "LaTeXML::State", but are not required
       to. Like TeX's registers, when they are digested, they expect an optional "=", and then a
       value of the appropriate type. Register definitions support these additional methods:

       "$value = $register->valueOf(@args);"
           Return the value associated with the register, by invoking it's "getter" function.
           The additional args are used by some registers to index into a set, such as the index
           to "\count".

       "$register->setValue($value,@args);"
           Assign a value to the register, by invoking it's "setter" function.

   More about Constructors
       A constructor has as it's "replacement" a subroutine or a string pattern representing the
       XML fragment it should generate.  In the case of a string pattern, the pattern is compiled
       into a subroutine on first usage by the internal class "LaTeXML::ConstructorCompiler".
       Like primitives, constructors may have "beforeDigest" and "afterDigest".

AUTHOR

       Bruce Miller <bruce.miller@nist.gov>

COPYRIGHT

       Public domain software, produced as part of work done by the United States Government &
       not subject to copyright in the US.