# HG changeset patch
# User robcast
# Date 1378455905 -7200
# Node ID bd7dfa8b164e4258ced8d8eb23a05923d523d520
# Parent 68625b3c5341731c2627efa694e1809ba91d0e42
move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
diff -r 68625b3c5341 -r bd7dfa8b164e .hgignore
--- a/.hgignore Wed Sep 04 09:03:23 2013 +0200
+++ b/.hgignore Fri Sep 06 10:25:05 2013 +0200
@@ -113,4 +113,10 @@
syntax: regexp
^servlet/\.project$
syntax: regexp
-^servlet/bin$
\ No newline at end of file
+^servlet/bin$
+syntax: regexp
+^doc/\.settings$
+syntax: regexp
+^doc/\.project$
+syntax: regexp
+^doc/target$
\ No newline at end of file
diff -r 68625b3c5341 -r bd7dfa8b164e doc/pom.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/pom.xml Fri Sep 06 10:25:05 2013 +0200
@@ -0,0 +1,50 @@
+
+ 4.0.0
+
+ digilib
+ digilib
+ 2.2-SNAPSHOT
+
+ digilib-doc
+ pom
+ digilib-doc
+ The Digital Image Library - documentation
+ http://digilib.berlios.de
+
+
+
+ org.apache.maven.plugins
+ maven-site-plugin
+ 3.3
+
+
+ org.apache.maven.doxia
+ doxia-module-markdown
+ 1.4
+
+
+
+
+
+
+
+
+ org.apache.maven.plugins
+ maven-project-info-reports-plugin
+ 2.7
+
+
+
+ project-team
+ mailing-list
+ scm
+ issue-tracking
+
+ license
+
+
+
+
+
+
+
\ No newline at end of file
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/markdown/build-maven.md
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/site/markdown/build-maven.md Fri Sep 06 10:25:05 2013 +0200
@@ -0,0 +1,91 @@
+# Building digilib with Maven
+
+The easiest way to get the latest and greatest digilib is the [Maven](http://maven.apache.org/) build tool.
+It will download, compile, and install the latest digilib version and all required libraries.
+
+## What you need
+
+* [Java](http://www.java.com/) (1.5 or higher)
+* [Maven](http://maven.apache.org/)
+* [Mercurial](http://mercurial.selenic.com/)
+* A Servlet container like [Tomcat](http://tomcat.apache.org/)
+or [Jetty](http://www.eclipse.org/jetty/) to run the web application.
+
+## Quick build
+
+The fastest way to build the digilib web application is to download the digilib
+project file [pom.xml](http://hg.berlios.de/repos/digilib/raw-file/tip/pom.xml)
+(download and save it) and run
+
+ mvn scm:bootstrap -N
+
+in the same directory as the `pom.xml` file.
+
+This will create a web application directory `digilib-webapp-2.2-SNAPSHOT`
+and a WAR file `digilib-webapp-2.2-SNAPSHOT-srv3.war` (or similar)
+in the subdirectory `target/checkout/webapp/target/`
+
+Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6
+and Tomcat version 7 or Jetty version 8 or later to use it.
+If you want to use the old non-Asynchronous Servlet API (2.3) add `-Pservlet2`
+to the Maven command line above.
+
+## Developer build
+
+If you are developing with digilib it is helpful to check out the source
+code separately so you can keep it around, modify it or change the configuration
+before you deploy.
+
+To check out the latest source code into the directory `digilib` run
+
+ hg clone http://hg.berlios.de/repos/digilib
+
+The digilib configuration files are now in `digilib/webapp/src/main/webapp/WEB-INF/`
+
+If you want to update your copy of digilib to the latest version at some time in the future
+just run
+
+ hg pull
+ hg up
+
+in the `digilib` directory.
+
+To build the resulting source code, change into the `digilib`
+directory you checked out above and run
+
+ mvn package
+
+This will create a web application directory `digilib-webapp-2.2-SNAPSHOT`
+and a WAR file `digilib-webapp-2.2-SNAPSHOT-srv3.war` (or similar) in
+the subdirectory `webapp/target/` .
+
+Digilib uses the Asynchronous Servlet API (3.0) by default. You will need Java version 6
+and Tomcat version 7 or Jetty version 8 or later to use it.
+If you want to use the old non-Asynchronous Servlet API (2.3) add `-Pservlet2`
+to the Maven command line above.
+
+## Deploying the web application by hand
+
+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 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)
+
+If you use the unmodified default configuration you should see the digilib logo
+and other sample images from the `sample-images` directory of the web application.
+
+## Configuring digilib
+
+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).
+
+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)
+
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/markdown/digilib-config.md
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/site/markdown/digilib-config.md Fri Sep 06 10:25:05 2013 +0200
@@ -0,0 +1,154 @@
+# 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 a different 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 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.
+
+Documentation on the directory layout and on using pre-scaled images is
+[here](image-directories.md).
+
+A minimal configuration looks like this:
+
+
+
+
+
+
+
+A more customized configuration may look like this (for a full list of
+configuration options use the source:
+[1](http://hg.berlios.de/repos/digilib/file/default/common/src/main/java/digilib/conf/DigilibConfiguration.java)
+[2](http://hg.berlios.de/repos/digilib/file/default/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java)
+[3](http://hg.berlios.de/repos/digilib/file/default/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java)
+):
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`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
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/markdown/history.md
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/site/markdown/history.md Fri Sep 06 10:25:05 2013 +0200
@@ -0,0 +1,36 @@
+## Early history of digilib (in German)
+
+### docuedit (auch DocumentDatabase, später doculight)
+
+Imageviewer mit Dokumenten-Baum Ansicht, in Java geschrieben, komplett
+Client-seitig. Entstanden vor März 1998 (müsste am MPIWG gewesen sein).
+Wesentlicher Autor Michael May (glaube ich).
+
+Von doculight gibt es hier sogar noch eine "Web-Version" von Anfang 2000
+aus Bern, die aber nicht mehr ganz funktioniert:
+
+[http://pythia2.unibe.ch/docuserver/viewerlite/frame.htm](http://pythia2.unibe.ch/docuserver/viewerlite/frame.htm)
+
+Und hier ist der Übergang zur Client-Server Lösung "gg.jsp" (noch ohne
+serverseitige Skalierung der Seiten) vom Juni 2000, das leider mangels
+JSP auf dem Server nicht mehr geht:
+
+[http://pythia2.unibe.ch/docuserver/viewerlite/gg.jsp](http://pythia2.unibe.ch/docuserver/viewerlite/gg.jsp)
+
+(Die Knöpfe sind zwar noch schlicht haben aber schon die gleichen
+Funktionen wie später)
+
+### digilib (ScaleServlet, später Scaler)
+
+Client-Server Lösung mit Javascript auf dem Client und Java auf dem Server.
+Entstanden ca. Juli 2000. Wesentlicher Autor zunächst Robert Gordesch (Stud.
+Hilfskraft MPIWG) für den Server-Teil in Java und Gerd Graßhoff (Bern) fürs
+Javascript (glaube ich), seit Februar 2001 Robert Casties (Bern, ab 2002 MPIWG),
+danach auch Christian Luginbühl. Seit Anfang 2002 Open Source Projekt bei
+BerliOS.
+
+## Articles on digilib
+
+1. Raspe, Martin; Casties, Robert; "Digilib: Wissenschaftliches Bildmaterial
+studieren und kommentierenim Internet", Jahrbuch der Max-Planck-Gesellschaft 2006,
+[http://www.mpg.de/411123/pdf.pdf](http://www.mpg.de/411123/pdf.pdf)
\ No newline at end of file
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/markdown/image-directories.md
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/site/markdown/image-directories.md Fri Sep 06 10:25:05 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
+
+
+
+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
+
+
+
+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!
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/markdown/index.md
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/site/markdown/index.md Fri Sep 06 10:25:05 2013 +0200
@@ -0,0 +1,33 @@
+
+
+## What is digilib?
+
+* `digilib` is a web based client/server technology for images. The image
+ content is processed on-the-fly by a Java Servlet on the server side so that
+ only the visible portion of the image is sent to the web browser on the client
+ side.
+* `digilib` supports a wide range of image formats and viewing options on
+ the server side while only requiring an internet browser with Javascript and a
+ low bandwidth internet connection on the client side.
+* `digilib` enables very detailed work on an image as required by
+ scholars with elaborate viewing features like an option to show images on the
+ screen in their original size.
+* `digilib` facilitates cooperation of scholars over the internet and
+ novel uses of source material by image annotations and stable references that
+ can be embedded in URLs.
+* `digilib` is Open Source Software under the Lesser General Public License,
+ jointly developed by the
+ [Max-Planck-Institute for the History of Science](http://www.mpiwg-berlin.mpg.de),
+ the [Bibliotheca Hertziana](http://www.biblhertz.it),
+ the [University of Bern](http://philoscience.unibe.ch) and others.
+
+## Where can I get digilib?
+
+`digilib` source code, binaries and documentation can be found on the
+[digilib project pages](http://developer.berlios.de/projects/digilib/)
+on [BerliOS](http://developer.berlios.de):
+
+* [Source code](http://hg.berlios.de/repos/digilib)
+* Daily built [WAR files](http://digilib.berlios.de/downloads/daily-build/)
+* Daily built [Javadoc](http://digilib.berlios.de/downloads/daily-build/javadoc/)
+* [Maven repository](http://it-dev.mpiwg-berlin.mpg.de/maven-repo/)
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/markdown/java-settings.md
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/site/markdown/java-settings.md Fri Sep 06 10:25:05 2013 +0200
@@ -0,0 +1,55 @@
+# Java VM settings for digilib
+
+The Java virtual machine (Java-VM) only uses a fixed amount of memory for
+its operations. When an operation needs more memory than available it aborts
+with an error ("out of memory error").
+
+digilib can need a lot of memory depending on the size and type of images.
+Since digilib runs as a servlet under Tomcat its in the same VM as the Tomcat
+server.
+
+The amount of memory Tomcat (version 5.0) uses is configured by creating a
+`setenv.sh` (or `setenbv.bat`) script with a line
+
+ CATALINA_OPTS="-Xmx512m"
+
+in Tomcat's `bin` directory (giving 512MB RAM in this case).
+
+You can check the amount of memory your digilib instance has available on the
+bottom of the web page `/server/dlConfig.jsp` in your digilib instance (e.g.
+
+
+# Installing JAI ImageIO
+
+In principle you should be able to install the
+[Java Advanced Imaging](http://java.sun.com/javase/technologies/desktop/media/jai/) JAI-ImageIO
+JAR file `jai_imageio.jar` (and native
+library files if available) in the `/WEB-INF/lib/` directory of the
+digilib web application as part of the default installation.
+
+You can see if the Jai-ImageIO plugin is active by checking for the
+availability of the TIFF image format under "Supported image types" on the
+[`/server/dlConfig.jsp`](http://localhost:8080/digilib/server/dlConfig.jsp)
+status page.
+
+Sometimes there are memory issues. Newer versions of Tomcat refuse to load
+the libraries and I found that in some cases digilib stopped reading TIFF files
+after a period of running. In these cases it helped to install the JAI files in
+Tomcats `lib/` directory or globally in the local Java JDK
+installation (i.e. in the Java's 'jre/lib/ext/' directory on linux).
+
+# Sample setup
+
+The current digilib setup at the MPIWG (as of December 2010):
+
+* One frontend server running the lightweight web-multiplexer [pound](http://www.apsis.ch/pound/)
+ on port 80 that distributes requests to three servers runnning digilib
+* the three servers run digilib under [Jetty](http://www.eclipse.org/jetty/) on port 8080 without Apache
+ * one server is the frontend server (Linux 32bit, Dual 2.4GHz Xeon, 2GB RAM)
+ * the other server is a separate, newer machine (Linux 64bit, Dual 1.8GHz Opteron, 2GB RAM)
+ * the third server is a separate, newer machine (Linux 32bit, Dual 2.8GHz Xeon, 4GB RAM)
+* the digilib instances (digilib 2.0b1 as of 12.12.2011) run on Jetty 8.0.4 on Java
+ 1.6.0_26 with 1GB of Java VM memory for digilib (-Xmx1024m) with JAI (1.1.3) and JAI-ImageIO (1.1)
+ installed in `Jetty/lib/ext`
+* both digilib servers access all image files over NFS (over GBit Ethernet) from a central file server
+ (Solaris 10, Sun Fire 240, multiple RAIDs on Fibrechannel)
\ No newline at end of file
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/resources/images/digilib-logo-big.png
Binary file doc/src/site/resources/images/digilib-logo-big.png has changed
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/resources/images/digilib-logo-small.png
Binary file doc/src/site/resources/images/digilib-logo-small.png has changed
diff -r 68625b3c5341 -r bd7dfa8b164e doc/src/site/site.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/site/site.xml Fri Sep 06 10:25:05 2013 +0200
@@ -0,0 +1,40 @@
+
+
+
+ org.apache.maven.skins
+ maven-fluido-skin
+ 1.3.0
+
+
+ digilib - a versatile image viewing environment for the internet
+ http://digilib.berlios.de/
+
+
+ images/digilib-logo-small.png
+ http://digilib.berlios.de/
+
+
+
+
+
+
+
+
+
diff -r 68625b3c5341 -r bd7dfa8b164e pom.xml
--- a/pom.xml Wed Sep 04 09:03:23 2013 +0200
+++ b/pom.xml Fri Sep 06 10:25:05 2013 +0200
@@ -207,6 +207,11 @@
digilib
+ digilib-doc
+ 2.2-SNAPSHOT
+
+
+ digilib
digilib-pdf
2.2-SNAPSHOT
@@ -250,5 +255,6 @@
servlet2
servlet3
webapp
+ doc
\ No newline at end of file