.\" Copyright (c) 2001-2003 Leon Bottou, Yann Le Cun, Patrick Haffner,

.\" Copyright (c) 2001 AT&T Corp., and Lizardtech, Inc.

.\"

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

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

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

.TH DJVUDIGITAL 1 "1/31/2004" "DjVuLibre-3.5" "DjVuLibre-3.5"

.SH NAME

djvudigital \- creates DjVu files from PS or PDF files.

.SH SYNOPSIS

.BI "djvudigital  [" "options" "] " "inputfile" " [" "outputfile" "]"

.SH DESCRIPTION

This program creates a DjVu file

from the PostScript

.BR "" "(" ".ps" "),"

GZipped PostScript

.BR "" "(" ".ps.gz" "),"

Encapsulated PostScript

.BR "" "(" ".eps" "),"

or Portable Document Format 

.BR "" "(" ".pdf" ")"

file

.IR inputfile .

The output file name is either given by argument

.I outputfile

or generated by replacing the input file name 

suffixes by the DjVu suffix

.BR "" "(" ".djvu" ")."

.SH PREREQUISITES

This program depends on a specific GhostScript driver.

If your GhostScript program does not provide this driver,

please check

.BR http://djvu.sourceforge.net/gsdjvu.html .

.SH OPTIONS

.TP

.BR "--verbose" ", " "-v"

Displays more informational messages while

converting the file.

.TP

.BR "--quiet" ", " "-q"

Do not display informational messages while

converting the file.

.TP

.BI "--dpi=" "resolution"

Specify the desired resolution to 

.I resolution

dots per inch.

The default is 300 dpi.

.TP

.BI "--psrotate=" "angle"

Rotate the PostScript file by 

.I angle

degrees clockwise. 

Only the values

.BR 0 ", " 90 ", " 180 ", and " 270

are supported.  

This option only applies to PostScript files.

PDF files are always converted according to

their native orientation.

.TP

.BI "--epsf=" "disposition"

Specify how to handle Encapsulated PostScript files. 

Argument

.I disposition

can take the values

.BR crop ", " fit ", and " ignore "."

The default disposition

.B crop

creates a DjVu file whose size matches the bounding box of 

the Encapsulated PostScript file. Value

.B fit

rescales the graphics to the default page size. 

Value

.B ignore

disables all Encapsulated PostScript specific code.

This option requires Ghostscript 7.07 or better.

.TP

.BI "--exact-color"

Enables a more accurate rendering of the colors.

This option requires GhostScript 6.52 or better.

.TP

.BI "--threshold=" "thres"

Specify a threshold for the foreground/background separation code.

Acceptable values of

.I thres

range from 0 to 100. Larger values place more 

information into the foreground layer.

The default threshold value is 80.

.TP

.BI "--bg-subsample=" "sub"

Specify the background subsampling ratio.

Argument 

.I sub

must be an integer between 1 and 6.

The default value is 3.

.TP

.BI "--bg-slices=" "n" "+...+" "n"

Specify the encoding quality of the background layer. 

The syntax for the argument is similar to that described for the

.B -slice

option of command

.BR c44 .

The default is

.BR 72+11+10+10 .

.TP

.BI "--fg-colors=" ncolors

Specify the maximum number of distinct colors in the foreground layer.

Argument 

.I ncolors

can take integer values between 1 and 4000.

The default value is 256.

.TP

.BI "--fg-image-colors=" ncolors

Specify the maximum number of distinct colors in an image for 

considering encoding it into the foreground layer.

Argument 

.I ncolors

can take integer values between 1 and 4000.

The default value is 256.

.TP

.BI "--words"

Extract the text from the PostScript code and

incorporates this information into the DjVu file.

This option records the location of every word.

.TP

.BI "--lines"

Extract the text from the PostScript code and

incorporates this information into the DjVu file.

This option saves a few bytes by only recording the 

location of each line.

.TP

.BI "--gsarg=" arg1 "[," arg2 ",...," argN "]"

Insert extra arguments on the GhostScript command line.

.TP

.BI "--cseparg=" arg1 "[," arg2 ",...," argN "]"

Insert extra arguments on the command line of

program

.BR csepdjvu " or " msepdjvu "."

.TP

.BI "--sepfile"

Produces a separated data file instead of a DjVu file. Program

.BR csepdjvu 

can then convert the separated data file into a DjVu file.

.TP

.BI "--check"

Display the names of the two auxiliary programs found by

.BR djvudigital ,

namely a suitable ghostscript interpreter and a suitable backend encoder.

See the next two section for details.

.TP

.BI "--dryrun"

Simply display the ghostscript command line generated by

.BR djvudigital

without running it.

No output file is produced

.TP

.BI "--help"

Display the manual page for 

.BR djvudigital .

.PP

.SH GHOSTSCRIPT ISSUES

Program

.B djvudigital 

internally relies on a specific Ghostscript driver named

.BR djvusep .

This driver analyzes the logical structure of the sequence

of PostScript rendering commands and decides to execute 

each command into either the foreground or the background layer.

The GhostScript driver produces a separated data file 

that is then compressed using the DjVuLibre program

.BR csepdjvu .

Before processing the input file, program

.B djvudigital

searches a Ghostscript executable providing the

.B djvusep

driver. The search starts with the file specified

by the environment variable

.B GSDJVU

and continues with command line executables named

.BR gs " and " gsdjvu "."

The DjVuLibre source code contains instruction

to compile such a GhostScript executable.

More information can be obtained from

.BR http://djvu.sourceforge.net/gsdjvu.html .

.SH CSEPDJVU ISSUES

The output of the

.B djvusep

GhostScript driver must be processed by 

the DjVuLibre program

.BR csepdjvu .

This program can also be replaced by the 

the proprietary Lizardtech program

.BR msepdjvu .

Before processing the input file, program

.B djvudigital

searches such an executable.

The search starts with the file specified

by the environment variable

.B CSEPDJVU

and continues with command line executables named

.BR msepdjvu " and " csepdjvu "."

.SH CREDITS

The first version of this converter was written 

by L\('eon Bottou <leonb@users.sourceforge.net>

in AT&T Labs.  The DjVuLibre version is derived 

from code graciously released by Lizardtech in 

January 2004.

.SH BUGS

Program

.B djvudigital

can only process input files that GhostScript can process properly.

.SH SEE ALSO

.BR djvu (1),

.BR csepdjvu (1),

.BR c44 (1),

.BR gs (1),

.BR gzip (1)