DJVUSED(1) DjVuLibre-3.5 DJVUSED(1)
djvused - Multi-purpose DjVu document editor.
djvused [options] djvufile
Program 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 more. The program first reads the DjVu document djvufile and executes a
number of djvused commands.
Djvused commands can be read from a specific file (when option -f is specified), read from the command line (when option -e is specified),
or read from the standard input (the default).
-v Cause djvused to print a command line prompt before reading commands and a brief message describing how each command was executed.
This option is very useful for debugging djvused scripts and also for interactively entering djvused commands on the standard input.
Cause djvused to read commands from file scriptfile.
Cause djvused to execute the commands specified by the option argument commands. It is advisable to surround the djvused commands
by single quotes in order to prevent unwanted shell expansion.
-s Cause djvused to save the file djvufile after executing the specified commands. This is similar to executing command save immedi-
ately before terminating the program.
-u Cause djvused to 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. This option also causes the
emission of an UTF-8 BOM under Windows.
-n Cause djvused to disregard save commands. This is useful for debugging djvused scripts without overwriting files on your disk.
There are many ways to use program djvused. The following examples illustrate some common uses of this program.
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 doc-
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.
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 informa-
tion 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 collecting several such files into a multi-page document might lead to useless data replication.
Commands set-thumbnails constructs thumbnails that can be later displayed by DjVu viewers. The following shell command, for instance, com-
putes thumbnails of size 64x64 pixels for all pages of file myfile.djvu.
djvused myfile.djvu -e 'set-thumbnails 64' -s
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.
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 com-
mands operate on selected component files. All component files are initially selected. The following commands are useful for changing the
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 con-
taining page data. When it is set, the optional page title (see command set-page-title below) is displayed after the component file
Select the component file identified by argument fileid. Argument fileid must be either a page number or a component file identi-
fier. The select command selects all component files when the argument fileid is omitted.
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 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.
Shows the currently selected component files with the same format as command ls.
Text and annotation commands
Print the text stored in the hidden text layer of the selected pages. A similar capability is offered by program djvutxt. Struc-
tural information is sometimes represented by control characters. Text from different pages is delimited by form feed characters
("f"). Lines are delimited by newline characters ("
"). Columns, regions, and paragraphs are sometimes delimited by vertical tab