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)