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.