pub fn parse_chunk(markup: &str) -> Result<Document, String>Expand description
Parse a standalone markup string into its own document — the port of Perl
LaTeXML::Common::XML::Parser::parseChunk (Common/XML/Parser.pm:36-39:
parse_string($string) then ->documentElement, “expects only a single
node”). Parsing lives here, beside the rest of the Common::XML helpers, and
NOT in Document — mirroring Perl, where Document::appendTree only ever
consumes already-parsed nodes.
Diverges from Perl in its RETURN, deliberately: Perl hands back the
documentElement and lets the GC keep its owner alive, which in Rust would
dangle — the nodes borrow the document that owns them. So we return the owning
[Document] and let the caller take get_root_element(), keeping the owner
alive for exactly as long as the nodes are used.
The markup must be a single well-formed XML root (parseChunk’s contract): a
bare fragment of several top-level nodes, or an undeclared HTML entity such as
, is a parse error. The error is returned as a rendered string for the
caller to report; this layer applies no logging policy of its own. See
ill_formed_markup_hint for why that string names the likely causes instead
of quoting libxml’s own diagnosis.
Recovery is deliberately OFF. libxml’s default is to salvage malformed
input, which here silently DESTROYS author content rather than reporting it —
measured: <b>a</b> <i>b</i> parsed to just <b>a</b> (the second element
dropped), <p>a b</p> to ab (the entity deleted), and <p>a & b</p>
to a b. Swallowing a author’s markup is the silent-failure mode this
project forbids, so a malformed chunk must fail loudly and insert nothing.
This also matches Perl, whose XML::LibXML->parse_string defaults to
recover => 0. Network access is refused too: a chunk is untrusted input and
must never make the parser fetch an external DTD.