
1- WHAT IS DJVU.
================

DjVu (pronounced "déjà vu") a set of compression technologies, a file format,
and a software platform for the delivery over the Web of digital documents,
scanned documents, and high resolution images.

DjVu documents download and display extremely quickly, and look exactly the
same on all platforms. DjVu can be seen as superior alternative to PDF and
Postscript for digital documents, to TIFF (and PDF) for scanned documents, to
JPEG for photographs and pictures, and to GIF for large palettized
images. DjVu is the only Web format that is practical for distributing
high-resolution scanned documents in color. No other format comes close.

Typical DjVu file sizes are as follows: 

- Bitonal scanned documents: 
        5 to 30KB per page at 300dpi, 
        3 to 10 times smaller than PDF or TIFF.

- Color scanned documents: 
           30 to 100KB per page at 300dpi,
           5 to 10 times smaller than JPEG.

- Photos:
        2 times smaller than JPEG, 
        about the same as JPEG-2000. 

- Palettized images: 
        2 times smaller than GIF,
        up to 10 times if there is text.

DjVu is used by hundreds of commercial, governmental, and non-commercial web
sites around the world to distribute scanned documents, digital documents, and
high-resolution photos.

Demos, and general information about DjVu can be found at 
http://www.djvuzone.org, or at http://www.lizardtech.com. 

DjVu was originally developed at AT&T Labs-Research. AT&T sold DjVu to
LizardTech Inc. in March 2000.



2- WHAT IS DJVULIBRE? 
=====================

In an effort to promote DjVu as a Web standard, LizardTech's management was
enlightened enough to release the reference implementation of DjVu under the
GNU GPL in October 2000. DjVuLibre (pronounced like the French "déjà vu
libre"), is an enhanced version of that code maintained by the original
inventors of DjVu. It is compatible with LizardTech's DjVu software v3.5.

This package includes: 

- An up-to-date version of the C++ DjVu Reference Library 
- A full-fledged wavelet-based compressor for pictures. 
- A simple compressor for bitonal (black and white) scanned pages. 
- A compressor for palettized images (a la GIF). 
- A full set of utilities to manipulate and assemble DjVu images and documents. 
- A set of decoders to convert DjVu to a number of other formats. 

The full-fledged DjVu file viewer and browser plugin DjView4
is available as a separate package.



3- BUILDING DJVULIBRE
=====================

3.1- PREREQUISITES
------------------

DjVuLibre-3.5 relies on various components available from the web.  
Most recent Linux distribution already come with these.  
You can also download and compile them if you wish.
Be sure to read the system specific notes 
at the end of this file.

COMPILER --
Development is done with the GCC g++ compiler, which is therefore
recommended for all platforms.  The CLANG compiler has been tried and
seems to work, but its output has not been seriously tested.

LIBJPEG/LIBTIFF --
A small number of DjVu files internally use JPEG encoding instead 
of IW44 wavelet encoding.  These files are processed using either 
version 6a or 6b of the IJG libjpeg library <http://www.ijg.org>.  
Some utility programs are able to read TIFF files. These programs
rely on the LIBTIFF library <http://libtiff.org>.
You can also compile DjVuLibre with neither JPEG nor TIFF support.  
You might never notice the difference.


3.2 - CONFIGURE
---------------

Chances are that everything will work by simply running 
commands "./configure", "make" and "make install".

Note that there will be no configure file if you obtain the djvulibre 
source using git clone. Instead there is a script 'autogen.sh' that 
uses automake to generate and call the actual configure script.
Since all autogen.sh arguments will be passed to configure,
you can simply treat autogen.sh as a replacement for configure.

Various options and environment variables affect the execution of the
configuration script.  A complete list can be obtained by typing 
"configure --help".  Also see the INSTALL file for further details.
Here are the most important ones.

* Option "--prefix=PREFIXDIR"
  This option specifies where the DjVuLibre software will be installed.
  The default prefix is /usr/local.  

* Option "--enable-desktopfiles[=(yes|no)]"
  Installs icon and mime type files in the customary xdg directories.
  The default is "yes".

* Option "--with-jpeg=JPEGDIR"
  This option specifies a directory where the JPEG library has been
  compiled. This directory contains both the include files and the 
  library.  Without this option, the configuration script will search 
  the JPEG library in standard places.
  When everything else fails, you can simply define the environment
  variables JPEG_CFLAGS and JPEG_LIBS.

* Option "--with-tiff=TIFFDIR"
  This option specifies a directory where the LIBTIFF library has been
  compiled. This directory contains both the include files and the 
  library.  Without this option, the configuration script will search 
  the LIBTIFF library in standard places.
  When everything else fails, you can simply define the environment
  variables TIFF_CFLAGS and TIFF_LIBS.

Always check the output of the configuration script for warnings and errors.
In particular, the configuration script might disable the compilation of
djview if it cannot locate the required libraries and utilities.  The warning
messages are the only way to know.

3.3 - MAKE
----------

You can then perform the compilation by typing 

        $ make

The compilation can last a few minutes.  Again check the output for warnings
and errors.  Finally a brief message lets you know that the compilation was
successful.  You can then proceed with the installation.

3.4 - INSTALL
------------

Typing:

        $ make install

or if necessary:

        $ sudo make install

should:

- install the executable programs into "${prefix}/bin/".
- possibly install the shared library into "${prefix}/lib/".
- install the man pages under "${prefix}/man or ${prefix}/share/man/".
- install various ancillary files under "${prefix}/share/djvu/".
- install "${prefix}/share/pkgconfig.pc".
- optionally install the icon and mime type information files

Where ${prefix} refers to the directory specified by the prefix option
of the configuration script, which defaults to "/usr/local", and the
paths above can be fine-tuned using appropriate arguments to
./configure and make.


4 - BUILDING FOR MAC OS X
=========================

We recommend that you first install homebrew and use 
command "brew install" to obtain the following packages:
  $ brew install autoconf automake libtool pkg-config
  $ brew install jpeg libtiff

Note that homebrew comes with a djvulibre package already.
The following instructions explain how to compile djvulibre
in a standalone manner. You may want to do that if you want
the latest version of djvulibre. Otherwise, chances are
that you should just install the djvulibre homebrew package.
  $ brew install djvulibre

But most people should find sufficient
to just install the homebrew package.

Then you can run configure
  $ ./configure --disable-desktopfiles 

Then you can compile with 
  $ make

Running "make install" will install djvulibre in directory /usr/local.
This may not be a good idea as they will interfere with homebrew.
You may instead specify an alternate directory with DESTDIR=...
  $ make install DESTDIR=/usr/local/djvulibre-install
  


5 - BUILDING FOR WINDOWS
========================

5.1- Using Microsoft Visual C++ 2012
------------------------------------

   See the directory win32.
   Populate the zlib, jpeg and tiff directories with
   the open source code suggested in the README files.
   Check win32/djvulibre/dirs.props to see
   how to name the directories.
   Then open win32/djvulibre/djvulibre.sln and compile.

   Next step would then be to follow the instructions
   in the djview package to create a djview project and
   add it to this solution. Finally you can use the script
   djvulibre-install.sh and djvulibre.nsi to prepare
   the djvulibre+djview installer.


5.2- Using Mingw
----------------

   You must first install the mingw compiler and the msys environment.
   See www.mingw.org for more information.
   From the msys shell, run the usual commands 
     $ configure
     $ make
   Then collect the djvulibre dll from directory libdjvu/.libs
   and the executables from directory tools/.libs 
   Please refer to the file INSTALL for information
   about the arguments of the script 'configure'.


5.3- Using Cygwin 
-----------------

   Simply run the usual commands 
     $ configure
     $ make
     $ make install
   Please refer to the file INSTALL for information
   about the arguments of the script 'configure'.
 


