Ubuntu Manpage: djvused - Multi-purpose DjVu document editor.

Provided by: djvulibre-bin_3.5.27.1-8ubuntu0.4_amd64

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.

       -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.

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.

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.

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 metadata 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. metadata 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 metadata value.

remove-meta
Remove the metadata part of the annotations of the selected component files.

set-meta [djvusedmetafile]
Set the metadata 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 metadata. 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.

print-xmp
Print the XMP metadata string contained in the annotation chunk of the selected
component file. This command displays in fact a subset of the information printed
by command print-ant.

remove-xmp
Removes the XMP tag from the annotation chunk of the selected component file.

set-xmp [xmpfile]
Set the XMP metadata part of the annotations of the selected component file. The
remaining part of the annotations is left unchanged. The optional argument xmpfile
names a file containing the XMP metadata in a format similar to that produced by
command print-xmp. When the optional argument is omitted, the program reads the
XMP 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.

remove-outline
Removes the outline from the document.

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. This command also displays the default page orientation
when it is different from zero.

set-rotation [+-]rot
Changes the default orientation of the selected pages. The orientation is
expressed as 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. Pages represented as a raw IW44
image cannot be rotated.

set-dpi dpi
Sets the resolution of the page image in dots per inche. Argument dpi should be in
range 25..6000.

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. 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).

(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

       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 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.