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.

perl v5.10.1                                       2009-06-11                             LaTeXML::Document(3pm)