# 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 @@ +![digilib](images/digilib-logo-big.png) + +## 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