NAME

       "LaTeXML::Document" - represents an XML document under construction.

DESCRIPTION

       A "LaTeXML::Document" constructs an XML document by absorbing the digested LaTeXML::List
       (from a LaTeXML::Stomach), Generally, the LaTeXML::Boxs and LaTeXML::Lists create text
       nodes, whereas the LaTeXML::Whatsits create "XML" document fragments, elements and
       attributes according to the defining LaTeXML::Constructor.

       The "LaTeXML::Document" maintains a current insertion point for where material will be
       added. The LaTeXML::Model, derived from various declarations and document type, is
       consulted to determine whether an insertion is allowed and when elements may need to be
       automatically opened or closed in order to carry out a given insertion.  For example, a
       "subsection" element will typically be closed automatically when it is attempted to open a
       "section" element.

       In the methods described here, the term $qname is used for XML qualified names.  These are
       tag names with a namespace prefix.  The prefix should be one registered with the current
       Model, for use within the code.  This prefix is not necessarily the same as the one used
       in any DTD, but should be mapped to the a Namespace URI that was registered for the DTD.

       The arguments named $node are an XML::LibXML node.

   Accessors
       "$doc = $document->getDocument;"
           Returns the "XML::LibXML::Document" currently being constructed.

       "$node = $document->getNode;"
           Returns the node at the current insertion point during construction.  This node is
           considered still to be `open'; any insertions will go into it (if possible).  The node
           will be an "XML::LibXML::Element", "XML::LibXML::Text" or, initially,
           "XML::LibXML::Document".

       "$node = $document->getElement;"
           Returns the closest ancestor to the current insertion point that is an Element.

       "$document->setNode($node);"
           Sets the current insertion point to be  $node.  This should be rarely used, if at all;
           The construction methods of document generally maintain the notion of insertion point
           automatically.  This may be useful to allow insertion into a different part of the
           document, but you probably want to set the insertion point back to the previous node,
           afterwards.

   Construction Methods
       "$document->absorb($digested);"
           Absorb the $digested object into the document at the current insertion point according
           to its type.  Various of the the other methods are invoked as needed, and document
           nodes may be automatically opened or closed according to the document model.

       "$xmldoc = $document->finalize;"
           This method finalizes the document by cleaning up various temporary attributes, and
           returns the XML::LibXML::Document that was constructed.

       "$document->openText($text,$font);"
           Open a text node in font $font, performing any required automatic opening and closing
           of intermedate nodes (including those needed for font changes) and inserting the
           string $text into it.

       "$document->insertMathToken($string,%attributes);"
           Insert a math token (XMTok) containing the string $string with the given attributes.
           Useful attributes would be name, role, font.  Returns the newly inserted node.

       "$document->openElement($qname,%attributes);"
           Open an element, named $qname and with the given attributes.  This will be inserted
           into the current node while  performing any required automatic opening and closing of
           intermedate nodes.  The new element is returned, and also becomes the current
           insertion point.  An error (fatal if in "Strict" mode) is signalled if there is no
           allowed way to insert such an element into the current node.

       "$document->closeElement($qname);"
           Close the closest open element named $qname including any intermedate nodes that may
           be automatically closed.  If that is not possible, signal an error.  The closed node's
           parent becomes the current node.  This method returns the closed node.

       "$node = $document->isOpenable($qname);"
           Check whether it is possible to open a $qname element at the current insertion point.

       "$node = $document->isCloseable($qname);"
           Check whether it is possible to close a $qname element, returning the node that would
           be closed if possible, otherwise undef.

       "$document->maybeCloseElement($qname);"
           Close a $qname element, if it is possible to do so, returns the closed node if it was
           found, else undef.

       "$document->insertElement($qname,$content,%attributes);"
           This is a shorthand for creating an element $qname (with given attributes), absorbing
           $content from within that new node, and then closing it.  The $content must be
           digested material, either a single box, or an array of boxes.  This method returns the
           newly created node, although it will no longer be the current insertion point.

       "$document->insertComment($text);"
           Insert, and return, a comment with the given $text into the current node.

       "$document->insertPI($op,%attributes);"
           Insert, and return,  a ProcessingInstruction into the current node.

       "$document->addAttribute($key=>$value);"
           Add the given attribute to the nearest node that is allowed to have it.

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.