updated documentation style and new docs for PDF generator.

Author: casties

doc/pom.xml

@@ -15,15 +15,15 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-site-plugin</artifactId>
-        <version>3.8.2</version>
+        <version>3.9.1</version>
         <configuration>
           <saveProcessedContent>true</saveProcessedContent>
         </configuration>
         <dependencies>
           <dependency>
             <groupId>org.apache.maven.doxia</groupId>
             <artifactId>doxia-module-markdown</artifactId>
-            <version>1.9</version>
+            <version>1.9.1</version>
           </dependency>
        </dependencies>
       </plugin>

doc/src/site/markdown/build-maven.md

@@ -146,8 +146,8 @@ to add `-Pservlet3` or `-Pservlet2` as well.
 
 ### pdf
 
-`-Ppdf` builds digilib with the "PDFCache" servlet to generate and download PDF files from images. 
-(see [the source](https://github.com/robcast/digilib/tree/master/pdf)).
+`-Ppdf` builds digilib with the "PDFGenerator" servlet to generate and download PDF files from images. 
+(see [the documentation](pdf-generator.html)).
 
 ## create-sprites
 

doc/src/site/markdown/features.md

@@ -29,12 +29,15 @@
 * **IIIF image API**: the digilib server provides [IIIF](http://iiif.io)
   image API (V2.1) compliant access to your images besides the digilib native server API.
 
+* **PDF generation**: the [PDFGenerator](pdf-generation.html) servlet can create custom 
+  PDF documents from images on the server.
+  
 * **OpenId Connect authentication**: the digilib server can use authentication
   information from an [OpenId Connect](http://openid.net/) identity server.
   See the [authorization](auth.html) documentation.
 
 * **CDSTAR storage backend**: the digilib server can access files on a [CDSTAR](https://cdstar.gwdg.de/) storage server.
 
-* **plugins**: there are several Digilib plugins written in Javascript to add functionality to the client side, making use of jQuery features. See the [plugins](plugins.html) documentation.
+* **client plugins**: there are several Digilib plugins written in Javascript to add functionality to the client side, making use of jQuery features. See the [plugins](plugins.html) documentation.
 
 * **digilib client API**: modify the settings, write Javascript functions or provide your own Digilib plugins and event handlers.

doc/src/site/markdown/index.md

@@ -25,7 +25,7 @@
 
 ## digilib resources
 
-<code>digilib</code>  source code, binaries and documentation can be found on the 
+**digilib** source code, binaries and documentation can be found on the 
 [digilib project pages](https://github.com/robcast/digilib)
 on [GitHub](https://github.com).
 

doc/src/site/markdown/pdf-generator.md

@@ -0,0 +1,82 @@
+# PDF generator
+
+The digilib `PDFGenerator` servlet creates custom PDF documents from images on the server 
+for download by the user. The user can specify the sequence of images, the image resolution
+and information for the generated cover page of the document. The frontend will reload
+the status page until the document has been generated and then download the document.
+Generated documents will be cached on the server to speed up subsequent requests for the same document.
+
+## Installation
+
+The `PDFGenerator` servlet and its frontend are built by the `pdf` and `frontend-pdf` modules.
+You can add both to the [manual build process](build-maven.html) using the `-Ppdf` option but it is
+easier to include the generated artifacts the `pom.xml` of your own Maven project:
+
+```
+<dependency>
+  <groupId>digilib</groupId>
+  <artifactId>digilib-frontend-pdf</artifactId>
+  <version>2.10.0</version>
+  <type>war</type>
+  <scope>runtime</scope>
+</dependency>
+```
+
+(see https://github.com/robcast/digilib-frontend-template for a basic setup)
+
+## Request
+
+The `PDFGenerator` servlet accepts the first request as a HTTP POST request with the following parameters:
+
+`fn`
+: image directory path name (required)
+
+`pgs`
+: image sequence specification (required) examples: "1-" (all pages), "1-5", "5,10,15", "1-7,9-13"
+
+`dw`
+: pixel image width (optional)
+
+`dh`
+: pixel image height (optional, default 500)
+
+`logo`
+: url of header logo for cover page (optional)
+
+`header-title`
+: header title for cover page (optional)
+
+`header-subtitle`
+: header subtitle for cover page (optional)
+
+`title`
+: document title for cover page (optional)
+
+`author`
+: document author for cover page (optional)
+
+`date`
+: document date for cover page (optional)
+
+`reference`
+: document full reference for cover page (optional, alternative to title, author, date)
+
+`online-url`
+: footer online url for cover page (optional)
+
+The very simple but functional HTML form `/pdf/form.jsp` can be used as a starting point for customization.
+
+The response to the first post request is a redirect to a HTTP GET request with an added `docid`
+parameter identifying the requested document. The following GET requests must provide the `docid`
+parameter and the response will be either a work-in-progress waiting page, an error page or the final document
+download.
+
+The `PDFGenerator` servlet can also be queried as a ReST-style API. Responses will be given as 
+JSON documents with the keys `docid`, `status` and `message` if the request carries the `Accept`
+header value `application/json`.
+
+## iText PDF license
+
+The `PDFGenerator` servlet uses the [iText PDF library](https://itextpdf.com). 
+You can use it either under an [AGPL license](https://itextpdf.com/en/how-buy/agpl-license)
+or request a commercial license from the vendor.

doc/src/site/site.xml

@@ -44,6 +44,7 @@
       <item name="Directory layout" href="image-directories.html"/>
       <item name="Java settings and tuning" href="java-settings.html"/>
       <item name="Access control" href="auth.html"/>
+      <item name="PDF generation" href="pdf-generator.html"/>
     </menu>
     <menu name="Development">
       <item name="The digilib Scaler API" href="scaler-api.html"/>