--- a/doc/src/site/markdown/digilib-config.md	Mon Nov 20 17:03:04 2017 +0100
+++ b/doc/src/site/markdown/digilib-config.md	Mon Nov 20 21:08:35 2017 +0100
@@ -1,15 +1,15 @@
 # Configuring digilib
 
 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.
+`WEB-INF` directory of the webapp. Alternatively you can also use 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)
 
 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
+**`basedir-list`** parameter however is **mandatory** unless you only want to serve
 the contributed example images for an evaluation.
 
 All options are defined as `parameter` elements with the attributes `name` and
@@ -62,22 +62,25 @@
 <parameter name="notfound-image" value="img/digilib-notfound.png" />
 ```
 
-This image to sent to indicate an undiscoverable image.
+This image to sent to indicate that the requested image does not exist or could not be read.
 
 ```xml
 <parameter name="use-mapping" value="false" />
 ```
 
 Enables the mapping of 'virtual directories' to actual directories in the
-filesystem.
+filesystem using a mapping file.
 
 ```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.
+[digilib-map.xml.template](https://github.com/robcast/digilib/blob/master/webapp/src/main/webapp/WEB-INF/digilib-map.xml.template)
+for an example. 
+
+The file contains `mapping` elements with a `link` attribute containing a 'virtual directory' name that is mapped to the 
+directory given in the `dir` attribute.
 
 
 ### Image processing options
@@ -86,30 +89,31 @@
 <parameter name="default-quality" value="2" />
 ```
 
-The default interpolation quality (`0` is worst).
+The default interpolation quality.
 
-**TODO** document valid value range
+* `0`: do not use interpolation (worst), 
+* `1`: use linear interpolation,
+* `2`: use bilinear interpolation and blur-before-scale (best).
 
 ```xml
 <parameter name="max-image-size" value="0" />
 ```
 
-The maximum size of delivered images, `0` means no limit.
-
-**TODO** mention measurement unit explicitly
+The maximum size of delivered images as pixel area, `40000` means up to 200x200 or 100x400, `0` means no limit.
 
 ```xml
 <parameter name="sendfile-allowed" value="true" />
 ```
 
-Defines whether requests with `mo=file` as parameter are allowed (see
+Defines whether requests with `mo=file` or `mo=rawfile` as parameter are allowed to download files (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
+Degree of subsampling on image load. This is the minimum factor that is scaled by interpolation and not by 
+subsampling, i.e. by skipping pixels.
 
 
 ### Authentication and authorization
@@ -121,19 +125,14 @@
 <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?
+Configuration file for authentication and authorization. The format and content of the configuration file
+is determined by the chosen authentication and authorization classes. 
 
 ```xml
 <parameter name="authn-token-cookie" value="id_token" />
 ```
 
-The name of the cookie that holds the authentication token.
+The name of the cookie that holds the authentication token for `digilib.auth.OpenIdAuthnOps`.
 
 ```xml
 <parameter name="authnops-class" value="digilib.auth.IpAuthnOps" />
@@ -151,18 +150,19 @@
 <parameter name="use-authorization" value="false" />
 ```
 
-Enables authorization.
+Enable or disable all authorization. If `use-authorization` is `true` it also needs to be configured
+using `authnops-class` and `authzops-class` and the `auth-file`.
 
 
 ### IIIF API options
 
-The options configure the [IIIF](iiif-api) interface.
+The options configure the IIIF interface. For more information see the [digilib IIIF documentation](iiif-api)
 
 ```xml
 <parameter name="iiif-api-version" value="2.1" />
 ```
 
-The supported IIIF API version. **FIXME**? shouldn't that be set programmatically?
+The IIIF API version for the generated `info.json` information response.  
 
 ```xml
 <parameter name="iiif-info-cors" value="true" />
@@ -186,7 +186,7 @@
 <parameter name="iiif-slash-replacement" value="!" />
 ```
 
-The character that replaces a slash in IIIF requests.
+The character that replaces a slash in the identifier of IIIF requests.
 
 
 ### Threading options
@@ -195,13 +195,13 @@
 <parameter name="max-waiting-threads" value="20" />
 ```
 
-The number of waiting requests in the queue.
+The maximum number of requests waiting in the queue before sending "service unavailable".
 
 ```xml
 <parameter name="worker-threads" value="2" />
 ```
 
-The number of working threads.
+The maximum number of concurrently working threads.
 
 ```xml
 <parameter name="worker-timeout" value="60000" />
@@ -216,23 +216,26 @@
 <parameter name="default-errmsg-type" value="image" />
 ```
 
-Defines how errors are represented. Allowed values are `code`, `image` and
+Defines how errors are presented to the user. Allowed values are `code`, `image` and
 `text`.
 
+* `image` sends an error-image as error code (see `denied-image`, `error-image`, `notfound-image` parameters).
+* `code` sends an HTTP error code, which may result in a broken image display in the browser.
+* `text` sends a plain-text error message, which may result in a broken image display in the browser.
+
 ```xml
 <parameter name="img-diskcache-allowed" value="false" />
 ```
 
-Enables the use of a disk cache for the image toolkit.
-**TODO** elaborate dis-/advantages.
+Enables the use of a disk cache for the image toolkit. Using the disk cache may leak file handles
+and lead to resource issues if digilib runs for a long time.
 
 ```xml
 <parameter name="log-config-file" value="log4j-config.xml" />
 ```
 
-Location of the logging configuration.
-
-**TODO** amend a link to a useful, elaborative resource
+Location of the logging configuration file. The current logger is 
+[Log4J 1.2](https://logging.apache.org/log4j/1.2/manual.html).
 
 
 ### Unknown category