.\" Copyright (c) 2002 Bill C. Riemers

.\"

.\" This is free documentation; you can redistribute it and/or

.\" modify it under the terms of the GNU General Public License as

.\" GNU General Public License, either Version 2 of the license,

.\" or (at your option) any later version. The license should have

.\" published by the Free Software Foundation; either version 2 of

.\" the License, or (at your option) any later version.

.\"

.\" The GNU General Public License's references to "object code"

.\" and "executables" are to be interpreted as the output of any

.\" document formatting or typesetting system, including

.\" intermediate and printed output.

.\"

.\" This manual is distributed in the hope that it will be useful,

.\" but WITHOUT ANY WARRANTY; without even the implied warranty of

.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

.\" GNU General Public License for more details.

.\"

.\" You should have received a copy of the GNU General Public

.\" License along with this manual. Otherwise check the web site

.\" of the Free Software Foundation at http://www.fsf.org.

.\"

.\" I, Bill C. Riemers, hereby grant all rights to this code,

.\" provided usage complies with the GPL or a written exception to 

.\" the GPL granted by any of Bill C. Riemers, Leon Bottou, 

.\" Yann Le Cun, or the Free Source Foundation.

.\"

.\" ------------------------------------------------------------------

.\" DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from

.\" Lizardtech Software.  Lizardtech Software has authorized us to

.\" replace the original DjVu(r) Reference Library notice by the following

.\" text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):

.\"

.\"  ------------------------------------------------------------------

.\" | DjVu (r) Reference Library (v. 3.5)

.\" | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.

.\" | The DjVu Reference Library is protected by U.S. Pat. No.

.\" | 6,058,214 and patents pending.

.\" |

.\" | This software is subject to, and may be distributed under, the

.\" | GNU General Public License, either Version 2 of the license,

.\" | or (at your option) any later version. The license should have

.\" | accompanied the software or you may obtain a copy of the license

.\" | from the Free Software Foundation at http://www.fsf.org .

.\" |

.\" | The computer code originally released by LizardTech under this

.\" | license and unmodified by other parties is deemed "the LIZARDTECH

.\" | ORIGINAL CODE."  Subject to any third party intellectual property

.\" | claims, LizardTech grants recipient a worldwide, royalty-free, 

.\" | non-exclusive license to make, use, sell, or otherwise dispose of 

.\" | the LIZARDTECH ORIGINAL CODE or of programs derived from the 

.\" | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU 

.\" | General Public License.   This grant only confers the right to 

.\" | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to 

.\" | the extent such infringement is reasonably necessary to enable 

.\" | recipient to make, have made, practice, sell, or otherwise dispose 

.\" | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to 

.\" | any greater extent that may be necessary to utilize further 

.\" | modifications or combinations.

.\" |

.\" | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY

.\" | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED

.\" | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF

.\" | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

.\" +------------------------------------------------------------------

.TH DJVUXML 1 "11/15/2002" "DjVuLibre XML Tools" "DjVuLibre XML Tools"

.de SS

.SH \\0\\0\\0\\$*

..

.SH NAME

djvutoxml, djvuxmlparser \- DjVuLibre XML Tools.

.SH SYNOPSIS

.BI "djvutoxml [" options "] " inputdjvufile " [" outputxmlfile "]"

.br

.BI "djvuxmlparser [ -o " djvufile " ] " inputxmlfile 

.SH DESCRIPTION

The DjVuLibre XML Tools provide for editing the

metadata, hyperlinks and hidden text 

associated with DjVu files.  Unlike 

.BR djvused (1)

the DjVuLibre XML Tools rely on the XML technology

and can take advantage of XML editors and verifiers.

.SH DJVUTOXML

Program

.B djvutoxml

creates a XML file

.I outputxmlfile

containing a reference to the original DjVu document

.I inputdjvufile

as well as tags describing the metadata,

hyperlinks, and hidden text associated with the DjVu file.

The following options are supported:

.TP

.BI "--page " "pagenum"

Select a page in a multi-page document.

Without this option, 

.B djvutoxml

outputs the XML 

corresponding to all pages of the document.

.TP 

.BI "--with-text"

Specifies the 

.B HIDDENTEXT 

element for each page should be included in the output.  

If specified without the

.B --with-anno

flag then the

.B --without-anno 

is implied.  If none of the  

.B --with-text, 

.B --without-text, 

.B --with-anno, 

or

.B --without-anno, 

flags are specified, then the  

.B --with-text 

and 

.B --with-anno 

flags are implied.

.TP

.BI "--without-text"

Specifies not to output the 

.B HIDDENTEXT 

element for each page.  If specified without the 

.B --without-anno 

flag then the 

.B --with-anno 

flag is implied.

.TP

.BI "--with-anno"

Specifies the area 

.B MAP 

element for each page should be included in the output.  

If specified without the

.B --with-text 

flag then the

.B --without-text 

flag is implied.

.TP

.BI "--without-anno"

Specifies the area 

.B MAP 

element for each page should not be included in the output.  

If specified without the

.B --without-text 

flag then the

.B --with-text 

flag is implied.

.SH DJVUXMLPARSER

Files produced by 

.B djvutoxml

can then be modified using 

either a text editor or a XML editor.

Program

.B djvuxmlparser

parses the XML file 

.I inputxmlfile

in order to modify the metadata of the corresponding DjVu file.

.TP

.BI "-o " "djvufile"

In principle the target DjVu file is the file 

referenced by the

.I OBJECT 

element of the XML file. 

This option provides the means to override the filename

specified in the 

.I OBJECT

element.

.SH DJVUXML DOCUMENT TYPE DEFINITION

The document type definition file (DTD)

.IP "" 2

.B DATADIR/djvu/pubtext/DjVuXML-s.dtd

.PP

defines the input and output of the DjVu XML tools.

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

.IP "" 2

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

.PP

with a few new attributes added specific to DjVu.  Each of the 

specified pages of a DjVu document are represented as 

.B OBJECT 

elements within the 

.B BODY 

element of the XML file. 

Each 

.B OBJECT

element may contain multiple 

.B PARAM 

elements to specify attributes like page name,

resolution,

and gamma factor.

Each 

.B OBJECT

element may also contain one

.B HIDDENTTEXT

element to specify the hidden text (usually generated with an OCR engine) 

within the DjVu page.  In addition each 

.B OBJECT

element may reference a single area 

.B MAP

element which contains multiple

.B AREA

elements to represent all the hyperlink and highlight areas within 

the DjVu document.

.SS PARAM Elements

Legal 

.B PARAM 

elements of a DjVu 

.B OBJECT 

include but are not limited to

.B PAGE

for specifying the page-name,

.B GAMMA

for specifying the gamma correction factor (normally 2.2), and

.B DPI

for specifying the page resolution.

.SS HIDDENTEXT Elements

The 

.B HIDDENTEXT

elements consists of nested elements of 

.B PAGECOLUMNS,

.B REGION,

.B PARAGRAPH,

.B LINE,

and

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

.B LINE 

or 

.B WORD 

as the lowest level element, but any element is legal as the lowest 

level element.  A white space is always added between 

.B WORD

elements and a line feed is always added between

.B LINE

elements.  Since languages such as Japanese do not use spaces between 

words, it is quite common for Asian OCR engines to use

.B WORD

as characters instead.

.SS MAP Elements

The body of the 

.B MAP

elements consist of 

.B AREA

elements.  In addition to the attributes listed in

.IP "" 2

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

.PP

the attributes

.BR bordertype ,

.BR bordercolor ,

.BR border ,

and 

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

.B oval

has been added to the legal list of shapes.  An oval uses a rectangular 

bounding box.

.SH BUGS

Perhaps it would have been better to use CC2 style sheets 

with standard HTML elements instead of defining the 

.B HIDDENTEXT 

element.

.SH CREDITS

The DjVu XML tools and DTD were written

by Bill C. Riemers <docbill@sourceforge.net> 

and Fred Crary.

.SH SEE ALSO

.BR djvu (1),

.BR djvused (1),

and

.BR utf8 (7).