DJVUXML(1)

💖 DJVUXML 💖

ok so real talk bestie, this is the manual for DJVUXML(1) from the DjVuLibre XML Tools crew — two little programs, djvutoxml and djvuxmlparser, and they are literally the moment for anyone who wants to mess with their DjVu files through XML instead of raw tooling. iykyk ✨

---

🌸 NAME 🌸

djvutoxml, djvuxmlparser — DjVuLibre XML Tools, periodt.

---

🎀 SYNOPSIS 🎀

djvutoxml [options] inputdjvufile [outputxmlfile]
djvuxmlparser [ -o djvufile ] inputxmlfile

---

✨ DESCRIPTION ✨

The DjVuLibre XML Tools are your besties for editing the metadata, hyperlinks, and hidden text that live inside DjVu files. 🦋

And the way this is different from djvused(1)?? Unlike djvused(1), the DjVuLibre XML Tools are fully built on XML technology, which means you get to flex with all your fave XML editors and verifiers. it's giving ✨interoperability✨. slay.

---

🧚 DJVUTOXML 🧚

So djvutoxml is the one that makes the XML. It creates an XML file called outputxmlfile, and that file contains:

• a reference to the original DjVu document inputdjvufile 👑
• tags describing the metadata associated with the DjVu file
• tags describing the hyperlinks associated with the DjVu file
• tags describing the hidden text associated with the DjVu file

The following options are supported, no cap:

• --page pagenum — picks one page out of a multi-page document. and if you don't pass this? then djvutoxml just outputs the XML for all pages of the document. main character energy, honestly.
• --with-text — says the HIDDENTEXT element for each page should be included in the output. ⚠️ but listen: if you specify this without the --with-anno flag, then --without-anno is implied. and if none of --with-text, --without-text, --with-anno, or --without-anno are specified, then --with-text and --with-anno are both implied.
• --without-text — says not to output the HIDDENTEXT element for each page. if you specify this without the --without-anno flag, then the --with-anno flag is implied.
• --with-anno — says the area MAP element for each page should be included in the output. if you specify this without the --with-text flag, then the --without-text flag is implied.
• --without-anno — says the area MAP element for each page should not be included in the output. if you specify this without the --without-text flag, then the --with-text flag is implied.

bestie these flag implications are a whole web of vibes. read them twice, fr fr. 🙈

---

🌈 DJVUXMLPARSER 🌈

ok so once djvutoxml hands you a file, you can go in and edit it — either with a plain text editor or with a full XML editor, whichever is your era. 💅

Then djvuxmlparser is the one that reads it back in. It parses the XML file inputxmlfile in order to modify the metadata of the corresponding DjVu file.

• -o djvufile — in principle, the target DjVu file is whatever file is referenced by the OBJECT element of the XML file. but this option gives you the power to override the filename specified in the OBJECT element. iconic override behavior, we love to see it.

---

👑 DJVUXML DOCUMENT TYPE DEFINITION 👑

The document type definition file — the DTD, if you're fancy — lives right here:

/usr/share/djvu/pubtext/DjVuXML-s.dtd

and this is what defines the input and output of the DjVu XML tools. ⭐

The DjVuXML-s DTD is a simplification of the HTML DTD:

http://www.w3c.org/TR/1998/REC-html40-19980424/sgml/dtd.html

...with a few new attributes added that are specific to DjVu. 💜

Here's the tea on the structure: each of the specified pages of a DjVu document is represented as OBJECT elements within the BODY element of the XML file. Each OBJECT element may contain multiple PARAM elements to specify attributes like page name, resolution, and gamma factor. Each OBJECT element may also contain one HIDDENTTEXT element to specify the hidden text (usually generated with an OCR engine) within the DjVu page. And on top of all that, each OBJECT element may reference a single area MAP element which contains multiple AREA elements to represent all the hyperlink and highlight areas within the DjVu document. 🦋

---

🍓 PARAM Elements 🍓

Legal PARAM elements of a DjVu OBJECT include but are not limited to:

• PAGE — for specifying the page-name
• GAMMA — for specifying the gamma correction factor (normally 2.2)
• DPI — for specifying the page resolution

---

🎀 HIDDENTEXT Elements 🎀

The HIDDENTEXT elements consist of nested elements of PAGECOLUMNS, REGION, PARAGRAPH, LINE, and WORD. ✨

The most deeply nested element specified should specify the bounding coordinates of the element in top-down orientation. The body of the most deeply nested element should contain the text.

Most DjVu documents use either LINE or WORD as the lowest level element, but — and this is important bestie — any element is legal as the lowest level element.

A white space is always added between WORD elements, and a line feed is always added between LINE elements. 🔥

Since languages such as Japanese do not use spaces between words, it is quite common for Asian OCR engines to use WORD as characters instead. no cap, that's just how it be.

---

💜 MAP Elements 💜

The body of the MAP elements consists of AREA elements. 😌

In addition to the attributes listed in:

http://www.w3.org/TR/1998/REC-html40-19980424/struct/objects.html#edef-AREA

...the attributes bordertype, bordercolor, border, and highlight have been added to specify border type, border color, border width, and highlight colors respectively. Legal values for each of these attributes are listed in the DjVuXML-s DTD. 👑

In addition, the shape oval has been added to the legal list of shapes. An oval uses a rectangular bounding box. that's right, an oval with a rectangular bounding box — not me questioning the geometry, it's just what the DTD says. 💀

---

😭 BUGS 😭

Perhaps it would have been better to use CC2 style sheets with standard HTML elements instead of defining the HIDDENTEXT element.

(the devs said it, not me 🙈)

---

🌟 CREDITS 🌟

The DjVu XML tools and DTD were written by Bill C. Riemers <docbill@sourceforge.net> and Fred Crary. absolute legends, we stan. 👑

---

💅 SEE ALSO 💅

djvu(1), djvused(1), and utf8(7). go read them next, bestie, you know you want to. 🫶

---

and that's the whole thing! this page was brought to you by DjVuLibre XML Tools, dated 11/15/2002 — yeah she's vintage but she still eats 💖✨🎀🦋🌸