--- a/website/build-maven.md	Tue Aug 27 18:46:41 2013 +0200
+++ b/website/build-maven.md	Thu Aug 29 09:47:38 2013 +0200
@@ -66,13 +66,13 @@
 
 ## Deploying the web application by hand
 
-To deploy digilib just copy the web application directory into the `webapp`
+To deploy digilib just copy the web application directory or the WAR file into the `webapp`
 directory of the Servlet container.
 
 Since the URL of your digilib server starts with the name of the web application
 and the name of the web application is derived from the name of the web
-application directory **please rename the web application directory to `digitallibrary` 
-before you start**
+application directory or the WAR file **please rename the web application directory or WAR file 
+to `digitallibrary` before you start**
 
 Then you should see your digilib running at the URL 
 [http://localhost:8080/digitallibrary/jquery/digilib.html](http://localhost:8080/digitallibrary/jquery/digilib.html)
@@ -81,7 +81,7 @@
 
 To change the configuration of digilib just edit the file `digilib-config.xml`
 in the web application directory (`digitallibrary/WEB-INF/digilib-config.xml`).
-Documentation of the configuration options is [here](digilib-config.html).
+Documentation of the configuration options is [here](digilib-config.md).
 
 You can see a summary of your running digilib configuration at the URL 
 [http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp)

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/website/digilib-config.md	Thu Aug 29 09:47:38 2013 +0200
@@ -0,0 +1,149 @@
+# Configuring digilib
+
+## digilib-config.xml
+
+The main configuration for digilib is `digilib-config.xml` in the `WEB-INF` 
+directory in the webapp. 
+(If you really need another location you can define it in the `config-file`
+init-parameter to the servlet.)
+
+In the XML-based configuration file you can set several paths and options. 
+
+You have to adjust the **`basedir-list`** parameter to the directories
+where your images are installed. The directory path has to be an absolute 
+path following the conventions of your operating system (a relative path 
+is taken to be relative to the web application directory).
+
+You need only one directory if you don't provide pre-scaled low resolution 
+versions of your images. If you have pre-scaled images the directory with the 
+high-resolution images must be the first entry in the list.
+
+Documentation on the directory layout and on using pre-scaled images is 
+[here](image-directories.md).
+
+A minimal configuration looks like this:
+
+	<!-- Digilib servlet config file -->
+	<digilib-config>
+	  <!-- List of directories where images are searched.
+	       The authoritative directory with the high-resolution images
+	       is first in list. -->
+	  <parameter name="basedir-list" value="/docuserver/images" />
+	</digilib-config>
+	
+A more customized configuration may look like this:
+
+	<!-- Digilib servlet config file -->
+	<digilib-config>
+	  <!--  Image to be sent to indicate general failure. -->
+	  <parameter name="error-image" value="/docuserver/images/icons/broken.gif" />
+	
+	  <!--  Image to be sent to indicate authorization failure. -->
+	  <parameter name="denied-image" value="/docuserver/images/icons/alert.red.gif" />
+	
+	  <!-- List of directories where images are searched.
+	       The authoritative directory with the high-resolution images
+	       is first in list. -->
+	  <parameter name="basedir-list" value="/docuserver/images:/docuserver/scaled/small" />
+	
+	  <!-- Java class to use for image operations -->
+	  <parameter name="docuimage-class" value="digilib.image.ImageLoaderDocuImage" />
+	
+	  <!-- mimimum amount of scaling done with antialiasing -->
+	  <parameter name="subsample-minimum" value="2"/>
+	
+	  <!-- default interpolation quality (0=worst) -->
+	  <parameter name="default-quality" value="1"/>
+	
+	  <!-- is sending whole image files with mo=file allowed? -->
+	  <parameter name="sendfile-allowed" value="true" />
+	
+	  <!-- the a maximum size of any sent image. (0 means no limit) -->
+	  <parameter name="max-image-size" value="0" />
+	
+	  <!-- number of working threads -->
+	  <parameter name="worker-threads" value="2" />
+	
+	  <!-- number of waiting requests in queue -->
+	  <parameter name="max-waiting-threads" value="20" />
+	
+	  <!-- Restrict access to authorized users.
+	       User authentication and roles are provided by the servlet container 
+	       (see tomcat-users.xml).
+	       Authorization for resources (directories) is evaluated by the servlet 
+	       (see auth-file). -->
+	  <parameter name="use-authorization" value="false"/>
+	
+	  <!-- Location of XML file with authorization requirements. -->
+	  <parameter name="auth-file" value="digilib-auth.xml"/>
+	
+	  <!-- Part of URL to indicate authenticated access to Tomcat. -->
+	  <parameter name="auth-url-path" value="authenticated/"/>
+	
+	  <!-- use mapping of "virtual directories" to real directories on the server -->
+	  <parameter name="use-mapping" value="false"/>
+	
+	  <!-- location of XML mapping file -->
+	  <parameter name="mapping-file" value="digilib-map.xml"/>
+	
+	  <!-- location of logger config file -->
+	  <parameter name="log-config-file" value="log4j-config.xml"/>
+	</digilib-config>
+
+You can supply your own icons for the "error" and "access denied" 
+messages by the servlet. Standard images will be used if these
+parameters are not defined.
+
+You can specify the Java toolkit implementation with the `docuimage-class`
+parameter. The `ImageLoaderDocuImage` usually gives best performance
+and works with JDK 1.4 and up.
+
+You can see a summary of your running digilib configuration at the URL 
+[http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp)
+
+
+## digilib-auth.xml
+
+The digilib access authorization is defined in the file defined by the `auth-file`
+parameter (default: `digilib-auth.xml` in `WEB-INF` ).
+
+The file has two parts `diglib-paths` and `diglib-addresses`. It looks like this:
+
+	<auth-config>
+	
+	  <digilib-paths>
+	    <!-- 
+	      A user must supply one of the roles under "role"
+	      to access the directory "name".
+	      Roles under "role" must be separated by comma only (no spaces).  
+	    -->
+	    <path name="histast/eastwood-collection" role="eastwood-coll" />
+	    <path name="ptolemaios_geo" role="ptolemaios-geo" />
+	  </digilib-paths>
+	
+	  <digilib-addresses>
+	    <!-- 
+	      A computer with an ip address that matches "ip"
+	      is automatically granted all roles under "role".
+	      The ip address is matched from the left (in full quads).
+	      Roles under "role" must be separated by comma only (no spaces). 
+	    -->
+	    <address ip="127" role="local" />
+	    <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
+	    <address ip="130.92.151" role="ALL" />
+	  </digilib-addresses>
+	
+	</auth-config>
+
+`diglib-paths` defines restricted directories and the roles needed
+for access. The roles are defined with the users in `tomcat-users.xml`
+(see above). All subdirectories of the given directories have the same
+restrictions. All directories not listed here (and not subdirectories of listed
+directories) are freely accessible.
+
+`diglib-addresses` defines hosts or networks of computers that are
+automatically authenticated without username and password. Hosts can be assigned
+roles. The special keyword `ALL` authorizes for everything. If the
+role assigned to the computer is not sufficient to access a resource the user
+will be asked for username and password.
+        
\ No newline at end of file

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/website/image-directories.md	Thu Aug 29 09:47:38 2013 +0200
@@ -0,0 +1,85 @@
+# Directory layout for images
+
+In digilib all images are identified by the `fn` and (optional) `pn` parameters. 
+The value for `fn` can be a directory path or a directory path and a filename, 
+separated by slashes, e.g. "`fn=books/book1/page0002`".
+
+If `fn` is a directory path without filename `pn` is the index number of the 
+image files in this directory in alphabetical order, e.g.
+"`fn=books/book1&pn=2`". The default for `pn` is 1 i.e. the first image. 
+
+If `fn` ends in a filename `pn` is ignored. File extensions are also ignored,
+i.e. "`books/book1/page0002`" and "`books/book1/page0002.tif`" identify the same 
+image. It is recommended to omit the file extension.
+
+The directory path in `fn` is relative to the base directory in the `basedir-list`
+parameter of the `digilib-config.xml` file, e.g. if
+
+	<parameter name="basedir-list" value="/docuserver/images" />
+
+and
+
+	fn=books/book1/page0002
+
+then digilib will try to load the file
+
+	/docuserver/images/books/book1/page0002.tif
+	
+(automatically finding the right file extension)
+	
+
+## Prescaled images
+
+You can provide any number of scaled-down versions of your images that
+digilib can use when a smaller version of an image is requested. Since less data
+has to be read and processed this can speed up digilib's performance considerably.
+
+The actual process is that the client requests a certain target size,
+digilib scans all available scaled-down versions of the same image, selects the
+smallest image that is larger than the requested size and scales it down to the
+requested size.
+
+There is another optimization in digilib: if the requested image is *exactly*
+the same size and type as the pre-scaled image then the pre-scaled image is sent
+unmodified to the client which is a lot faster. So it makes sense to produce
+thumbnails of exactly 90 pixel width when they are used in an HTML page where
+all images are 90 pixel wide.
+
+The scaled-down versions of the image have to have the same file name as
+the original hi-res file. They can have a different type and extension (e.g.
+`img002.jpg` for `img002.TIFF`)
+
+The scaled down images have to have the same directory path (the part that
+shows up in digilib's "fn" parameter) as the hi-res file wile the first part of each
+directory tree is configured by the `basedir-list` parameter in
+`digilib-config.xml`.
+
+The sequence of directories in `basedir-list` is from high-res to low-res.
+Images must be present in the hires directory but they need not be present in
+all lower-res directories.
+
+e.g. if digilib-config.xml contains
+
+	<parameter name="basedir-list" value="/images:/scaled:/thumb" />
+
+and a user requests the image `books/book1/page0002` digilib looks for
+
+1. `/thumb/books/book1/page0002.jpg`
+2. `/scaled/books/book1/page002.jpg`
+3. `/images/books/book1/page002.tif`
+
+(automatically finding the right file extension) 
+and uses the first image that is bigger than or equal to the requested size.
+
+For batch-prescaling our images we use a script called "scale-o-mat" that uses a
+lot of freely available imaging libraries (ImageMagick, libtiff, netpbm) and is
+available in our public CVS [[1]](http://itgroup.mpiwg-berlin.mpg.de/cgi-bin/cvsweb.cgi/scaleomat/). 
+The script is given a
+hi-res base directory, a destination base directory, a destination size and a
+starting directory. It then processes all files in the starting directory and
+all its subdirectories and creates scaled images in corresponding directories
+under the destination base directory.
+
+We currently use prescaled thumbnails of 100 pixels and images for browser
+display of 1500 pixels. Remember that the prescaled image has to be larger (or
+the same size) than the requested image size!