NAME
djvused - Multi-purpose DjVu document editor.
SYNOPSIS
djvused [options] djvufile
DESCRIPTION
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).
OPTIONS
-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.
-f scriptfile
Cause djvused to read commands from file scriptfile.
-e command
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
immediately before terminating the program.
-n Cause djvused to disregard save commands. This is useful for
debugging djvused scripts without overwriting files on your
disk.
DJVUSED EXAMPLES
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
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.
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 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.
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.
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.
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.
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
Print a djvused script that reconstructs the annotation
information for the selected pages. This script can later be
edited and executed by invoking program djvused with option -f.
print-meta
Print the meta-data part of the annotations for the selected
component file. This command displays a subset of the
information printed by command print-ant using a different
syntax. Meta-data are organized as key-value pairs. Each
printed line contains the key name such as author, title,etc.,
followed by a tab character ("\t") and a double-quoted string
representing the UTF-8 encoded meta-data value.
set-meta [djvusedmetafile]
Set the meta-data part of the annotations of the selected
component file. The remaining part of the annotations is left
unchanged. The optional argument djvusedmetafile names a file
containing the meta-data. This file must contain data similar
to what is produced by command print-meta. 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-all
Print a djvused script that reconstructs both the hidden text
and the annotation information for the selected pages. This
script can later be edited and executed by invoking program
djvused with option -f.
Outline/bookmarks commands
print-outline
Print the outline of the document. Nothing is printed if the
document contains no outline.
set-outline [djvusedoutlinefile]
Insert outline information into the document. The optional
argument djvusedoutlinefile names a file containing the outline
information. This file must contain data similar to what is
produced by command print-outline. 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.
Thumbnail commands
set-thumbnails sz
Compute thumbnails of size szxsz pixels and insert them into the
document. DjVu viewers can later display these thumbnails very
efficiently without need to download the data for each page.
Typical thumbnail size range from 48 to 128 pixels.
remove-thumbnails
Remove the pre-computed thumbnails from the DjVu document. New
thumbnails can then be computed using command set-thumbnails.
Save commands
The above commands only modify the memory image of the DjVu document.
The following commands provide means to save the modified data into the
file system.
save Save the modified DjVu document back into the input file
djvufile specified by the arguments of the program djvused.
Nothing is done if the DjVu file was not modified. Passing
option -s program djvused is equivalent to executing command
save before exiting the program.
save-bundled filename
Save the current DjVu document as a bundled multi-page DjVu
document named filename. A similar capability is offered by
program djvmcvt.
save-indirect filename
Save the current DjVu document as an indirect multi-page DjVu
document. The index file of the indirect document will be named
filename. All other files composing the indirect document will
be saved into the same directory as the index file. A similar
capability is offered by program djvmcvt.
save-page filename
Save the selected component file into DjVu file filename. The
selected component file might import data from another component
file using the so-called inclusion ( INCL ) chunks. This
command 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.
save-page-with filename
Save the selected component file into DjVu file filename. All
data imported from other component files is copied into the
output file as well. This command always produces a usable DjVu
file. On the other hand, collecting several such files into a
multi-page document might lead to useless data replication.
Miscellaneous commands
help Display a help message listing all commands supported by
djvused.
dump Display the EA IFF 85 structure of the document or of the
selected component file. A similar capability is offered by
program djvudump.
size Display the width and the height of the selected pages. The
dimensions of each page are displayed using a syntax suitable
for direct insertion into the <EMBED...></EMBED> tags.
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 also accept them
in page selection options. Command ls can be used to see both
the page titles and page identifiers. To unset a page title,
simply make it equal to the page identifier.
DJVUSED FILE FORMATS
Djvused uses a simple parenthesized syntax to represent both
annotations and hidden text.
* This syntax is the native syntax used by DjVu for storing
annotations. Program djvused simply compresses the annotation data
using the bzz(1) algorithm.
* This syntax differs from the native syntax used by DjVu for storing
the hidden text. Program djvused performs the translations between
the compact binary representation used by DjVu and the easily
modifiable parenthesized syntax.
General syntax
Djvused files are ASCII text files. The legal characters in djvused
files are the printable ASCII characters and the space, tab, cr, and nl
characters. Using other characters has undefined results.
Djvused files are composed of a sequence of expressions separated by
blank characters (space, tab, cr, or nl). There are four kind of
expressions, namely integers, symbols, strings and lists.
Integers:
Integer numbers are represented by one or more digits, with the
usual interpretation.
Symbols:
Symbols, or 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 "#". Names
should not begin with a digit or a minus character.
Strings:
Strings denote an arbitrary sequence of bytes, usually
interpreted as a sequence of UTF-8 encoded characters. Strings
in djvused files are similar to strings in the C language. They
are surrounded by double quote characters. Certain sequences of
characters starting with a backslash ("\") have a special
meaning. A backslash followed by 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.
Lists: Lists are sequence of expressions separated by blanks and
surrounded by parentheses. All expressions types are acceptable
within a list, including sub-lists.
Hidden text syntax
The building blocks of the hidden text syntax are lists representing
each structural component of the hidden text. Structural components
have the following 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. The integers
xmin, ymin, xmax, and ymax represent the coordinates of a rectangle
indicating the position of the structural component in 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 either
is a single string representing the encoded text associated with this
structural component, or is a sequence of structural components with a
lesser type.
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.
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 the following 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. 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 are represented with 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.
(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.
The default border is a simple black line. 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).
(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 meta-data 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
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.
CREDITS
This program was initially written by Leon 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.
SEE ALSO
djvu(1), djvutxt(1), djvmcvt(1), djvudump(1), bzz(1)