djvuserve(1)

1DJVUSERVE(1)                     DjVuLibre-3.5                    DJVUSERVE(1)
2
3
4

NAME

6       djvuserve - Generate indirect DjVu documents on the fly.
7
8

DESCRIPTION

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

USING DJVUSERVE

16       Program djvuserve must first be installed as a CGI program for your web
17       server.  There are several ways  to  achieve  this.    The  Apache  web
18       server,  for  instance, often defines a specific directory for CGI pro‐
19       grams using the ScriptAlias directive.  Assume that the file httpd.conf
20       contains the following line:
21
22          ScriptAlias /cgi–bin/ "/var/www/cgi–bin"
23
24       It  is  then  sufficient  to  create  a  small  executable shell script
25       /var/www/cgi–bin/djvuserve containing the following lines:
26
27          #!/bin/sh
28          exec /full/path/to/djvuserve
29
30       Suppose that a large bundled multi-page DjVu document is  available  at
31       the following URL.
32
33          http://server/dir/doc.djvu
34
35       The  CGI  program  djvuserve  lets  you access this same document as an
36       indirect multi-page DjVu document using the following URL.
37
38          http://server/cgi–bin/djvuserve/dir/doc.djvu/index.djvu
39
40       Serving indirect multi-page DjVu  documents  provides  for  efficiently
41       browsing large document without transferring unnecessary pages over the
42       network.  See djvu(1) for more information.
43
44       Furthermore djvuserve searches certain keywords among the CGI arguments
45       of  the  URL.   The  keyword  bundled forces serving a bundled document
46       using
47
48          http://server/cgi–bin/djvuserve/dir/doc.djvu?bundled
49
50       The keyword download inserts a content  disposition  HTTP  header  that
51       suggests to display a save dialog instead of displaying the document.
52
53          http://server/cgi–bin/djvuserve/dir/doc.djvu?download
54

USING DJVUSERVE AS A HANDLER

56       The Apache web server provides a way to automatically execute djvuserve
57       for all DjVu documents.  This  can  be  achieved  using  the  following
58       directives  in  either  the  Apache configuration file or the .htaccess
59       files.
60
61          Action djvu-server /cgi–bin/djvuserve/
62          AddHandler djvu-server .djvu
63
64       Apache then executes program djvuserve  for  serving  all  DjVu  files.
65       Providing  the  URL of DjVu file serves this DjVu file as usual, except
66       that bundled multipage documents are converted to indirect documents on
67       the  fly.   This  convenience comes at the expense of the computational
68       cost of executing djvuserve whenever a DjVu file is requested.
69
70

TECHNICAL DETAILS

72       Program djvuserve provides a mean to directly access any component of a
73       bundled multi-page DjVu document can be accessed using an extended URL.
74       Suppose  that  the  component  file  representing  page  1   is   named
75       p0001.djvu.  The following URL provides a direct access to this page:
76
77          http://server/cgi–bin/djvuserve/dir/doc.djvu/p0001.djvu
78
79       It  is preferred however to access individual pages using the CGI style
80       arguments described in nsdejavu(1), as in the following URL.
81
82          http://server/cgi–bin/djvuserve/dir/doc.djvu?djvuopts&page=12
83
84       The special component file name index.djvu is recognized as  a  request
85       for  the  index  of the corresponding indirect multi-page document.  In
86       fact, when you access a bundled document using djvuserve,  the  browser
87       gets redirected to the following URL:
88
89          http://server/cgi–bin/djvuserve/dir/doc.djvu/index.djvu
90
91       and  then behaves as if the bundled file was a directory containing the
92       various component files of an equivalent indirect document.
93
94

ACCESS CONTROL

96       Program djvuserve, like many CGI programs, bypasses a number of  access
97       protections established in a web server.  Assume for instance that your
98       web  site  contains  DjVu  files  protected  by  a  password.   Program
99       djvuserve  knows  nothing  about this protection and will happily serve
100       any DjVu file associated with a valid URL.
101
102       Access control with djvuserve can be implemented by  first  remembering
103       that  the web server always executes program djvuserve via shell script
104       /var/www/cgi–bin/djvuserve.
105
106       This script can decide to execute the real  program  djvuserve  on  the
107       basis  of  the  target  filename  available in the environment variable
108       PATH_TRANSLATED.
109
110       There can be several such scripts providing access to  various  collec‐
111       tions  of  DjVu files.  Each of these scripts can be password protected
112       using the usual methods supported by your web server.
113
114

KNOWN BUGS

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

CREDITS

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