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)

DjVuLibre-3.5                                      01/22/2002                                       DJVUSERVE(1)