NAME

       djvutoxml, djvuxmlparser - DjVuLibre XML Tools.

SYNOPSIS

       djvutoxml [options] inputdjvufile [outputxmlfile]
       djvuxmlparser [ -o djvufile ] inputxmlfile

DESCRIPTION

       The DjVuLibre XML Tools provide for editing the metadata, hyperlinks and hidden text associated with DjVu
       files.  Unlike djvused(1) the DjVuLibre XML Tools rely on the XML technology and can  take  advantage  of
       XML editors and verifiers.

DJVUTOXML

       Program  djvutoxml  creates a XML file outputxmlfile containing a reference to the original DjVu document
       inputdjvufile as well as tags describing the metadata, hyperlinks, and hidden text  associated  with  the
       DjVu file.

       The following options are supported:

       --page pagenum
              Select  a  page  in  a  multi-page  document.   Without  this  option,  djvutoxml  outputs the XML
              corresponding to all pages of the document.

       --with-text
              Specifies the HIDDENTEXT element for each page should be included in  the  output.   If  specified
              without  the  --with-anno  flag  then  the --without-anno is implied.  If none of the --with-text,
              --without-text, --with-anno, or --without-anno, flags are  specified,  then  the  --with-text  and
              --with-anno flags are implied.

       --without-text
              Specifies not to output the HIDDENTEXT element for each page.  If specified without the --without-
              anno flag then the --with-anno flag is implied.

       --with-anno
              Specifies the area MAP element for each page should be  included  in  the  output.   If  specified
              without the --with-text flag then the --without-text flag is implied.

       --without-anno
              Specifies  the  area MAP element for each page should not be included in the output.  If specified
              without the --without-text flag then the --with-text flag is implied.

DJVUXMLPARSER

       Files produced by djvutoxml can then be modified using either a text editor or  a  XML  editor.   Program
       djvuxmlparser  parses the XML file inputxmlfile in order to modify the metadata of the corresponding DjVu
       file.

       -o djvufile
              In principle the target DjVu file is the file referenced by the OBJECT element of  the  XML  file.
              This option provides the means to override the filename specified in the OBJECT element.

DJVUXML DOCUMENT TYPE DEFINITION

       The document type definition file (DTD)

         /usr/share/djvu/pubtext/DjVuXML-s.dtd

       defines the input and output of the DjVu XML tools.

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

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

       with  a  few  new  attributes added specific to DjVu.  Each of the specified pages of a DjVu document are
       represented as OBJECT elements within the BODY element of the XML file.  Each OBJECT element may  contain
       multiple  PARAM elements to specify attributes like page name, resolution, and gamma factor.  Each OBJECT
       element may also contain one HIDDENTTEXT element to specify the hidden text (usually  generated  with  an
       OCR  engine)  within  the  DjVu  page.   In  addition each OBJECT element may reference a single area MAP
       element which contains multiple AREA elements to represent all the hyperlink and highlight  areas  within
       the DjVu document.

   PARAM Elements
       Legal  PARAM  elements of a DjVu OBJECT include but are not limited to PAGE for specifying the page-name,
       GAMMA for specifying the gamma correction  factor  (normally  2.2),  and  DPI  for  specifying  the  page
       resolution.

   HIDDENTEXT Elements
       The  HIDDENTEXT  elements  consists of nested elements of PAGECOLUMNS, REGION, PARAGRAPH, LINE, and 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 LINE or WORD as the lowest level element, but any element is  legal  as  the  lowest
       level  element.   A  white  space  is  always added between WORD elements and a line feed is always added
       between LINE elements.  Since languages such as Japanese do not use spaces between  words,  it  is  quite
       common for Asian OCR engines to use WORD as characters instead.

   MAP Elements
       The body of the MAP elements consist of AREA elements.  In addition to the attributes listed in

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

       the  attributes  bordertype,  bordercolor,  border, and 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 oval has been added to the legal list of shapes.
       An oval uses a rectangular bounding box.

BUGS

       Perhaps it would have been better to use CC2 style sheets with standard HTML elements instead of defining
       the HIDDENTEXT element.

CREDITS

       The DjVu XML tools and DTD were written by Bill C. Riemers <docbill@sourceforge.net> and Fred Crary.

SEE ALSO

       djvu(1), djvused(1), and utf8(7).