DJVUSED(1)

DJVUSED(1) 💅

okay so bestie, you found the manual page for djvused from DjVuLibre-3.5 — and yes, it's giving iconic multi-tool energy. Sit down, grab a boba, we're doing this. 🧋✨

---

✨ NAME ✨

djvused — your multi-purpose DjVu document editor. 🎀 Like, it does everything, no cap.

---

🦋 SYNOPSIS 🦋

djvused [options] djvufile

---

🌸 DESCRIPTION 🌸

Okay so listen. djvused is a powerful command line tool for manipulating multi-page documents, creating or editing annotation chunks, creating or editing hidden text layers, pre-computing thumbnail images, and so much more. It's basically the main character of DjVu tooling. 👑

Here's the flow: the program first reads the DjVu document djvufile, then it executes a bunch of djvused commands. Simple as that. 💖

And where do those commands come from? Pick your vibe:

• read from a specific file (when option -f is specified) 📄
• read from the command line (when option -e is specified) ⌨️
• read from the standard input (this is the default, bestie) 🫶

---

💅 OPTIONS 💅

• -v — makes djvused print a command line prompt before reading commands, plus a little brief message describing how each command was executed. This one is so useful for debugging djvused scripts, and also for interactively entering djvused commands on the standard input. Debugging era fr fr. 🔍
• -f scriptfile — makes djvused read commands from file scriptfile. 📂
• -e command — makes djvused execute the commands specified by the option argument commands. Pro tip from the source material: it is advisable to surround the djvused commands by single quotes so you don't get unwanted shell expansion jumping out at you. 🙈
• -s — makes djvused save the file djvufile after executing the specified commands. This is similar to executing command save immediately before terminating the program. Basically it's save but make it a flag. 💾
• -u — makes djvused print hidden text and annotations as UTF-8 instead of encoding non-ASCII characters with octal escape sequences for maximal portability. This option is convenient for manually editing or viewing the djvused output. Also — heads up — this option also causes the emission of a UTF-8 BOM under Windows. 🪟✨
• -n — makes djvused disregard save commands. Useful for debugging djvused scripts without overwriting files on your disk. Protect your files, queen. 🛡️

---

🎀 DJVUSED EXAMPLES 🎀

There are many ways to use program djvused. The following examples illustrate some common uses of this program. Let's get into it. 🌈

🍓 Obtaining the size of a page

Command size outputs the width and height of the selected pages using a HTML friendly syntax. For instance, the following command prints the size of page 3 of document myfile.djvu.

djvused myfile.djvu -e 'select 3; size'

🔥 Extracting the hidden text

Command print-pure-txt outputs the text associated with a page or a document. For instance, the following shell command outputs the text for the entire document. Lines and pages are delimited by the usual control characters.

djvused myfile.djvu -e 'print-pure-txt'

Command print-txt produces a more extensive output describing the structure and the location of the text components. The syntax of this output is described later in this man page. For instance, the following shell command outputs extended text information for page 3 of document myfile.djvu.

djvused myfile.djvu -e 'select 3; print-txt'

💜 Extracting the annotations

Annotation data can be extracted using command print-ant. The syntax of the annotation data is described later in this man page. For instance, the following shell command outputs the annotation data for the first page of document myfile.djvu.

djvused myfile.djvu -e 'select 1; print-ant'

Command print-ant only prints the annotations stored in the selected component file. Command print-merged-ant also retrieves annotations from all the component files referenced by the current page (using INCL chunks) and prints the merged information. Merged > not merged, periodt. 💫

🌸 Dumping/restoring annotations and text

Three commands — output-txt, output-ant, and output-all — produce djvused scripts. For instance, the following shell command produces a djvused script, myfile.dsed, that recreates all the text and annotation data in document myfile.djvu.

djvused myfile.djvu -e 'output-all' > myfile.dsed

Script myfile.dsed is a text file that can be easily edited. The following shell command then recreates the text and annotation information in file myfile.djvu.

djvused myfile.djvu -f myfile.dsed -s

🦋 Extracting a page

Both commands save-page and save-page-with create a DjVu file representing the selected component file of a document. The following shell command, for instance, creates a file p05.djvu containing page 5 of document myfile.djvu.

djvused myfile.djvu -e 'select 5; save-page p05.djvu'

Each page of a document might import data from another component file using the so-called inclusion ( INCL ) chunks. Command save-page then produces a file with unresolved references to imported data. Such a file should then be made part of a multi-page document containing the required data in other component files. On the other hand, command save-page-with copies all the imported data into the output file. This file is directly usable. Yet — and this is the tradeoff bestie — collecting several such files into a multi-page document might lead to useless data replication. 🙃

⭐ Pre-computing thumbnails

Commands set-thumbnails constructs thumbnails that can be later displayed by DjVu viewers. The following shell command, for instance, computes thumbnails of size 64x64 pixels for all pages of file myfile.djvu.

djvused myfile.djvu -e 'set-thumbnails 64' -s

---

👑 DJVUSED COMMANDS 👑

Command lines might contain zero, one, or more djvused commands and an optional comment. Multiple djvused commands must be separated by a semicolon character ';'. Comments are introduced by the '#' character and extend until the end of the command line. Write that down. 📝

🌈 Selection commands

Multi-page DjVu documents are composed of a number of component files. Most component files describe a specific page of a document. Some component files contain information shared by several pages such as shared image data, shared annotations or thumbnails. Many djvused commands operate on selected component files. All component files are initially selected. The following commands are useful for changing the selection. ✨

• n — Print the total number of pages in the document. 🔢
• ls — List all component files in the document. Each line contains an optional page number, a letter describing the component file type, the size of the component file, and identifier of the component file. Component file type letters P, I, A, and T respectively stand for page data, shared image data, shared annotation data, and thumbnail data. Page numbers are only listed for component files containing page data. When it is set, the optional page title (see command set-page-title below) is displayed after the component file identifier. 📋
• select [fileid] — Select the component file identified by argument fileid. Argument fileid must be either a page number or a component file identifier. The select command selects all component files when the argument fileid is omitted. 🎯
• select-shared-ant — Select a component file containing shared annotations. Only one such component file is supported by the current DjVu software. This component file usually contains annotations pertaining to the whole document as opposed to specific pages. An error message is displayed if there is no such component file. 😭
• create-shared-ant — Create and select a component file containing shared annotations. This command only selects the shared annotation component file if such a component file already exists. Otherwise it creates a new shared annotation component file and makes sure that it is imported by all pages in the document. Look at her, making connections everywhere. 🕸️💖
• showsel — Shows the currently selected component files with the same format as command ls. 👀

🧚 Text and annotation commands

• print-pure-txt — Print the text stored in the hidden text layer of the selected pages. A similar capability is offered by program djvutxt. Structural information is sometimes represented by control characters. Text from different pages is delimited by form feed characters ("\f"). Lines are delimited by newline characters ("\n"). Columns, regions, and paragraphs are sometimes delimited by vertical tab ("\013"), group separators ("\035") and unit separators ("\037") respectively. Control characters are doing the most, lowkey. 🫠
• print-txt — Prints extensive hidden text information for the selected pages. This information describes the structure of the text on the document page and locates the structural elements in the page image. The syntax of this output is described later in this man page. 🗺️
• remove-txt — Remove the hidden text information from the selected component files. For instance, executing commands select and remove-txt removes all hidden text information from the DjVu document. 🧹
• set-txt [djvusedtxtfile] — Insert hidden text information into the selected pages. The optional argument djvusedtxtfile names a file containing the hidden text information. This file must contain data similar to what is produced by command print-txt. When the optional argument is omitted, the program reads the hidden text information from the djvused script until reaching an end-of-file or a line containing a single period. 📥
• output-txt — Prints a djvused script that reconstructs the hidden text information for the selected pages. This script can later be edited and executed by invoking program djvused with option -f. ♻️
• print-ant — Prints the annotations of the selected component file. The annotation data is represented using a simple syntax described later in this document. 🖍️
• print-merged-ant — Merge the annotations stored in the selected component files with the annotations imported from other component files such as the shared annotation component file.. The annotation data is represented using a simple syntax described later in this document. (Yes the original has two dots, we keep it, we respect the text. 💀)
• remove-ant — Remove the annotation information from the selected component files. For instance, executing commands select and remove-ant removes all annotation information from the DjVu document. 🗑️
• set-ant [djvusedantfile] — Insert annotations into the selected component file. The optional argument djvusedantfile names a file containing the annotation data. This file must contain data similar to what is produced by command print-ant. When the optional argument is omitted, the program reads the annotation data from the djvused script itself until reaching an end-of-file or a line containing a single period. 🫶
• output-ant — prints a whole djvused script that rebuilds the annotation info for the pages you picked, bestie ✨. You can edit that script later and run it by calling djvused with option -f. It's giving "save your work as a re-runnable recipe".
• print-meta — prints the metadata chunk of the annotations for the selected component file. Lowkey this is a subset of what print-ant gives you, just in a different syntax. The metadata are organized as key-value pairs, and every printed line has the key name (like author, title, etc.) followed by a tab character ("\t") and then a double-quoted string holding the UTF-8 encoded metadata value. 🎀
• remove-meta — yeets the metadata part of the annotations out of the selected component files. Gone. Periodt.
• set-meta [djvusedmetafile] — sets the metadata part of the annotations of the selected component file, and leaves the rest of the annotations completely untouched 💅. That optional djvusedmetafile argument names a file containing the metadata, and that file has to contain data similar to what print-meta spits out. If you skip the optional argument, the program reads the annotation data straight from the djvused script itself until it hits an end-of-file or a line containing a single period.
• print-xmp — prints the XMP metadata string sitting in the annotation chunk of the selected component file. Honestly? It's a subset of what print-ant shows you. iykyk.
• remove-xmp — removes the XMP tag from the annotation chunk of the selected component file. bye girl 👋
• set-xmp [xmpfile] — sets the XMP metadata part of the annotations of the selected component file, leaving the rest of the annotations unchanged 🫶. The optional xmpfile argument names a file containing the XMP metadata in a format similar to what print-xmp produces. Omit the argument and the program reads the XMP annotation data from the djvused script itself until it reaches an end-of-file or a line containing a single period.
• output-all — prints a djvused script that reconstructs both the hidden text and the annotation information for the selected pages 🔥. Same deal as before: edit it later, run it later, just invoke djvused with option -f. Main character energy, truly.

---

👑 Outline/bookmarks commands 👑

• print-outline — prints the outline of the document. And if the document has no outline? Nothing gets printed. Nothing. Silence. 💀
• remove-outline — removes the outline from the document. That's it, that's the whole thing.
• set-outline [djvusedoutlinefile] — inserts outline information into the document ✨. The optional djvusedoutlinefile argument names a file containing that outline information, and the file must contain data similar to what print-outline produces. Skip the optional argument and the program reads the hidden text information from the djvused script until it hits an end-of-file or a line containing a single period.

---

🌸 Thumbnail commands 🌸

• set-thumbnails sz — computes thumbnails of size szxsz pixels and drops them into the document 🖼️. DjVu viewers can then show these thumbnails super efficiently without having to download the data for every single page — obsessed. Typical thumbnail sizes run from 48 to 128 pixels.
• remove-thumbnails — removes the pre-computed thumbnails from the DjVu document. After that you can compute new ones with set-thumbnails. Fresh start, bestie 🦋.

---

💖 Save commands 💖

Okay so real talk: everything above only messes with the memory image of the DjVu document. These next commands are how you actually get that modified data onto the file system. No cap.

• save — saves the modified DjVu document back into the input file djvufile that you specified in djvused's arguments. If the DjVu file wasn't modified, nothing happens — it's not doing extra work for free 💅. And passing option -s to djvused is equivalent to running save right before the program exits.
• save-bundled filename — saves the current DjVu document as a bundled multi-page DjVu document named filename. Program djvmcvt can do a similar thing, if that's more your vibe.
• save-indirect filename — saves the current DjVu document as an indirect multi-page DjVu document. The index file of the indirect document gets named filename, and all the other files that make up the indirect document get saved into the same directory as the index file 🗂️. Again, program djvmcvt offers a similar capability.
• save-page filename — saves the selected component file into the DjVu file filename. Heads up though: the selected component file might import data from another component file using the so-called inclusion (INCL) chunks. When that happens, this command produces a file with unresolved references to imported data 😭. Such a file should then be made part of a multi-page document that contains the required data in other component files.
• save-page-with filename — saves the selected component file into the DjVu file filename, and this time all the data imported from other component files gets copied into the output file too. So this command always produces a usable DjVu file 👑. Downside? Collecting several such files into a multi-page document might lead to useless data replication. Trade-offs, bestie.

---

🌈 Miscellaneous commands 🌈

• help — displays a help message listing all the commands djvused supports. Your little cheat sheet 🎀.
• dump — displays the EA IFF 85 structure of the document or of the selected component file. Program djvudump offers a similar capability, fyi.
• size — displays the width and the height of the selected pages 📐. Each page's dimensions get printed using a syntax you can drop straight into <EMBED...></EMBED> tags. This command also shows the default page orientation when it's different from zero.
• set-rotation [+-]rot — changes the default orientation of the selected pages 🔄. The orientation is an integer in range 0..3 representing a number of 90 degree counter-clockwise rotations. When the argument is preceded by a sign + or -, argument rot counts how many additional 90 degree counter-clockwise rotations should be applied to the page. Otherwise, argument rot represents the desired absolute page orientation. Only DjVu pages can be rotated, though — pages represented as a raw IW44 image cannot be rotated. Sorry to that one page 💀.
• set-dpi dpi — sets the resolution of the page image in dots per inche. Argument dpi should be in range 25..6000. (Yes, the manual says "inche", we keep the lore verbatim 😌)
• set-page-title title — sets a page title for the selected page 🏷️. When page titles are available, recent versions of the DjVuLibre viewers display these page titles instead of page numbers, and they also accept them in page selection options. Command ls can be used to see both the page titles and page identifiers. Wanna unset a page title? Just make it equal to the page identifier. Simple as that ✨.

💖 DJVUSED FILE FORMATS 💖

okay so bestie, djvused speaks in a cute little parenthesized syntax, and it uses that same syntax to hold both annotations AND hidden text. two icons, one grammar. 🎀

• this syntax IS the native syntax DjVu uses for storing annotations. what does djvused do to it? it just compresses that annotation data with the bzz(1) algorithm. that's it. that's the whole job. 💅
• this syntax is NOT the same as the native syntax DjVu uses for hidden text. nope! djvused does the translating for you — back and forth between the compact binary representation DjVu actually stores and this easily modifiable parenthesized syntax. it's giving bilingual queen. 🌈

---

✨ General syntax ✨

djvused files are ASCII text files, periodt. the legal characters are the printable ASCII characters plus space, tab, cr, and nl. using other characters? undefined results. we do not do that. 🙈

so the file is just a sequence of expressions separated by blank characters (space, tab, cr, or nl). and there are four kinds of expressions: integers, symbols, strings and lists. let's go. 🦋

Integers:

• Integer numbers are represented by one or more digits, with the usual interpretation. yes bestie, just numbers. iconic behavior.

Symbols:

• Symbols, aka identifiers, are sequences of printable ascii characters representing a name or a keyword. acceptable characters are the alpha-numeric characters, the underscore "_", the minus character "-", and the hash character "#". and heads up: names should not begin with a digit or a minus character. noted. 📝

Strings:

• Strings denote an arbitrary sequence of bytes, usually interpreted as a sequence of UTF-8 encoded characters. they're basically strings in the C language — surrounded by double quote characters. 💫
• certain sequences of characters starting with a backslash ("\") have a special meaning. a backslash followed by the letter "a", "b", "t", "n", "v", "f", "r", "\", and " stands for the ascii character BEL(007), BS(008), HT(009), LF(010), VT(011), FF(012), CR(013), BACKSLASH(134) and DOUBLEQUOTE(042) respectively.
• a backslash followed by one to three digits stands for the byte whose octal code is expressed by the digits.
• all other backslash sequences are illegal. 🚫 all non printable ascii characters must be escaped. no exceptions, bestie.

Lists:

• Lists are sequence of expressions separated by blanks and surrounded by parentheses. all expression types are acceptable within a list, including sub-lists. nesting rights!! 🫶

---

🌸 Hidden text syntax 🌸

the building blocks of the hidden text syntax are lists representing each structural component of the hidden text. structural components have this form:

(type xmin ymin xmax ymax ... )

the symbol type must be one of page, column, region, para, line, word, or char — listed here by decreasing order of importance, so you know who the main characters are. 👑

the integers xmin, ymin, xmax, and ymax represent the coordinates of a rectangle showing where that structural component sits on the page. coordinates are measured in pixels and have their origin at the bottom left corner of the page. 📐

the remaining expressions in the list are either a single string representing the encoded text associated with this structural component, or a sequence of structural components with a lesser type. choose your own adventure. ✨

the hidden text for each page is simply represented by a single structural element of type page. various level of structural information are acceptable — for instance, the page level component might only specify a page level string, or might only provide a list of lines, or might provide a full hierarchy down to the individual characters. lowkey flexible, highkey slay. 💅

---

💜 Outline/Bookmark syntax 💜

the outline syntax is a single list of the form

(bookmarks ...)

the first element of the list is symbol bookmarks. the subsequent elements are lists representing the toplevel outline entries. each outline entry is represented by a list with this form:

(title url ... )

the string title is the title of the outline entry. the destination string url can be either an arbitrary percent encoded URL, or composed of the hash character ("#") followed by a page name or number, or composed of the question mark character ("?") followed by cgi-style arguments interpreted by the djvu viewer. and the remaining expressions in the list describe subentries of this outline entry. 🌈

---

🎀 Annotation syntax 🎀

Annotations are represented by a sequence of annotation expressions. the following annotation expressions are recognized:

• (background color) — specify the color of the viewer area surrounding the DjVu image. colors use the X11 hexadecimal syntax #RRGGBB. for instance, #000000 is black and #FFFFFF is white. 🖤🤍
• (zoom zoomvalue) — specify the initial zoom factor of the image. argument zoomvalue can be one of stretch, one2one, width, page, or composed of the letter d followed by a number in range 1 to 999 representing a zoom factor (such as in d300 or d150 for instance.) 🔍
• (mode modevalue) — specify the initial display mode of the image. argument modevalue is one of color, bw, fore, or back.
• (align horzalign vertalign) — specify how the image should be aligned on the viewer surface. by default the image is located in the center. argument horzalign can be one of left, center, or right. argument vertalign can be one of top, center, or bottom. centered and unbothered, fr fr. 🧘
• (maparea url comment area ...) — define an hyper-link for the specified destination.

argument url can have one of the following forms:

href
(url href target)

where href is a string representing the destination and target is a string representing the target frame for the hyper-link, as defined by the HTML anchor tag <A>. the destination string href can be either an arbitrary percent encoded URL, or composed of the hash character ("#") followed by a page name or number, or composed of the question mark character ("?") followed by cgi-style arguments interpreted by the djvu viewer. page numbers may be prefixed with an optional sign to represent a page displacement. for instance the strings "#-1" and "#+1" can be used to access the previous page and the next page. ⏪⏩

argument comment is a string that might be displayed by the viewer when the user moves the mouse over the hyper-link. 👀

argument area defines the shape and the location of the hyperlink. the following forms are recognized:

(rect xmin ymin width height)
(oval xmin ymin width height)
(poly x0 y0 x1 y1 ... )
(text xmin ymin width height)
(line x0 y0 x1 y1)

all parameters are numbers representing coordinates. coordinates are measured in pixels and have their origin at the bottom left corner of the page. 📍

the remaining expressions in the maparea list represent the visual effect associated with the hyper-link.

a first set of options defines how borders are drawn for rect, oval, polygon, or text hyperlink areas.

(none)
(xor)
(border color)
(shadow_in [thickness])
(shadow_out [thickness])
(shadow_ein [thickness])
(shadow_eout [thickness])

where parameter color has syntax #RRGGBB as described above, and parameter thickness is an integer in range 1 to 32. the last four border options are only supported for rect hyperlink areas. although the border mode defaults to (xor), it is wise to always specify the border mode. border options do not apply to line areas.

when a border option is specified, the border becomes visible when the user moves the mouse over the hyperlink. the border may be made always visible by using the following option:

(border_avis)

the following two options may be used with rect hyperlink areas. the complete area will be highlighted using the specified color at the specified opacity (0-100, default 50). some viewers (e.g., djview4) support opacities in range 0-200 with 200 representing a fully opaque color. ✨

(hilite color)
(opacity op)

this is often used with an empty URL for simply emphasizing a specific segment of an image. 💅

the following three options may be used with line areas to specify an optional ending arrow, the line width and color. the default is a black line with width 1 and without arrow.

(arrow)
(width w)
(lineclr color)

finally the following three options can be used with text areas. the default background color is transparent. the default text color is black. the pushpin option indicates that the text is symbolized by a small pushpin icon. clicking the icon reveals the text. 📌

(backclr bkcolor)
(textclr txtcolor)
(pushpin)

• (metadata ... (key value) ... ) — define metadata entries. each entry is identified by a symbol key representing the nature of the meta data entry. the string value represents the value associated with the corresponding key. two sets of keys are noteworthy: keys borrowed from the BibTex bibliography system, and keys borrowed from the PDF DocInfo metadata. BibTex keys are always expressed in lowercase, such as year, booktitle, editor, author, etc.. DocInfo keys start with an uppercase letter, such as Title, Author, Subject, Creator, Produced, Trapped, CreationDate, and ModDate. the values associated with the last two keys should be dates expressed according to RFC 3339. 🗓️

---

😭 LIMITATIONS 😭

not to be dramatic but: the current version of program djvused only supports selecting one component file or all component files. there is no way to select only a few component files. all or one, bestie. that's the vibe check and it failed. 💀

---

👑 CREDITS 👑

this program was initially written by Léon Bottou <leonb@users.sourceforge.net> and was improved by Yann Le Cun <profshadoko@users.sourceforge.net>, Florin Nicsa, Bill Riemers <docbill@sourceforge.net> and many others. legends only, we stan. 🫶

---

🦋 SEE ALSO 🦋

djvu(1), djvutxt(1), djvmcvt(1), djvudump(1), bzz(1), Emacs djvused front end djvu.el on GNU Elpa repository. go read them, they're part of the family. 💖

---

and that's a wrap on the whole page, bestie!! ✨ this one's from DjVuLibre-3.5, dated 5/22/2005, and yeah the date is giving vintage but she still ate. 💅🎀 go forth and annotate responsibly. 🦋🌸