DJVUSERVE(1)							   DjVuLibre-3.5						      DJVUSERVE(1)

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  computa-
       tional 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)