djvused man page on Mandriva

Man page or keyword search:  
man Server   17060 pages
apropos Keyword Search (all sections)
Output format
Mandriva logo
[printable version]

DJVUSED(1)			 DjVuLibre-3.5			    DJVUSED(1)

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  num‐
       ber 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 com‐
	      mands and a brief message describing how each command  was  exe‐
	      cuted.  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 com‐
	      mands by single quotes in order to prevent unwanted shell expan‐
	      sion.

       -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  follow‐
       ing shell command outputs extended text information for page 3 of docu‐
       ment 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 fol‐
       lowing 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 repre‐
       senting 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 dis‐
       played 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 com‐
       ponent 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	selec‐
       tion.

       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 com‐
	      ponent file.  Component file type letters P, I, A, and T respec‐
	      tively stand for page data, shared image data, shared annotation
	      data, and thumbnail data.	 Page numbers are only listed for com‐
	      ponent 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.	 Argu‐
	      ment 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 mes‐
	      sage is displayed if there is no such component file.

       create-shared-ant
	      Create and select a component  file  containing  shared  annota‐
	      tions.   This  command only selects the shared annotation compo‐
	      nent 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 char‐
	      acters.	Text  from  different  pages is delimited by form feed
	      characters ("\f").  Lines are delimited  by  newline  characters
	      ("\n").	Columns,  regions, and paragraphs are sometimes delim‐
	      ited 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 doc‐
	      ument  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	 argu‐
	      ment  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 infor‐
	      mation 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	 docu‐
	      ment.

       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 informa‐
	      tion 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  informa‐
	      tion  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 compo‐
	      nent 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 con‐
	      taining 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	 djvu‐
	      file 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 doc‐
	      ument  named  filename.  A similar capability is offered by pro‐
	      gram 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  com‐
	      mand then produces a file with unresolved references to imported
	      data.  Such a file should then be made part of a multi-page doc‐
	      ument 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 out‐
	      put  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 annota‐
       tions and hidden text.

       *  This syntax is the native syntax used by DjVu	 for  storing  annota‐
	  tions.   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	 modi‐
	  fiable 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	 char‐
	      acters  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	inter‐
	      preted  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	 mean‐
	      ing.   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), BACK‐
	      SLASH(134) and DOUBLEQUOTE(042) respectively.  A backslash  fol‐
	      lowed  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  sur‐
	      rounded  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.	 Coor‐
       dinates 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 struc‐
       tural  component,  or  is  a  sequence  of structural components with a
       lesser type.

       The hidden text for each page is simply represented by a single	struc‐
       tural  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 ele‐
       ments  are  lists representing the toplevel outline entries.  Each out‐
       line 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 an arbitrary URL or can be composed of the hash char‐
       acter ("#") followed by either the component  file  identifier  or  the
       page  number corresponding to the outline entry.	 The remaining expres‐
       sions 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 zoom‐
	      value can be one of stretch, one2one, width, page,  or  composed
	      of  the  letter  d followed by a number in range 1 to 999 repre‐
	      senting a zoom factor (such as in d300 or d150 for instance.)

       (mode modevalue)
	      Specify the initial display mode of the image.   Argument	 mode‐
	      value 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	horza‐
	      lign  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 an arbitrary URL or can be composed of the hash character
	      ("#") followed by either a component file identifier or  a  page
	      number.	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 hyper‐
	      link.  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.   Coordi‐
	      nates 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 vis‐
	      ual 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 spec‐
	      ify 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	lower‐
	      case,  such  as  year, booktitle, editor, author, etc..  DocInfo
	      keys start with an uppercase letter, such as Title, Author, Sub‐
	      ject,  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 com‐
       ponent 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.source‐
       forge.net> and was improved by Yann Le  Cun  <profshadoko@users.source‐
       forge.net>,  Florin  Nicsa,  Bill Riemers <docbill@sourceforge.net> and
       many others.

SEE ALSO
       djvu(1), djvutxt(1), djvmcvt(1), djvudump(1), bzz(1)

DjVuLibre-3.5			   5/22/2005			    DJVUSED(1)
[top]

List of man pages available for Mandriva

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net