--- a/doc/src/site/markdown/digilib-config.md	Mon Jun 12 16:02:44 2017 +0200
+++ b/doc/src/site/markdown/digilib-config.md	Thu Aug 17 16:20:23 2017 +0200
@@ -1,100 +1,269 @@
 # Configuring digilib
 
-## digilib-config.xml
+The main configuration for *digilib* is the XML file `digilib-config.xml` in the
+`WEB-INF` directory of the webapp or a Java properties file `digilib.properties`
+somewhere in the classpath.
+(If you really need a different location for the XML file you can define it in
+the `config-file` init-parameter to the Servlet. **TODO** add an example)
 
-The main configuration for digilib is the XML file `digilib-config.xml` in the `WEB-INF` 
-directory in the webapp or a Java properties file `digilib.properties` somewhere in the classpath.
-(If you really need a different location for the XML file you can define it in the `config-file`
-init-parameter to the Servlet.)
+In the configuration file you can set lots of paths and options. *digilib* uses
+default values for all configuration settings that meet most requirements.
+Hence you have to configure only the settings that you want to change. The
+**`basedir-list`** parameter however is **mandatory** unless you want to serve
+the contributed example images for an evaluation.
 
-In the configuration file you can set lots of paths and options. digilib uses
-default values for all configuration settings that meet most requirements
-so you have to configure only the settings that you want to change.
+All options are defined as `parameter` elements with the attributes `name` and
+`value` that are wrapped in the root element `digilib-config`. A minimal
+configuration looks like this:
 
-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).
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<digilib-config>
+    <parameter name="basedir-list" value="/usr/local/images" />
+</digilib-config>
+```
 
-You need only one directory if you don't want to 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.
+A more extensive example is included in the sources as
+[digilib-config.xml.template](https://github.com/robcast/digilib/blob/master/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template).
+
+
+## Available parameters
 
-Documentation on the directory layout and on using pre-scaled images is 
-[here](image-directories.html).
+The documented parameter values below are the defaults.
+
+If relative paths are provided as file locations, these will be resolved with
+the web application's directory as base.
 
-A minimal configuration looks like this:
+You can inspect a summary of your running digilib configuration at the URL
+`<base_url>/server/dlConfig.jsp`.
+
+### Image locations
+
+```xml
+<parameter name="basedir-list" value="sample-images" />
+```
 
-	<!-- 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 the following 
-(for another commented example see 
-[digilib-config.xml.template](https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template),
-for a full list of
-configuration options and their default values use the source:
-[DigilibConfiguration](https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibConfiguration.java),
-[DigilibServletConfiguration](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java),
-[DigilibServlet3Configuration](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java)
-):
+A list of directories where images are searched. See
+[this document](image-directories.html) for details.
+
+```xml
+<parameter name="denied-image" value="img/digilib-denied.png" />
+```
+
+This image is sent to indicate an authorization failure.
+
+```xml
+<parameter name="error-image" value="img/digilib-error.png" />
+```
+
+This image is sent to indicate a general failure.
 
-	<!-- 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" />
-	
-	  <!--  Image to be sent to indicate file-not-found. -->
-	  <parameter name="notfound-image" value="/docuserver/images/icons/notfound.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" />
-	
-	  <!-- default interpolation quality (0=worst) -->
-	  <parameter name="default-quality" value="2"/>
-	
-	  <!-- 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 -->
-	  <parameter name="use-authorization" value="false"/>
-	
-	  <!-- use mapping of "virtual directories" to real directories on the server -->
-	  <parameter name="use-mapping" value="true"/>
-	
-	  <!-- location of XML name 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>
+```xml
+<parameter name="notfound-image" value="img/digilib-notfound.png" />
+```
+
+This image to sent to indicate an undiscoverable image.
+
+```xml
+<parameter name="use-mapping" value="false" />
+```
+
+Enables the mapping of 'virtual directories' to actual directories in the
+filesystem.
+
+```xml
+<parameter name="mapping-file" value="digilib-map.xml" />
+```
+
+The location of the mapping file. Refer to
+[this template](https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-map.xml.template)
+for an example. **TODO** elaborate `link` and `dir` attribute or the whole file structure.
+
+
+### Image processing options
+
+```xml
+<parameter name="default-quality" value="2" />
+```
 
-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.
+The default interpolation quality (`0` is worst).
+
+**TODO** document valid value range
+
+```xml
+<parameter name="max-image-size" value="0" />
+```
+
+The maximum size of delivered images, `0` means no limit.
+
+**TODO** mention measurement unit explicitly
 
-If you need authorization set `use-authorization` to true and read the 
+```xml
+<parameter name="sendfile-allowed" value="true" />
+```
+
+Defines whether requests with `mo=file` as parameter are allowed (see
+[Scaler API](scaler-api.html)).
+
+```xml
+<parameter name="subsample-minimum" value="2.0" />
+```
+
+Degree of subsampling on image load. **TODO** valid / recommended value range
+
+
+### Authentication and authorization
+
+Details are provided in the
 [documentation on authentication and authorization](auth.html).
 
-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)
+```xml
+<parameter name="auth-file" value="digilib-auth.xml" />
+```
+
+Configuration file for authentication and authorization.
+
+```xml
+<parameter name="auth-url-path" value="authenticated/" />
+```
+
+This part of the URL indicates authorized access. **TODO** clarify by example?
+
+```xml
+<parameter name="authn-token-cookie" value="id_token" />
+```
+
+The name of the cookie that holds the authentication token.
+
+```xml
+<parameter name="authnops-class" value="digilib.auth.IpAuthnOps" />
+```
+
+The class to handle authentication.
+
+```xml
+<parameter name="authzops-class" value="digilib.auth.PathAuthzOps" />
+```
+
+The class to handle authorization.
+
+```xml
+<parameter name="use-authorization" value="false" />
+```
+
+Enables authorization.
+
+
+### IIIF API options
+
+The options configure the [IIIF](iiif-api) interface.
+
+```xml
+<parameter name="iiif-api-version" value="2.1" />
+```
+
+The supported IIIF API version. **FIXME**? shouldn't that be set programmatically?
+
+```xml
+<parameter name="iiif-info-cors" value="true" />
+```
+
+Enables the `Cross-Origin Resource Sharing` header in IIIF info requests.
+
+```xml
+<parameter name="iiif-image-cors" value="true" />
+```
+
+Enables the `Cross-Origin Resource Sharing` header in IIIF image requests.
+
+```xml
+<parameter name="iiif-prefix" value="IIIF" />
+```
+
+The prefix (after `Scaler`) that leads to the IIIF API.
+
+```xml
+<parameter name="iiif-slash-replacement" value="!" />
+```
+
+The character that replaces a slash in IIIF requests.
+
+
+### Threading options
 
-        
\ No newline at end of file
+```xml
+<parameter name="max-waiting-threads" value="20" />
+```
+
+The number of waiting requests in the queue.
+
+```xml
+<parameter name="worker-threads" value="2" />
+```
+
+The number of working threads.
+
+```xml
+<parameter name="worker-timeout" value="60000" />
+```
+
+Timeout for worker threads in milliseconds.
+
+
+### Assorted options
+
+```xml
+<parameter name="default-errmsg-type" value="image" />
+```
+
+Defines how errors are represented. Allowed values are `code`, `image` and
+`text`.
+
+```xml
+<parameter name="img-diskcache-allowed" value="false" />
+```
+
+Enables the use of a disk cache for the image toolkit.
+**TODO** elaborate dis-/advantages.
+
+```xml
+<parameter name="log-config-file" value="log4j-config.xml" />
+```
+
+Location of the logging configuration.
+
+**TODO** amend a link to a useful, elaborative resource
+
+
+### Unknown category
+
+**TODO** move items to appropriate sections
+
+```xml
+<parameter name="dirmeta-class" value="digilib.meta.IndexMetaDirMeta" />
+```
+
+Class for **TODO**.
+
+```xml
+<parameter name="docudirectory-class" value="digilib.io.BaseDirDocuDirectory" />
+```
+
+Class for **TODO**.
+
+```xml
+<parameter name="docuimage-class" value="digilib.image.ImageLoaderDocuImage" />
+```
+
+Class for the `DocuImage` instance, **TODO** elaborate intended use
+
+```xml
+<parameter name="docuimage-hacks" value="" />
+```
+
+**TODO** elaborate
+
+```xml
+<parameter name="filemeta-class" value="digilib.meta.IndexMetaFileMeta" />
+```
+Class for **TODO**.