LaTeXM...ocument(3pm)

okay bestie, welcome to LaTeXM...ocument(3pm), straight out of User Contributed Perl Documentation 💅. This is your girl explaining the whole thing, no cap.

💖 NAME 💖

LaTeXML::Core::Document — represents an XML document under construction. 🚧✨

✨ DESCRIPTION ✨

So a LaTeXML::Core::Document is literally an XML document that LaTeXML is still building, and it also hands you the methods to build it. It extends LaTeXML::Common::Object. Slay. 💅

By the time this kicks in, LaTeXML has already digested the source material into a LaTeXML::Core::List (from a LaTeXML::Core::Stomach) made of LaTeXML::Core::Boxs, LaTeXML::Core::Whatsits and sublists. At this stage a document gets created, and it is responsible for absorbing the digested material. Generally, the LaTeXML::Core::Boxs and LaTeXML::Core::Lists create text nodes, while the LaTeXML::Core::Whatsits create XML document fragments, elements and attributes according to the defining LaTeXML::Core::Definition::Constructor. Periodt. 💜

Most document construction happens at a current insertion point where material gets added, and that point moves along with the inserted material. The LaTeXML::Common::Model — derived from various declarations and document type — gets consulted to determine whether an insertion is allowed and when elements may need to be automatically opened or closed to carry out a given insertion. For example, a subsection element will typically be closed automatically when someone tries to open a section element. It's giving document model realness. 🦋

In these methods, $qname means an XML qualified name. These are tag names with a namespace prefix. The prefix should be one registered with the current Model, for use within the code. That prefix is not necessarily the same as the one used in any DTD, but it should be mapped to a Namespace URI that was registered for the DTD. iykyk 🧚

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

The methods here are grouped into three sections: basic access to the document, insertion methods at the current insertion point, and the less commonly used, lower-level, document manipulation methods. Let's go 💖

---

🎀 Accessors 🎀

• $doc = $document->getDocument; — returns the XML::LibXML::Document currently being constructed.
• $doc = $document->getModel; — returns the LaTeXML::Common::Model that represents the document model used for this document.
• $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.
• $node = $document->getChildElement($node); — returns a list of the child elements, if any, of $node. (The signature says $node, the text says list — we just report the chaos 🙈)
• @nodes = $document->getLastChildElement($node); — returns the last child element of $node, if it has one, else undef.
• $node = $document->getFirstChildElement($node); — returns the first child element of $node, if it has one, else undef.
• @nodes = $document->findnodes($xpath,$node); — returns a list of nodes matching the given $xpath expression. The context node for $xpath is $node, if given, otherwise it is the document element.
• $node = $document->findnode($xpath,$node); — returns the first node matching the given $xpath expression. The context node for $xpath is $node, if given, otherwise it is the document element.
• $node = $document->getNodeQName($node); — returns the qualified name (localname with namespace prefix) of the given $node. The namespace prefix mapping is the code mapping of the current document model.
• $boolean = $document->canContain($tag,$child); — returns whether an element $tag can contain a child $child. $tag and $child can be nodes, qualified names of nodes (prefix:localname), or one of a set of special symbols: #PCDATA, #Comment, #Document or #ProcessingInstruction.
• $boolean = $document->canContainIndirect($tag,$child); — returns whether an element $tag can contain a child $child either directly, or after automatically opening one or more autoOpen-able elements.
• $boolean = $document->canContainSomehow($tag,$child); — returns whether an element $tag can contain a child $child either directly, or after automatically opening one or more autoOpen-able elements. (Yes, same vibe as above — the page says it twice, so we say it twice 💀)
• $boolean = $document->canHaveAttribute($tag,$attrib); — returns whether an element $tag can have an attribute named $attrib.
• $boolean = $document->canAutoOpen($tag); — returns whether an element $tag is able to be automatically opened.
• $boolean = $document->canAutoClose($node); — returns whether the node $node can be automatically closed.

---

🛠️ Construction Methods 🛠️

These are the most common methods used for construction of documents. They generally operate by creating new material at the current insertion point. That point initially is just the document itself, but it moves along to follow any new insertions. These methods also adapt to the document model so as to automatically open or close elements when it is required for the pending insertion and allowed by the document model (See Tag). Not me being obsessed with the way the insertion point just moves along. Main character energy, fr fr. 🔥

• $xmldoc = $document->finalize; — finalizes the document by cleaning up various temporary attributes, and returns the XML::LibXML::Document that was constructed. Iconic cleanup moment ✨
• @nodes = $document->absorb($digested); — absorbs the $digested object into the document at the current insertion point according to its type. Various of the other methods are invoked as needed, and document nodes may be automatically opened or closed according to the document model. This method returns the nodes that were constructed. Heads up: the nodes may include children of other nodes, and nodes that may already have been removed from the document (See filterChildren and filterDeleted). Also, text insertions are often merged with existing text nodes; in such cases, the whole text node is included in the result. 🫶
• $document->insertElement($qname,$content,%attributes); — 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, which will be absorbed into the element. This method returns the newly created node, although it will no longer be the current insertion point.
• $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->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->openText($text,$font); — open a text node in font $font, performing any required automatic opening and closing of intermediate nodes (including those needed for font changes) and inserting the string $text into it.
• $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 intermediate 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 intermediate 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->addAttribute($key=>$value); — add the given attribute to the node nearest to the current insertion point that is allowed to have it. This does not change the current insertion point.
• $document->closeToNode($node); — this method closes all children of $node until $node becomes the insertion point. Note that it closes any open nodes, not only autoCloseable ones. 👑

🧚 Internal Insertion Methods 🧚

These are described as an aide to understanding the code; they rarely, if ever, should be used outside this module. ngl, they are lowkey the backstage crew. 🫶

• $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.
• $string = $document->getInsertionContext($levels); — for debugging, return a string showing the context of the current insertion point; that is, the string of the nodes leading up to it. If $levels is defined, show only that many nodes.
• $node = $document->find_insertion_point($qname); — this internal method is used to find the appropriate point, relative to the current insertion point, that an element with the specified $qname can be inserted. That position may require automatic opening or closing of elements, according to what is allowed by the document model.
• @nodes = getInsertionCandidates($node); — returns a list of elements where an arbitrary insertion might take place. Roughly this is a list starting with $node, followed by its parent and the parents siblings (in reverse order), followed by the grandparent and siblings (in reverse order).
• $node = $document->floatToElement($qname); — bestie, this one hunts for the nearest element at or before your current insertion point (see "getInsertionCandidates") that can accept an element named $qname; it moves the insertion point to that spot and returns the previous insertion point. Generally, after you do whatever you need at the new insertion point, you should call $document->setNode($node); to restore the insertion point. If no such point is found, the insertion point stays exactly where it was and undef is returned. 💅
• $node = $document->floatToAttribute($key); — same energy as floatToElement, but it finds the nearest element that can accept the attribute $key. ✨
• $node = $document->openText_internal($text); — this is an internal method, used by openText, and it assumes the insertion point has already been appropriately adjusted. Lowkey kitchen-only stuff. 🫶
• $node = $document->openMathText_internal($text); — this internal method appends $text to the current insertion point, which is assumed to be a math node. It checks for math ligatures and carries out any combinations called for. Math girlies rise. 🔥
• $node = $document->closeText_internal(); — this internal method closes the current node, which should be a text node. It carries out any text ligatures on the content. 🎀
• $node = $document->closeNode_internal($node); — this internal method closes any open text or element nodes starting at the current insertion point, up to and including $node. Afterwards, the parent of $node will be the current insertion point. It condenses the tree to avoid redundant font switching elements. Iconic cleanup behavior. 🧚
• $document->afterOpen($node); — carries out any afterOpen operations that have been recorded (using Tag) for the element name of $node. 💖
• $document->afterClose($node); — carries out any afterClose operations that have been recorded (using Tag) for the element name of $node. Matching set, we love to see it. 🌸

🛠️ Document Modification 🛠️

Okay so these next methods are for doing various sorts of modification and rearrangement of the document, after the normal flow of insertion has already happened. You might need them after an environment (or maybe the whole entire document) has been completed, and now you need to analyze what it contains to decide on the appropriate representation. Very “post-processing era” of you. 💅

• $document->setAttribute($node,$key,$value); — sets the attribute $key to $value on $node. This method is preferred over the direct LibXML one, since it takes care of decoding namespaces (if $key is a qname), and it also manages recording of xml:ids. 👑
• $document->recordID($id,$node); — records the association of the given $node with the $id, which should be the xml:id attribute of the $node. Usually this association will be maintained by the methods that create nodes or set attributes. 🪪
• $document->unRecordID($id); — removes the node associated with the given $id, if any. This might be needed if a node is deleted. Bye-bye association. 💀
• $document->modifyID($id); — adjusts $id, if needed, so that it is unique. It does this by appending a letter and incrementing until it finds an id that is not yet associated with a node. Incremental slay. 🔁
• $node = $document->lookupID($id); — returns the node, if any, that is associated with the given $id. 🔎
• $document->setNodeBox($node,$box); — records the $box (being a Box, Whatsit or List) that was (presumably) responsible for the creation of the element $node. This information is useful for determining source locations, original TeX strings, and so forth. Very “we remember where you came from” energy. 📦
• $box = $document->getNodeBox($node); — returns the $box that was responsible for creating the element $node. 🎁
• $document->setNodeFont($node,$font); — records the font object that encodes the font that should be used to display any text within the element $node. 💅
• $font = $document->getNodeFont($node); — returns the font object associated with the element $node. ✨
• $node = $document->openElementAt($point,$qname,%attributes); — opens a new child element in $point with the qualified name $qname and with the given attributes. This method is not affected by, nor does it affect, the current insertion point. It does manage namespaces, xml:ids, and associating a box, font and locator with the new element, as well as running any afterOpen operations. Multitasking icon. 🌈
• $node = $document->closeElementAt($node); — closes $node. This method is not affected by, nor does it affect, the current insertion point. However, it does run any afterClose operations, so any element that was created using the lower-level openElementAt should be closed using this method. No half-finished exits, bestie. 🚪
• $node = $document->appendClone($node,@newchildren); — appends clones of @newchildren to $node. This method modifies any ids found within @newchildren (using modifyID), and fixes up any references to those ids within the clones so that they refer to the modified id. Clone responsibly. 🧬
• $node = $document->wrapNodes($qname,@nodes); — this method wraps the @nodes by a new element with qualified name $qname; that new node replaces the first of @node. The remaining nodes in @nodes must be following siblings of the first one. 💝

NOTE: Does this need multiple nodes? If so, perhaps some kind of movenodes helper? Otherwise, what about attributes?

• $node = $document->unwrapNodes($node); — unwrap the children of $node, by replacing $node by its children. Free them from the enclosure. 🦋
• $node = $document->replaceNode($node,@nodes); — replace $node by @nodes; presumably they are some sort of descendant nodes. 🔄
• $node = $document->renameNode($node,$newname); — rename $node to the tagname $newname; equivalently replace $node by a new node with name $newname and copy the attributes and contents. It is assumed that $newname can contain those attributes and contents. Name change, same vibe. 🏷️
• @nodes = $document->filterDeletions(@nodes); — this function is useful with "$doc-"absorb($box)>, when you want to filter out any nodes that have been deleted and no longer appear in the document. Deleted means deleted, periodt. 🗑️
• @nodes = $document->filterChildren(@nodes); — this function is useful with "$doc-"absorb($box)>, when you want to filter out any nodes that are children of other nodes in @nodes. We only want the main characters, not the whole family tree. 👑

👑 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.

---

💖 That’s the whole page, bestie. The footer says source/version perl v5.40.1, dated 2025-11-16, for LaTeXM...ocument(3pm). Go forth and slay your document tree. 💅✨