NAME

       djvuserve - Generate indirect DjVu documents on the fly.

DESCRIPTION

       Program  djvuserve is a CGI program that can be executed by a HTTP server for serving DjVu
       documents.  This program is able to convert a bundled multi-page document into an indirect
       document on the fly.

USING DJVUSERVE

       Program djvuserve must first be installed as a CGI program for your web server.  There are
       several ways to achieve this.   The Apache web  server,  for  instance,  often  defines  a
       specific directory for CGI programs using the ScriptAlias directive.  Assume that the file
       httpd.conf contains the following line:

          ScriptAlias /cgi–bin/ "/var/www/cgi–bin"

       It is then sufficient to create a small executable shell script /var/www/cgi–bin/djvuserve
       containing the following lines:

          #!/bin/sh
          exec /full/path/to/djvuserve

       Suppose that a large bundled multi-page DjVu document is available at the following URL.

          http://server/dir/doc.djvu

       The  CGI  program  djvuserve  lets you access this same document as an indirect multi-page
       DjVu document using the following URL.

          http://server/cgi–bin/djvuserve/dir/doc.djvu/index.djvu

       Serving indirect  multi-page  DjVu  documents  provides  for  efficiently  browsing  large
       document  without  transferring  unnecessary pages over the network.  See djvu(1) for more
       information.

       Furthermore djvuserve searches certain keywords among the CGI arguments of the  URL.   The
       keyword bundled forces serving a bundled document using

          http://server/cgi–bin/djvuserve/dir/doc.djvu?bundled

       The  keyword download inserts a content disposition HTTP header that suggests to display a
       save dialog instead of displaying the document.

          http://server/cgi–bin/djvuserve/dir/doc.djvu?download

USING DJVUSERVE AS A HANDLER

       The Apache web server provides a way to  automatically  execute  djvuserve  for  all  DjVu
       documents.   This  can  be  achieved  using  the following directives in either the Apache
       configuration file or the .htaccess files.

          Action djvu-server /cgi–bin/djvuserve/
          AddHandler djvu-server .djvu

       Apache then executes program djvuserve for serving all DjVu files.  Providing the  URL  of
       DjVu  file  serves  this  DjVu  file as usual, except that bundled multipage documents are
       converted to indirect documents on the fly.  This convenience comes at the expense of  the
       computational cost of executing djvuserve whenever a DjVu file is requested.

TECHNICAL DETAILS

       Program djvuserve provides a mean to directly access any component of a bundled multi-page
       DjVu document can be accessed using an extended URL.   Suppose  that  the  component  file
       representing  page  1  is named p0001.djvu.  The following URL provides a direct access to
       this page:

          http://server/cgi–bin/djvuserve/dir/doc.djvu/p0001.djvu

       It is preferred however to access individual pages using the CGI style arguments described
       in nsdejavu(1), as in the following URL.

          http://server/cgi–bin/djvuserve/dir/doc.djvu?djvuopts&page=12

       The special component file name index.djvu is recognized as a request for the index of the
       corresponding indirect multi-page document.  In fact, when you access a  bundled  document
       using djvuserve, the browser gets redirected to the following URL:

          http://server/cgi–bin/djvuserve/dir/doc.djvu/index.djvu

       and  then  behaves as if the bundled file was a directory containing the various component
       files of an equivalent indirect document.

ACCESS CONTROL

       Program djvuserve, like many  CGI  programs,  bypasses  a  number  of  access  protections
       established  in  a web server.  Assume for instance that your web site contains DjVu files
       protected by a password.  Program djvuserve knows nothing about this protection  and  will
       happily serve any DjVu file associated with a valid URL.

       Access  control with djvuserve can be implemented by first remembering that the web server
       always executes program djvuserve via shell script /var/www/cgi–bin/djvuserve.

       This script can decide to execute the real program djvuserve on the basis  of  the  target
       filename available in the environment variable PATH_TRANSLATED.

       There  can  be several such scripts providing access to various collections of DjVu files.
       Each of these scripts can be password protected using the usual methods supported by  your
       web server.

KNOWN BUGS

       Hyperlinks  specified  using  a  relative URL may not work with djvuserve.  These URLs are
       relative to the URL of the DjVu document. Yet djvuserve changes the apparent document  URL
       http://server/dir/doc.djvu        into        the        more        complicated       URL
       http://server/cgi–bin/djvuserve/dir/doc.djvu/index.djvu.  The extra components change  the
       interpretation of relative URLs.

CREDITS

       This program was written by Leon Bottou <leonb@users.sourceforge.com>.

SEE ALSO

       djvu(1), djvmcvt(1), nsdejavu(1)