Initial revision

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352063 13f79535-47bb-0310-9956-ffa450edef68

.cvsignore

@@ -0,0 +1,13 @@
+.ant.properties
+dist
+build
+distributions
+prj.el
+emacs-jprj.el
+docs
+todo
+p1.log
+p2.log
+poi.ipr
+release-bin
+POILogger.log

README.txt

@@ -0,0 +1,49 @@
+
+                                  P O I
+
+                               @version@
+
+
+  What is it?
+  -----------
+
+
+
+  Where is it?
+  ------------
+
+  The home page for the POI project can be found in the POI 
+  Project web site (http://poi.sourceforge.net/). There you also find 
+  information on how to download the latest release as well as all the other 
+  information you might need regarding this project.
+
+
+  Requirements
+  ------------
+
+ The following requirements exist for installing it:
+
+   o  A Java 1.2 or later compatible virtual machine for your operating system.
+
+  Installation Instructions and Documentation
+  -------------------------------------------
+
+  The documentation available as of the date of this release is
+  included in the "docs/" directory.
+
+  Look for the most updated documentation on the POI web site.
+
+
+  Licensing and legal issues
+  --------------------------
+
+  For legal and licensing issues, please read the LICENSE files
+  in the /legal directory.
+
+
+  Thanks for using POI.
+
+                                           The POI Project
+                                           http://poi.sourceforgef.net/
+
+  

build.bat

@@ -0,0 +1,23 @@
+@echo off
+rem ----------------------------------------------------------------------------
+rem build.bat - Win32 Build Script for Apache Cocoon
+rem
+rem $Id$
+rem ----------------------------------------------------------------------------
+
+rem ----- Copy Xalan and Xerces for the build system    ------------------------
+copy lib\optional\xerces*.jar  tools\lib
+copy lib\optional\xalan*.jar   tools\lib
+copy lib\optional\xml-api*.jar tools\lib
+copy lib\optional\jtidy*.jar tools\lib
+
+rem ----- Verify and Set Required Environment Variables ------------------------
+
+REM Commented out so it always uses poi's ant -- gjs -- if not "%ANT_HOME%" == "" goto gotAntHome
+set OLD_ANT_HOME=%ANT_HOME%
+set ANT_HOME=tools
+:gotAntHome
+
+call %ANT_HOME%\bin\ant %1 %2 %3 %4 %5 %6 %7 %8 %9
+set ANT_HOME=%OLD_ANT_HOME%
+

build.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+
+echo
+echo "POI Build System            "
+echo "----------------------------"
+
+cp -f ./lib/optional/xalan*.jar ./tools/lib
+cp -f ./lib/optional/xerces*.jar ./tools/lib
+cp -f ./lib/optional/xml-api*.jar ./tools/lib
+cp -f ./lib/optional/jtidy*.jar ./tools/lib
+
+chmod u+x ./tools/bin/antRun
+chmod u+x ./tools/bin/ant
+
+unset ANT_HOME
+
+CP=$CLASSPATH
+export CP
+unset CLASSPATH
+
+$PWD/tools/bin/ant -logger org.apache.tools.ant.NoBannerLogger -emacs $@ 
+
+CLASSPATH=$CP
+export CLASSPATH

legal/LICENSE

@@ -0,0 +1,53 @@
+/* ====================================================================
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2001 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution,
+ *    if any, must include the following acknowledgment:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowledgment may appear in the software itself,
+ *    if and wherever such third-party acknowledgments normally appear.
+ *
+ * 4. The names "Apache" and "Apache Software Foundation" and
+ *    "Apache POI" must not be used to endorse or promote products
+ *    derived from this software without prior written permission. For
+ *    written permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache",
+ *    "Apache POI", nor may "Apache" appear in their name, without
+ *    prior written permission of the Apache Software Foundation.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ */

legal/LICENSE.apache

@@ -0,0 +1,50 @@
+/*
+
+ ============================================================================
+                   The Apache Software License, Version 1.1
+ ============================================================================
+ 
+ Copyright (C) @year@ The Apache Software Foundation. All rights reserved.
+ 
+ Redistribution and use in source and binary forms, with or without modifica-
+ tion, are permitted provided that the following conditions are met:
+ 
+ 1. Redistributions of  source code must  retain the above copyright  notice,
+    this list of conditions and the following disclaimer.
+ 
+ 2. Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+ 
+ 3. The end-user documentation included with the redistribution, if any, must
+    include  the following  acknowledgment:  "This product includes  software
+    developed  by the  Apache Software Foundation  (http://www.apache.org/)."
+    Alternately, this  acknowledgment may  appear in the software itself,  if
+    and wherever such third-party acknowledgments normally appear.
+ 
+ 4. The names "Apache Cocoon" and  "Apache Software Foundation" must  not  be
+    used to  endorse or promote  products derived from  this software without
+    prior written permission. For written permission, please contact
+    apache@apache.org.
+ 
+ 5. Products  derived from this software may not  be called "Apache", nor may
+    "Apache" appear  in their name,  without prior written permission  of the
+    Apache Software Foundation.
+ 
+ THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
+ INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
+ APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
+ DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
+ ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
+ (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
+ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ 
+ This software  consists of voluntary contributions made  by many individuals
+ on  behalf of the Apache Software  Foundation and was  originally created by
+ Stefano Mazzocchi  <stefano@apache.org>. For more  information on the Apache 
+ Software Foundation, please see <http://www.apache.org/>.
+ 
+*/

legal/LICENSE.resolver

@@ -0,0 +1,153 @@
+Software License Agreement
+
+SUN MICROSYSTEMS, INC.  ("SUN") IS WILLING TO LICENSE THE
+XML ENTITY AND URI RESOLVERS, VERSION 1.0 SOFTWARE TO YOU
+ONLY UPON THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS
+CONTAINED IN THIS LICENSE AGREEMENT ("AGREEMENT").  PLEASE
+READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY.
+BY INSTALLING THIS SOFTWARE, YOU ACCEPT THE TERMS AND
+CONDITIONS OF THIS AGREEMENT.  IF YOU ARE NOT WILLING TO BE
+BOUND BY ITS TERMS, SELECT THE "DECLINE" BUTTON AT THE
+BOTTOM OF THIS PAGE AND THE INSTALLATION PROCESS WILL NOT
+CONTINUE.
+
+1.0 DEFINITIONS "Licensed Software" means the XML Entity and
+URI Resolvers, Version 1.0 Software and any other machine
+readable materials (including, but not limited to,
+libraries, source files, header files, and data files) and
+any user manuals, programming guides and other documentation
+provided to you by Sun under this Agreement.
+
+2.0 LIMITED LICENSE 2.1 Sun grants to you, a non-exclusive,
+non-transferable, royalty-free and limited license to
+reproduce, modify, and create derivative works of the
+Licensed Software for the sole purpose of adding value and
+improving the Licensed Software for the development of
+applications ("Programs").  No license is granted to you for
+any other purpose.  2.2 In addition to the license granted
+in Section 2.1, Sun grants to you, a non-exclusive,
+non-transferable, royalty-free and limited license to
+distribute the Licensed Software modified by you as
+permitted in Section 2.1 ("Modified Software") in source or
+binary form, provided that; i) the Modified Software is only
+distributed bundled as a part of your Programs, ii) the
+Modified Software improves on and adds value to the Licensed
+Software, and iii) the Programs are only distributed subject
+to a license agreement that protects Sun's interests
+consistent with the terms and conditions contained in this
+Agreement.
+
+3.0 LICENSE RESTRICTIONS 3.1 You agree to reproduce any
+copyright and other proprietary right notices on any such
+copy.  3.2 Except as otherwise provided by Section 2.0, you
+may not modify or create derivative works of the Licensed
+Software, or reverse engineer, disassemble or decompile
+binary portions of the Licensed Software, or otherwise
+attempt to derive the source code from such portions.  3.3
+No right, title, or interest in or to Licensed Software, any
+trademarks, service marks, or trade names of Sun or Sun's
+licensors is granted under this Agreement.
+
+4.0 NO SUPPORT Sun is under no obligation to support
+Licensed Software or to provide you with updates or error
+corrections (collectively "Software Updates").  If Sun at
+its sole option, supplies Software Updates to you, the
+Software Updates will be considered part of Licensed
+Software, and subject to the terms of this Agreement.
+
+5.0 TERM AND TERMINATION OF AGREEMENT 5.1 You may terminate
+this Agreement at any time by destroying all copies of
+Software.  5.2 Either party may terminate this Agreement
+immediately should any Software become, or in either party's
+opinion be likely to become, the subject of a claim of
+infringement of any intellectual property right.  5.3 This
+Agreement will terminate immediately without notice from Sun
+if the you fail to comply with any provision of this
+Agreement.  5.4 Upon termination or expiration of this
+Agreement, you shall immediately cease use of and destroy
+Licensed Software and any copies thereof.  5.5 Rights and
+obligations under this Agreement which by their nature
+should survive, will remain in effect after termination or
+expiration hereof.
+
+6.0 DISCLAIMER OF WARRANTY 6.1 Licensee acknowledges that
+Licensed Software may contain errors and is not designed or
+intended for use in the design, construction, operation or
+maintenance of any nuclear facility ("High Risk
+Activities").  Sun disclaims any express or implied warranty
+of fitness for such uses.  You represent and warrant to Sun
+that you will not use, distribute or license the Licensed
+Software for High Risk Activities.  6.2 LICENSED SOFTWARE IS
+PROVIDED "AS IS".  ALL EXPRESS OR IMPLIED CONDITIONS,
+REPRESENTATIONS, AND WARRANTIES, INCLUDING ANY IMPLIED
+WARRANTY OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS
+FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT, ARE
+DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE
+HELD TO BE LEGALLY INVALID.
+
+7.0 LIMITATION OF LIABILITY 7.1 You acknowledge that the
+Licensed Software is experimental.  You acknowledge that the
+Licensed Software may have defects or deficiencies which
+cannot or will not be corrected by Sun.  You will hold Sun
+harmless from any claims based on your use or inability to
+use the Licensed Software for any purpose, and from any
+claims that later versions or releases of any Licensed
+Software furnished to you are incompatible with the Licensed
+Software provided to you under this Agreement.  7.2 You
+shall have the sole responsibility to protect adequately and
+backup your data and/or equipment used in connection with
+the Licensed Software.  You shall not claim against Sun for
+lost data, re-run time, inaccurate output, work delays or
+lost profits resulting from your use of the Licensed
+Software.  7.3 Neither party will be liable for any
+indirect, punitive, special, incidental or consequential
+damage in connection with or arising out of this Agreement
+(including loss of business, revenue, profits, use, data or
+other economic advantage), however it arises, whether for
+breach or in tort, even if that party has been previously
+advised of the possibility of such damage.
+
+8.0 U.S.  GOVERNMENT RIGHTS If this Software is being
+acquired by or on behalf of the U.S.  Government or by a
+U.S.  Government prime contractor or subcontractor (at any
+tier), then the Government's rights in the Software and
+accompanying documentation shall be only as set forth in
+this license; this is in accordance with 48 C.F.R.  227.7201
+through 227.7202-4 (for Department of Defense (DoD)
+acquisitions) and with 48 C.F.R.  2.101 and 12.212 (for
+non-DoD acquisitions).
+
+9.0 GENERAL TERMS 9.1 Any action related to this Agreement
+will be governed by California law and controlling U.S.
+federal law.  The U.N.  Convention for the International
+Sale of Goods and the choice of law rules of any
+jurisdiction will not apply.  9.2 Licensed Software and
+technical data delivered under this Agreement are subject to
+U.S.  export control laws and may be subject to export or
+import regulations in other countries.  You agree to comply
+strictly with all such laws and regulations and acknowledge
+that you have the responsibility to obtain such licenses to
+export, re-export or import as may be required after
+delivery to you.  9.3 Neither party may assign or otherwise
+transfer any of its rights or obligations under this
+Agreement, without the prior written consent of the other
+party, except that Sun may assign this Agreement to an
+affiliated company.  9.4 This Agreement is the parties'
+entire agreement relating to its subject matter.  It
+supersedes all prior or contemporaneous oral or written
+communications, proposals, conditions, representations and
+warranties and prevails over any conflicting or additional
+terms of any quote, order, acknowledgment, or other
+communication between the parties relating to its subject
+matter during the term of this Agreement.  No modification
+to this Agreement will be binding, unless in writing and
+signed by an authorized representative of each party.
+
+For inquiries please contact:  Sun Microsystems, Inc.  901
+San Antonio Road, Palo Alto, California 94303
+
+Copyright 2001 Sun Microsystems, Inc., All rights reserved.
+(LFI# 90748/FORMID#011801)
+
+
+	

src/documentation/cocoon.xconf

@@ -0,0 +1,365 @@
+<?xml version="1.0"?>
+<cocoon version="2.0">
+
+<!-- ================ Apache Cocoon configuration file ================== -->
+<!-- Please refer to the online documentation for full descriptions.
+     The notes that accompany the settings below are intended to be concise.
+-->
+
+<!-- ===================== General Components =========================== -->
+
+  <!-- Parser:
+    The default parser used in the Apache Cocoon 2 system is
+    org.apache.cocoon.components.parser.JaxpParser
+    Apache Cocoon 2 system requires a JAXP 1.1 parser.
+    If you have problems because your servlet environment uses its own
+    parser not conforming to JAXP 1.1 try using the alternative
+    XercesParser instead of the JaxpParser. To activate the XercesParser,
+    change the class attribute to
+  <parser class="org.apache.cocoon.components.parser.XercesParser"/>
+    You will also need to add a system property to your JVM
+    (probably on the startup of your servlet engine like this:
+    -Dorg.apache.cocoon.components.parser.Parser=org.apache.cocoon.components.parser.XercesParser
+
+    validate: This parameter causes the parser to be a validating parser.
+      XML validation is only being used for the documentation build.
+      (If you are going to use it elsewhere, then do so with caution.)
+      You really should have validated all of your XML documents already,
+      according to their proper DTD or schema. Do not expect Cocoon to do it.
+  -->
+  <parser class="org.apache.cocoon.components.parser.JaxpParser">
+   <parameter name="validate" value="false"/>
+  </parser>
+
+  <!-- Storing:
+    freememory: Indicates how much memory should be left free in the
+                JVM for normal operation.
+    heapsize: Indicates how big the heap size can grow to before the
+              cleanup thread kicks in.
+    objectlifetime: Indicates how long (seconds) a cache object will
+                    be hold in memory. The object will be thrown out,
+                    when the time is over.
+    interval: Indicates the interval of the cleanup thread in seconds.
+    maxobjects: Indicates how many objects will be hold in the cache.
+                When the number of maxobjects has been reached. The
+                last object in the cache will be thrown out.
+    usethread: Indicates whether we use a cleanup thread or not.
+    threadpriority: Indicates the priority of the cleanup thread.
+                    (1 is the lowest priority and 10 is the highest).
+    filesystem: Turns the filesystem storage for objects on or off.
+  -->
+  <store class="org.apache.cocoon.components.store.MRUMemoryStore">
+     <parameter name="maxobjects" value="100"/>
+     <parameter name="threadpriority" value="5"/>
+     <parameter name="filesystem" value="true"/>
+  </store>
+
+  <!-- Store Janitor:
+    freememory = How much free memory shall be available in the jvm
+    heapsize = Indicates the limit of the jvm memory consumption
+    cleanupthreadinterval = How often shall the cleanup thread check memory
+    threadpriority = Indicates the thread priority of the cleanup thread
+
+    Be careful with the heapsize and freememory paramters. Wrong values can
+    cause high cpu usage.
+    Example configuration:
+    Jvm settings: 
+      -Xms100000000 -Xmx200000000
+    store-janitor settings:
+       <parameter name="freememory" value="50000000"/>
+       <parameter name="heapsize" value="150000000"/>
+  
+    Heapsize must be higher then the -Xms parameter and freememory
+    between those both.    
+  -->
+  <store-janitor class="org.apache.cocoon.components.store.StoreJanitorImpl" logger="root.store">
+     <parameter name="freememory" value="1000000"/>
+     <parameter name="heapsize" value="60000000"/>
+     <parameter name="cleanupthreadinterval" value="10"/>
+     <parameter name="threadpriority" value="5"/>
+  </store-janitor>
+
+  <!-- Entity resolution catalogs:
+    catalog:
+    The default catalog is distributed at /resources/entities/catalog
+    This is the contextual pathname for Cocoon resources.
+    You can override this path, if necessary, using the "catalog" parameter.
+   <parameter name="catalog" value="/resources/entities/catalog"/>
+    However, it is probably desirable to leave this default catalog config
+    and declare your own local catalogs, which are loaded in addition to
+    the system catalog.
+
+    There are various ways to do local configuration (see "Entity Catalogs"
+    documentation). One way is via the CatalogManager.properties file.
+    As an additional method, you can specify the "local-catalog" parameter here.
+
+    local-catalog:
+    The full filesystem pathname to a single local catalog file.
+   <parameter name="local-catalog" value="/usr/local/sgml/mycatalog"/>
+
+    verbosity:
+    The level of messages for status/debug (messages go to standard output)
+    The following messages are provided ...
+     0 = none
+     1 = ? (... not sure yet)
+     2 = 1+, Loading catalog, Resolved public, Resolved system
+     3 = 2+, Catalog does not exist, resolvePublic, resolveSystem
+     10 = 3+, List all catalog entries when loading a catalog
+    (Cocoon also logs the "Resolved public" messages.) 
+    TODO: determine all messages at each level
+   <parameter name="verbosity" value="2"/>
+
+  -->
+  <resolver class="org.apache.cocoon.components.resolver.ResolverImpl">
+   <parameter name="catalog" value="/resources/entities/catalog"/>
+   <parameter name="verbosity" value="0"/>
+  </resolver>
+
+  <!-- XSLT Processor:
+  -->
+  <xslt-processor class="org.apache.cocoon.components.xslt.XSLTProcessorImpl" logger="root.xslt">
+     <parameter name="use-store" value="true"/>
+  </xslt-processor>
+
+  <!-- URL Factory:
+    The url factory adds special url protocols to the system, they are then
+    available inside Cocoon, e.g. as a source argument for one of the sitemap
+    components.
+  -->
+  <url-factory>
+    <protocol name="resource" class="org.apache.cocoon.components.url.ResourceURLFactory"/>
+    <protocol name="context"  class="org.apache.cocoon.components.url.ContextURLFactory"/>
+  </url-factory>
+
+  <!-- Source Handler:
+    The source handler adds special url protocols to the system, they are
+    then available inside Cocoon, e.g. as a source argument for one of the
+    sitemap components.
+  -->
+  <source-handler>
+  </source-handler>
+
+  <!-- Program Generator:
+    The ProgamGenerator builds programs from a XML document written in a
+    MarkupLanguage.
+       auto-reload:
+       root-package: persistent code repository.
+       preload:
+  -->
+  <program-generator>
+    <parameter name="auto-reload" value="false"/>
+    <parameter name="root-package" value="orgapachecocoonwww"/>
+    <parameter name="preload" value="true"/>
+  </program-generator>
+
+  <!-- Programming Languages:
+  -->
+  <programming-languages>
+    <java-language name="java">
+      <!-- compiler parameter specifies which class to use to compile Java.
+           Possible variants are Javac and Jikes compilers.
+           Javac requires javac.jar (included with Cocoon distribution).
+           Jikes requires IBM jikes compiler to be present in the PATH  -->
+      <parameter name="compiler" value="org.apache.cocoon.components.language.programming.java.Javac"/>
+      <!-- A singleton-like implementation of a ClassLoader -->
+      <parameter name="class-loader" value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
+    </java-language>
+  </programming-languages>
+
+  <!-- Class loader:
+    A singleton-like implementation of a ClassLoader.
+  -->
+  <classloader class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
+
+  <!-- Markup Languages:
+    This section defines several builtin logicsheets. A logicsheet is an XML
+    filter used to translate user-defined, dynamic markup into equivalent
+    code embedding directives for a given markup language.
+  -->
+  <markup-languages>
+    <xsp-language name="xsp">
+      <parameter name="prefix" value="xsp"/>
+      <parameter name="uri" value="http://apache.org/xsp"/>
+
+      <!-- Defines the XSP Core logicsheet for the Java language -->
+      <target-language name="java">
+        <parameter name="core-logicsheet" value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>
+        
+        <!-- The Request logicsheet (taglib) is an XSP logicsheet that wraps XML tags 
+             around standard request operations -->
+        <builtin-logicsheet>
+          <parameter name="prefix" value="xsp-request"/>
+          <parameter name="uri" value="http://apache.org/xsp/request/2.0"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
+        </builtin-logicsheet>
+       
+        <!-- The Response logicsheet (taglib) is an XSP logicsheet that wraps XML tags 
+             around standard response operations -->
+        <builtin-logicsheet>
+          <parameter name="prefix" value="xsp-response"/>
+          <parameter name="uri" value="http://apache.org/xsp/response/2.0"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/response.xsl"/>
+        </builtin-logicsheet>
+
+        <!-- The Session logicsheet (taglib) is an XSP logicsheet that wraps XML tags around 
+             standard session operations. Specifically, the Session logicsheet provides an 
+             XML interface to most methods of the HttpSession object (see the Java Servlet API 
+             Specification, version 2.2 ) for more information. -->
+        <builtin-logicsheet>
+          <parameter name="prefix" value="session"/>
+          <parameter name="uri" value="http://apache.org/xsp/session/2.0"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/session.xsl"/>
+        </builtin-logicsheet>
+
+        <builtin-logicsheet>
+          <parameter name="prefix" value="xsp-cookie"/>
+          <parameter name="uri" value="http://apache.org/xsp/cookie/2.0"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/cookie.xsl"/>
+        </builtin-logicsheet>
+
+        <!-- The ESQL logicsheet is an XSP logicsheet that performs sql queries and 
+             serializes their results as XML. This allows you to work with data from a 
+             wide variety of different sources when using Apache Cocoon. 
+        <builtin-logicsheet>
+          <parameter name="prefix" value="esql"/>
+          <parameter name="uri" value="http://apache.org/cocoon/SQL/v2"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/esql.xsl"/>
+        </builtin-logicsheet>
+-->
+        <builtin-logicsheet>
+          <parameter name="prefix" value="log"/>
+          <parameter name="uri" value="http://apache.org/xsp/log/2.0"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/log.xsl"/>
+        </builtin-logicsheet>
+
+        <builtin-logicsheet>
+          <parameter name="prefix" value="util"/>
+          <parameter name="uri" value="http://apache.org/xsp/util/2.0"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/util.xsl"/>
+        </builtin-logicsheet>
+<!--        
+         The xsp-formval taglib serves as interface to retrieve validation results 
+             from a request attribute
+        <builtin-logicsheet>
+          <parameter name="prefix" value="xsp-formval"/>
+          <parameter name="uri" value="http://apache.org/xsp/form-validator/2.0"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/form-validator.xsl"/>
+        </builtin-logicsheet>
+
+         The capture taglib is for capturing parts of the XSP-generated XML as
+             XML fragments or DOM nodes 
+        <builtin-logicsheet>
+          <parameter name="prefix" value="capture"/>
+          <parameter name="uri" value="http://apache.org/cocoon/capture/1.0"/>
+          <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/capture.xsl"/>
+        </builtin-logicsheet>
+-->
+      </target-language>
+    </xsp-language>
+
+    <!-- Defines Sitemap Core logicsheet for the Java language -->
+    <sitemap-language name="sitemap">
+      <parameter name="prefix" value="map"/>
+      <parameter name="uri" value="http://apache.org/cocoon/sitemap/1.0"/>
+
+      <target-language name="java">
+        <parameter name="core-logicsheet" value="resource://org/apache/cocoon/components/language/markup/sitemap/java/sitemap.xsl"/>
+      </target-language>
+    </sitemap-language>
+  </markup-languages>
+
+  <!-- Stream Pipeline:
+    Either collects a Reader and lets it produce a character stream
+    or connects an EventPipeline with a Serializer and lets them produce
+    the character stream.
+  -->
+  <stream-pipeline class="org.apache.cocoon.components.pipeline.CachingStreamPipeline"
+                   pool-max="32" pool-min="4" pool-grow="4"/>
+
+  <!-- Caching of stream pipeline:
+    freememory: Indicates how much memory should be left free in the
+                JVM for normal operation.
+    heapsize: Indicates how big the heap size can grow to before the
+              cleanup thread kicks in.
+    objectlifetime: Indicates how long (seconds) a cache object will
+                    be hold in memory. The object will be thrown out,
+                    when the time is over.
+    interval: Indicates the interval of the cleanup thread in seconds.
+    maxobjects: Indicates how many objects will be hold in the cache.
+                When the number of maxobjects has been reached. The
+                last object in the cache will be thrown out.
+    usethread: Indicates whether we use a cleanup thread or not.
+    threadpriority: Indicates the priority of the cleanup thread.
+                    (1 is the lowest priority and 10 is the highest).
+    filesystem: Turns the filesystem storage for objects on or off.
+  -->
+  <stream-cache class="org.apache.cocoon.components.store.MRUMemoryStore" logger="root.store">
+     <parameter name="maxobjects" value="100"/>
+     <parameter name="threadpriority" value="5"/>
+     <parameter name="filesystem" value="true"/>
+  </stream-cache>
+
+  <!-- Event Pipeline:
+    Connects the generator and the various transformers and produces a
+    character stream. Alternatives to CachingEventPipeline are:
+    <event-pipeline class="org.apache.cocoon.components.pipeline.NonCachingEventPipeline"/>
+  -->
+  <event-pipeline class="org.apache.cocoon.components.pipeline.CachingEventPipeline"
+                  pool-max="32" pool-min="4" pool-grow="4"/>
+
+  <!-- Caching of event pipeline:
+    freememory: Indicates how much memory should be left free in the
+                JVM for normal operation.
+    heapsize: Indicates how big the heap size can grow to before the
+              cleanup thread kicks in.
+    objectlifetime: Indicates how long (seconds) a cache object will
+                    be hold in memory. The object will be thrown out,
+                    when the time is over.
+    interval: Indicates the interval of the cleanup thread in seconds.
+    maxobjects: Indicates how many objects will be hold in the cache.
+                When the number of maxobjects has been reached. The
+                last object in the cache will be thrown out.
+    usethread: Indicates whether we use a cleanup thread or not.
+    threadpriority: Indicates the priority of the cleanup thread.
+                    (1 is the lowest priority and 10 is the highest).
+    filesystem: Turns the filesystem storage for objects on or off.
+  -->
+  <event-cache class="org.apache.cocoon.components.store.MRUMemoryStore" logger="root.store">
+     <parameter name="maxobjects" value="100"/>
+     <parameter name="threadpriority" value="5"/>
+     <parameter name="filesystem" value="true"/>
+  </event-cache>
+
+  <!-- SAXConnector:
+    Connects the various pipeline components.
+    LoggingSAXConnector logs SAX events between pipeline components
+    into cocoon's log file.
+    Uncomment one of the following lines for using the SAXConnector.
+  <sax-connector class="org.apache.cocoon.components.saxconnector.LoggingSAXConnector"/>
+  -->
+
+<!-- ======================== The sitemap  ============================== -->
+
+  <!-- Reloading of the sitemap:
+    The check-reload attribute determines if the sitemap is reloaded on change.
+    Set to "no", the sitemap is generated once at startup.
+    Set to "yes", the sitemap is regenerated if it changes.
+
+    The reload-method specifies the method for the regeneration:
+    asynchron: If the sitemap changes, the sitemap is regenerated at the
+               next request in the background and the incoming request is
+               served with the old sitemap. All subsequent requests are
+               served with the old sitemap until the regeneration in the
+               background has finished.
+    synchron: If the sitemap changes, the sitemap is regenerated at the
+              next request. When the regeneration is finished, the request
+              (and all subsequent ones) is served with the new sitemap.
+
+    For development environment, set the reload-method to synchron and the
+    check-reload to yes.
+    For production environment, it is advisable to set the reload-method to
+    asynchron and for more safety the check-reload to no.
+  -->
+  <sitemap file="sitemap.xmap" reload-method="synchron" check-reload="no"/>
+
+</cocoon>

src/documentation/linkalarm-readme.txt

@@ -0,0 +1,28 @@
+The LinkAlarm report for xml.apache.org/cocoon/ is at
+http://reports.linkalarm.com/373104199608/
+
+LinkAlarm scans are run after each release to detect any
+issues that need to be addressed prior to the next release.
+
+The LinkAlarm report gives detailed HTML views of the situation
+in an easy-to-read style. However, the summary file that is
+explained below has concise info about actual broken links.
+One other LinkAlarm page that is of special interest is the
+"mailto:" validation page (those errors are not included in
+the summary listing below).
+
+To facilitate the management of link mending by the cocoon-dev
+team, there is a summary file in the HEAD CVS at
+ documentation/linkalarm-broken.txt
+This tab-delimited file has the following format ...
+
+status problem_link referring_page response_code meaning comment
+
+where "status" has these codes ...
+ - ... not yet addressed
+ F ... fixed
+ ? ... has some issue (see the "comment" field)
+ [1-3] ... external link has been broken for n runs
+
+To reduce duplication of effort, please update the "status"
+tag for each issue that you might address.

src/documentation/sitemap.xmap

@@ -0,0 +1,211 @@
+<?xml version="1.0"?>
+
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+
+<!-- =========================== Components ================================ -->
+
+ <map:components>
+
+  <map:generators default="file">
+   <map:generator  name="file"        src="org.apache.cocoon.generation.FileGenerator" label="content"/>
+   <!-- FIXME: Change this once better view handling is implemented -->
+   <map:generator  name="file-nolabel" src="org.apache.cocoon.generation.FileGenerator"/>
+  </map:generators>
+
+  <map:transformers default="xslt">
+   <map:transformer     name="xslt"      src="org.apache.cocoon.transformation.TraxTransformer">
+    <use-request-parameters>false</use-request-parameters>
+    <use-browser-capabilities-db>false</use-browser-capabilities-db>
+   </map:transformer>
+  </map:transformers>
+
+  <map:readers default="resource">
+   <map:reader name="resource"       src="org.apache.cocoon.reading.ResourceReader"/>
+  </map:readers>
+
+  <map:serializers default="html">
+   <map:serializer name="html"   mime-type="text/html"        src="org.apache.cocoon.serialization.HTMLSerializer">
+     <encoding>iso8859-1</encoding>
+   </map:serializer>
+   <map:serializer name="xml"    mime-type="text/xml"         src="org.apache.cocoon.serialization.XMLSerializer"/>
+   <map:serializer name="links"                               src="org.apache.cocoon.serialization.LinkSerializer"/>
+  </map:serializers>
+
+  <map:matchers default="wildcard">
+   <map:matcher name="wildcard" src="org.apache.cocoon.matching.WildcardURIMatcher"/>
+  </map:matchers>
+ </map:components>
+
+<!-- =========================== Views =================================== -->
+
+ <map:views>
+  <map:view name="content" from-label="content">
+   <map:serialize type="xml"/>
+  </map:view>
+
+  <map:view name="links" from-position="last">
+   <map:transform src="stylesheets/filterlinks.xsl"/>
+   <map:serialize type="links"/>
+  </map:view>
+
+ </map:views>
+
+<!-- =========================== Pipelines ================================= -->
+
+ <map:pipelines>
+
+  <!-- C2 documentation pipeline -->
+  <map:pipeline>
+   <map:match pattern="">
+    <map:redirect-to uri="index.html"/>
+   </map:match>
+
+   <map:match pattern="**book-**.xml">
+     <map:generate src="xdocs/{1}book.xml"/>
+       <map:transform src="stylesheets/book2menu.xsl">
+         <map:parameter name="use-request-parameters" value="true"/>
+         <map:parameter name="resource" value="{2}.html"/>
+       </map:transform>
+     <map:serialize type="xml"/>
+   </map:match>
+
+   <map:match pattern="body-todo.xml">
+     <map:generate type="file-nolabel" src="xdocs/todo.xml"/>
+     <map:transform src="stylesheets/todo2document.xsl" label="content"/>     
+     <map:transform src="stylesheets/document2docbook.xsl"/>
+     <map:transform src="stylesheets/docbook2body.xsl"/>
+     <map:serialize/>
+   </map:match>
+
+   <map:match pattern="body-changes.xml">
+     <map:generate type="file-nolabel" src="xdocs/changes.xml"/>
+     <map:transform src="stylesheets/changes2document.xsl" label="content"/>
+     <map:transform src="stylesheets/document2docbook.xsl"/>
+     <map:transform src="stylesheets/docbook2body.xsl"/>
+     <map:serialize/>
+   </map:match>
+
+   <map:match pattern="body-faq.xml">
+     <map:generate type="file-nolabel" src="xdocs/faq.xml"/>
+     <map:transform src="stylesheets/faq2document.xsl" label="content"/>
+     <map:transform src="stylesheets/document2docbook.xsl"/>
+     <map:transform src="stylesheets/docbook2body.xsl"/>
+     <map:serialize/>
+   </map:match>
+
+   <!-- Generate the "doclist" - list of all documentation
+     The first match generates each book.xml and adds a new attribute "uri".
+     The second match aggregates each book.xml into a doclist and
+     then converts it to a document.
+   -->
+   <map:match pattern="doclist/xdocs/**book.xml">
+     <map:generate src="xdocs/{1}book.xml"/>
+     <map:transform src="stylesheets/doclist.xsl">
+       <map:parameter name="uri" value="{1}"/>
+     </map:transform>
+     <map:serialize type="xml"/>
+   </map:match>
+   <map:match pattern="body-doclist.xml">
+     <map:aggregate element="doclist">
+       <map:part src="cocoon:/doclist/xdocs/book.xml"/>
+       <map:part src="cocoon:/doclist/xdocs/plan/book.xml"/>
+       <map:part src="cocoon:/doclist/xdocs/poifs/book.xml"/>
+       <map:part src="cocoon:/doclist/xdocs/hdf/book.xml"/>
+       <map:part src="cocoon:/doclist/xdocs/hssf/book.xml"/>
+       <map:part src="cocoon:/doclist/xdocs/utils/book.xml"/>     
+     </map:aggregate>
+     <map:transform src="stylesheets/doclist2document.xsl"/>
+     <map:transform src="stylesheets/document2html.xsl"/>
+     <map:serialize type="html"/>
+   </map:match>
+
+   <map:match pattern="body-**.xml">
+     <map:generate src="xdocs/{1}.xml"/>
+     <map:transform src="stylesheets/document2docbook.xsl"/>
+     <map:transform src="stylesheets/docbook2body.xsl"/>
+     <map:serialize/>
+   </map:match>
+
+   <map:match pattern="*.xml">
+    <map:aggregate element="site">
+     <map:part src="cocoon:/book-{1}.xml"/>
+     <map:part src="cocoon:/body-{1}.xml" label="content"/>
+    </map:aggregate>
+    <map:transform src="stylesheets/site2xhtml.xsl">
+       <map:parameter name="use-request-parameters" value="true"/>
+       <map:parameter name="header" value="graphics/{1}-header.jpg"/>
+     </map:transform>
+    <map:serialize/>
+   </map:match>
+
+   <map:match pattern="*.html">
+    <map:aggregate element="site">
+     <map:part src="cocoon:/book-{1}.xml"/>
+     <map:part src="cocoon:/body-{1}.xml" label="content"/>
+    </map:aggregate>
+    <map:transform src="stylesheets/site2xhtml.xsl">
+       <map:parameter name="use-request-parameters" value="true"/>
+       <map:parameter name="header" value="graphics/{1}-header.jpg"/>
+     </map:transform>
+    <map:serialize/>
+   </map:match>
+
+   <map:match pattern="**/*.html">
+    <map:aggregate element="site">
+     <map:part src="cocoon:/{1}/book-{1}/{2}.xml"/>
+     <map:part src="cocoon:/body-{1}/{2}.xml" label="content"/>
+    </map:aggregate>
+    <map:transform src="stylesheets/site2xhtml.xsl">
+       <map:parameter name="use-request-parameters" value="true"/>
+       <map:parameter name="header" value="graphics/{2}-header.jpg"/>
+     </map:transform>
+    <map:serialize/>
+   </map:match>
+
+   <!-- ================  Static  =========================== -->
+
+   <map:match pattern="**sample/**">
+    <map:read src="xdocs/{1}sample/{2}" mime-type="text/plain"/>
+   </map:match>
+
+   <map:match pattern="**.txt">
+    <map:read src="xdocs/{1}.txt" mime-type="text/plain"/>
+   </map:match>
+
+   <map:match pattern="**resources/script.js">
+     <map:read src="stylesheets/script-cli.js" mime-type="application/javascript"/>
+   </map:match>
+
+   <map:match pattern="**resources/**.js">
+     <map:read src="stylesheets/{2}.js" mime-type="application/javascript"/>
+   </map:match>
+
+   <map:match pattern="**.css">
+    <map:read src="{1}.css" mime-type="text/css"/>
+   </map:match>
+
+   <map:match pattern="**images/*.png">
+    <map:read src="images/{2}.png" mime-type="image/png"/>
+   </map:match>
+
+   <map:match pattern="**images/*.jpg">
+    <map:read src="images/{2}.jpg" mime-type="image/jpeg"/>
+   </map:match>
+
+   <map:match pattern="**images/*.gif">
+    <map:read src="images/{2}.gif" mime-type="image/gif"/>
+   </map:match>
+
+   <map:match pattern="**graphics/**-*.jpg">
+     <map:generate src="svg/{3}.xml"/>
+     <map:transform src="svg/addlabel.xsl">
+       <map:parameter name="use-request-parameters" value="true"/>
+       <map:parameter name="label" value="{2}"/>
+     </map:transform>
+     <map:serialize type="svg2jpeg"/>
+   </map:match>
+
+  </map:pipeline>
+ </map:pipelines>
+
+</map:sitemap>

src/documentation/stylesheets/announcement.xsl

@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet version="1.0"
+xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+  <xsl:template match="changes">
+    <xsl:variable name="file" select="concat('../', @file)"/>
+    <xsl:variable name="version" select="@version"/>
+    <xsl:apply-templates select="document($file)/changes/release[attribute::version=string($version)]"/>
+  </xsl:template>
+</xsl:stylesheet>

src/documentation/stylesheets/announcement2txt.xsl

@@ -0,0 +1,108 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet version="1.0"
+xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <xsl:import href="announcement.xsl"/>
+  <xsl:output method="text" indent="no"/>
+
+  <xsl:template match="announcement">
+    <xsl:variable name="titlelen" select="string-length(project)+9"/>
+    <text>
+      <xsl:value-of select="project"/><xsl:text> Released
+</xsl:text>
+      <xsl:call-template name="line">
+        <xsl:with-param name="len" select="$titlelen"/>
+      </xsl:call-template>
+      <xsl:text>
+</xsl:text>
+      <xsl:apply-templates select="abstract"/>
+      <xsl:apply-templates select="body"/>
+      <xsl:text>
+For more information about </xsl:text>
+      <xsl:value-of select="project"/>
+      <xsl:text>, please go to
+</xsl:text>
+      <xsl:value-of select="@site"/>
+      <xsl:text>
+
+Changes with </xsl:text>
+      <xsl:value-of select="project"/>
+      <xsl:text>
+
+</xsl:text>
+      <xsl:apply-templates select="changes"/>
+    </text>
+  </xsl:template>
+
+  <xsl:template match="project"/>
+  <xsl:template match="title"/>
+
+  <xsl:template match="subproject">
+    <xsl:variable name="titlelen" select="string-length(title)"/>
+    <xsl:text>
+</xsl:text>
+    <xsl:value-of select="title"/>
+    <xsl:text>
+</xsl:text>
+    <xsl:call-template name="line">
+      <xsl:with-param name="len" select="$titlelen"/>
+    </xsl:call-template>
+    <xsl:text>
+</xsl:text>
+    <xsl:apply-templates select="abstract"/>
+    <xsl:text>
+For more information about </xsl:text>
+    <xsl:value-of select="title"/>
+    <xsl:text>, please go to
+</xsl:text>
+    <xsl:value-of select="@site"/>
+    <xsl:text>
+
+Changes with </xsl:text>
+    <xsl:value-of select="title"/>
+    <xsl:text>
+
+</xsl:text>
+    <xsl:apply-templates select="changes"/>
+  </xsl:template>
+
+  <xsl:template match="abstract">
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="p">
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="link">
+    <xsl:value-of select="."/>
+    <xsl:text> (</xsl:text>
+    <xsl:value-of select="@href"/>
+    <xsl:text>)</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="release">
+    <xsl:for-each select="action">
+      <xsl:text>*) </xsl:text>
+      <xsl:value-of select="normalize-space(.)"/><xsl:text> </xsl:text>
+      <xsl:if test="@dev">
+        <xsl:text>[</xsl:text>
+	<xsl:value-of select="@dev"/>
+	<xsl:text>]</xsl:text>
+      </xsl:if>
+      <xsl:text>
+
+</xsl:text>
+    </xsl:for-each>
+  </xsl:template>
+
+  <xsl:template name="line">
+    <xsl:param name="len"/>
+    <xsl:if test="number($len) > 0">
+      <xsl:text>-</xsl:text>
+      <xsl:call-template name="line">
+        <xsl:with-param name="len" select="number($len)-1"/>
+      </xsl:call-template>
+    </xsl:if>
+  </xsl:template>
+</xsl:stylesheet>

src/documentation/stylesheets/book2menu.xsl

@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+
+  <xsl:template match="book">
+    <menu>
+      <xsl:apply-templates/>
+    </menu>
+  </xsl:template>
+
+  <xsl:template match="project">
+    <br/><a href="{@href}"><font color="#F3510C" size="+1"><xsl:value-of select="@label"/></font></a><br/>
+  </xsl:template>
+
+  <xsl:template match="menu">
+    <font color="#000000" size="+1"><xsl:value-of select="@label"/></font>
+    <font size="-1">
+      <ul>
+        <xsl:apply-templates/>
+      </ul>
+    </font><br/>
+  </xsl:template>
+
+  <xsl:template match="menu-item">
+    <xsl:if test="not(@type) or @type!='hidden'">
+      <li><a href="{@href}"><font size="-1"><xsl:value-of select="@label"/></font></a></li>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template match="node()|@*" priority="-1"/>
+</xsl:stylesheet>
+

src/documentation/stylesheets/changes2document.xsl

@@ -0,0 +1,58 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+ <xsl:import href="copyover.xsl"/>
+
+ <xsl:param name="name"/>
+
+ <xsl:variable name="bugzilla">http://nagoya.apache.org/bugzilla/show_bug.cgi?id=</xsl:variable>
+
+ <xsl:template match="changes">
+  <document>
+   <header>
+    <title><xsl:value-of select="@title"/></title>
+   </header>
+   <body>
+    <xsl:apply-templates/>
+   </body>
+  </document>
+ </xsl:template>
+
+ <xsl:template match="release">
+  <s2 title="{$name} {@version} ({@date})">
+   <sl>
+    <xsl:apply-templates/>
+   </sl>
+  </s2>
+ </xsl:template>
+
+ <xsl:template match="action">
+  <li>
+   <icon src="images/{@type}.jpg" alt="{@type}"/>
+   <xsl:apply-templates/>
+   <xsl:text>(</xsl:text><xsl:value-of select="@dev"/><xsl:text>)</xsl:text>
+
+   <xsl:if test="@due-to">
+    <xsl:text> Thanks to </xsl:text>
+    <link href="mailto:{@due-to-email}"><xsl:value-of select="@due-to"/></link>
+    <xsl:text>.</xsl:text>
+   </xsl:if>
+
+   <xsl:if test="@fixes-bug">
+    <xsl:text> Fixes </xsl:text>
+    <link href="{$bugzilla}{@fixes-bug}">
+     <xsl:text>bug </xsl:text><xsl:value-of select="@fixes-bug"/>
+    </link>
+    <xsl:text>.</xsl:text>
+   </xsl:if>
+  </li>
+ </xsl:template>
+
+ <xsl:template match="devs">
+  <!-- remove -->
+ </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/copyover.xsl

@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+  <xsl:template match="@*|*|text()|processing-instruction()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|*|text()|processing-instruction()"/>
+    </xsl:copy>
+  </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/docbook2body.xsl

@@ -0,0 +1,441 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+
+  <xsl:template match="book">
+    <body>
+      <title><xsl:value-of select="title"/></title>
+      <center>
+        <table width="80%">
+          <tr>
+            <td bgcolor="#F3DD61">
+              <br/><center><b><xsl:value-of select="title"/><xsl:if test="subtitle"><xsl:text>: </xsl:text><xsl:value-of select="subtitle"/></xsl:if></b></center>
+              <br/>
+            </td>
+          </tr>
+        </table>
+      </center><br/>
+      <xsl:apply-templates select="dedication"/>
+      <xsl:apply-templates select="bookinfo"/>
+    </body>
+  </xsl:template>
+
+  <xsl:template match="chapter|article|appendix">
+    <body>
+    <xsl:if test="normalize-space(title)!=''">
+      <title><xsl:value-of select="title"/></title>
+      <center>
+        <table width="80%">
+          <tr>
+            <td bgcolor="#F3DD61">
+              <font size="+1" face="Arial,sans-serif"><center><b><xsl:value-of select="title"/></b></center></font>
+            </td>
+          </tr>
+        </table>
+      </center>
+      </xsl:if>
+      
+      <xsl:if test="subtitle">
+        <font color="#525D76"><i><xsl:value-of select="subtitle"/></i></font><br/>
+      </xsl:if>
+
+      <font color="#000000" size="-2">
+        <p>
+          <xsl:for-each select="//authorgroup/author">
+            <xsl:choose>
+              <xsl:when test="position()=1">by</xsl:when>
+              <xsl:otherwise>, </xsl:otherwise>
+            </xsl:choose>
+          </xsl:for-each>
+          <a href="mailto:{address/email}">
+            <xsl:if test="honorific"><xsl:value-of select="honorific"/>. </xsl:if>
+            <xsl:if test="firstname"><xsl:value-of select="firstname"/> </xsl:if>
+            <xsl:value-of select="surname"/>
+          </a>
+        </p>
+      </font>
+
+      
+        <xsl:apply-templates select="para"/>
+      <br/>
+
+      <xsl:apply-templates select="section">
+        <xsl:with-param name="level" select="1"/>
+      </xsl:apply-templates>
+
+      <xsl:apply-templates select="//footnote" mode="base"/>
+    </body>
+  </xsl:template>
+
+  <xsl:template match="title|subtitle"/>
+
+  <xsl:template match="author">
+    <body>
+      <title>
+        <xsl:value-of select="honorific"/><xsl:text>. </xsl:text>
+        <xsl:value-of select="firstname"/><xsl:text> </xsl:text>
+        <xsl:value-of select="surname"/>
+      </title>
+      <center>
+        <table width="80%">
+          <tr>
+            <td bgcolor="#F3DD61">
+              <br/><center><b><xsl:text>Author: </xsl:text><xsl:value-of select="honorific"/><xsl:text>. </xsl:text><xsl:value-of select="firstname"/><xsl:text> </xsl:text><xsl:value-of select="surname"/></b></center>
+              <br/>
+            </td>
+          </tr>
+        </table>
+      </center><br/>
+      <div align="right">
+        <table border="0" cellpadding="2" cellspacing="0" width="100%">
+          <tr>
+            <td bgcolor="#525D76">
+              <font color="#ffffff" size="+1"><b>Affiliations</b></font>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <br/>
+                <ul>
+                  <xsl:apply-templates select="affiliation"/>
+                </ul>
+            
+            </td>
+          </tr>
+        </table>
+      </div><br/>
+      <xsl:apply-templates select="authorblurb"/>
+    </body>
+  </xsl:template>
+
+  <xsl:template match="affiliation">
+    <li>
+      <xsl:text>[</xsl:text><xsl:value-of select="shortaffil"/><xsl:text>] </xsl:text>
+      <b><xsl:value-of select="jobtitle"/></b>
+      <i><xsl:value-of select="orgname"/><xsl:if test="orgdiv"><xsl:text>/</xsl:text><xsl:value-of select="orgdiv"/></xsl:if></i>
+    </li>
+  </xsl:template>
+
+  <xsl:template match="authorblurb">
+    <div align="right">
+      <table border="0" cellpadding="2" cellspacing="0" width="100%">
+        <tr>
+          <td bgcolor="#525D76">
+            <font color="#ffffff" size="+1"><b>Bio</b></font>
+          </td>
+        </tr>
+        <tr>
+          <td>
+            <br/>
+              <ul>
+                <xsl:apply-templates/>
+              </ul>
+            
+          </td>
+        </tr>
+      </table>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="honorific|firstname|surname|orgdiv|orgname|shortaffil|jobtitle"/>
+
+  <xsl:template match="revhistory">
+    <body>
+      <title>Revision History</title>
+      <center>
+        <table width="80%">
+          <tr>
+            <td bgcolor="#F3DD61">
+              <br/><center><b>Revision History</b></center>
+              <br/>
+            </td>
+          </tr>
+        </table>
+      </center><br/>
+      <div align="right">
+        <table border="0" cellpadding="2" cellspacing="0" width="100%">
+          <xsl:variable name="unique-revisions" 
+            select="revision[not(revnumber=preceding-sibling::revision/revnumber)]/revnumber"/>
+          <xsl:variable name="base" select="."/>
+          <xsl:for-each select="$unique-revisions">
+          <tr>
+            <td bgcolor="#525D76">
+              <font color="#ffffff">
+                <b>Revision <xsl:value-of select="."/> 
+                   (<xsl:value-of select="$base/revision[revnumber=current()]/date"/>)
+                </b>
+              </font>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <br/>
+                <ul>
+                  <xsl:apply-templates select="$base/revision[revnumber=current()]"/>
+                </ul>
+              
+            </td>
+          </tr>
+          </xsl:for-each>
+        </table>
+      </div>
+    </body>
+  </xsl:template>
+
+  <xsl:template match="para">
+    <p align="justify"><xsl:apply-templates/></p>
+  </xsl:template>
+
+  <xsl:template match="emphasis"><em><xsl:apply-templates/></em></xsl:template>
+
+  <xsl:template match="revision">
+    <li>
+      <xsl:choose>
+        <xsl:when test="@revisionflag='added'">
+          <img align="absmiddle" alt="added" border="0" src="images/add.jpg"/>
+        </xsl:when>
+        <xsl:when test="@revisionflag='changed'">
+          <img align="absmiddle" alt="changed" border="0" src="images/update.jpg"/>
+        </xsl:when>
+        <xsl:when test="@revisionflag='deleted'">
+          <img align="absmiddle" alt="deleted" border="0" src="images/remove.jpg"/>
+        </xsl:when>
+        <xsl:when test="@revisionflag='off'">
+          <img align="absmiddle" alt="off" border="0" src="images/fix.jpg"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <img align="absmiddle" alt="changed" border="0" src="images/update.jpg"/>
+        </xsl:otherwise>
+      </xsl:choose>
+      <xsl:value-of select="revremark"/>
+      <xsl:text> (</xsl:text><xsl:value-of select="authorinitials"/><xsl:text>)</xsl:text>
+    </li>
+  </xsl:template>
+
+  <xsl:template match="revnumber|revremark|authorinitials|date"/>
+
+  <xsl:template match="section">
+    <xsl:param name="level"/>
+
+    <div align="right">
+      <table border="0" cellpadding="2" cellspacing="0">
+        <xsl:attribute name="width"><xsl:value-of select="number(100)-(1*(number($level)-1))"/>%</xsl:attribute>
+        <tr>
+          <td bgcolor="#525D76">
+            <font color="#ffffff">
+              <xsl:attribute name="size">
+                <xsl:choose>
+                  <xsl:when test="number($level)=1">+1</xsl:when>
+                  <xsl:when test="number($level)=2">+0</xsl:when>
+                  <xsl:otherwise>-<xsl:value-of select="number($level)-2"/></xsl:otherwise>
+                </xsl:choose>
+              </xsl:attribute>
+              <font face="Arial,sans-serif"><b><xsl:value-of select="title"/></b></font>
+            </font>
+          </td>
+        </tr>
+        <tr>
+          <td>
+              <br/>
+              <xsl:apply-templates>
+                <xsl:with-param name="level" select="number($level)+1"/>
+              </xsl:apply-templates>
+          </td>
+        </tr>
+      </table>
+    </div><br/>
+  </xsl:template>
+
+  <xsl:template match="bookinfo">
+    <div align="right">
+      <table border="0" cellpadding="2" cellspacing="0" width="100%">
+        <tr>
+          <td bgcolor="#525D76">
+            <font color="#ffffff" size="+1">
+              <b><xsl:value-of select="edition"/></b><xsl:text> </xsl:text>
+              <i><font size="0">pub. <xsl:value-of select="pubdate"/></font></i>
+            </font>
+          </td>
+        </tr>
+        <tr>
+          <td>
+              <br/>
+              <xsl:apply-templates/>
+          </td>
+        </tr>
+      </table>
+    </div><br/>
+  </xsl:template>
+
+  <xsl:template match="dedication">
+    <div align="right">
+      <table border="0" cellpadding="2" cellspacing="0" width="100%">
+        <tr>
+          <td bgcolor="#525D76">
+            <font color="#ffffff" size="+1">
+              <b>Dedication</b>
+            </font>
+          </td>
+        </tr>
+        <tr>
+          <td>
+              <br/>
+              <xsl:apply-templates/>
+          </td>
+        </tr>
+      </table>
+    </div><br/>
+  </xsl:template>
+
+  <xsl:template match="edition|pubdate|year|holder"/>
+
+  <xsl:template match="copyright">
+    <p>Copyright &#x00A9;<xsl:value-of select="year"/> by <xsl:value-of select="holder"/>.<br/>
+      <i>All rights reserved.</i>
+    </p>
+  </xsl:template>
+
+  <xsl:template match="legalnotice">
+    <div align="center">
+      <table border="1" cellpadding="2" cellspacing="2">
+        <tr>
+          <td><xsl:apply-templates/></td>
+        </tr>
+      </table>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="programlisting">
+    <div align="center">
+      <table border="1" cellpadding="2" cellspacing="2">
+        <tr>
+          <td>
+            <pre>
+              <xsl:apply-templates/>
+            </pre>
+          </td>
+        </tr>
+      </table>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="orderedlist"><ol><xsl:apply-templates/></ol></xsl:template>
+
+  <xsl:template match="listitem"><li><xsl:apply-templates/></li></xsl:template>
+
+  <xsl:template match="itemizedlist"><ul><xsl:apply-templates/></ul></xsl:template>
+
+  <xsl:template match="classname|function|parameter"><code><xsl:apply-templates/><xsl:if test="name(.)='function'"><xsl:text>()</xsl:text></xsl:if></code></xsl:template>
+
+  <xsl:template match="blockquote">
+    <div align="center">
+      <table border="1" cellpadding="2" cellspacing="2">
+        <xsl:if test="title">
+          <tr>
+            <td bgcolor="#525D76">
+              <font color="#ffffff"><xsl:value-of select="title"/></font>
+            </td>
+          </tr>
+        </xsl:if>
+        <tr>
+          <td bgcolor="#c0c0c0">
+            <font color="#023264" size="-1"><xsl:apply-templates/></font>
+          </td>
+        </tr>
+      </table>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="warning">
+    <div align="center">
+      <table border="1" cellpadding="2" cellspacing="2">
+        <xsl:if test="title">
+          <tr>
+            <td bgcolor="#800000">
+              <font color="#ffffff"><xsl:value-of select="title"/></font>
+            </td>
+          </tr>
+        </xsl:if>
+        <tr>
+          <td bgcolor="#c0c0c0">
+            <font color="#023264" size="-1"><xsl:apply-templates/></font>
+          </td>
+        </tr>
+      </table>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="ulink"><a href="{@uri}"><xsl:apply-templates/></a></xsl:template>
+
+  <xsl:template match="footnote"><sup><a href="#{generate-id(.)}"><xsl:value-of select="generate-id(.)"/></a></sup></xsl:template>
+
+  <xsl:template match="footnote" mode="base">
+    <div align="left">
+      <a name="{generate-id(.)}"/><font size="-2"><xsl:value-of select="generate-id(.)"/><xsl:text>) </xsl:text><i><xsl:value-of select="."/></i></font>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="figure">
+    <div align="center">
+      <table border="0" cellpadding="2" cellspacing="2">
+        <tr>
+          <td bgcolor="#525D76"><font color="#ffffff" size="0"><xsl:value-of select="title"/></font></td>
+        </tr>
+        <xsl:apply-templates/>
+      </table>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="graphic">
+    <tr>
+      <td><img border="0" alt="{@srccredit}" src="{@fileref}"/></td>
+    </tr>
+    <xsl:if test="@srccredit">
+      <tr>
+        <td><font size="-1"><ul><li><xsl:value-of select="@srccredit"/></li></ul></font></td>
+      </tr>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template match="table">
+    <table border="0" cellpadding="2" cellspacing="2" width="100%">
+      <xsl:apply-templates/>
+    </table>
+  </xsl:template>
+
+  <xsl:template match="tgroup">
+    <xsl:apply-templates select="thead|tbody|tfoot"/>
+  </xsl:template>
+
+  <xsl:template match="thead">
+    <xsl:apply-templates select="row" mode="head"/>
+  </xsl:template>
+
+  <xsl:template match="row" mode="head">
+    <th><xsl:apply-templates/></th>
+  </xsl:template>
+
+  <xsl:template match="row">
+    <tr><xsl:apply-templates/></tr>
+  </xsl:template>
+
+  <xsl:template match="tbody|tfoot">
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="entry">
+    <td align="left" bgcolor="#a0ddf0" valign="top">
+      <font color="#000000" size="-1"><xsl:apply-templates/></font>
+    </td>
+  </xsl:template>
+
+  <xsl:template match="trademark"><xsl:apply-templates/><sup>TM</sup></xsl:template>
+
+  <xsl:template match="node()|@*" priority="-1">
+    <xsl:copy>
+      <xsl:apply-templates select="node()|@*"/>
+    </xsl:copy>
+  </xsl:template>
+</xsl:stylesheet>
+

src/documentation/stylesheets/docbook2fo.xsl

@@ -0,0 +1,742 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"
+                version="1.0">
+
+  <xsl:template match="book">
+    <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
+   
+    <fo:layout-master-set>
+        <fo:simple-page-master master-name="title"
+                               page-height="11in"
+                               page-width="8.5in"
+                               margin-top="1in"
+                               margin-bottom="1in"
+                               margin-left="1.25in"
+                               margin-right="1.5in">
+          <fo:region-before extent=".5in" region-name="title-header"/>
+          <fo:region-body margin-top="1in" margin-bottom="1in"/>
+          <fo:region-after extent=".5in" region-name="title-footer"/>
+        </fo:simple-page-master>
+
+        <fo:simple-page-master master-name="inside"
+                               page-height="11in"
+                               page-width="8.5in"
+                               margin-top="1in"
+                               margin-bottom="1in"
+                               margin-left="1.5in"
+                               margin-right="1.25in">
+          <fo:region-before extent=".5in" region-name="inside-header"/>
+          <fo:region-body margin-top="1in" margin-bottom="1in"/>
+          <fo:region-after extent=".5in" region-name="inside-footer"/>
+        </fo:simple-page-master>
+
+        <fo:simple-page-master master-name="even-page"
+                               page-height="11in" 
+                               page-width="8.5in"
+                               margin-top="1in" 
+                               margin-bottom="1in" 
+                               margin-left="1.25in" 
+                               margin-right="1in">
+          <fo:region-before extent=".5in" region-name="even-header"/>
+          <fo:region-body margin-top=".5in" margin-bottom=".5in"/>
+          <fo:region-after extent=".5in" region-name="even-footer"/>
+        </fo:simple-page-master>
+
+        <fo:simple-page-master master-name="odd-page"
+                               page-height="11in"
+                               page-width="8.5in"
+                               margin-top="1in"
+                               margin-bottom="1in"
+                               margin-left="1in"
+                               margin-right="1.25in">
+          <fo:region-before extent=".5in" region-name="odd-header"/>
+          <fo:region-body margin-top=".5in" margin-bottom=".5in"/>
+          <fo:region-after extent=".5in" region-name="odd-footer"/>
+        </fo:simple-page-master>
+
+        <fo:page-sequence-master master-name="chapter">
+          <fo:repeatable-page-master-alternatives>
+            <fo:conditional-page-master-reference master-name="title"
+                                                  page-position="first"
+                                                  odd-or-even="odd"/>
+            <fo:conditional-page-master-reference master-name="odd-page"
+                                                  odd-or-even="odd"
+                                                  blank-or-not-blank="not-blank"/>
+            <fo:conditional-page-master-reference master-name="even-page"
+                                                  page-position="last"/>
+            <fo:conditional-page-master-reference master-name="even-page"
+                                                  odd-or-even="even"/>
+          </fo:repeatable-page-master-alternatives>
+        </fo:page-sequence-master>
+      </fo:layout-master-set>
+
+      <fo:page-sequence master-name="title">
+        <xsl:if test="bookinfo/authorgroup">
+          <fo:static-content flow-name="title-footer">
+            <fo:block font-family="serif"
+                      font-size="16pt"
+                      font-style="italic"
+                      text-align="end">
+              <xsl:for-each select="bookinfo/authorgroup/author">
+                <xsl:value-of select="firstname"/>
+                <xsl:text> </xsl:text>
+                <xsl:value-of select="surname"/>
+              </xsl:for-each>
+            </fo:block>
+          </fo:static-content>
+        </xsl:if>
+        <fo:flow flow-name="xsl-region-body">
+          <fo:block font-family="serif"
+                    font-size="48pt"
+                    font-weight="bold">
+            <xsl:value-of select="title"/>
+          </fo:block>
+          <xsl:if test="subtitle">
+            <fo:block font-family="serif"
+                      font-size="24pt"
+                      border-top-style="solid"
+                      border-top-width=".5pt"
+                      space-before="12pt"
+                      text-align="end">
+              <xsl:value-of select="subtitle"/>
+            </fo:block>
+          </xsl:if>
+        </fo:flow>
+      </fo:page-sequence>
+      <xsl:apply-templates/>
+      <xsl:call-template name="authors"/>
+    </fo:root>
+  </xsl:template>
+
+  <xsl:template match="chapter|article|appendix">
+    <fo:page-sequence force-page-count="end-on-even" master-name="chapter">
+      <fo:title><xsl:value-of select="title"/></fo:title>
+      <fo:static-content flow-name="even-header">
+        <fo:block text-align="start"
+                  line-height="12pt"
+                  font-style="italic"
+                  font-family="serif"
+                  font-size="10pt"
+                  border-after-style="solid"
+                  border-after-width=".5pt">
+          <xsl:value-of select="/book/title"/>
+        </fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="even-footer">
+        <fo:block text-align="start"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="odd-header">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  font-style="italic"
+                  font-family="serif"
+                  font-size="10pt"
+                  border-after-style="solid"
+                  border-after-width=".5pt">
+          <xsl:value-of select="title"/>
+        </fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="odd-footer">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="title-footer">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:flow flow-name="xsl-region-body">
+        <fo:block space-before="2in" font-family="serif" font-size="24pt" font-weight="bold">
+          <xsl:value-of select="title"/>
+        </fo:block>
+        <xsl:if test="subtitle">
+          <fo:block font-style="italic"
+                    font-family="serif"
+                    font-size="18pt"
+                    space-after="10pt">
+            <xsl:value-of select="subtitle"/>
+          </fo:block>
+        </xsl:if>
+        <xsl:apply-templates/>
+        <xsl:apply-templates select="/bookinfo/authorgroup"/>
+      </fo:flow>
+    </fo:page-sequence>
+  </xsl:template>
+
+  <xsl:template match="title|subtitle"/>
+  <xsl:template match="honorific|firstname|surname|orgdiv|orgname|shortaffil|jobtitle"/>
+
+  <xsl:template match="bookinfo/revhistory">
+    <fo:block font-family="serif" font-size="10pt" font-weight="bold" space-before="10pt">
+      Revision History:
+    </fo:block>
+    <xsl:variable name="unique-revisions" 
+                  select="revision[not(revnumber=preceding-sibling::revision/revnumber)]/revnumber"/>
+    <xsl:variable name="base" select="."/>
+    <xsl:for-each select="$unique-revisions">
+      <fo:block font-family="serif"
+                font-size="8pt">
+        <xsl:value-of select="$base/revision[revnumber=current()]/date"/>: Revision <xsl:value-of select="."/>
+      </fo:block>
+    </xsl:for-each>
+  </xsl:template>
+
+  <xsl:template match="book/revhistory">
+    <fo:page-sequence force-page-count="end-on-even" master-name="chapter">
+      <fo:title>Revision History</fo:title>
+      <fo:static-content flow-name="even-header">
+        <fo:block text-align="start"
+                  line-height="12pt"
+                  font-style="italic"
+                  font-family="serif"
+                  font-size="10pt"
+                  border-after-style="solid"
+                  border-after-width=".5pt">
+          <xsl:value-of select="/book/title"/>
+        </fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="even-footer">
+        <fo:block text-align="start"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="odd-header">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  font-style="italic"
+                  font-family="serif"
+                  font-size="10pt"
+                  border-after-style="solid"
+                  border-after-width=".5pt">
+          <xsl:value-of select="title"/>
+        </fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="odd-footer">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="title-footer">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:flow flow-name="xsl-region-body">
+        <fo:block space-before="2in" font-family="serif" font-size="24pt" font-weight="bold" space-after="10pt">
+          Revision History
+        </fo:block>
+        <xsl:variable name="unique-revisions" 
+                      select="revision[not(revnumber=preceding-sibling::revision/revnumber)]/revnumber"/>
+        <xsl:variable name="base" select="."/>
+        <xsl:for-each select="$unique-revisions">
+          <fo:block font-weight="bold"
+                    font-family="serif"
+                    font-size="14pt"
+                    space-before="10pt">
+            Revision <xsl:value-of select="."/>
+            (<xsl:value-of select="$base/revision[revnumber=current()]/date"/>)
+          </fo:block>
+          <fo:list-block provisional-distance-between-starts="9mm"
+                   provisional-label-separation="3mm">
+            <xsl:apply-templates select="$base/revision[revnumber=current()]"/>
+          </fo:list-block>
+        </xsl:for-each>
+      </fo:flow>
+    </fo:page-sequence>
+  </xsl:template>
+
+  <xsl:template match="para">
+    <fo:block space-after="8pt"
+              font-family="serif"><xsl:apply-templates/></fo:block>
+  </xsl:template>
+
+  <xsl:template match="emphasis">
+    <fo:inline font-style="italic"><xsl:apply-templates/></fo:inline>
+  </xsl:template>
+
+  <xsl:template match="revision">
+    <fo:list-item>
+      <fo:list-item-label start-indent="3mm" end-indent="label-end()">
+        <fo:block>&#x2022;</fo:block>
+      </fo:list-item-label>
+      <fo:list-item-body start-indent="body-start()">
+        <fo:block>
+          <xsl:apply-templates/>
+          <fo:inline font-variant="small-caps">
+            <xsl:value-of select="@revisionflag"/><xsl:text>&#x2014;</xsl:text>
+          </fo:inline>
+          <xsl:value-of select="revremark"/>
+          <xsl:text> (</xsl:text><xsl:value-of select="authorinitials"/><xsl:text>)</xsl:text>
+        </fo:block>
+      </fo:list-item-body>
+    </fo:list-item>
+  </xsl:template>
+
+  <xsl:template match="revnumber|revremark|authorinitials|date"/>
+
+  <xsl:template match="section">
+    <xsl:param name="level">0</xsl:param>
+    <xsl:variable name="size" select="16-(number($level)*2)"/>
+
+    <fo:block font-family="serif"
+              font-size="{$size}pt"
+              font-weight="bold"
+              space-before="12pt">
+      <xsl:value-of select="title"/>
+    </fo:block>
+    <xsl:apply-templates>
+      <xsl:with-param name="level" select="number($level)+1"/>
+    </xsl:apply-templates>
+  </xsl:template>
+
+  <xsl:template match="bookinfo">
+    <fo:page-sequence master-name="inside">
+      <fo:flow flow-name="xsl-region-body">
+        <fo:block font-weight="bold" font-size="14pt">
+          <xsl:value-of select="title"/>
+        </fo:block>
+        <xsl:if test="subtitle">
+          <fo:block font-weight="bold" font-size="10pt">
+            <xsl:value-of select="subtitle"/>
+          </fo:block>
+        </xsl:if>
+        <xsl:if test="authorgroup">
+          <fo:block font-size="10pt">
+            <xsl:text>by </xsl:text>
+            <xsl:for-each select="authorgroup/author">
+              <xsl:if test="not(position()=1)">
+                <xsl:text>, </xsl:text>
+              </xsl:if>
+              <xsl:if test="honorific">
+                <xsl:value-of select="honorific"/><xsl:text>. </xsl:text>
+              </xsl:if>
+              <xsl:value-of select="firstname"/>
+              <xsl:text> </xsl:text>
+              <xsl:value-of select="surname"/>
+            </xsl:for-each>
+          </fo:block>
+        </xsl:if>
+        <xsl:apply-templates select="copyright"/>
+        <fo:block space-before="10pt" font-size="10pt">
+          <xsl:value-of select="edition"/><xsl:text> published </xsl:text>
+          <xsl:value-of select="pubdate"/>
+        </fo:block>
+        <xsl:apply-templates select="revhistory"/>
+        <xsl:apply-templates select="legalnotice"/>
+      </fo:flow>
+    </fo:page-sequence>
+  </xsl:template>
+
+
+  <xsl:template name="authors">
+    <fo:page-sequence force-page-count="end-on-even" master-name="chapter">
+      <fo:title>About the Authors</fo:title>
+      <fo:static-content flow-name="even-header">
+        <fo:block text-align="start"
+                  line-height="12pt"
+                  font-style="italic"
+                  font-family="serif"
+                  font-size="10pt"
+                  border-after-style="solid"
+                  border-after-width=".5pt">
+          <xsl:value-of select="/book/title"/>
+        </fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="even-footer">
+        <fo:block text-align="start"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="odd-header">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  font-style="italic"
+                  font-family="serif"
+                  font-size="10pt"
+                  border-after-style="solid"
+                  border-after-width=".5pt">
+          About the Authors
+        </fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="odd-footer">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:static-content flow-name="title-footer">
+        <fo:block text-align="end"
+                  line-height="12pt"
+                  border-before-style="solid"
+                  border-before-width=".5pt"
+                  font-family="serif"
+                  font-size="10pt"><fo:page-number/></fo:block>
+      </fo:static-content>
+      <fo:flow flow-name="xsl-region-body">
+        <fo:block space-before="2in" font-family="serif" font-size="24pt" font-weight="bold" space-after="10pt">
+          About the Authors
+        </fo:block>
+        <xsl:apply-templates select="/book/bookinfo/authorgroup/author"/>
+      </fo:flow>
+    </fo:page-sequence>
+  </xsl:template>
+
+  <xsl:template match="author">
+    <fo:block font-family="serif"
+              font-size="16pt"
+              font-weight="bold"
+              space-before="12pt">
+      <xsl:value-of select="honorific"/><xsl:text>. </xsl:text>
+      <xsl:value-of select="firstname"/><xsl:text> </xsl:text>
+      <xsl:value-of select="surname"/>
+    </fo:block>
+    <fo:block font-family="serif"
+              font-size="14pt"
+              font-weight="bold"
+              space-before="12pt">
+      Affiliations
+    </fo:block>
+    <fo:list-block provisional-distance-between-starts="9mm"
+                   provisional-label-separation="3mm">
+      <xsl:apply-templates select="affiliation"/>
+    </fo:list-block>
+    <xsl:apply-templates select="authorblurb"/>
+  </xsl:template>
+
+  <xsl:template match="affiliation">
+    <fo:list-item>
+      <fo:list-item-label start-indent="50%" end-indent="label-end()">
+        <fo:block>&#x2022;</fo:block>
+      </fo:list-item-label>
+      <fo:list-item-body start-indent="body-start()">
+        <fo:block>
+          <xsl:text>[</xsl:text><xsl:value-of select="shortaffil"/><xsl:text>] </xsl:text>
+          <fo:inline font-weight="bold"><xsl:value-of select="jobtitle"/><xsl:text> </xsl:text></fo:inline>
+          <fo:inline font-style="italic">
+            <xsl:value-of select="orgname"/>
+            <xsl:if test="orgdiv"><xsl:text>/</xsl:text><xsl:value-of select="orgdiv"/></xsl:if>
+          </fo:inline>
+        </fo:block>
+      </fo:list-item-body>
+    </fo:list-item>
+  </xsl:template>
+
+  <xsl:template match="authorblurb">
+    <fo:block font-family="serif"
+              font-size="14pt"
+              font-weight="bold"
+              space-before="12pt">
+      Bio
+    </fo:block>
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="dedication">
+    <fo:page-sequence master-name="title">
+      <fo:flow flow-name="xsl-region-body">
+        <xsl:for-each select="para">
+          <fo:block font-style="italic" font-family="serif" space-before="3in" font-size="10pt" text-align="center">
+            <xsl:apply-templates/>
+          </fo:block>
+        </xsl:for-each>
+      </fo:flow>
+    </fo:page-sequence>
+    <fo:page-sequence master-name="inside">
+      <fo:flow flow-name="xsl-region-body">
+        <fo:block> </fo:block>
+      </fo:flow>
+    </fo:page-sequence>
+  </xsl:template>
+
+  <xsl:template match="edition|pubdate|year|holder"/>
+
+  <xsl:template match="copyright">
+    <fo:block font-size="10pt" space-before="10pt">
+      Copyright &#x00A9;<xsl:value-of select="year"/> by <xsl:value-of select="holder"/>.
+      All rights reserved.
+    </fo:block>
+  </xsl:template>
+
+  <xsl:template match="legalnotice">
+    <fo:block font-size="8pt"
+              text-align="justify"
+              space-before="20pt"
+              width="7.5in"
+              font-family="serif">
+      <xsl:apply-templates/>
+    </fo:block>
+  </xsl:template>
+
+  <xsl:template match="programlisting">
+    <fo:block font-family="monospace"
+              font-size="10pt"
+              background-color="#f0f0f0"
+              white-space-collapse="false"
+              keep-together="always">
+       <xsl:apply-templates/>
+    </fo:block>
+  </xsl:template>
+
+  <xsl:template match="orderedlist|itemizedlist">
+    <fo:list-block provisional-distance-between-starts="9mm"
+                   provisional-label-separation="3mm">
+      <xsl:apply-templates/>
+    </fo:list-block>
+  </xsl:template>
+
+  <xsl:template match="orderedlist/listitem">
+    <fo:list-item>
+      <fo:list-item-label start-indent="50%" end-indent="label-end()">
+        <fo:block>
+          <xsl:number format="1."/>
+        </fo:block>
+      </fo:list-item-label>
+      <fo:list-item-body start-indent="body-start()">
+        <fo:block>
+          <xsl:apply-templates/>
+        </fo:block>
+      </fo:list-item-body>
+    </fo:list-item>
+  </xsl:template>
+
+  <xsl:template match="itemizedlist/listitem">
+    <fo:list-item>
+      <fo:list-item-label start-indent="50%" end-indent="label-end()">
+        <fo:block>&#x2022;</fo:block>
+      </fo:list-item-label>
+      <fo:list-item-body start-indent="body-start()">
+        <fo:block>
+          <xsl:apply-templates/>
+        </fo:block>
+      </fo:list-item-body>
+    </fo:list-item>
+  </xsl:template>
+
+  <xsl:template match="classname|function|parameter">
+    <fo:inline font-family="monospace">
+      <xsl:apply-templates/><xsl:if test="name(.)='function'"><xsl:text>()</xsl:text></xsl:if>
+    </fo:inline>
+  </xsl:template>
+
+  <xsl:template match="blockquote">
+    <fo:block margin-left="1in"
+              margin-right="1in"
+              font-weight="bold"
+              font-size="10pt"
+              font-family="serif"
+              space-before="10pt"
+              border-before-style="solid"
+              border-start-style="solid"
+              border-end-style="solid"
+              background-color="#000000"
+              color="#ffffff">
+      <xsl:value-of select="title"/>
+    </fo:block>
+    <fo:block margin-left="1in"
+              margin-right="1in"
+              font-family="serif"
+              font-size="8pt"
+              border-after-style="solid"
+              border-start-style="solid"
+              border-end-style="solid"
+              background-color="#f0f0f0"
+              padding-start="3pt"
+              padding-end="3pt"
+              padding-before="3pt"
+              padding-after="3pt"
+              space-after="20pt">
+      <xsl:apply-templates/>
+    </fo:block>
+  </xsl:template>
+
+  <xsl:template match="warning">
+    <fo:block margin-left="1in"
+              margin-right="1in"
+              font-weight="bold"
+              font-size="10pt"
+              font-family="serif"
+              space-before="10pt"
+              border-before-style="solid"
+              border-start-style="solid"
+              border-end-style="solid"
+              background-color="#800000"
+              color="#ffffff">
+      Warning: <xsl:value-of select="title"/>
+    </fo:block>
+    <fo:block margin-left="1in"
+              margin-right="1in"
+              font-family="serif"
+              font-size="8pt"
+              border-after-style="solid"
+              border-start-style="solid"
+              border-end-style="solid"
+              background-color="#f0f0f0"
+              padding-start="3pt"
+              padding-end="3pt"
+              padding-before="3pt"
+              padding-after="3pt">
+      <xsl:apply-templates/>
+    </fo:block>
+  </xsl:template>
+
+  <xsl:template match="ulink">
+    <fo:basic-link external-destination="{@uri}"><xsl:apply-templates/></fo:basic-link>
+  </xsl:template>
+
+  <xsl:template match="footnote">
+    <fo:footnote>
+      <fo:inline>
+        (see <xsl:value-of select="generate-id()"/> below)
+      </fo:inline>
+      <fo:footnote-body>
+        <fo:block font-family="serif"
+                  font-size="8pt"
+                  line-height="12pt"
+                  font-style="italic">
+          <xsl:value-of select="generate-id()"/>) <xsl:value-of select="."/>
+        </fo:block>
+      </fo:footnote-body>
+    </fo:footnote>
+  </xsl:template>
+
+  <xsl:template match="figure">
+    <fo:block text-align="center" font-weight="bold" font-family="serif" space-before="10pt" space-after="20pt">
+      <xsl:value-of select="title"/>
+      <xsl:apply-templates/>
+    </fo:block>
+  </xsl:template>
+
+  <xsl:template match="graphic">
+    <fo:external-graphic src="build/documentation/resources/{@fileref}">
+      <xsl:attribute name="content-type">
+        <xsl:text>content-type:image/</xsl:text>
+        <xsl:value-of select="translate(@format,'ABCDEFGHIJKLMNOPQRSTUVWXYZ','abcdefghijklmnopqrstuvwxyz')"/>
+      </xsl:attribute>
+    </fo:external-graphic>
+    <xsl:if test="@srccredit">
+      <fo:block font-size="8pt" font-family="serif" font-style="italic">
+        &#x2022; <xsl:value-of select="@srccredit"/>
+      </fo:block>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template match="table">
+    <fo:table width="100%" table-layout="fixed">
+      <xsl:apply-templates/>
+    </fo:table>
+  </xsl:template>
+
+  <xsl:template match="colspec">
+    <fo:table-column>
+      <xsl:attribute name="column-number">
+        <xsl:number count="colspec"/>
+      </xsl:attribute>
+      <xsl:attribute name="column-width">
+        <xsl:call-template name="calc.column.width">
+          <xsl:with-param name="colwidth">
+            <xsl:value-of select="@colwidth"/>
+          </xsl:with-param>
+        </xsl:call-template>
+      </xsl:attribute>
+    </fo:table-column>
+  </xsl:template>
+
+  <xsl:template match="tgroup">
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="thead">
+    <fo:table-header>
+      <xsl:apply-templates/>
+    </fo:table-header>
+  </xsl:template>
+
+  <xsl:template match="tfoot">
+    <fo:table-footer>
+      <xsl:apply-templates/>
+    </fo:table-footer>
+  </xsl:template>
+
+  <xsl:template match="row">
+    <fo:table-row><xsl:apply-templates/></fo:table-row>
+  </xsl:template>
+
+  <xsl:template match="tbody">
+    <fo:table-body>
+      <xsl:apply-templates/>
+    </fo:table-body>
+  </xsl:template>
+
+  <xsl:template match="entry">
+    <fo:table-cell>
+      <xsl:apply-templates/>
+    </fo:table-cell>
+  </xsl:template>
+
+  <xsl:template name="calc.column.width">
+    <xsl:param name="colwidth">1*</xsl:param>
+
+    <xsl:if test="contains($colwidth, '*')">
+      <xsl:text>proportional-column-width(</xsl:text>
+      <xsl:value-of select="substring-before($colwidth, '*')"/>
+      <xsl:text>)</xsl:text>
+    </xsl:if>
+
+    <xsl:variable name="width-units">
+      <xsl:choose>
+        <xsl:when test="contains($colwidth, '*')">
+          <xsl:value-of select="normalize-space(substring-after($colwidth, '*'))"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="normalize-space($colwidth)"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+
+    <xsl:variable name="width"
+                  select="normalize-space(translate($width-units, '+-0123456789.abcdefghijklmnopqrstuvwxyz', '+-0123456789.'))"/>
+
+    <xsl:variable name="units"
+                 select="normalize-space(translate($width-units, 'abcdefghijklmnopqrstuvwxyz+-0123456789.', 'abcdefghijklmnopqrstuvwxyz'))"/>
+
+    <xsl:value-of select="$width"/>
+
+    <xsl:choose>
+      <xsl:when test="$units='pi'">pc</xsl:when>
+      <xsl:when test="$units='' and $width != ''">pt</xsl:when>
+      <xsl:otherwise><xsl:value-of select="$units"/></xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <xsl:template match="trademark"><xsl:apply-templates/>&#x2122;</xsl:template>
+
+</xsl:stylesheet>
+

src/documentation/stylesheets/doclist.xsl

@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+ <xsl:param name="uri"/>
+
+ <xsl:template match="book">
+  <book title="{@title}" uri="{$uri}">
+    <xsl:copy-of select="node()"/>
+  </book>
+ </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/doclist2document.xsl

@@ -0,0 +1,85 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+ <xsl:template match="doclist">
+  <document>
+   <header>
+    <title>List of all documentation</title>
+   </header>
+   <body>
+    <s1 title="Documentation List">
+     <p>
+      This complete list shows, at a glance, how all of the documentation
+      fits together within the hierarchy of sections.
+<!--      For an overview of the documentation see the new
+      &quot;Table of Contents&quot;. -->
+     </p>
+     <p>
+      The side-panel of each actual document is used to reach other documents
+      that are relevant to that section. The side-panel will change, according
+      to that section's location in the documentation hierarchy.
+     </p>
+    </s1>
+    <xsl:apply-templates/>
+   </body>
+  </document>
+ </xsl:template>
+
+ <xsl:template match="book">
+  <s1 title="{@title}">
+   <xsl:if test="position()=1">
+    <p>This first section is a list of the top-level documentation
+     (and is a replica of this page's side-panel).</p>
+   </xsl:if>
+   <xsl:apply-templates/>
+  </s1>
+ </xsl:template>
+
+ <xsl:template match="menu">
+  <xsl:if test="@label!='Navigation'">
+  <p><strong><xsl:value-of select="@label"/></strong></p>
+   <ul>
+    <xsl:apply-templates>
+     <xsl:with-param name="uri" select="../@uri"/>
+    </xsl:apply-templates>
+   </ul>
+  </xsl:if>
+ </xsl:template>
+
+ <xsl:template match="menu-item">
+  <xsl:param name="uri"/>
+  <xsl:if test="not(@type) or @type!='hidden'">
+   <xsl:if test="@label!='Main' and @label!='User Documentation'">
+<!-- FIXME: ensure href is not full URL scheme:// -->
+<!--
+  (uri=<xsl:value-of select="$uri"/> href=<xsl:value-of select="@href"/>)
+-->
+    <li><link href="{$uri}{@href}"><xsl:value-of select="@label"/></link>
+    </li>
+   </xsl:if>
+  </xsl:if>
+ </xsl:template>
+
+ <xsl:template match="external">
+  <xsl:param name="uri"/>
+  <xsl:if test="not(@type) or @type!='hidden'">
+   <xsl:choose>
+    <!-- FIXME: specially handle menu item "API (Javadoc)", it causes a bug. -->
+    <xsl:when test="starts-with(@label,'API')">
+     <li><link href="http://xml.apache.org/cocoon/apidocs/"><xsl:value-of select="@label"/></link></li>
+<!-- FIXME: here is the bug:
+     <li><link href="{@href}"><xsl:value-of select="@label"/></link></li>
+     <li><xsl:value-of select="@label"/>href=<xsl:value-of select="@href"/></li>
+-->
+    </xsl:when>
+    <xsl:otherwise>
+     <li><link href="{@href}"><xsl:value-of select="@label"/></link></li>
+    </xsl:otherwise>
+   </xsl:choose>
+  </xsl:if>
+ </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/document2docbook.xsl

@@ -0,0 +1,177 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+
+  <xsl:template match="document">
+    <article>
+      <articleinfo>
+        <authorgroup>
+          <xsl:for-each select="header/person">
+            <author>
+              <firstname><xsl:value-of select="@name"/></firstname>
+              <address><email><xsl:value-of select="@email"/></email></address>
+            </author>
+          </xsl:for-each>
+        </authorgroup>
+      </articleinfo>
+      <title><xsl:value-of select="header/title"/></title>
+      <xsl:apply-templates select="body"/>
+    </article>
+  </xsl:template>
+
+  <xsl:template match="changes">
+    <revhistory>
+      <xsl:apply-templates select="//action"/>
+    </revhistory>
+  </xsl:template>
+
+  <xsl:template match="action">
+    <revision>
+      <xsl:attribute name="revisionflag">
+        <xsl:choose>
+          <xsl:when test="@type='add'">added</xsl:when>
+          <xsl:when test="@type='update'">changed</xsl:when>
+          <xsl:when test="@type='remove'">deleted</xsl:when>
+          <xsl:when test="@type='fix'">off</xsl:when>
+          <xsl:otherwise>changed</xsl:otherwise>
+        </xsl:choose>
+      </xsl:attribute>
+      <revnumber><xsl:value-of select="../@version"/></revnumber>
+      <date><xsl:value-of select="../@date"/></date>
+      <authorinitials><xsl:value-of select="@dev"/></authorinitials>
+      <revremark>
+        <xsl:value-of select="."/>
+      </revremark>
+    </revision>
+  </xsl:template>
+
+  <xsl:template match="body">
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="s1">
+    <section>
+      <title><xsl:value-of select="@title"/></title>
+      <xsl:apply-templates/>
+    </section>
+  </xsl:template>
+
+  <xsl:template match="s2">
+    <section>
+      <title><xsl:value-of select="@title"/></title>
+      <xsl:apply-templates/>
+    </section>
+  </xsl:template>
+
+  <xsl:template match="s3">
+    <section>
+      <title><xsl:value-of select="@title"/></title>
+      <xsl:apply-templates/>
+    </section>
+  </xsl:template>
+
+  <xsl:template match="s4">
+    <section>
+      <title><xsl:value-of select="@title"/></title>
+      <xsl:apply-templates/>
+    </section>
+  </xsl:template>
+
+  <xsl:template match="p|br">
+    <para>
+      <xsl:apply-templates/>
+    </para>
+  </xsl:template>
+
+  <xsl:template match="strong|em">
+    <emphasis><xsl:apply-templates/></emphasis>
+  </xsl:template>
+
+  <xsl:template match="ul">
+    <itemizedlist><xsl:apply-templates/></itemizedlist>
+  </xsl:template>
+
+  <xsl:template match="li">
+    <listitem><xsl:apply-templates/></listitem>
+  </xsl:template>
+
+  <xsl:template match="ol">
+    <orderedlist><xsl:apply-templates/></orderedlist>
+  </xsl:template>
+
+  <xsl:template match="link">
+    <ulink uri="{@href}"><xsl:apply-templates/></ulink>
+  </xsl:template>
+
+  <xsl:template match="figure">
+    <xsl:choose>
+      <xsl:when test="@src">
+        <figure>
+          <title><xsl:value-of select="@alt"/></title>
+          <graphic fileref="{@src}" srccredit="{@alt}"/>
+        </figure>
+      </xsl:when>
+      <xsl:otherwise>
+        <figure>
+          <xsl:apply-templates/>
+        </figure>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <xsl:template match="fixme">
+    <warning><xsl:apply-templates/></warning>
+  </xsl:template>
+
+  <xsl:template match="note">
+    <note><xsl:apply-templates/></note>
+  </xsl:template>
+
+  <xsl:template match="warn">
+    <warning><xsl:apply-templates/></warning>
+  </xsl:template>
+
+  <xsl:template match="code">
+    <classname><xsl:apply-templates/></classname>
+  </xsl:template>
+
+  <xsl:template match="source">
+    <programlisting><xsl:apply-templates/></programlisting>
+  </xsl:template>
+
+  <xsl:template match="table">
+    <table>
+      <tgroup>
+        <xsl:attribute name="cols"><xsl:value-of select="count(tr/td)"/></xsl:attribute>
+        <xsl:if test="th">
+          <thead>
+            <xsl:apply-templates select="th"/>
+          </thead>
+        </xsl:if>
+        <tbody>
+          <xsl:apply-templates select="tr"/>
+        </tbody>
+      </tgroup>
+    </table>
+  </xsl:template>
+
+  <xsl:template match="th|tr">
+    <row>
+      <xsl:apply-templates/>
+    </row>
+  </xsl:template>
+
+  <xsl:template match="td">
+    <entry>
+      <xsl:apply-templates/>
+    </entry>
+  </xsl:template>
+
+  <xsl:template match="node()|@*" priority="-1">
+    <xsl:copy>
+      <xsl:apply-templates select="node()|@*"/>
+    </xsl:copy>
+  </xsl:template>
+</xsl:stylesheet>
+

src/documentation/stylesheets/document2html.xsl

@@ -0,0 +1,389 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+<!-- ====================================================================== -->
+<!-- document section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="/">
+  <!-- checks if this is the included document to avoid neverending loop -->
+  <xsl:if test="not(book)">
+      <document>
+      <xsl:choose>
+		<xsl:when test="document/header/title">
+		      <title><xsl:value-of select="document/header/title"/></title>
+		</xsl:when>
+		<xsl:otherwise>
+			<title>NO TITLE</title>
+		</xsl:otherwise>
+	</xsl:choose>
+      <body text="#000000" link="#039acc" vlink="#0086b2" alink="#cc0000"
+            topmargin="4" leftmargin="4" marginwidth="4" marginheight="4"
+            bgcolor="#ffffff">
+        
+        <xsl:apply-templates/>
+        
+      </body>
+      </document>
+   </xsl:if>
+   
+   <xsl:if test="book">
+    <xsl:apply-templates/>
+   </xsl:if>
+  </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- header section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="header">
+  <!-- ignore on general document -->
+ </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- body section -->
+<!-- ====================================================================== -->
+
+  <xsl:template match="s1">
+   <div align="right">
+    <table border="0" width="98%" cellspacing="0" cellpadding="0">
+      <tr>
+        <td width="9" height="7" valign="bottom" align="right"><img src="images/bar-top-left.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
+        <td background="images/bar-border-top.gif"><img src="images/void.gif" width="1" height="5" vspace="0" hspace="0" border="0"/></td>
+        <td width="9" height="7" valign="bottom" align="left"><img src="images/bar-top-right.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td width="9" background="images/bar-border-left.gif"><img src="images/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td width="100%" bgcolor="#0086b2">
+          <font size="+1" face="arial,helvetica,sanserif" color="#ffffff">
+            <img src="images/void.gif" width="5" height="5" vspace="0" hspace="0" border="0"/><b><xsl:value-of select="@title"/></b></font>
+         </td>
+        <td width="9" background="images/bar-border-right.gif"><img src="images/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td width="9" height="12" valign="top" align="right"><img src="images/bar-bottom-left.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
+        <td background="images/bar-border-bottom.gif"><img src="images/void.gif" height="12" vspace="0" hspace="0" border="0"/></td>
+        <td width="9" height="12" valign="top" align="left"><img src="images/bar-bottom-right.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+     </table>
+     <table border="0" width="98%" cellspacing="0" cellpadding="0">
+      <tr>
+       <td>
+        <font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
+       </td>
+      </tr>
+    </table>
+   </div>
+   <br/>
+  </xsl:template>
+
+  <xsl:template match="s2">
+   <div align="right">
+    <table border="0" width="95%" cellspacing="0" cellpadding="0">
+      <tr>
+        <td width="9" height="7" valign="bottom" align="right"><img src="images/bar-top-left.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
+        <td background="images/bar-border-top.gif"><img src="images/void.gif" width="1" height="5" vspace="0" hspace="0" border="0"/></td>
+        <td width="9" height="7" valign="bottom" align="left"><img src="images/bar-top-right.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td width="9" background="images/bar-border-left.gif"><img src="images/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td width="100%" bgcolor="#0086b2">
+          <font face="arial,helvetica,sanserif" color="#ffffff">
+            <img src="images/void.gif" width="5" height="5" vspace="0" hspace="0" border="0"/><b><xsl:value-of select="@title"/></b></font>
+         </td>
+        <td width="9" background="images/bar-border-right.gif"><img src="images/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td width="9" height="12" valign="top" align="right"><img src="images/bar-bottom-left.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
+        <td background="images/bar-border-bottom.gif"><img src="images/void.gif" width="1" height="12" vspace="0" hspace="0" border="0"/></td>
+        <td width="9" height="12" valign="top" align="left"><img src="images/bar-bottom-right.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+     </table>
+     <table border="0" width="95%" cellspacing="0" cellpadding="0">
+      <tr>
+       <td>
+        <font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
+       </td>
+      </tr>
+    </table>
+   </div>
+   <br/>
+  </xsl:template>
+
+  <xsl:template match="s3">
+   <div align="right">
+    <table border="0" width="90%" cellspacing="0" cellpadding="0">
+      <tr>
+        <td width="9" height="7" valign="bottom" align="right"><img src="images/bar-top-left.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
+        <td background="images/bar-border-top.gif"><img src="images/void.gif" width="1" height="5" vspace="0" hspace="0" border="0"/></td>
+        <td width="9" height="7" valign="bottom" align="left"><img src="images/bar-top-right.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td width="9" background="images/bar-border-left.gif"><img src="images/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td width="100%" bgcolor="#0086b2">
+          <font size="-1" face="arial,helvetica,sanserif" color="#ffffff">
+            <img src="images/void.gif" width="5" height="5" vspace="0" hspace="0" border="0"/><b><xsl:value-of select="@title"/></b></font>
+         </td>
+        <td width="9" background="images/bar-border-right.gif"><img src="images/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td width="9" height="12" valign="top" align="right"><img src="images/bar-bottom-left.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
+        <td background="images/bar-border-bottom.gif"><img src="images/void.gif" width="1" height="12" vspace="0" hspace="0" border="0"/></td>
+        <td width="9" height="12" valign="top" align="left"><img src="images/bar-bottom-right.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+     </table>
+     <table border="0" width="90%" cellspacing="0" cellpadding="0">
+      <tr>
+       <td>
+        <font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
+       </td>
+      </tr>
+    </table>
+   </div>
+   <br/>
+  </xsl:template>
+
+  <xsl:template match="s4">
+   <div align="right">
+    <table border="0" width="85%" cellspacing="0" cellpadding="0">
+      <tr>
+        <td width="9" height="7" valign="bottom" align="right"><img src="images/bar-top-left.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
+        <td background="images/bar-border-top.gif"><img src="images/void.gif" width="1" height="5" vspace="0" hspace="0" border="0"/></td>
+        <td width="9" height="7" valign="bottom" align="left"><img src="images/bar-top-right.gif" width="9" height="7" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td width="9" background="images/bar-border-left.gif"><img src="images/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
+        <td width="100%" bgcolor="#0086b2">
+          <font size="-2" face="arial,helvetica,sanserif" color="#ffffff">
+            <img src="images/void.gif" width="5" height="5" vspace="0" hspace="0" border="0"/><b><xsl:value-of select="@title"/></b></font>
+         </td>
+        <td width="9" background="images/bar-border-right.gif"><img src="images/void.gif" width="9" height="1" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+      <tr>
+        <td width="9" height="12" valign="top" align="right"><img src="images/bar-bottom-left.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
+        <td background="images/bar-border-bottom.gif"><img src="images/void.gif" width="1" height="12" vspace="0" hspace="0" border="0"/></td>
+        <td width="9" height="12" valign="top" align="left"><img src="images/bar-bottom-right.gif" width="9" height="12" vspace="0" hspace="0" border="0"/></td>
+      </tr>
+     </table>
+     <table border="0" width="85%" cellspacing="0" cellpadding="0">
+      <tr>
+       <td>
+        <font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
+       </td>
+      </tr>
+    </table>
+   </div>
+   <br/>
+  </xsl:template>
+    
+<!-- ====================================================================== -->
+<!-- footer section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="footer">
+  <!-- ignore on general documents -->
+ </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- paragraph section -->
+<!-- ====================================================================== -->
+
+  <xsl:template match="p">
+    <p align="justify"><xsl:apply-templates/></p>
+  </xsl:template>
+
+  <xsl:template match="note">
+   <p>
+    <table width="100%" cellspacing="3" cellpadding="0" border="0">
+      <tr>
+        <td width="28" valign="top">
+          <img src="images/note.gif" width="28" height="29" vspace="0" hspace="0" border="0" alt="Note"/>
+        </td>
+        <td valign="top">
+          <font size="-1" face="arial,helvetica,sanserif" color="#000000">
+            <i>
+              <xsl:apply-templates/>
+            </i>
+          </font>
+        </td>
+      </tr>  
+    </table>
+   </p>
+  </xsl:template>
+
+  <xsl:template match="source">
+   <div align="center">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#0086b2" width="1" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#0086b2" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#0086b2" width="1" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#0086b2" width="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre><xsl:apply-templates/></pre></td>
+      <td bgcolor="#0086b2" width="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#0086b2" width="1" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#0086b2" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#0086b2" width="1" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+   </div>
+  </xsl:template>
+  
+  <xsl:template match="fixme">
+   <!-- ignore on documentation -->
+  </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- list section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="ul|ol|dl">
+  <blockquote>
+   <xsl:copy>
+    <xsl:apply-templates/>
+   </xsl:copy>
+  </blockquote>
+ </xsl:template>
+ 
+ <xsl:template match="li">
+  <xsl:copy>
+   <xsl:apply-templates/>
+  </xsl:copy>
+ </xsl:template>
+
+ <xsl:template match="sl">
+  <ul>
+   <xsl:apply-templates/>
+  </ul>
+ </xsl:template>
+
+ <xsl:template match="dt">
+  <li>
+   <strong><xsl:value-of select="."/></strong>
+   <xsl:text> - </xsl:text>
+   <xsl:apply-templates select="dd"/>   
+  </li>
+ </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- table section -->
+<!-- ====================================================================== -->
+
+  <xsl:template match="table">
+    <table width="100%" border="0" cellspacing="2" cellpadding="2">
+      <caption><xsl:value-of select="caption"/></caption>
+      <xsl:apply-templates/>
+    </table>
+  </xsl:template>
+
+  <xsl:template match="tr">
+    <tr><xsl:apply-templates/></tr>
+  </xsl:template>
+
+  <xsl:template match="th">
+    <td bgcolor="#039acc" colspan="{@colspan}" rowspan="{@rowspan}" valign="center" align="center">
+      <font color="#ffffff" size="-1" face="arial,helvetica,sanserif">
+        <b><xsl:apply-templates/></b>&#160;
+      </font>
+    </td>
+  </xsl:template>
+
+  <xsl:template match="td">
+    <td bgcolor="#a0ddf0" colspan="{@colspan}" rowspan="{@rowspan}" valign="top" align="left">
+      <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+        <xsl:apply-templates/>&#160;
+      </font>
+    </td>
+  </xsl:template>
+
+  <xsl:template match="tn">
+    <td bgcolor="#ffffff" colspan="{@colspan}" rowspan="{@rowspan}">
+      &#160;
+    </td>
+  </xsl:template>
+  
+  <xsl:template match="caption">
+    <!-- ignore since already used -->
+  </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- markup section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="strong">
+   <b><xsl:apply-templates/></b>
+ </xsl:template>
+
+ <xsl:template match="em">
+    <i><xsl:apply-templates/></i>
+ </xsl:template>
+
+ <xsl:template match="code">
+    <code><font face="courier, monospaced"><xsl:apply-templates/></font></code>
+ </xsl:template>
+ 
+<!-- ====================================================================== -->
+<!-- images section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="figure">
+  <p align="center">
+  <xsl:choose>
+   <xsl:when test="string(@width) and string(@height)">
+   <img src="{@src}" alt="{@alt}" width="{@width}" height="{@height}" border="0" vspace="4" hspace="4"/>
+   </xsl:when>
+   <xsl:otherwise>
+   <img src="{@src}" alt="{@alt}" border="0" vspace="4" hspace="4"/>
+   </xsl:otherwise>
+  </xsl:choose>
+  </p>
+ </xsl:template>
+ 
+ <xsl:template match="img">
+   <img src="{@src}" alt="{@alt}" border="0" vspace="4" hspace="4" align="right"/>
+ </xsl:template>
+
+ <xsl:template match="icon">
+   <img src="{@src}" alt="{@alt}" border="0" align="absmiddle"/>
+ </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- links section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="link">
+   <a href="{@href}"><xsl:apply-templates/></a>
+ </xsl:template>
+
+ <xsl:template match="connect">
+  <xsl:apply-templates/>
+ </xsl:template>
+
+ <xsl:template match="jump">
+   <a href="{@href}#{@anchor}"><xsl:apply-templates/></a>
+ </xsl:template>
+
+ <xsl:template match="fork">
+   <a href="{@href}" target="_blank"><xsl:apply-templates/></a>
+ </xsl:template>
+
+ <xsl:template match="anchor">
+   <a name="{@id}"><xsl:comment>anchor</xsl:comment></a>
+ </xsl:template>  
+
+<!-- ====================================================================== -->
+<!-- specials section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="br">
+  <br/>
+ </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/faq2document.xsl

@@ -0,0 +1,50 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+ <xsl:import href="copyover.xsl"/>
+
+  <xsl:template match="faqs">
+   <document>
+    <header>
+     <title><xsl:value-of select="@title"/></title>
+    </header>
+    <body>
+      <s1 title="Questions">
+       <ul>
+        <xsl:apply-templates select="faq" mode="index"/>
+       </ul>
+      </s1>
+      <s1 title="Answers">
+        <xsl:apply-templates select="faq"/>
+      </s1>
+    </body>
+   </document>  
+  </xsl:template>
+
+  <xsl:template match="faq" mode="index">
+    <li>
+      <jump anchor="faq-{position()}">
+        <xsl:value-of select="question"/>
+      </jump>
+    </li>
+  </xsl:template>
+
+  <xsl:template match="faq">
+    <anchor id="faq-{position()}"/>
+    <s2 title="{question}">
+      <xsl:apply-templates/>
+    </s2>
+  </xsl:template>
+
+  <xsl:template match="question">
+    <!-- ignored since already used -->
+  </xsl:template>
+
+  <xsl:template match="answer">
+    <xsl:apply-templates/>
+  </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/filterlinks.xsl

@@ -0,0 +1,42 @@
+<?xml version="1.0"?>
+
+<!--
+This stylesheet filters all references to the javadocs
+and the samples.
+-->
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+  <xsl:template match="@src|@href|@background">
+    <xsl:if test="not(contains(.,'apidocs')) and not(starts-with(., 'samples/'))">
+      <xsl:copy>
+        <xsl:apply-templates select="."/>
+      </xsl:copy>
+    </xsl:if>
+  </xsl:template>
+
+  <!-- This is a hack which makes the javascript images work -->
+  <xsl:template match="img[@onLoad and starts-with(@src, 'graphics')]">
+      <img src="{@src}"/>
+      <img>
+        <xsl:attribute name="src">
+          <xsl:value-of select="substring-before(@src, '.')"/>_over.<xsl:value-of select="substring-after(@src, '.')"/>
+        </xsl:attribute>
+      </img>
+  </xsl:template>
+
+  <xsl:template match="img[@onLoad and starts-with(@src, 'images') and contains(@src, '-lo.gif')]">
+      <img src="{@src}"/>
+      <img>
+        <xsl:attribute name="src"><xsl:value-of select="substring-before(@src, '-lo.gif')"/>-hi.gif</xsl:attribute>
+      </img>
+  </xsl:template>
+
+  <xsl:template match="@*|node()">
+   <xsl:copy>
+    <xsl:apply-templates select="@*|node()"/>
+   </xsl:copy>
+  </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/printer_skin/book2menu.xsl

@@ -0,0 +1,62 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+
+  <xsl:param name="resource"/>
+
+  <xsl:template match="book">
+    <menu>
+      <xsl:apply-templates/>
+    </menu>
+  </xsl:template>
+
+  <xsl:template match="project">
+  </xsl:template>
+
+  <xsl:template match="menu[position()=1]">
+    <xsl:apply-templates/>
+  </xsl:template>
+
+  <xsl:template match="menu">
+     <tr>
+       <td align="left" valign="top">
+         ----------
+         <br/>
+         <b><xsl:value-of select="@label"/></b>
+       </td>
+     </tr>
+     <xsl:apply-templates/>
+  </xsl:template>
+
+
+  <xsl:template match="menu-item">
+    <xsl:if test="not(@type) or @type!='hidden'">
+     <tr>
+      <td align="left" valign="top">
+       <xsl:choose>
+         <xsl:when test="@href=$resource">
+          <xsl:value-of select="@label"/>
+         </xsl:when>
+         <xsl:otherwise>
+          <a href="{@href}"><xsl:value-of select="@label"/></a>
+        </xsl:otherwise>
+       </xsl:choose>
+      </td>
+     </tr>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template match="external">
+    <xsl:if test="not(@type) or @type!='hidden'">
+     <tr>
+	<td align="left" valign="top">
+          <a href="{@href}"><xsl:value-of select="@label"/></a>
+	</td>
+     </tr>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template match="node()|@*" priority="-1"/>
+</xsl:stylesheet>
+

src/documentation/stylesheets/printer_skin/copyover.xsl

@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+  <xsl:template match="@*|*|text()|processing-instruction()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|*|text()|processing-instruction()"/>
+    </xsl:copy>
+  </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/printer_skin/document2html.xsl

@@ -0,0 +1,277 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+<!-- ====================================================================== -->
+<!-- document section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="/">
+  <!-- checks if this is the included document to avoid neverending loop -->
+  <xsl:if test="not(book)">
+      <document>
+      <xsl:choose>
+		<xsl:when test="document/header/title">
+		      <title><xsl:value-of select="document/header/title"/></title>
+		</xsl:when>
+		<xsl:otherwise>
+			<title>NO TITLE</title>
+		</xsl:otherwise>
+	</xsl:choose>
+      <body text="#000000" link="#039acc" vlink="#0086b2" alink="#cc0000"
+            topmargin="4" leftmargin="4" marginwidth="4" marginheight="4"
+            bgcolor="#ffffff">
+        
+        <xsl:apply-templates/>
+        
+      </body>
+      </document>
+   </xsl:if>
+   
+   <xsl:if test="book">
+    <xsl:apply-templates/>
+   </xsl:if>
+  </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- header section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="header">
+  <!-- ignore on general document -->
+ </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- body section -->
+<!-- ====================================================================== -->
+
+  <xsl:template match="s1">
+   <h1><xsl:value-of select="@title"/></h1>
+   <font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
+  </xsl:template>
+
+  <xsl:template match="s2">
+   <h2><xsl:value-of select="@title"/></h2>
+   <font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
+  </xsl:template>
+
+  <xsl:template match="s3">
+   <h3><xsl:value-of select="@title"/></h3>
+   <font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
+  </xsl:template>
+
+  <xsl:template match="s4">
+   <h4><xsl:value-of select="@title"/></h4>
+   <font face="arial,helvetica,sanserif" color="#000000"><xsl:apply-templates/></font>
+  </xsl:template>
+    
+<!-- ====================================================================== -->
+<!-- footer section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="footer">
+  <!-- ignore on general documents -->
+ </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- paragraph section -->
+<!-- ====================================================================== -->
+
+  <xsl:template match="p">
+    <p align="justify"><xsl:apply-templates/></p>
+  </xsl:template>
+
+  <xsl:template match="note">
+   <p>
+    <table width="100%" cellspacing="3" cellpadding="0" border="0">
+      <tr>
+        <td width="28" valign="top">
+          <img src="images/note.gif" width="28" height="29" vspace="0" hspace="0" border="0" alt="Note"/>
+        </td>
+        <td valign="top">
+          <font size="-1" face="arial,helvetica,sanserif" color="#000000">
+            <i>
+              <xsl:apply-templates/>
+            </i>
+          </font>
+        </td>
+      </tr>  
+    </table>
+   </p>
+  </xsl:template>
+
+  <xsl:template match="source">
+   <div align="center">
+    <table cellspacing="4" cellpadding="0" border="0">
+    <tr>
+      <td bgcolor="#0086b2" width="1" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#0086b2" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#0086b2" width="1" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#0086b2" width="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#ffffff"><pre><xsl:apply-templates/></pre></td>
+      <td bgcolor="#0086b2" width="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    <tr>
+      <td bgcolor="#0086b2" width="1" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#0086b2" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+      <td bgcolor="#0086b2" width="1" height="1"><img src="images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+    </tr>
+    </table>
+   </div>
+  </xsl:template>
+  
+  <xsl:template match="fixme">
+   <!-- ignore on documentation -->
+  </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- list section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="ul|ol|dl">
+  <blockquote>
+   <xsl:copy>
+    <xsl:apply-templates/>
+   </xsl:copy>
+  </blockquote>
+ </xsl:template>
+ 
+ <xsl:template match="li">
+  <xsl:copy>
+   <xsl:apply-templates/>
+  </xsl:copy>
+ </xsl:template>
+
+ <xsl:template match="sl">
+  <ul>
+   <xsl:apply-templates/>
+  </ul>
+ </xsl:template>
+
+ <xsl:template match="dt">
+  <li>
+   <strong><xsl:value-of select="."/></strong>
+   <xsl:text> - </xsl:text>
+   <xsl:apply-templates select="dd"/>   
+  </li>
+ </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- table section -->
+<!-- ====================================================================== -->
+
+  <xsl:template match="table">
+    <table width="100%" border="0" cellspacing="2" cellpadding="2">
+      <caption><xsl:value-of select="caption"/></caption>
+      <xsl:apply-templates/>
+    </table>
+  </xsl:template>
+
+  <xsl:template match="tr">
+    <tr><xsl:apply-templates/></tr>
+  </xsl:template>
+
+  <xsl:template match="th">
+    <td bgcolor="#039acc" colspan="{@colspan}" rowspan="{@rowspan}" valign="center" align="center">
+      <font color="#ffffff" size="-1" face="arial,helvetica,sanserif">
+        <b><xsl:apply-templates/></b>&#160;
+      </font>
+    </td>
+  </xsl:template>
+
+  <xsl:template match="td">
+    <td bgcolor="#a0ddf0" colspan="{@colspan}" rowspan="{@rowspan}" valign="top" align="left">
+      <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+        <xsl:apply-templates/>&#160;
+      </font>
+    </td>
+  </xsl:template>
+
+  <xsl:template match="tn">
+    <td bgcolor="#ffffff" colspan="{@colspan}" rowspan="{@rowspan}">
+      &#160;
+    </td>
+  </xsl:template>
+  
+  <xsl:template match="caption">
+    <!-- ignore since already used -->
+  </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- markup section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="strong">
+   <b><xsl:apply-templates/></b>
+ </xsl:template>
+
+ <xsl:template match="em">
+    <i><xsl:apply-templates/></i>
+ </xsl:template>
+
+ <xsl:template match="code">
+    <code><font face="courier, monospaced"><xsl:apply-templates/></font></code>
+ </xsl:template>
+ 
+<!-- ====================================================================== -->
+<!-- images section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="figure">
+  <p align="center">
+  <xsl:choose>
+   <xsl:when test="string(@width) and string(@height)">
+   <img src="{@src}" alt="{@alt}" width="{@width}" height="{@height}" border="0" vspace="4" hspace="4"/>
+   </xsl:when>
+   <xsl:otherwise>
+   <img src="{@src}" alt="{@alt}" border="0" vspace="4" hspace="4"/>
+   </xsl:otherwise>
+  </xsl:choose>
+  </p>
+ </xsl:template>
+ 
+ <xsl:template match="img">
+   <img src="{@src}" alt="{@alt}" border="0" vspace="4" hspace="4" align="right"/>
+ </xsl:template>
+
+ <xsl:template match="icon">
+   <img src="{@src}" alt="{@alt}" border="0" align="absmiddle"/>
+ </xsl:template>
+
+<!-- ====================================================================== -->
+<!-- links section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="link">
+   <a href="{@href}"><xsl:apply-templates/></a>
+ </xsl:template>
+
+ <xsl:template match="connect">
+  <xsl:apply-templates/>
+ </xsl:template>
+
+ <xsl:template match="jump">
+   <a href="{@href}#{@anchor}"><xsl:apply-templates/></a>
+ </xsl:template>
+
+ <xsl:template match="fork">
+   <a href="{@href}" target="_blank"><xsl:apply-templates/></a>
+ </xsl:template>
+
+ <xsl:template match="anchor">
+   <a name="{@id}"><xsl:comment>anchor</xsl:comment></a>
+ </xsl:template>  
+
+<!-- ====================================================================== -->
+<!-- specials section -->
+<!-- ====================================================================== -->
+
+ <xsl:template match="br">
+  <br/>
+ </xsl:template>
+
+</xsl:stylesheet>

src/documentation/stylesheets/printer_skin/simple.css

@@ -0,0 +1,58 @@
+body {
+	background: white fixed no-repeat left top; 
+	color: black; 
+	font-family: sans-serif; 
+	margin: 2em 1em 2em 1em;
+}
+
+h1 {
+	text-align: left;
+	color: #005a9c;
+	font: 170% sans-serif;
+}
+
+h2 {
+	text-align: left;
+	color: #005a9c;
+	font: 140% sans-serif;
+}
+
+h3 {
+	text-align: left;
+	color: #005a9c;
+	font: 120% sans-serif;
+}
+
+h4 {
+	text-align: left;
+	color: #005a9c;
+	font: bold 100% sans-serif;
+}
+
+#main-panel {}
+#side-bar {}
+#content-panel {}
+
+#s1
+#s2
+#s3
+#s4
+
+p {
+        padding: 10px 10px 10px 10px;
+        margin: 10px 20px 10px 20px;
+        text-align: justify;
+}
+
+p.note {
+        font-style: italic;
+}
+
+p.source {
+	font-family: monospace;
+}
+
+a:link { color: #005a9c }
+a:visited { color: #a00000 }
+a:active { color: #00a000 }
+a:hover { background: #ffa }

src/documentation/stylesheets/printer_skin/site2xhtml.xsl

@@ -0,0 +1,122 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+	<xsl:param name="header"/>
+
+<xsl:template match="/">
+<html>
+      <head>
+        <title><xsl:value-of select="/site/document/title"/></title>
+      </head>
+
+      <body text="#000000" link="#039acc" vlink="#0086b2" alink="#cc0000"
+            topmargin="4" leftmargin="4" marginwidth="4" marginheight="4"
+            bgcolor="#ffffff">
+        <!-- THE TOP BAR (HEADER) -->
+        <table width="100%" cellspacing="0" cellpadding="0" border="0">
+          <tr>
+            <td width="135" height="60" rowspan="3" valign="top" align="left">
+              <img width="135" height="60" src="images/logo.gif" hspace="0" vspace="0" border="0"/>
+            </td>
+            <td width="100%" height="5" valign="top" align="left" colspan="2" background="images/line.gif">
+              <img width="1" height="5" src="images/line.gif" hspace="0" vspace="0" border="0" align="left"/>
+            </td>
+            <td width="29" height="60"  rowspan="3" valign="top" align="left">
+              <img width="29" height="60" src="images/right.gif" hspace="0" vspace="0" border="0"/>
+            </td>
+          </tr>
+          <tr>
+            <!-- using svg 
+            <td width="100%" height="35" valign="top" align="right" colspan="2" bgcolor="#0086b2">
+              <img src="{$header}?label={/site/document/title}" hspace="0" vspace="0" border="0" alt="{/site/document/title}" align="right"/>           
+            </td>
+            -->
+            <td width="100%" height="35" valign="top" align="right" colspan="2" bgcolor="#0086b2">
+              <p align="right" style="color:white; font-family:arial; font-size:30px; font-style:italic">
+                <xsl:value-of select="/site/document/title"/>
+              </p>
+            </td>
+          </tr>
+          <tr>
+            <td width="100%" height="20" valign="top" align="left" bgcolor="#0086b2" background="images/bottom.gif">
+              <img width="3" height="20" src="images/bottom.gif" hspace="0" vspace="0" border="0" align="left"/>
+            </td>
+            <td align="right" bgcolor="#0086b2" height="20" valign="top" width="288" background="images/bottom.gif">
+              <table border="0" cellpadding="0" cellspacing="0" width="288">
+                <tr>
+                  <td width="96" height="20" valign="top" align="left">
+                    <a href="http://xml.apache.org/" target="new">
+                      <img alt="http://xml.apache.org/" width="96" height="20" src="images/button-xml-lo.gif"
+                           name="xml" hspace="0" vspace="0" border="0"/>
+                    </a>
+                  </td>
+                  <td width="96" height="20" valign="top" align="left">
+                    <a href="http://www.apache.org/" target="new">
+                      <img alt="http://www.apache.org/" width="96" height="20" src="images/button-asf-lo.gif"
+                           name="asf" hspace="0" vspace="0" border="0"/>
+                    </a>
+                  </td>
+                  <td width="96" height="20" valign="top" align="left">
+                    <a href="http://www.w3.org/" target="new">
+                      <img alt="http://www.w3.org/" width="96" height="20" src="images/button-w3c-lo.gif"
+                           name="w3c" hspace="0" vspace="0" border="0"/>
+                    </a>
+                  </td>
+                </tr>
+              </table>
+            </td>
+          </tr>
+        </table>
+
+<table border="0" cellpadding="0" cellspacing="0" width="100%">
+	<tr width="100%">
+		<td width="120" valign="top"> 
+			<table border="0" cellpadding="0" cellspacing="0" width="120">
+			      <tr>
+					<td align="left" valign="top">
+						<img border="0" height="14" hspace="0" src="images/join.gif" vspace="0" width="120"/>
+						<br/>
+					</td>
+				</tr>
+				<xsl:copy-of select="/site/menu/node()|@*"/>
+<!--
+				<tr>
+					<td valign="top" align="left">
+						<img border="0" height="14" hspace="0" src="images/close.gif" vspace="0" width="120"/>
+						<br/>
+					</td>
+				</tr>
+-->
+			</table>
+		</td>
+		<td>
+			<table border="0" cellpadding="0" cellspacing="0">
+				<tr><td width="100%" height="10"/></tr>
+				<tr><td><xsl:copy-of select="/site/document/body/node()|@*"/></td></tr>
+			</table>
+		</td>
+	</tr>
+ </table>
+<table border="0" cellpadding="0" cellspacing="0" width="100%">
+  <tr>
+    <td bgcolor="#0086b2">
+      <img height="1" src="images/dot.gif" width="1"/>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <font color="#0086b2" face="arial,helvetica,sanserif" size="-1">
+        <i>Copyright &#169; @year@ The Apache Software Foundation. All Rights Reserved.</i>
+      </font>
+    </td>
+  </tr>
+</table>
+</body>
+
+
+</html>
+</xsl:template>
+</xsl:stylesheet>

src/documentation/stylesheets/script-cli.js

@@ -0,0 +1,27 @@
+rolloverImagesOn=new Array();
+rolloverImagesOff=new Array();
+
+function rolloverOn(name) {
+  if(document.images[name] && rolloverImagesOn[name]) document.images[name].src=rolloverImagesOn[name].src;
+}
+
+function rolloverOff(name) {
+ if(document.images[name] && rolloverImagesOff[name]) document.images[name].src=rolloverImagesOff[name].src;
+}
+
+
+function rolloverLoad(name,on,off) {
+  rolloverImagesOn[name]=new Image();
+  rolloverImagesOn[name].src=mangle(on);
+  rolloverImagesOff[name]=new Image();
+  rolloverImagesOff[name].src=mangle(off);
+}
+
+function mangle(name) {
+
+  name = name.replace(/:/g, "_");
+  name = name.replace(/\?/g, "_");
+  name = name.replace(/\"/g, "\'");
+
+  return name;
+}

src/documentation/stylesheets/script.js

@@ -0,0 +1,17 @@
+rolloverImagesOn=new Array();
+rolloverImagesOff=new Array();
+
+function rolloverOn(name) {
+ if(document.images[name] && rolloverImagesOn[name]) document.images[name].src=rolloverImagesOn[name].src;
+}
+
+function rolloverOff(name) {
+ if(document.images[name] && rolloverImagesOff[name]) document.images[name].src=rolloverImagesOff[name].src;
+}
+
+function rolloverLoad(name,on,off) {
+  rolloverImagesOn[name]=new Image();
+  rolloverImagesOn[name].src=on;
+  rolloverImagesOff[name]=new Image();
+  rolloverImagesOff[name].src=off;
+}

src/documentation/stylesheets/site2xhtml.xsl

@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+
+<html xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+      xsl:version="1.0">
+  <head><title><xsl:value-of select="/site/body/title"/></title></head>
+  <body text="#000000" link="#525D76" vlink="#023264" alink="#023264"
+        topmargin="4" leftmargin="4" marginwidth="4" marginheight="4"
+	bgcolor="#ffffff">
+    <table width="100%" cellspacing="0" cellpadding="0" border="0">
+      <tr>
+        <td valign="top" align="left">
+          <a href="http://jakarta.apache.org/index.html">
+            <img hspace="0" vspace="0" border="0" src="images/jakarta-logo.gif"/>
+          </a>
+        </td>
+        <td width="100%" valign="top" align="left" bgcolor="#ffffff">
+          <img hspace="0"
+               vspace="0"
+               border="0"
+               align="right"
+               src="images/header.gif"/>
+        </td>
+      </tr>
+      <tr>
+        <td width="100%" height="2" colspan="2"><hr noshade="" size="1"/></td>
+      </tr>
+    </table>
+ 
+    <table width="100%" cellspacing="0" cellpadding="0" border="0">
+      <tr>
+        <td width="1%" valign="top"/>
+        <td width="14%" valign="top" nowrap="1">
+          <br/>
+          <font face="arial,helvetica,sanserif">
+            <br/>
+            <xsl:copy-of select="/site/menu/node()|@*"/>
+            <br/>
+          </font>
+        </td>
+        <td width="*" valign="top" align="left">
+          <xsl:copy-of select="/site/body/node()|@*"/>
+        </td>
+      </tr>
+    </table>
+    <br/>
+    <table width="100%" border="0" cellspacing="0" cellpadding="0">
+      <tr><td><hr noshade="" size="1"/></td></tr>
+      <tr>
+        <td align="center">
+          <font face="arial,helvetica,sanserif" size="-1" color="#525D76">
+            <i>
+              Copyright &#169;2002 Apache Software Foundation
+            </i>
+          </font>
+        </td>
+        <td align="right" width="5%">
+          <img hspace="0"
+               vspace="0"
+               border="0"
+               align="right"
+               src="images/cocoon2-small.jpg"/>
+        </td>        
+      </tr>
+    </table>
+  </body>
+</html>
+

src/documentation/stylesheets/todo2document.xsl

@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="1.0">
+
+ <xsl:import href="copyover.xsl"/>
+ 
+ <xsl:template match="todo">
+  <document>
+   <header>
+    <title><xsl:value-of select="@title"/></title>
+   </header>
+   <body>
+    <xsl:apply-templates/>
+   </body>
+  </document>
+ </xsl:template>
+
+ <xsl:template match="actions">
+  <s2 title="{@priority}">
+   <sl>
+    <xsl:for-each select="action">
+     <li>
+      <strong><xsl:text>[</xsl:text><xsl:value-of select="@context"/><xsl:text>]</xsl:text></strong><xsl:text> </xsl:text>
+      <xsl:apply-templates/>
+     </li>
+    </xsl:for-each>
+   </sl>
+  </s2>
+ </xsl:template>
+ 
+</xsl:stylesheet>

src/documentation/xdocs/3rdparty.xml

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Third Party Contributions</title>
+  <authors>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
+  </authors>
+ </header>
+
+ <body>
+
+ <s1 title="How to Contribute">
+  <p>
+   See <link href="contrib.xml">How to contribute to Poi</link>.
+  </p>
+
+ </s1>
+
+ <s1 title="Contributed Components">
+  <p>
+   These are not necessarily deemed to be high enough quality to be included in the
+   core distribution, but they have been tested under <connect href="contrib.xml">
+   several key environments</connect>, they are provided under the same license
+   as Poi, and they are included in the POI distribution under the
+   <code>contrib/</code> directory.
+  </p>
+
+  <p>
+   <strong>None as yet!</strong> - although you can expect that some of the links
+   listed below will eventually migrate to the "contributed components" level, and
+   then maybe even into the main distribution.
+  </p>
+ </s1>
+
+ <s1 title="Patch Queue">
+  <p><link href="patches.html">Submissions of modifications</link>
+   to Poi which are awaiting review. Anyone can
+   comment on them on the dev mailing list - code reviewers are needed!
+   <strong>Use these at your own risk</strong> - although Poi has no guarantee
+   either, these patches have not been reviewed, let alone accepted.
+  </p>
+ </s1>
+
+ <s1 title="Other Extensions">
+  <p>The other extensions listed here are <strong>not endorsed</strong> by the Poi
+   project either - they are provided as a convenience only. They may or may not work,
+   they may or may not be open source, etc.
+  </p>
+
+  <p>To have a link added to this table, see <link href="contrib.xml">How to contribute
+   to POI</link>.</p>
+
+  <table>
+   <tr>
+    <th>Name and Link</th>
+    <th>Type</th>
+    <th>Description</th>
+    <th>Status</th>
+    <th>Licensing</th>
+    <th>Contact</th>
+   </tr>
+  </table>
+
+ </s1>
+</body>
+</document>

src/documentation/xdocs/book.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "dtd/book-cocoon-v10.dtd">
+
+<book software="Poi" 
+      title="Poi Project Documentation" 
+      copyright="@year@ Poi Project"
+      xmlns:xlink="http://www.w3.org/1999/xlink">
+
+  <menu label="Main">
+    <menu-item label="Jakarta" href="http://jakarta.apache.org"/>
+  </menu>
+
+  <menu label="About">
+    <menu-item label="Index" href="index.html"/>
+    <menu-item label="History" href="historyandfuture.html"/>
+    <menu-item label="Future"  href="historyandfuture.html"/>
+    <menu-item label="Download" href="http://sourceforge.net/project/showfiles.php?group_id=32701"/>
+    <menu-item label="Design" href="plan/POI10Vision.html"/>
+    <menu-item label="Who we are" href="who.html"/>    
+    <menu-item label="FAQ File" href="faq.html"/>
+    <menu-item label="Changes" href="changes.html"/>
+    <menu-item label="Todo" href="todo.html"/>    
+  </menu>
+  
+  <menu label="Sub-Projects">
+    <menu-item label="Overview" href="overview.html"/>
+    <menu-item label="POIFS" href="poifs/index.html"/>
+    <menu-item label="HSSF" href="hssf/index.html"/>
+    <menu-item label="HDF" href="hdf/index.html"/>
+    <menu-item label="POI-Utils" href="utils/index.html"/>
+  </menu>
+
+  <menu label="References">
+    <menu-item label="Live Sites" href="livesites.html"/>
+    <menu-item label="XLS spec [PDF]" href="http://sc.openoffice.org/excelfileformat.pdf"/>
+    <menu-item label="Apache Cocoon" href="http://xml.apache.org/cocoon/"/>
+  </menu>
+
+  <menu label="Get Involved">
+    <menu-item label="Contributing" href="contrib.html"/>
+    <menu-item label="Bug Database" href="https://sourceforge.net/tracker/?atid=406288&amp;group_id=32701&amp;func=browse"/>
+    <menu-item label="CVS" href="http://jakarta.apache.org/site/cvsindex.html"/>
+    <menu-item label="Mail Lists" href="http://jakarta.apache.org/site/mail.html"/>
+  </menu>
+
+</book>

src/documentation/xdocs/changes.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE changes PUBLIC "-//APACHE//DTD Changes V1.0//EN" "src/documentation/xdocs/dtd/changes-v10.dtd">
+
+<changes title="History of Changes">
+
+ <devs>
+  <!-- in strict alphabetical order -->
+  <person id="AO"  name="Andrew C. Oliver"   email="acoliver2@users.sourceforge.net"/>
+  <person id="GS"  name="Glen Stampoultzis"  email="gstamp@iprimus.com.au"/>  
+  <person id="MJ"  name="Marc Johnson"       email="mjohnson at apache dot org"/>
+  <person id="NKB" name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
+  <person id="open" name="Poi Developers"    email="poi-devel@lists.sourceforge.net"/>
+ </devs>
+ <release version="@version@" date="@date@">
+  <action dev="NKB" type="update">
+    New project build.
+  </action>
+  <action dev="NKB" type="update">
+    New project documentation system based on Cocoon.
+  </action>
+ </release>
+
+</changes>

src/documentation/xdocs/contrib.xml

@@ -0,0 +1,275 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Contribution to POI</title>
+  <authors>
+   <person name="Robin Green" email="greenrd@hotmail.com"/>
+   <person name="Stefano Mazzocchi" email="stefano@apache.org"/> 
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> 
+   </authors>
+ </header>
+
+ <body>
+
+ <s1 title="Introduction">
+
+  <p>
+   The POI Project is an <link href="http://www.opensource.org/">Open Source</link>
+   volunteer project released under a very open license.
+   This means there are many ways to contribute to the project - either
+   with direct participation (coding, documenting, answering questions,
+   proposing ideas, reporting bugs, suggesting bug-fixes, etc..) or by resource
+   donations (money, time, publicity, hardware, software, conference
+   presentations, speeches, etc...).
+  </p>
+  <p>
+   To begin with, we suggest you to subscribe to the
+   <link href="mail-lists.html">POI mailing lists</link>
+   (follow the link for information on how to subscribe and to access the mail
+   list archives). Listen-in for a while, to hear how others make contibutions.
+  </p>
+
+  <p>You can get your local working copy of the
+   <link href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/POI">latest and
+   greatest code</link> (which you find in the POI module in
+   the CVS code repository.
+   Review the <link href="todo.html">todo</link> list, choose a task
+   (or perhaps you have noticed something that needs patching). Make the
+   changes, do the testing, generate a patch, and post to the dev
+   mailing list. (Do not worry - the process is easy and explained below.)
+  </p>
+
+  <p>
+   Document writers are usually the most wanted people so if
+   you like to help but you're not familiar with the innermost technical details, don't worry:
+   we have work for you!
+  </p>
+
+ </s1>
+
+ <s1 title="Help Wanted Here">
+  <p>
+   The rest of this document is mainly about
+   contributing new or improved code and/or documentation, but we would also be glad to have
+   extra help in any of the following areas:
+  </p>
+  <ul>
+   <li>Answering questions on the <code>users</code> mailing list - there is often a problem of
+    having too many questioners and not enough experts to respond to all the questions.</li>
+   <li>Testing POI (especially its less-frequently-used features) on various configurations
+    and reporting back.</li>
+   <li>Debugging - producing reproduceable test cases and/or finding causes of bugs. Some known bugs are informally listed on
+    <link href="todo.html">To Do</link>, and some are recorded in Bugzilla
+    (see <link href="#procedure">explanation below</link>).</li>
+   <li>Specifying/analysing/designing new features - and beyond. (If you wish to get involved
+    with this, please join <code>general POI mailing list</code>
+    , install and try out POI
+    and read some of the <link href="mail-lists.html">mail archives</link>.
+    You should have a strong "fluency" in XML technologies, Java and a basic understanding of
+    the POI architecture - don't just say "it should have XYZ" without reading anything first -
+    because chances are, someone's already thought of that feature!)</li>
+   <li>Packaging easy-to-install packages (such as RPMs) for the myriad of possible configurations out
+    there. (The project does not maintain anything but the basic <code>.zip</code> and
+    <code>.tar.gz</code> packages, but anyone is welcome to build their own specific packages and
+    announce them on the <code>general POI list</code>)</li>
+   <li>... and there is just one other thing - don't forget to tell everyone who asks, how great POI is! ;-)
+    The more people that know about and start to use POI, the larger the pool of
+    potential contributors there will be.
+    </li>
+  </ul>
+ 
+ </s1>
+
+ <anchor id="cvshowto"/>
+ <s1 title="CVS Usage Precis">
+  <p>An overview of how to use CVS to participate in POI development.
+   Do not be afraid - you cannot accidently destroy the actual code repository,
+   because you are working with a local copy as an anonymous user. Therefore,
+   you do not have the system permissions to change anything. You can only 
+   update your local repository and compare your revisions with the real
+   repository.
+  </p>
+
+  <p>
+   (Further general CVS usage information is at
+   <link href="http://www.cvshome.org/">www.cvshome.org</link> and your local
+   <code>info cvs</code> pages or <code>man cvs</code> pages or user
+   documentation.) 
+  </p>
+
+  <p>
+   Let us lead by example. We will show you how to establish your local
+   repository, how to keep it up-to-date, and how to generate the differences
+   to create a patch. (The commands are for Linux.)
+  </p>
+ </s1>
+ <anchor id="ssh"/>
+ <s1 title="CVS Committer with Secure Shell access">
+  <p>After a developer has consistently provided contributions (code,
+   documentation and discussion), then the rest of the dev community
+   may vote to grant this developer commit access to CVS.
+  </p>
+
+  <p>You will need secure access to the repository to be able to commit
+   patches. Here are some resources that help to get your machine configured
+   to use the repository over SSH.
+  </p>
+
+  <ul>
+   <li><link href="http://cvsbook.red-bean.com/">The CVS Book</link></li>
+   <li><link href="http://www.cvshome.org/">www.cvshome.org</link></li>
+   <li><link href="https://sourceforge.net/cvs/?group_id=32701"></link>
+    - See the bottom of the page for links to tips for UNIX and Windows.
+    Even if you are on UNIX, the Windows page will also help.</li>
+  </ul>
+ </s1>
+
+ <anchor id="procedure"/>
+ <s1 title="Procedure for Raising Development Issues">
+  <p>
+   There are two methods for discussing development and submitting patches.
+   So that everyone can be productive, it is important to know which method
+   is appropriate for a certain situation and how to go about it without
+   confusion. This section explains when to use the 
+   <code>developer</code> <link href="mail-lists.html">mailing list</link>
+   the bug database.
+  </p>
+
+  <p>
+   Research your topic thoroughly before beginning to discuss a new
+   development issue. Search and browse through the email archives - your
+   issue may have been discussed before. Prepare your post clearly and
+   concisely.
+  </p>
+
+  <p>
+   Most issues will be discovered, resolved, and then patched quickly
+   via the <code>developer</code> mailing list. Larger issues, and ones that
+   are not yet fully understood or are hard to solve, are destined for
+   Bugzilla.
+  </p>
+
+  <p>
+   Experienced developers use Bugzilla directly, as they are very sure
+   when they have found a bug and when not. However, less experienced users
+   should first discuss it on the user or developer mailing list (as
+   appropriate). Impatient people always enter everything into Bugzilla
+   without caring if it is a bug of POI or their own
+   installation/configuration mistake - please do not do this.
+  </p>
+
+  <p>
+   As a rule-of-thumb, discuss an issue on the <code>developers</code>
+   mailing list first to work out any details.
+   After it is confirmed to be worthwhile, and you are clear about it,
+   then submit the bug description or patch via Bug Tracking.
+  </p>
+
+  <p>
+   Perhaps you do not get any answer on your first reply, so just post
+   it again until you get one. (But please not every hour - allow a few
+   days for the list to deal with it.) Do not be impatient - remember that
+   the whole world is busy, not just you. Bear in mind that other countries
+   will have holidays at different times to your country and that they are
+   in different time zones. You might also consider re-writing your initial
+   posting - perhaps it was not clear enough
+   and the readers' eyes glazed over.
+  </p>
+ </s1>
+
+ <anchor id="tips"/>
+ <s1 title="Contribution Notes and Tips">
+  <p>
+   This is a collection of tips for contributing to the project in a manner
+   that is productive for all parties.
+  </p>
+
+  <ul>
+   <li>
+    Every contribution is worthwhile. Even if the ensuing discussion
+    proves it to be off-beam, then it may jog ideas for other people.
+   </li>
+   <li>
+    Use sensible and concise email subject headings. Search engines, and
+    humans trying to browse a voluminous list, will respond favourably to a
+    descriptive title.
+   </li>
+   <li>Start new threads with new Subject for new topics, rather than
+    re-using the previous Subject line.
+   </li>
+   <li>Keep each topic focussed. If some new topic arises then start a new
+    discussion. This leaves the original topic to continue un-cluttered.
+   </li>
+   <li>Whenever you decide to start a new topic, then start with a fresh
+    new email message window. Do not use the &quot;Reply to&quot; button,
+    because threaded mail-readers get confused (they utilise the 
+    <code>In-reply-to</code> header). If so, then your new topic will get
+    lost in the previous thread and go un-answered.
+   </li>
+   <li>
+    Prepend your email subject line with a marker when that is appropriate,
+    e.g. <code>[Patch]</code>, <code>[Proposal]</code>, 
+    <code>[RT]</code> (Random Thought which quickly blossom into research
+    topics :-), <code>[STATUS]</code> (development status of a certain
+    facility).
+   </li>
+   <li>
+    When making changes to XML documentation, or any XML document for that
+    matter, use a 
+    <link href="http://www.oasis-open.org/cover/">validating parser</link>
+    (one that is tried and true is
+    <link href="http://www.jclark.com/sp/">SP/nsgmls</link>).
+    This procedure will detect errors without having to go through the whole
+    <code>build docs</code> process to find them. Do not expect POI
+    or the build system to detect the validation errors for you - they can
+    do it, but that is not their purpose. (Anyway, nsgmls validation error
+    messages are more informative.)
+   </li>
+   <li>
+    Remember that most people are participating in development on a
+    volunteer basis and in their "spare time". These enthusiasts will attempt
+    to respond to issues. It may take a little while to get your answers.
+   </li>
+   <li>
+    Research your topic thoroughly before beginning to discuss a new
+    development issue. Search and browse through the email archives - your
+    issue may have been discussed before. Do not just perceive a problem and
+    then rush out with a question - instead, delve.
+   </li>
+   <li>
+    Try to at least offer a partial solution and not just a problem statement.
+   </li>
+   <li>
+    Take the time to clearly explain your issue and write a concise email
+    message. Less confusion facilitates fast and complete resolution.
+   </li>
+   <li>
+    Do not bother to send an email reply that simply says "thanks".
+    When the issue is resolved, that is the finish - end of thread.
+    Reduce clutter.
+   </li>
+   <li>
+    You would usually do any development work against the HEAD branch of CVS.
+   </li>
+   <li>
+    When sending a patch, you usually do not need to worry about which CVS
+    branch it should be applied to. The maintainers of the repository will
+    decide.
+   </li>
+   <li>
+    If an issue starts to get bogged down in list discussion, then it may
+    be appropriate to go into private off-list discussion with a few interested
+    other people. Spare the list from the gory details. Report a summary back
+    to the list to finalise the thread.
+   </li>
+   <li>
+    Become familiar with the mailing lists. As you browse and search, you will
+    see the way other people do things. Follow the leading examples.
+   </li>
+  </ul>
+ </s1>
+
+</body>
+</document>

src/documentation/xdocs/dictionary.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<package name="org.apache.poi">
+  <class name="Class">
+    To be done
+  </class>
+  <interface name="Interface">
+   To be done
+  </interface>
+  <package name="package">
+    <interface name="int2">
+      To be done
+    </interface>
+  </package>
+</package>

src/documentation/xdocs/dtd/XMLSchema.dtd

@@ -0,0 +1,395 @@
+<!-- DTD for XML Schemas: Part 1: Structures
+     Public Identifier: "-//W3C//DTD XMLSCHEMA 200010//EN"
+     Official Location: http://www.w3.org/2000/10/XMLSchema.dtd -->
+<!-- $Id$ -->
+<!-- Note this DTD is NOT normative, or even definitive. -->           <!--d-->
+<!-- prose copy in the structures REC is the definitive version -->    <!--d-->
+<!-- (which shouldn't differ from this one except for this -->         <!--d-->
+<!-- comment and entity expansions, but just in case) -->              <!--d-->
+<!-- With the exception of cases with multiple namespace
+     prefixes for the XML Schema namespace, any XML document which is
+     not valid per this DTD given redefinitions in its internal subset of the
+     'p' and 's' parameter entities below appropriate to its namespace
+     declaration of the XML Schema namespace is almost certainly not
+     a valid schema. -->
+
+<!-- The simpleType element and its constituent parts
+     are defined in XML Schema: Part 2: Datatypes -->
+<!ENTITY % xs-datatypes PUBLIC 'datatypes' 'datatypes.dtd' >
+
+<!ENTITY % p ''> <!-- can be overriden in the internal subset of a
+                      schema document to establish a namespace prefix -->
+<!ENTITY % s ''> <!-- if %p is defined (e.g. as foo:) then you must
+                      also define %s as the suffix for the appropriate
+                      namespace declaration (e.g. :foo) -->
+<!ENTITY % nds 'xmlns%s;'>
+
+<!-- Define all the element names, with optional prefix -->
+<!ENTITY % schema "%p;schema">
+<!ENTITY % complexType "%p;complexType">
+<!ENTITY % complexContent "%p;complexContent">
+<!ENTITY % simpleContent "%p;simpleContent">
+<!ENTITY % extension "%p;extension">
+<!ENTITY % element "%p;element">
+<!ENTITY % unique "%p;unique">
+<!ENTITY % key "%p;key">
+<!ENTITY % keyref "%p;keyref">
+<!ENTITY % selector "%p;selector">
+<!ENTITY % field "%p;field">
+<!ENTITY % group "%p;group">
+<!ENTITY % all "%p;all">
+<!ENTITY % choice "%p;choice">
+<!ENTITY % sequence "%p;sequence">
+<!ENTITY % any "%p;any">
+<!ENTITY % anyAttribute "%p;anyAttribute">
+<!ENTITY % attribute "%p;attribute">
+<!ENTITY % attributeGroup "%p;attributeGroup">
+<!ENTITY % include "%p;include">
+<!ENTITY % import "%p;import">
+<!ENTITY % redefine "%p;redefine">
+<!ENTITY % notation "%p;notation">
+
+<!-- annotation elements -->
+<!ENTITY % annotation "%p;annotation">
+<!ENTITY % appinfo "%p;appinfo">
+<!ENTITY % documentation "%p;documentation">
+
+<!-- Customisation entities for the ATTLIST of each element type.
+     Define one of these if your schema takes advantage of the
+     anyAttribute='##other' in the schema for schemas -->
+
+<!ENTITY % schemaAttrs ''>
+<!ENTITY % complexTypeAttrs ''>
+<!ENTITY % complexContentAttrs ''>
+<!ENTITY % simpleContentAttrs ''>
+<!ENTITY % extensionAttrs ''>
+<!ENTITY % elementAttrs ''>
+<!ENTITY % groupAttrs ''>
+<!ENTITY % allAttrs ''>
+<!ENTITY % choiceAttrs ''>
+<!ENTITY % sequenceAttrs ''>
+<!ENTITY % anyAttrs ''>
+<!ENTITY % anyAttributeAttrs ''>
+<!ENTITY % attributeAttrs ''>
+<!ENTITY % attributeGroupAttrs ''>
+<!ENTITY % uniqueAttrs ''>
+<!ENTITY % keyAttrs ''>
+<!ENTITY % keyrefAttrs ''>
+<!ENTITY % selectorAttrs ''>
+<!ENTITY % fieldAttrs ''>
+<!ENTITY % includeAttrs ''>
+<!ENTITY % importAttrs ''>
+<!ENTITY % redefineAttrs ''>
+<!ENTITY % notationAttrs ''>
+
+<!ENTITY % complexDerivationChoice "(extension|restriction)">
+<!ENTITY % complexDerivationSet "CDATA">
+      <!-- #all or space-separated list drawn from derivationChoice -->
+<!ENTITY % blockSet "CDATA">
+      <!-- #all or space-separated list drawn from
+                      derivationChoice + 'substitution' -->
+
+<!ENTITY % mgs '%all; | %choice; | %sequence;'>
+<!ENTITY % cs '%choice; | %sequence;'>
+<!ENTITY % formValues '(qualified|unqualified)'>
+
+
+<!ENTITY % attrDecls    '((%attribute;| %attributeGroup;)*,(%anyAttribute;)?)'>
+
+<!ENTITY % particleAndAttrs '((%mgs; | %group;)?, %attrDecls;)'>
+
+<!-- This is used in part2 -->
+<!ENTITY % restriction1 '((%mgs; | %group;)?)'>
+
+%xs-datatypes;
+
+<!-- the duplication below is to produce an unambiguous content model
+     which allows annotation everywhere -->
+<!ELEMENT %schema; ((%include; | %import; | %redefine; | %annotation;)*,
+                    ((%simpleType; | %complexType;
+                      | %element; | %attribute;
+                      | %attributeGroup; | %group;
+                      | %notation; ),
+                     (%annotation;)*)* )>
+<!ATTLIST %schema;
+   targetNamespace      %URIref;               #IMPLIED
+   version              CDATA                  #IMPLIED
+   %nds;                %URIref;               #FIXED 'http://www.w3.org/2000/10/XMLSchema'
+   finalDefault         %complexDerivationSet; ''
+   blockDefault         %blockSet;             ''
+   id                   ID                     #IMPLIED
+   elementFormDefault   %formValues;           'unqualified'
+   attributeFormDefault %formValues;           'unqualified'
+   %schemaAttrs;>
+<!-- Note the xmlns declaration is NOT in the Schema for Schemas,
+     because at the Infoset level where schemas operate,
+     xmlns(:prefix) is NOT an attribute! -->
+ 
+<!-- The id attribute here and below is for use in external references
+     from non-schemas using simple fragment identifiers.
+     It is NOT used for schema-to-schema reference, internal or
+     external. -->
+
+<!-- a type is a named content type specification which allows attribute
+     declarations-->
+<!-- -->
+
+<!ELEMENT %complexType; ((%annotation;)?,
+                         (%simpleContent;|%complexContent;|
+                          %particleAndAttrs;))>
+
+<!ATTLIST %complexType;
+          name      %NCName;                        #IMPLIED
+          id        ID                              #IMPLIED
+          abstract  %boolean;                       'false'
+          final     %complexDerivationSet;          #IMPLIED
+          block     %complexDerivationSet;          ''
+          mixed (true|false) 'false'
+          %complexTypeAttrs;>
+
+<!-- particleAndAttrs is shorthand for a root type -->
+<!-- mixed is disallowed if simpleContent, overriden if complexContent
+     has one too. -->
+
+<!-- If anyAttribute appears in one or more referenced attributeGroups
+     and/or explicitly, the intersection of the permissions is used -->
+
+<!ELEMENT %complexContent; (%restriction;|%extension;)>
+<!ATTLIST %complexContent;
+          mixed (true|false) #IMPLIED
+          id    ID           #IMPLIED
+          %complexContentAttrs;>
+
+<!-- restriction should use the branch defined above, not the simple
+     one from part2; extension should use the full model  -->
+
+<!ELEMENT %simpleContent; (%restriction;|%extension;)>
+<!ATTLIST %simpleContent;
+          id    ID           #IMPLIED
+          %simpleContentAttrs;>
+
+<!-- restriction should use the simple branch from part2, not the 
+     one defined above; extension should have no particle  -->
+
+<!ELEMENT %extension; (%particleAndAttrs;)>
+<!ATTLIST %extension;
+          base  %QName;      #REQUIRED
+          id    ID           #IMPLIED
+          %extensionAttrs;>
+
+<!-- an element is declared by either:
+ a name and a type (either nested or referenced via the type attribute)
+ or a ref to an existing element declaration -->
+
+<!ELEMENT %element; ((%annotation;)?, (%complexType;| %simpleType;)?,
+                     (%unique; | %key; | %keyref;)*)>
+<!-- simpleType or complexType only if no type|ref attribute -->
+<!-- ref not allowed at top level -->
+<!ATTLIST %element;
+            name               %NCName;               #IMPLIED
+            id                 ID                     #IMPLIED
+            ref                %QName;                #IMPLIED
+            type               %QName;                #IMPLIED
+            minOccurs          %nonNegativeInteger;   #IMPLIED
+            maxOccurs          CDATA                  #IMPLIED
+            nullable           %boolean;              #IMPLIED
+            substitutionGroup  %QName;                #IMPLIED
+            abstract           %boolean;              'false'
+            final              %complexDerivationSet; #IMPLIED
+            block              %blockSet;             #IMPLIED
+            default            CDATA                  #IMPLIED
+            fixed              CDATA                  #IMPLIED
+            form               %formValues;           #IMPLIED
+            %elementAttrs;>
+<!-- type and ref are mutually exclusive.
+     name and ref are mutually exclusive, one is required -->
+<!-- In the absence of type AND ref, type defaults to type of
+     substitutionGroup, if any, else the ur-type, i.e. unconstrained -->
+<!-- default and fixed are mutually exclusive -->
+
+<!ELEMENT %group; ((%annotation;)?,(%mgs;)?)>
+<!ATTLIST %group; 
+          name        %NCName;               #IMPLIED
+          ref         %QName;                #IMPLIED
+          minOccurs   %nonNegativeInteger;   #IMPLIED
+          maxOccurs   CDATA                  #IMPLIED
+          id          ID                     #IMPLIED
+          %groupAttrs;>
+
+<!ELEMENT %all; ((%annotation;)?, (%element;)*)>
+<!ATTLIST %all;
+          minOccurs   (1)                    #FIXED '1'
+          maxOccurs   (1)                    #FIXED '1'
+          id          ID                     #IMPLIED
+          %allAttrs;>
+
+<!ELEMENT %choice; ((%annotation;)?, (%element;| %group;| %cs; | %any;)*)>
+<!ATTLIST %choice;
+          minOccurs   %nonNegativeInteger;   '1'
+          maxOccurs   CDATA                  '1'
+          id          ID                     #IMPLIED
+          %choiceAttrs;>
+
+<!ELEMENT %sequence; ((%annotation;)?, (%element;| %group;| %cs; | %any;)*)>
+<!ATTLIST %sequence;
+          minOccurs   %nonNegativeInteger;   '1'
+          maxOccurs   CDATA                  '1'
+          id          ID                     #IMPLIED
+          %sequenceAttrs;>
+
+<!-- an anonymous grouping in a model, or
+     a top-level named group definition, or a reference to same -->
+
+<!-- Note that if order is 'all', group is not allowed inside.
+     If order is 'all' THIS group must be alone (or referenced alone) at
+     the top level of a content model -->
+<!-- If order is 'all', minOccurs==maxOccurs==1 on element/any inside -->
+<!-- Should allow minOccurs=0 inside order='all' . . . -->
+
+<!ELEMENT %any; (%annotation;)?>
+<!ATTLIST %any;
+            namespace       CDATA                  '##any'
+            processContents (skip|lax|strict)      'strict'
+            minOccurs       %nonNegativeInteger;   '1'
+            maxOccurs       CDATA                  '1'
+            id              ID                     #IMPLIED
+            %anyAttrs;>
+
+<!-- namespace is interpreted as follows:
+                  ##any      - - any non-conflicting WFXML at all
+
+                  ##other    - - any non-conflicting WFXML from namespace other
+                                  than targetNamespace
+
+                  ##local    - - any unqualified non-conflicting WFXML/attribute
+                  one or     - - any non-conflicting WFXML from
+                  more URI        the listed namespaces
+                  references
+
+                  ##targetNamespace ##local may appear in the above list,
+                    with the obvious meaning -->
+
+<!ELEMENT %anyAttribute; (%annotation;)?>
+<!ATTLIST %anyAttribute;
+            namespace       CDATA              '##any'
+            processContents (skip|lax|strict)  'strict'
+            id              ID                 #IMPLIED
+            %anyAttributeAttrs;>
+<!-- namespace is interpreted as for 'any' above -->
+
+<!-- simpleType only if no type|ref attribute -->
+<!-- ref not allowed at top level, name iff at top level -->
+<!ELEMENT %attribute; ((%annotation;)?, (%simpleType;)?)>
+<!ATTLIST %attribute;
+          name      %NCName;      #IMPLIED
+          id        ID            #IMPLIED
+          ref       %QName;       #IMPLIED
+          type      %QName;       #IMPLIED
+          use       (prohibited|optional|required|fixed|default) #IMPLIED
+          value     CDATA         #IMPLIED
+          form      %formValues;  #IMPLIED
+          %attributeAttrs;>
+<!-- type and ref are mutually exclusive.
+     name and ref are mutually exclusive, one is required -->
+<!-- value only if use is fixed, required or default, or name -->
+<!-- name and use are mutually exclusive -->
+<!-- default for use is optional when nested, none otherwise -->
+<!-- type attr and simpleType content are mutually exclusive -->
+
+<!-- an attributeGroup is a named collection of attribute decls, or a
+     reference thereto -->
+<!ELEMENT %attributeGroup; ((%annotation;)?,
+                       (%attribute; | %attributeGroup;)*,
+                       (%anyAttribute;)?) >
+<!ATTLIST %attributeGroup;
+                 name       %NCName;       #IMPLIED
+                 id         ID             #IMPLIED
+                 ref        %QName;        #IMPLIED
+                 %attributeGroupAttrs;>
+
+<!-- ref iff no content, no name.  ref iff not top level -->
+
+<!-- better reference mechanisms -->
+<!ELEMENT %unique; ((%annotation;)?, %selector;, (%field;)+)>
+<!ATTLIST %unique;
+          name     %NCName;       #REQUIRED
+	  id       ID             #IMPLIED
+	  %uniqueAttrs;>
+
+<!ELEMENT %key;    ((%annotation;)?, %selector;, (%field;)+)>
+<!ATTLIST %key;
+          name     %NCName;       #REQUIRED
+	  id       ID             #IMPLIED
+	  %keyAttrs;>
+
+<!ELEMENT %keyref; ((%annotation;)?, %selector;, (%field;)+)>
+<!ATTLIST %keyref;
+          name     %NCName;       #REQUIRED
+	  refer    %QName;        #REQUIRED
+	  id       ID             #IMPLIED
+	  %keyrefAttrs;>
+
+<!ELEMENT %selector; ((%annotation;)?)>
+<!ATTLIST %selector;
+          xpath %XPathExpr; #REQUIRED
+          id    ID          #IMPLIED
+          %selectorAttrs;>
+<!ELEMENT %field; ((%annotation;)?)>
+<!ATTLIST %field;
+          xpath %XPathExpr; #REQUIRED
+          id    ID          #IMPLIED
+          %fieldAttrs;>
+
+<!-- Schema combination mechanisms -->
+<!ELEMENT %include; (%annotation;)?>
+<!ATTLIST %include;
+          schemaLocation %URIref; #REQUIRED
+          id             ID       #IMPLIED
+          %includeAttrs;>
+
+<!ELEMENT %import; (%annotation;)?>
+<!ATTLIST %import;
+          namespace      %URIref; #IMPLIED
+          schemaLocation %URIref; #IMPLIED
+          id             ID       #IMPLIED
+          %importAttrs;>
+
+<!ELEMENT %redefine; (%annotation; | %simpleType; | %complexType; |
+                      %attributeGroup; | %group;)*>
+<!ATTLIST %redefine;
+          schemaLocation %URIref; #REQUIRED
+          id             ID       #IMPLIED
+          %redefineAttrs;>
+
+<!ELEMENT %notation; (%annotation;)?>
+<!ATTLIST %notation;
+	  name        %NCName;    #REQUIRED
+	  id          ID          #IMPLIED
+	  public      CDATA       #REQUIRED
+	  system      %URIref;    #IMPLIED
+	  %notationAttrs;>
+
+<!-- Annotation is either application information or documentation -->
+<!-- By having these here they are available for datatypes as well
+     as all the structures elements -->
+
+<!ELEMENT %annotation; (%appinfo; | %documentation;)*>
+
+<!-- User must define annotation elements in internal subset for this
+     to work -->
+<!ELEMENT %appinfo; ANY>   <!-- too restrictive -->
+<!ATTLIST %appinfo;
+          source     %URIref;      #IMPLIED
+          id         ID         #IMPLIED
+          %appinfoAttrs;>
+<!ELEMENT %documentation; ANY>   <!-- too restrictive -->
+<!ATTLIST %documentation;
+          source     %URIref;   #IMPLIED
+          id         ID         #IMPLIED
+          xml:lang   CDATA      #IMPLIED
+          %documentationAttrs;>
+
+<!NOTATION XMLSchemaStructures PUBLIC
+           'structures' 'http://www.w3.org/2000/10/XMLSchema.xsd' >
+<!NOTATION XML PUBLIC
+           'REC-xml-1998-0210' 'http://www.w3.org/TR/1998/REC-xml-19980210' >

src/documentation/xdocs/dtd/book-cocoon-v10.dtd

@@ -0,0 +1,70 @@
+<!-- ===================================================================
+     
+     Apache Cocoon Documentation Book DTD (Version 1.0)
+
+PURPOSE:
+This DTD defines the */book.xml documentation configuration files.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE book PUBLIC
+       "-//APACHE//DTD Cocoon Documentation Book Vx.yz//EN"
+       "http://xml.apache.org/DTD/book-cocoon-vxyz.dtd">
+
+  where 
+  
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+      
+NOTES:
+We need to replace this DTD with the proper one.
+We are only using this DTD to enable validation during "build docs"
+because every XML instance must declare its ruleset.
+
+This initial minimal DTD has been reverse-engineered from the structure
+of the current documents, e.g. 
+ docuemntation/xdocs/book.xml
+  
+AUTHORS:
+  David Crossley <crossley@apache.org>
+  
+FIXME:
+  - find the proper DTD for book.xml
+
+CHANGE HISTORY:
+  20011031 Initial version. (DC)
+    
+COPYRIGHT:
+  Copyright (c) @year@ The Apache Software Foundation.
+  
+  Permission to copy in any form is granted provided this notice is 
+  included in all copies. Permission to redistribute is granted 
+  provided this file is distributed untouched in all its parts and 
+  included files.
+  
+==================================================================== -->
+
+<!ELEMENT book (menu+)> 
+<!ELEMENT menu (menu-item|external)*>
+<!ELEMENT menu-item EMPTY>
+<!ELEMENT external EMPTY>
+<!ATTLIST book software CDATA #REQUIRED
+               title CDATA #REQUIRED
+               copyright CDATA #REQUIRED
+               xmlns:xlink CDATA #IMPLIED
+>
+<!ATTLIST menu label CDATA #REQUIRED
+>
+<!ATTLIST menu-item label CDATA #REQUIRED
+                    href CDATA #REQUIRED
+                    type (visible|hidden) "visible"
+>
+<!ATTLIST external  label CDATA #REQUIRED
+                    href CDATA #REQUIRED
+                    type (visible|hidden) "visible"
+>
+
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

src/documentation/xdocs/dtd/changes-v10.dtd

@@ -0,0 +1,91 @@
+<!-- ===================================================================
+
+     Apache Changes DTD (Version 1.0)
+
+PURPOSE:
+  This DTD was developed to create a simple yet powerful document
+  type for software development changes for use with the Apache projects.
+  It is an XML-compliant DTD and it's maintained by the Apache XML
+  project.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE document PUBLIC
+       "-//APACHE//DTD Changes Vx.yz//EN"
+       "http://xml.apache.org/DTD/changes-vxyz.dtd">
+
+  where
+
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+
+NOTES:
+  It is important, expecially in open developped software projects, to keep
+  track of software changes both to give users indications of bugs that might
+  have been resolved, as well, and not less important, to provide credits
+  for the support given to the project. It is considered vital to provide
+  adequate payback using recognition and credits to let users and developers
+  feel part of the community, thus increasing development power.
+
+AUTHORS:
+  Stefano Mazzocchi <stefano@apache.org>
+
+FIXME:
+
+CHANGE HISTORY:
+  19991129 Initial version. (SM)
+  20000316 Added bugfixing attribute. (SM)
+
+COPYRIGHT:
+  Copyright (c) @year@ The Apache Software Foundation.
+
+  Permission to copy in any form is granted provided this notice is
+  included in all copies. Permission to redistribute is granted
+  provided this file is distributed untouched in all its parts and
+  included files.
+
+==================================================================== -->
+
+<!-- =============================================================== -->
+<!-- Extend the Documentation DTD -->
+<!-- =============================================================== -->
+
+<!-- FIXME (SM): this is hardcoding. Find a better way of doing this
+     possibly using public identifiers -->
+<!ENTITY % document-dtd SYSTEM "document-v10.dtd">
+%document-dtd;
+
+<!-- =============================================================== -->
+<!-- Common entities -->
+<!-- =============================================================== -->
+
+<!ENTITY % types "add|remove|update|fix">
+
+<!-- =============================================================== -->
+<!-- Document Type Definition -->
+<!-- =============================================================== -->
+
+<!ELEMENT changes (devs, release*)>
+<!ATTLIST changes %common.att;
+                  %title.att;>
+
+    <!ELEMENT devs (person+)>
+    <!ATTLIST devs %common.att;>
+
+    <!ELEMENT release (action+)>
+    <!ATTLIST release %common.att;
+                      version  CDATA  #REQUIRED
+                      date     CDATA  #REQUIRED>
+
+        <!ELEMENT action (%content.mix;)*>
+        <!ATTLIST action %common.att;
+                         dev  IDREF  #REQUIRED
+                         type (%types;)  #IMPLIED
+                         due-to CDATA #IMPLIED
+                         due-to-email CDATA #IMPLIED
+                         fixes-bug CDATA #IMPLIED>
+
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

src/documentation/xdocs/dtd/characters.ent

@@ -0,0 +1,290 @@
+<!-- 
+     Portions (C) International Organization for Standardization 1986
+     Permission to copy in any form is granted for use with
+     conforming SGML systems and applications as defined in
+     ISO 8879, provided this notice is included in all copies.
+-->
+
+<!-- 
+     Character entity set.
+-->
+
+<!-- Latin A -->
+<!ENTITY nbsp     "&#160;">  <!-- U+00A0 ISOnum    - no-break space = non-breaking space                                   -->
+<!ENTITY iexcl    "&#161;">  <!-- U+00A1 ISOnum    - inverted exclamation mark                                             -->
+<!ENTITY cent     "&#162;">  <!-- U+00A2 ISOnum    - cent sign                                                             -->
+<!ENTITY pound    "&#163;">  <!-- U+00A3 ISOnum    - pound sign                                                            -->
+<!ENTITY curren   "&#164;">  <!-- U+00A4 ISOnum    - currency sign                                                         -->
+<!ENTITY yen      "&#165;">  <!-- U+00A5 ISOnum    - yen sign = yuan sign                                                  -->
+<!ENTITY brvbar   "&#166;">  <!-- U+00A6 ISOnum    - broken bar = broken vertical bar                                      -->
+<!ENTITY sect     "&#167;">  <!-- U+00A7 ISOnum    - section sign                                                          -->
+<!ENTITY uml      "&#168;">  <!-- U+00A8 ISOdia    - diaeresis = spacing diaeresis                                         -->
+<!ENTITY copy     "&#169;">  <!-- U+00A9 ISOnum    - copyright sign                                                        -->
+<!ENTITY ordf     "&#170;">  <!-- U+00AA ISOnum    - feminine ordinal indicator                                            -->
+<!ENTITY laquo    "&#171;">  <!-- U+00AB ISOnum    - left-pointing double angle quotation mark = left pointing guillemet   -->
+<!ENTITY not      "&#172;">  <!-- U+00AC ISOnum    - not sign                                                              -->
+<!ENTITY shy      "&#173;">  <!-- U+00AD ISOnum    - soft hyphen = discretionary hyphen                                    -->
+<!ENTITY reg      "&#174;">  <!-- U+00AE ISOnum    - registered sign = registered trade mark sign                          -->
+<!ENTITY macr     "&#175;">  <!-- U+00AF ISOdia    - macron = spacing macron = overline = APL overbar                      -->
+<!ENTITY deg      "&#176;">  <!-- U+00B0 ISOnum    - degree sign                                                           -->
+<!ENTITY plusmn   "&#177;">  <!-- U+00B1 ISOnum    - plus-minus sign = plus-or-minus sign                                  -->
+<!ENTITY sup2     "&#178;">  <!-- U+00B2 ISOnum    - superscript two = superscript digit two = squared                     -->
+<!ENTITY sup3     "&#179;">  <!-- U+00B3 ISOnum    - superscript three = superscript digit three = cubed                   -->
+<!ENTITY acute    "&#180;">  <!-- U+00B4 ISOdia    - acute accent = spacing acute                                          -->
+<!ENTITY micro    "&#181;">  <!-- U+00B5 ISOnum    - micro sign                                                            -->
+<!ENTITY para     "&#182;">  <!-- U+00B6 ISOnum    - pilcrow sign = paragraph sign                                         -->
+<!ENTITY middot   "&#183;">  <!-- U+00B7 ISOnum    - middle dot = Georgian comma = Greek middle dot                        -->
+<!ENTITY cedil    "&#184;">  <!-- U+00B8 ISOdia    - cedilla = spacing cedilla                                             -->
+<!ENTITY sup1     "&#185;">  <!-- U+00B9 ISOnum    - superscript one = superscript digit one                               -->
+<!ENTITY ordm     "&#186;">  <!-- U+00BA ISOnum    - masculine ordinal indicator                                           -->
+<!ENTITY raquo    "&#187;">  <!-- U+00BB ISOnum    - right-pointing double angle quotation mark = right pointing guillemet -->
+<!ENTITY frac14   "&#188;">  <!-- U+00BC ISOnum    - vulgar fraction one quarter = fraction one quarter                    -->
+<!ENTITY frac12   "&#189;">  <!-- U+00BD ISOnum    - vulgar fraction one half = fraction one half                          -->
+<!ENTITY frac34   "&#190;">  <!-- U+00BE ISOnum    - vulgar fraction three quarters = fraction three quarters              -->
+<!ENTITY iquest   "&#191;">  <!-- U+00BF ISOnum    - inverted question mark = turned question mark                         -->
+<!ENTITY Agrave   "&#192;">  <!-- U+00C0 ISOlat1   - latin capital letter A with grave = latin capital letter A grave      -->
+<!ENTITY Aacute   "&#193;">  <!-- U+00C1 ISOlat1   - latin capital letter A with acute                                     -->
+<!ENTITY Acirc    "&#194;">  <!-- U+00C2 ISOlat1   - latin capital letter A with circumflex                                -->
+<!ENTITY Atilde   "&#195;">  <!-- U+00C3 ISOlat1   - latin capital letter A with tilde                                     -->
+<!ENTITY Auml     "&#196;">  <!-- U+00C4 ISOlat1   - latin capital letter A with diaeresis                                 -->
+<!ENTITY Aring    "&#197;">  <!-- U+00C5 ISOlat1   - latin capital letter A with ring above = latin capital letter A ring  -->
+<!ENTITY AElig    "&#198;">  <!-- U+00C6 ISOlat1   - latin capital letter AE = latin capital ligature AE                   -->
+<!ENTITY Ccedil   "&#199;">  <!-- U+00C7 ISOlat1   - latin capital letter C with cedilla                                   -->
+<!ENTITY Egrave   "&#200;">  <!-- U+00C8 ISOlat1   - latin capital letter E with grave                                     -->
+<!ENTITY Eacute   "&#201;">  <!-- U+00C9 ISOlat1   - latin capital letter E with acute                                     -->
+<!ENTITY Ecirc    "&#202;">  <!-- U+00CA ISOlat1   - latin capital letter E with circumflex                                -->
+<!ENTITY Euml     "&#203;">  <!-- U+00CB ISOlat1   - latin capital letter E with diaeresis                                 -->
+<!ENTITY Igrave   "&#204;">  <!-- U+00CC ISOlat1   - latin capital letter I with grave                                     -->
+<!ENTITY Iacute   "&#205;">  <!-- U+00CD ISOlat1   - latin capital letter I with acute                                     -->
+<!ENTITY Icirc    "&#206;">  <!-- U+00CE ISOlat1   - latin capital letter I with circumflex                                -->
+<!ENTITY Iuml     "&#207;">  <!-- U+00CF ISOlat1   - latin capital letter I with diaeresis                                 -->
+<!ENTITY ETH      "&#208;">  <!-- U+00D0 ISOlat1   - latin capital letter ETH                                              -->
+<!ENTITY Ntilde   "&#209;">  <!-- U+00D1 ISOlat1   - latin capital letter N with tilde                                     -->
+<!ENTITY Ograve   "&#210;">  <!-- U+00D2 ISOlat1   - latin capital letter O with grave                                     -->
+<!ENTITY Oacute   "&#211;">  <!-- U+00D3 ISOlat1   - latin capital letter O with acute                                     -->
+<!ENTITY Ocirc    "&#212;">  <!-- U+00D4 ISOlat1   - latin capital letter O with circumflex                                -->
+<!ENTITY Otilde   "&#213;">  <!-- U+00D5 ISOlat1   - latin capital letter O with tilde                                     -->
+<!ENTITY Ouml     "&#214;">  <!-- U+00D6 ISOlat1   - latin capital letter O with diaeresis                                 -->
+<!ENTITY times    "&#215;">  <!-- U+00D7 ISOnum    - multiplication sign                                                   -->
+<!ENTITY Oslash   "&#216;">  <!-- U+00D8 ISOlat1   - latin capital letter O with stroke = latin capital letter O slash     -->
+<!ENTITY Ugrave   "&#217;">  <!-- U+00D9 ISOlat1   - latin capital letter U with grave                                     -->
+<!ENTITY Uacute   "&#218;">  <!-- U+00DA ISOlat1   - latin capital letter U with acute                                     -->
+<!ENTITY Ucirc    "&#219;">  <!-- U+00DB ISOlat1   - latin capital letter U with circumflex                                -->
+<!ENTITY Uuml     "&#220;">  <!-- U+00DC ISOlat1   - latin capital letter U with diaeresis                                 -->
+<!ENTITY Yacute   "&#221;">  <!-- U+00DD ISOlat1   - latin capital letter Y with acute                                     -->
+<!ENTITY THORN    "&#222;">  <!-- U+00DE ISOlat1   - latin capital letter THORN                                            -->
+<!ENTITY szlig    "&#223;">  <!-- U+00DF ISOlat1   - latin small letter sharp s = ess-zed                                  -->
+<!ENTITY agrave   "&#224;">  <!-- U+00E0 ISOlat1   - latin small letter a with grave = latin small letter a grave          -->
+<!ENTITY aacute   "&#225;">  <!-- U+00E1 ISOlat1   - latin small letter a with acute                                       -->
+<!ENTITY acirc    "&#226;">  <!-- U+00E2 ISOlat1   - latin small letter a with circumflex                                  -->
+<!ENTITY atilde   "&#227;">  <!-- U+00E3 ISOlat1   - latin small letter a with tilde                                       -->
+<!ENTITY auml     "&#228;">  <!-- U+00E4 ISOlat1   - latin small letter a with diaeresis                                   -->
+<!ENTITY aring    "&#229;">  <!-- U+00E5 ISOlat1   - latin small letter a with ring above = latin small letter a ring      -->
+<!ENTITY aelig    "&#230;">  <!-- U+00E6 ISOlat1   - latin small letter ae = latin small ligature ae                       -->
+<!ENTITY ccedil   "&#231;">  <!-- U+00E7 ISOlat1   - latin small letter c with cedilla                                     -->
+<!ENTITY egrave   "&#232;">  <!-- U+00E8 ISOlat1   - latin small letter e with grave                                       -->
+<!ENTITY eacute   "&#233;">  <!-- U+00E9 ISOlat1   - latin small letter e with acute                                       -->
+<!ENTITY ecirc    "&#234;">  <!-- U+00EA ISOlat1   - latin small letter e with circumflex                                  -->
+<!ENTITY euml     "&#235;">  <!-- U+00EB ISOlat1   - latin small letter e with diaeresis                                   -->
+<!ENTITY igrave   "&#236;">  <!-- U+00EC ISOlat1   - latin small letter i with grave                                       -->
+<!ENTITY iacute   "&#237;">  <!-- U+00ED ISOlat1   - latin small letter i with acute                                       -->
+<!ENTITY icirc    "&#238;">  <!-- U+00EE ISOlat1   - latin small letter i with circumflex                                  -->
+<!ENTITY iuml     "&#239;">  <!-- U+00EF ISOlat1   - latin small letter i with diaeresis                                   -->
+<!ENTITY eth      "&#240;">  <!-- U+00F0 ISOlat1   - latin small letter eth                                                -->
+<!ENTITY ntilde   "&#241;">  <!-- U+00F1 ISOlat1   - latin small letter n with tilde                                       -->
+<!ENTITY ograve   "&#242;">  <!-- U+00F2 ISOlat1   - latin small letter o with grave                                       -->
+<!ENTITY oacute   "&#243;">  <!-- U+00F3 ISOlat1   - latin small letter o with acute                                       -->
+<!ENTITY ocirc    "&#244;">  <!-- U+00F4 ISOlat1   - latin small letter o with circumflex                                  -->
+<!ENTITY otilde   "&#245;">  <!-- U+00F5 ISOlat1   - latin small letter o with tilde                                       -->
+<!ENTITY ouml     "&#246;">  <!-- U+00F6 ISOlat1   - latin small letter o with diaeresis                                   -->
+<!ENTITY divide   "&#247;">  <!-- U+00F7 ISOnum    - division sign                                                         -->
+<!ENTITY oslash   "&#248;">  <!-- U+00F8 ISOlat1   - latin small letter o with stroke = latin small letter o slash         -->
+<!ENTITY ugrave   "&#249;">  <!-- U+00F9 ISOlat1   - latin small letter u with grave                                       -->
+<!ENTITY uacute   "&#250;">  <!-- U+00FA ISOlat1   - latin small letter u with acute                                       -->
+<!ENTITY ucirc    "&#251;">  <!-- U+00FB ISOlat1   - latin small letter u with circumflex                                  -->
+<!ENTITY uuml     "&#252;">  <!-- U+00FC ISOlat1   - latin small letter u with diaeresis                                   -->
+<!ENTITY yacute   "&#253;">  <!-- U+00FD ISOlat1   - latin small letter y with acute                                       -->
+<!ENTITY thorn    "&#254;">  <!-- U+00FE ISOlat1   - latin small letter thorn                                              -->
+<!ENTITY yuml     "&#255;">  <!-- U+00FF ISOlat1   - latin small letter y with diaeresis                                   -->
+
+<!-- Latin Extended-A -->
+<!ENTITY OElig    "&#338;">  <!-- U+0152 ISOlat2   - latin capital ligature OE                                             -->
+<!ENTITY oelig    "&#339;">  <!-- U+0153 ISOlat2   - latin small ligature oe                                               -->
+
+<!-- ligature is a misnomer, this is a separate character in some languages -->
+<!ENTITY Scaron   "&#352;">  <!-- U+0160 ISOlat2   - latin capital letter S with caron                                     -->
+<!ENTITY scaron   "&#353;">  <!-- U+0161 ISOlat2   - latin small letter s with caron                                       -->
+<!ENTITY Yuml     "&#376;">  <!-- U+0178 ISOlat2   - latin capital letter Y with diaeresis                                 -->
+
+<!-- Spacing Modifier Letters -->
+<!ENTITY circ     "&#710;">  <!-- U+02C6 ISOpub    - modifier letter circumflex accent                                     -->
+<!ENTITY tilde    "&#732;">  <!-- U+02DC ISOdia    - small tilde                                                           -->
+
+<!-- General Punctuation -->
+<!ENTITY ensp     "&#8194;"> <!-- U+2002 ISOpub    - en space                                                              -->
+<!ENTITY emsp     "&#8195;"> <!-- U+2003 ISOpub    - em space                                                              -->
+<!ENTITY thinsp   "&#8201;"> <!-- U+2009 ISOpub    - thin space                                                            -->
+<!ENTITY zwnj     "&#8204;"> <!-- U+200C RFC 2070  - zero width non-joiner                                                 -->
+<!ENTITY zwj      "&#8205;"> <!-- U+200D RFC 2070  - zero width joiner                                                     -->
+<!ENTITY lrm      "&#8206;"> <!-- U+200E RFC 2070  - left-to-right mark                                                    -->
+<!ENTITY rlm      "&#8207;"> <!-- U+200F RFC 2070  - right-to-left mark                                                    -->
+<!ENTITY ndash    "&#8211;"> <!-- U+2013 ISOpub    - en dash                                                               -->
+<!ENTITY mdash    "&#8212;"> <!-- U+2014 ISOpub    - em dash                                                               -->
+<!ENTITY lsquo    "&#8216;"> <!-- U+2018 ISOnum    - left single quotation mark                                            -->
+<!ENTITY rsquo    "&#8217;"> <!-- U+2019 ISOnum    - right single quotation mark                                           -->
+<!ENTITY sbquo    "&#8218;"> <!-- U+201A NEW       - single low-9 quotation mark                                           -->
+<!ENTITY ldquo    "&#8220;"> <!-- U+201C ISOnum    - left double quotation mark                                            -->
+<!ENTITY rdquo    "&#8221;"> <!-- U+201D ISOnum    - right double quotation mark,                                          -->
+<!ENTITY bdquo    "&#8222;"> <!-- U+201E NEW       - double low-9 quotation mark                                           -->
+<!ENTITY dagger   "&#8224;"> <!-- U+2020 ISOpub    - dagger                                                                -->
+<!ENTITY Dagger   "&#8225;"> <!-- U+2021 ISOpub    - double dagger                                                         -->
+<!ENTITY permil   "&#8240;"> <!-- U+2030 ISOtech   - per mille sign                                                        -->
+<!ENTITY lsaquo   "&#8249;"> <!-- U+2039 ISO prop. - single left-pointing angle quotation mark                             -->
+
+<!-- lsaquo is proposed but not yet ISO standardized -->
+<!ENTITY rsaquo   "&#8250;"> <!-- U+203A ISO prop. -   single right-pointing angle quotation mark                          -->
+
+<!-- rsaquo is proposed but not yet ISO standardized -->
+<!ENTITY euro     "&#8364;"> <!-- U+20AC NEW       -   euro sign                                                           -->
+
+<!-- Latin Extended-B -->
+<!ENTITY fnof     "&#402;">  <!-- U+0192 ISOtech   - latin small f with hook = function = florin                           -->
+
+<!-- Greek -->
+<!ENTITY Alpha    "&#913;">  <!-- U+0391           - greek capital letter alpha                                            -->
+<!ENTITY Beta     "&#914;">  <!-- U+0392           - greek capital letter beta                                             -->
+<!ENTITY Gamma    "&#915;">  <!-- U+0393 ISOgrk3   - greek capital letter gamma                                            -->
+<!ENTITY Delta    "&#916;">  <!-- U+0394 ISOgrk3   - greek capital letter delta                                            -->
+<!ENTITY Epsilon  "&#917;">  <!-- U+0395           - greek capital letter epsilon                                          -->
+<!ENTITY Zeta     "&#918;">  <!-- U+0396           - greek capital letter zeta                                             -->
+<!ENTITY Eta      "&#919;">  <!-- U+0397           - greek capital letter eta                                              -->
+<!ENTITY Theta    "&#920;">  <!-- U+0398 ISOgrk3   - greek capital letter theta                                            -->
+<!ENTITY Iota     "&#921;">  <!-- U+0399           - greek capital letter iota                                             -->
+<!ENTITY Kappa    "&#922;">  <!-- U+039A           - greek capital letter kappa                                            -->
+<!ENTITY Lambda   "&#923;">  <!-- U+039B ISOgrk3   - greek capital letter lambda                                           -->
+<!ENTITY Mu       "&#924;">  <!-- U+039C           - greek capital letter mu                                               -->
+<!ENTITY Nu       "&#925;">  <!-- U+039D           - greek capital letter nu                                               -->
+<!ENTITY Xi       "&#926;">  <!-- U+039E ISOgrk3   - greek capital letter xi                                               -->
+<!ENTITY Omicron  "&#927;">  <!-- U+039F           - greek capital letter omicron                                          -->
+<!ENTITY Pi       "&#928;">  <!-- U+03A0 ISOgrk3   - greek capital letter pi                                               -->
+<!ENTITY Rho      "&#929;">  <!-- U+03A1           - greek capital letter rho                                              -->
+<!ENTITY Sigma    "&#931;">  <!-- U+03A3 ISOgrk3   - greek capital letter sigma                                            -->
+<!ENTITY Tau      "&#932;">  <!-- U+03A4           - greek capital letter tau                                              -->
+<!ENTITY Upsilon  "&#933;">  <!-- U+03A5 ISOgrk3   - greek capital letter upsilon                                          -->
+<!ENTITY Phi      "&#934;">  <!-- U+03A6 ISOgrk3   - greek capital letter phi                                              -->
+<!ENTITY Chi      "&#935;">  <!-- U+03A7           - greek capital letter chi                                              -->
+<!ENTITY Psi      "&#936;">  <!-- U+03A8 ISOgrk3   - greek capital letter psi                                              -->
+<!ENTITY Omega    "&#937;">  <!-- U+03A9 ISOgrk3   - greek capital letter omega                                            -->
+<!ENTITY alpha    "&#945;">  <!-- U+03B1 ISOgrk3   - greek small letter alpha                                              -->
+<!ENTITY beta     "&#946;">  <!-- U+03B2 ISOgrk3   - greek small letter beta                                               -->
+<!ENTITY gamma    "&#947;">  <!-- U+03B3 ISOgrk3   - greek small letter gamma                                              -->
+<!ENTITY delta    "&#948;">  <!-- U+03B4 ISOgrk3   - greek small letter delta                                              -->
+<!ENTITY epsilon  "&#949;">  <!-- U+03B5 ISOgrk3   - greek small letter epsilon                                            -->
+<!ENTITY zeta     "&#950;">  <!-- U+03B6 ISOgrk3   - greek small letter zeta                                               -->
+<!ENTITY eta      "&#951;">  <!-- U+03B7 ISOgrk3   - greek small letter eta                                                -->
+<!ENTITY theta    "&#952;">  <!-- U+03B8 ISOgrk3   - greek small letter theta                                              -->
+<!ENTITY iota     "&#953;">  <!-- U+03B9 ISOgrk3   - greek small letter iota                                               -->
+<!ENTITY kappa    "&#954;">  <!-- U+03BA ISOgrk3   - greek small letter kappa                                              -->
+<!ENTITY lambda   "&#955;">  <!-- U+03BB ISOgrk3   - greek small letter lambda                                             -->
+<!ENTITY mu       "&#956;">  <!-- U+03BC ISOgrk3   - greek small letter mu                                                 -->
+<!ENTITY nu       "&#957;">  <!-- U+03BD ISOgrk3   - greek small letter nu                                                 -->
+<!ENTITY xi       "&#958;">  <!-- U+03BE ISOgrk3   - greek small letter xi                                                 -->
+<!ENTITY omicron  "&#959;">  <!-- U+03BF NEW       - greek small letter omicron                                            -->
+<!ENTITY pi       "&#960;">  <!-- U+03C0 ISOgrk3   - greek small letter pi                                                 -->
+<!ENTITY rho      "&#961;">  <!-- U+03C1 ISOgrk3   - greek small letter rho                                                -->
+<!ENTITY sigmaf   "&#962;">  <!-- U+03C2 ISOgrk3   - greek small letter final sigma                                        -->
+<!ENTITY sigma    "&#963;">  <!-- U+03C3 ISOgrk3   - greek small letter sigma                                              -->
+<!ENTITY tau      "&#964;">  <!-- U+03C4 ISOgrk3   - greek small letter tau                                                -->
+<!ENTITY upsilon  "&#965;">  <!-- U+03C5 ISOgrk3   - greek small letter upsilon                                            -->
+<!ENTITY phi      "&#966;">  <!-- U+03C6 ISOgrk3   - greek small letter phi                                                -->
+<!ENTITY chi      "&#967;">  <!-- U+03C7 ISOgrk3   - greek small letter chi                                                -->
+<!ENTITY psi      "&#968;">  <!-- U+03C8 ISOgrk3   - greek small letter psi                                                -->
+<!ENTITY omega    "&#969;">  <!-- U+03C9 ISOgrk3   - greek small letter omega                                              -->
+<!ENTITY thetasym "&#977;">  <!-- U+03D1 NEW       - greek small letter theta symbol                                       -->
+<!ENTITY upsih    "&#978;">  <!-- U+03D2 NEW       - greek upsilon with hook symbol                                        -->
+<!ENTITY piv      "&#982;">  <!-- U+03D6 ISOgrk3   - greek pi symbol                                                       -->
+
+<!-- General Punctuation -->
+<!ENTITY bull     "&#8226;"> <!-- U+2022 ISOpub    - bullet = black small circle                                           -->
+<!ENTITY hellip   "&#8230;"> <!-- U+2026 ISOpub    - horizontal ellipsis = three dot leader                                -->
+<!ENTITY prime    "&#8242;"> <!-- U+2032 ISOtech   - prime = minutes = feet                                                -->
+<!ENTITY Prime    "&#8243;"> <!-- U+2033 ISOtech   - double prime = seconds = inches                                       -->
+<!ENTITY oline    "&#8254;"> <!-- U+203E NEW       - overline = spacing overscore                                          -->
+<!ENTITY frasl    "&#8260;"> <!-- U+2044 NEW       - fraction slash                                                        -->
+
+<!-- Letterlike Symbols -->
+<!ENTITY weierp   "&#8472;"> <!-- U+2118 ISOamso   - script capital P = power set = Weierstrass p                          -->
+<!ENTITY image    "&#8465;"> <!-- U+2111 ISOamso   - blackletter capital I = imaginary part                                -->
+<!ENTITY real     "&#8476;"> <!-- U+211C ISOamso   - blackletter capital R = real part symbol                              -->
+<!ENTITY trade    "&#8482;"> <!-- U+2122 ISOnum    - trade mark sign                                                       -->
+<!ENTITY alefsym  "&#8501;"> <!-- U+2135 NEW       - alef symbol = first transfinite cardinal                              -->
+
+<!-- Arrows -->
+<!ENTITY larr     "&#8592;"> <!-- U+2190 ISOnum    - leftwards arrow                                                       -->
+<!ENTITY uarr     "&#8593;"> <!-- U+2191 ISOnum    - upwards arrow                                                         -->
+<!ENTITY rarr     "&#8594;"> <!-- U+2192 ISOnum    - rightwards arrow                                                      -->
+<!ENTITY darr     "&#8595;"> <!-- U+2193 ISOnum    - downwards arrow                                                       -->
+<!ENTITY harr     "&#8596;"> <!-- U+2194 ISOamsa   - left right arrow                                                      -->
+<!ENTITY crarr    "&#8629;"> <!-- U+21B5 NEW       - downwards arrow with corner leftwards = carriage return               -->
+<!ENTITY lArr     "&#8656;"> <!-- U+21D0 ISOtech   - leftwards double arrow                                                -->
+<!ENTITY uArr     "&#8657;"> <!-- U+21D1 ISOamsa   - upwards double arrow                                                  -->
+<!ENTITY rArr     "&#8658;"> <!-- U+21D2 ISOtech   - rightwards double arrow                                               -->
+<!ENTITY dArr     "&#8659;"> <!-- U+21D3 ISOamsa   - downwards double arrow                                                -->
+<!ENTITY hArr     "&#8660;"> <!-- U+21D4 ISOamsa   - left right double arrow                                               -->
+
+<!-- Mathematical Operators -->
+<!ENTITY forall   "&#8704;"> <!-- U+2200 ISOtech   - for all                                                               -->
+<!ENTITY part     "&#8706;"> <!-- U+2202 ISOtech   - partial differential                                                  -->
+<!ENTITY exist    "&#8707;"> <!-- U+2203 ISOtech   - there exists                                                          -->
+<!ENTITY empty    "&#8709;"> <!-- U+2205 ISOamso   - empty set = null set = diameter                                       -->
+<!ENTITY nabla    "&#8711;"> <!-- U+2207 ISOtech   - nabla = backward difference                                           -->
+<!ENTITY isin     "&#8712;"> <!-- U+2208 ISOtech   - element of                                                            -->
+<!ENTITY notin    "&#8713;"> <!-- U+2209 ISOtech   - not an element of                                                     -->
+<!ENTITY ni       "&#8715;"> <!-- U+220B ISOtech   - contains as member                                                    -->
+<!ENTITY prod     "&#8719;"> <!-- U+220F ISOamsb   - n-ary product = product sign                                          -->
+<!ENTITY sum      "&#8721;"> <!-- U+2211 ISOamsb   - n-ary sumation                                                        -->
+<!ENTITY minus    "&#8722;"> <!-- U+2212 ISOtech   - minus sign                                                            -->
+<!ENTITY lowast   "&#8727;"> <!-- U+2217 ISOtech   - asterisk operator                                                     -->
+<!ENTITY radic    "&#8730;"> <!-- U+221A ISOtech   - square root = radical sign                                            -->
+<!ENTITY prop     "&#8733;"> <!-- U+221D ISOtech   - proportional to                                                       -->
+<!ENTITY infin    "&#8734;"> <!-- U+221E ISOtech   - infinity                                                              -->
+<!ENTITY ang      "&#8736;"> <!-- U+2220 ISOamso   - angle                                                                 -->
+<!ENTITY and      "&#8743;"> <!-- U+2227 ISOtech   - logical and = wedge                                                   -->
+<!ENTITY or       "&#8744;"> <!-- U+2228 ISOtech   - logical or = vee                                                      -->
+<!ENTITY cap      "&#8745;"> <!-- U+2229 ISOtech   - intersection = cap                                                    -->
+<!ENTITY cup      "&#8746;"> <!-- U+222A ISOtech   - union = cup                                                           -->
+<!ENTITY int      "&#8747;"> <!-- U+222B ISOtech   - integral                                                              -->
+<!ENTITY there4   "&#8756;"> <!-- U+2234 ISOtech   - therefore                                                             -->
+<!ENTITY sim      "&#8764;"> <!-- U+223C ISOtech   - tilde operator = varies with = similar to                             -->
+<!ENTITY cong     "&#8773;"> <!-- U+2245 ISOtech   - approximately equal to                                                -->
+<!ENTITY asymp    "&#8776;"> <!-- U+2248 ISOamsr   - almost equal to = asymptotic to                                       -->
+<!ENTITY ne       "&#8800;"> <!-- U+2260 ISOtech   - not equal to                                                          -->
+<!ENTITY equiv    "&#8801;"> <!-- U+2261 ISOtech   - identical to                                                          -->
+<!ENTITY le       "&#8804;"> <!-- U+2264 ISOtech   - less-than or equal to                                                 -->
+<!ENTITY ge       "&#8805;"> <!-- U+2265 ISOtech   - greater-than or equal to                                              -->
+<!ENTITY sub      "&#8834;"> <!-- U+2282 ISOtech   - subset of                                                             -->
+<!ENTITY sup      "&#8835;"> <!-- U+2283 ISOtech   - superset of                                                           -->
+<!ENTITY nsub     "&#8836;"> <!-- U+2284 ISOamsn   - not a subset of                                                       -->
+<!ENTITY sube     "&#8838;"> <!-- U+2286 ISOtech   - subset of or equal to                                                 -->
+<!ENTITY supe     "&#8839;"> <!-- U+2287 ISOtech   - superset of or equal to                                               -->
+<!ENTITY oplus    "&#8853;"> <!-- U+2295 ISOamsb   - circled plus = direct sum                                             -->
+<!ENTITY otimes   "&#8855;"> <!-- U+2297 ISOamsb   - circled times = vector product                                        -->
+<!ENTITY perp     "&#8869;"> <!-- U+22A5 ISOtech   - up tack = orthogonal to = perpendicular                               -->
+<!ENTITY sdot     "&#8901;"> <!-- U+22C5 ISOamsb   - dot operator                                                          -->
+
+<!-- Miscellaneous Technical -->
+<!ENTITY lceil    "&#8968;"> <!-- U+2308 ISOamsc   - left ceiling = apl upstile                                            -->
+<!ENTITY rceil    "&#8969;"> <!-- U+2309 ISOamsc   - right ceiling                                                         -->
+<!ENTITY lfloor   "&#8970;"> <!-- U+230A ISOamsc   - left floor = apl downstile                                            -->
+<!ENTITY rfloor   "&#8971;"> <!-- U+230B ISOamsc   - right floor                                                           -->
+<!ENTITY lang     "&#9001;"> <!-- U+2329 ISOtech   - left-pointing angle bracket = bra                                     -->
+<!ENTITY rang     "&#9002;"> <!-- U+232A ISOtech   - right-pointing angle bracket = ket                                    -->
+
+<!-- Geometric Shapes -->
+<!ENTITY loz      "&#9674;"> <!-- U+25CA ISOpub    - lozenge                                                               -->
+
+<!-- Miscellaneous Symbols -->
+<!ENTITY spades   "&#9824;"> <!-- U+2660 ISOpub    - black spade suit                                                      -->
+<!ENTITY clubs    "&#9827;"> <!-- U+2663 ISOpub    - black club suit = shamrock                                            -->
+<!ENTITY hearts   "&#9829;"> <!-- U+2665 ISOpub    - black heart suit = valentine                                          -->
+<!ENTITY diams    "&#9830;"> <!-- U+2666 ISOpub    - black diamond suit                                                    -->

src/documentation/xdocs/dtd/datatypes.dtd

@@ -0,0 +1,195 @@
+<!-- DTD for XML Schemas: Part 2: Datatypes -->
+<!-- Id: datatypes.dtd,v 1.14 2000/10/23 08:58:09 ht Exp  -->
+
+<!-- This DTD cannot be used on its own, it is intended only for incorporation
+     in XMLSchema.dtd, q.v. -->
+
+<!-- Define all the element names, with optional prefix -->
+<!ENTITY % simpleType "%p;simpleType">
+<!ENTITY % restriction "%p;restriction">
+<!ENTITY % list "%p;list">
+<!ENTITY % union "%p;union">
+<!ENTITY % maxExclusive "%p;maxExclusive">
+<!ENTITY % minExclusive "%p;minExclusive">
+<!ENTITY % maxInclusive "%p;maxInclusive">
+<!ENTITY % minInclusive "%p;minInclusive">
+<!ENTITY % precision "%p;precision">
+<!ENTITY % scale "%p;scale">
+<!ENTITY % length "%p;length">
+<!ENTITY % minLength "%p;minLength">
+<!ENTITY % maxLength "%p;maxLength">
+<!ENTITY % enumeration "%p;enumeration">
+<!ENTITY % whiteSpace "%p;whiteSpace">
+<!ENTITY % pattern "%p;pattern">
+<!ENTITY % encoding "%p;encoding">
+<!ENTITY % period "%p;period">
+<!ENTITY % duration "%p;duration">
+
+<!-- Customisation entities for the ATTLIST of each element type.
+     Define one of these if your schema takes advantage of the
+     anyAttribute='##other' in the schema for schemas -->
+
+<!ENTITY % simpleTypeAttrs "">
+<!ENTITY % restrictionAttrs "">
+<!ENTITY % listAttrs "">
+<!ENTITY % unionAttrs "">
+<!ENTITY % simpleTypeAttrs "">
+<!ENTITY % maxExclusiveAttrs "">
+<!ENTITY % minExclusiveAttrs "">
+<!ENTITY % maxInclusiveAttrs "">
+<!ENTITY % minInclusiveAttrs "">
+<!ENTITY % precisionAttrs "">
+<!ENTITY % scaleAttrs "">
+<!ENTITY % lengthAttrs "">
+<!ENTITY % minLengthAttrs "">
+<!ENTITY % maxLengthAttrs "">
+<!ENTITY % enumerationAttrs "">
+<!ENTITY % whiteSpaceAttrs "">
+<!ENTITY % patternAttrs "">
+<!ENTITY % encodingAttrs "">
+<!ENTITY % periodAttrs "">
+<!ENTITY % durationAttrs "">
+<!ENTITY % appinfoAttrs "">
+<!ENTITY % documentationAttrs "">
+
+<!-- Define some entities for informative use as attribute types -->
+<!ENTITY % URIref "CDATA">
+<!ENTITY % XPathExpr "CDATA">
+<!ENTITY % QName "NMTOKEN">
+<!ENTITY % QNames "NMTOKENS">
+<!ENTITY % NCName "NMTOKEN">
+<!ENTITY % nonNegativeInteger "NMTOKEN">
+<!ENTITY % boolean "(true|false)">
+
+<!-- Note that the use of 'facet' below is less restrictive than is
+     really intended:  There should in fact be no more than one of each of
+     minInclusive, minExclusive, maxInclusive, maxExclusive,
+     precision, scale,
+     length, maxLength, minLength, encoding, period within datatype,
+     and the min- and max- variants of Inclusive and Exclusive are
+     mutually exclusive.
+     On the other hand,  pattern and enumeration may repeat -->
+<!ENTITY % minBound "(%minInclusive; | %minExclusive;)">
+<!ENTITY % maxBound "(%maxInclusive; | %maxExclusive;)">
+<!ENTITY % bounds "%minBound; | %maxBound;">
+<!ENTITY % numeric "%precision; | %scale;">
+<!ENTITY % ordered "%bounds; | %numeric;">
+<!ENTITY % unordered
+   "%pattern; | %enumeration; | %whiteSpace; | %length; | %maxLength; | %minLength;
+    | %encoding; | %period; | %duration;">
+<!ENTITY % facet "%ordered; | %unordered;">
+<!ENTITY % facetAttr "value CDATA #REQUIRED">
+<!ENTITY % fixedAttr "fixed %boolean; #IMPLIED">
+<!ENTITY % facetModel "(%annotation;)?">
+<!ELEMENT %simpleType; ((%annotation;)?, (%restriction; | %list; | %union;))>
+<!ATTLIST %simpleType;
+    name      %NCName; #IMPLIED
+    id        ID       #IMPLIED
+    %simpleTypeAttrs;>
+<!-- name is required at top level -->
+<!ELEMENT %restriction; ((%annotation;)?,
+                         (%restriction1; |
+                          ((%simpleType;)?,(%facet;)*)),
+                         (%attrDecls;))>
+<!ATTLIST %restriction;
+    base      %QName;                  #IMPLIED
+    id        ID       #IMPLIED
+    %restrictionAttrs;>
+<!-- base and simpleType child are mutually exclusive, one is required -->
+<!-- restriction is shared between simpleType and simpleContent and -->
+<!-- complexContent (in XMLSchema.xsd). restriction1 is for the latter -->
+<!-- cases, when this is restricting a complex type, as is attrDecls -->
+<!ELEMENT %list; ((%annotation;)?,(%simpleType;)?)>
+<!ATTLIST %list;
+    itemType      %QName;             #IMPLIED
+    id        ID       #IMPLIED
+    %listAttrs;>
+<!-- itemType and simpleType child are mutually exclusive, one is required -->
+<!ELEMENT %union; ((%annotation;)?,(%simpleType;)*)>
+<!ATTLIST %union;
+    id            ID       #IMPLIED
+    memberTypes   %QNames;            #IMPLIED
+    %unionAttrs;>
+<!-- At least one item in memberTypes or one simpleType child is required -->
+
+<!ELEMENT %maxExclusive; %facetModel;>
+<!ATTLIST %maxExclusive;
+        %facetAttr;
+        %fixedAttr;
+    %maxExclusiveAttrs;>
+<!ELEMENT %minExclusive; %facetModel;>
+<!ATTLIST %minExclusive;
+        %facetAttr;
+        %fixedAttr;
+        %minExclusiveAttrs;>
+
+<!ELEMENT %maxInclusive; %facetModel;>
+<!ATTLIST %maxInclusive;
+        %facetAttr;
+        %fixedAttr;
+        %maxInclusiveAttrs;>
+<!ELEMENT %minInclusive; %facetModel;>
+<!ATTLIST %minInclusive;
+        %facetAttr;
+        %fixedAttr;
+        %minInclusiveAttrs;>
+
+<!ELEMENT %precision; %facetModel;>
+<!ATTLIST %precision;
+        %facetAttr;
+        %fixedAttr;
+        %precisionAttrs;>
+<!ELEMENT %scale; %facetModel;>
+<!ATTLIST %scale;
+        %facetAttr;
+        %fixedAttr;
+        %scaleAttrs;>
+
+<!ELEMENT %length; %facetModel;>
+<!ATTLIST %length;
+        %facetAttr;
+        %fixedAttr;
+        %lengthAttrs;>
+<!ELEMENT %minLength; %facetModel;>
+<!ATTLIST %minLength;
+        %facetAttr;
+        %fixedAttr;
+        %minLengthAttrs;>
+<!ELEMENT %maxLength; %facetModel;>
+<!ATTLIST %maxLength;
+        %facetAttr;
+        %fixedAttr;
+        %maxLengthAttrs;>
+
+<!-- This one can be repeated -->
+<!ELEMENT %enumeration; %facetModel;>
+<!ATTLIST %enumeration;
+        %facetAttr;
+        %enumerationAttrs;>
+
+<!ELEMENT %whiteSpace; %facetModel;>
+<!ATTLIST %whiteSpace;
+        %facetAttr;
+        %whiteSpaceAttrs;>
+
+<!-- This one can be repeated -->
+<!ELEMENT %pattern; %facetModel;>
+<!ATTLIST %pattern;
+        %facetAttr;
+        %patternAttrs;>
+
+<!ELEMENT %encoding; %facetModel;>
+<!ATTLIST %encoding;
+        %facetAttr;
+        %fixedAttr;
+        %encodingAttrs;>
+<!ELEMENT %period; %facetModel;>
+<!ATTLIST %period;
+        %facetAttr;
+        %fixedAttr;
+        %periodAttrs;>
+<!ELEMENT %duration; %facetModel;>
+<!ATTLIST %duration;
+        %facetAttr;
+        %fixedAttr;
+        %durationAttrs;>

src/documentation/xdocs/dtd/document-v10.dtd

@@ -0,0 +1,555 @@
+<!-- ===================================================================
+
+     Apache Documentation DTD (Version 1.0)
+
+PURPOSE:
+  This DTD was developed to create a simple yet powerful document
+  type for software documentation for use with the Apache projects.
+  It is an XML-compliant DTD and it's maintained by the Apache XML
+  project.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE document PUBLIC
+       "-//APACHE//DTD Documentation Vx.yz//EN"
+       "http://xml.apache.org/DTD/document-vxyz.dtd">
+
+  where
+
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+
+NOTES:
+  Many of the design patterns used in this DTD were take from the
+  W3C XML Specification DTD edited by Eve Maler <elm@arbortext.com>.
+
+  Where possible, great care has been used to reutilize HTML tag
+  names to reduce learning efforts and to allow HTML editors to be
+  used for complex authorings like tables and lists.
+
+AUTHORS:
+  Stefano Mazzocchi <stefano@apache.org>
+
+FIXME:
+  - how can we include char entities without hardwiring them?
+  - should "form" tags be included?
+  - should all style-free HTML 4.0 markup tags be included?
+  - how do we handle the idea of "soft" xlinks?
+  - should we add "soft" links to images?
+
+CHANGE HISTORY:
+  19991121 Initial version. (SM)
+  19991123 Replaced "res" with more standard "strong" for emphasis. (SM)
+  19991124 Added "fork" element for window forking behavior. (SM)
+  19991124 Added "img-inline" element to separate from "img". (SM)
+  19991129 Removed "affiliation" from "author". (SM)
+  19991129 Made "author" empty and moved "name|email" as attributes. (SM)
+  19991215 Simplified table section. (SM)
+  19991215 Changed "img-block" in more friendly "figure". (SM)
+  20000125 Added the "icon" image. (SM)
+  20000126 Allowed "anchor" in all levels. (SM)
+  20000404 Removed the "role" attribute from common-xxx.att. (SM)
+  20000815 Allowed "code" inside "strong" and "em". (SM)
+
+COPYRIGHT:
+  Copyright (c) 1999-2000 The Apache Software Foundation.
+
+  Permission to copy in any form is granted provided this notice is
+  included in all copies. Permission to redistribute is granted
+  provided this file is distributed untouched in all its parts and
+  included files.
+
+==================================================================== -->
+
+
+
+
+<!-- =============================================================== -->
+<!-- Common character entities (included from external file) -->
+<!-- =============================================================== -->
+
+<!-- FIXME (SM): this is hardcoding. Find a better way of doing this
+     possibly using public identifiers of ISO latin char sets -->
+<!ENTITY % charEntity SYSTEM "characters.ent">
+%charEntity;
+
+
+
+
+<!-- =============================================================== -->
+<!-- Userful entitieis for increased DTD readability -->
+<!-- =============================================================== -->
+
+<!ENTITY % text "#PCDATA">
+
+
+<!-- =============================================================== -->
+<!-- Entities for general XML compliance -->
+<!-- =============================================================== -->
+
+<!-- Common attributes
+        Every element has an ID attribute (sometimes required,
+        but usually optional) for links. %common.att;
+        is for common attributes where the ID is optional, and
+        %common-idreq.att; is for common attributes where the
+        ID is required.
+-->
+<!ENTITY % common.att
+        'id                     ID              #IMPLIED
+         xml:lang               NMTOKEN         #IMPLIED'>
+<!ENTITY % common-idreq.att
+        'id                     ID              #REQUIRED
+         xml:lang               NMTOKEN         #IMPLIED'>
+
+
+<!-- xml:space attribute ===============================================
+        Indicates that the element contains white space
+        that the formatter or other application should retain,
+        as appropriate to its function.
+==================================================================== -->
+<!ENTITY % xmlspace.att
+        'xml:space (default|preserve) #FIXED "preserve"'>
+
+
+<!-- def attribute =====================================================
+        Points to the element where the relevant definition can be
+        found, using the IDREF mechanism.  %def.att; is for optional
+        def attributes, and %def-req.att; is for required def
+        attributes.
+==================================================================== -->
+<!ENTITY % def.att
+        'def                    IDREF           #IMPLIED'>
+<!ENTITY % def-req.att
+        'def                    IDREF           #REQUIRED'>
+
+
+
+<!-- ref attribute =====================================================
+        Points to the element where more information can be found,
+        using the IDREF mechanism.  %ref.att; is for optional
+        ref attributes, and %ref-req.att; is for required ref
+        attributes.
+================================================================== -->
+<!ENTITY % ref.att
+        'ref                    IDREF           #IMPLIED'>
+<!ENTITY % ref-req.att
+        'ref                    IDREF           #REQUIRED'>
+
+
+<!-- =============================================================== -->
+<!-- Entities for XLink compliance -->
+<!-- =============================================================== -->
+
+<!ENTITY % xlink-simple.att
+        'type      (simple|extended|locator|arc) #FIXED "simple"
+         href      CDATA                         #IMPLIED
+         role      CDATA                         #IMPLIED
+         title     CDATA                         #IMPLIED '>
+<!--    'xmlns     CDATA                         #FIXED "http://www.w3.org/XML/XLink/0.9" -->
+<!-- FIXME: brain-dead IE5 has broken support for
+     namespace validation and since I use it for editing
+     I remove this for now -->
+
+<!ENTITY % xlink-user-replace.att
+        'show      (new|parsed|replace)   #FIXED "replace"
+         actuate   (user|auto)            #FIXED "user" '>
+
+<!ENTITY % xlink-user-new.att
+        'show      (new|parsed|replace)   #FIXED "new"
+         actuate   (user|auto)            #FIXED "user" '>
+
+<!ENTITY % xlink-auto-parsed.att
+        'show      (new|parsed|replace)   #FIXED "parsed"
+         actuate   (user|auto)            #FIXED "auto" '>
+
+<!-- FIXME (SM): XLink doesn't yet cover the idea of soft links so
+     introducing it here using the same namespace is _somewhat_
+     illegal. Should we create it own namespace?
+-->
+<!ENTITY % xlink-soft.att
+        'mode      (hard|soft)            #FIXED "soft" '>
+
+
+<!-- =============================================================== -->
+<!-- Entities for general usage -->
+<!-- =============================================================== -->
+
+
+<!-- Key attribute =====================================================
+        Optionally provides a sorting or indexing key, for cases when
+        the element content is inappropriate for this purpose.
+==================================================================== -->
+<!ENTITY % key.att
+        'key                    CDATA           #IMPLIED'>
+
+
+
+<!-- Title attributes ==================================================
+        Indicates that the element requires to have a title.
+==================================================================== -->
+<!ENTITY % title.att
+        'title                  CDATA           #REQUIRED'>
+
+
+
+<!-- Name attributes ==================================================
+        Indicates that the element requires to have a name.
+==================================================================== -->
+<!ENTITY % name.att
+        'name                   CDATA           #REQUIRED'>
+
+
+
+<!-- Email attributes ==================================================
+        Indicates that the element requires to have an email.
+==================================================================== -->
+<!ENTITY % email.att
+        'email                  CDATA           #REQUIRED'>
+
+
+
+
+
+<!-- =============================================================== -->
+<!-- General definitions -->
+<!-- =============================================================== -->
+
+<!-- A person is a general human entity -->
+<!ELEMENT person EMPTY>
+<!ATTLIST person %common.att;
+                 %name.att;
+                 %email.att;>
+
+
+
+
+<!-- =============================================================== -->
+<!-- Content definitions -->
+<!-- =============================================================== -->
+
+<!ENTITY % local.content.mix "">
+
+<!ENTITY % markup "strong|em|code|sub|sup">
+
+<!ENTITY % links "link|connect|jump|fork|anchor">
+
+<!ENTITY % special "br|img|icon">
+
+<!ENTITY % link-content.mix "%text;|%markup;|%special;%local.content.mix;">
+
+<!ENTITY % content.mix "%link-content.mix;|%links;">
+
+    <!-- ==================================================== -->
+    <!-- Phrase Markup -->
+    <!-- ==================================================== -->
+
+    <!-- Code (typically monospaced) -->
+    <!ELEMENT code (%text;)>
+    <!ATTLIST code %common.att;>
+
+    <!-- Strong (typically bold) -->
+    <!ELEMENT strong (%text;|code)*>
+    <!ATTLIST strong %common.att;>
+
+    <!-- Emphasis (typically italic) -->
+    <!ELEMENT em (%text;|code)*>
+    <!ATTLIST em %common.att;>
+
+    <!-- Superscript (typically smaller and higher) -->
+    <!ELEMENT sup (%text;)>
+    <!ATTLIST sup %common.att;>
+
+    <!-- Subscript (typically smaller and lower) -->
+    <!ELEMENT sub (%text;)>
+    <!ATTLIST sub %common.att;>
+
+    <!-- FIXME (SM): should we add these HTML 4.0 markups
+         which are style-free?
+
+          -dfn
+          -samp
+          -kbd
+          -var
+          -cite
+          -abbr
+          -acronym
+
+     -->
+
+    <!-- ==================================================== -->
+    <!-- Hypertextual Links -->
+    <!-- ==================================================== -->
+
+    <!-- hard replacing link (equivalent of <a ...>) -->
+    <!ELEMENT link (%link-content.mix;)*>
+    <!ATTLIST link %common.att;
+                   %xlink-simple.att;
+                   %xlink-user-replace.att;>
+
+    <!-- Hard window replacing link (equivalent of <a ... target="_top">) -->
+    <!ELEMENT jump (%link-content.mix;)*>
+    <!ATTLIST jump %common.att;
+                   %xlink-simple.att;
+                   %xlink-user-new.att;>
+
+    <!-- Hard window forking link (equivalent of <a ... target="_new">) -->
+    <!ELEMENT fork (%link-content.mix;)*>
+    <!ATTLIST fork %common.att;
+                   %xlink-simple.att;
+                   %xlink-user-new.att;>
+
+    <!-- Anchor point (equivalent of <a name="...">) -->
+    <!ELEMENT anchor EMPTY>
+    <!ATTLIST anchor %common-idreq.att;>
+
+    <!-- Soft link between processed pages (no equivalent in HTML) -->
+    <!ELEMENT connect (%link-content.mix;)*>
+    <!ATTLIST connect %common.att;
+                      %xlink-simple.att;
+                      %xlink-user-replace.att;
+                      %xlink-soft.att;>
+
+    <!-- ==================================================== -->
+    <!-- Specials -->
+    <!-- ==================================================== -->
+
+    <!-- Breakline Object (typically forces line break) -->
+    <!ELEMENT br EMPTY>
+    <!ATTLIST br %common.att;>
+
+    <!-- Image Object (typically an inlined image) -->
+    <!-- FIXME (SM): should we have the notion of soft links even here
+         for inlined objects? -->
+    <!ELEMENT img EMPTY>
+    <!ATTLIST img src    CDATA  #REQUIRED
+                  alt    CDATA  #REQUIRED
+                  height CDATA  #IMPLIED
+                  width  CDATA  #IMPLIED
+                  usemap CDATA  #IMPLIED
+                  ismap  (ismap) #IMPLIED
+                  %common.att;>
+
+    <!-- Image Icon (typically an inlined image placed as graphical item) -->
+    <!-- FIXME (SM): should we have the notion of soft links even here
+         for inlined objects? -->
+    <!ELEMENT icon EMPTY>
+    <!ATTLIST icon src    CDATA  #REQUIRED
+                   alt    CDATA  #REQUIRED
+                   height CDATA  #IMPLIED
+                   width  CDATA  #IMPLIED
+                   %common.att;>
+
+
+
+
+<!-- =============================================================== -->
+<!-- Blocks definitions -->
+<!-- =============================================================== -->
+
+<!ENTITY % local.blocks "">
+
+<!ENTITY % local.lists "">
+
+<!ENTITY % paragraphs "p|source|note|fixme|figure">
+
+<!ENTITY % tables "table">
+
+<!ENTITY % lists "ol|ul|sl|dl %local.lists;">
+
+<!ENTITY % blocks "anchor|%paragraphs;|%tables;|%lists; %local.blocks;">
+
+    <!-- ==================================================== -->
+    <!-- Paragraphs -->
+    <!-- ==================================================== -->
+
+    <!-- Text Paragraph (normally vertically space delimited) -->
+    <!ELEMENT p (%content.mix;)*>
+    <!ATTLIST p %common.att;>
+
+    <!-- Source Paragraph (normally space is preserved) -->
+    <!ELEMENT source (%content.mix;)*>
+    <!ATTLIST source %common.att;
+                     %xmlspace.att;>
+
+    <!-- Note Paragraph (normally shown encapsulated) -->
+    <!ELEMENT note (%content.mix;)*>
+    <!ATTLIST note %common.att;>
+
+    <!-- Fixme Paragraph (normally not shown) -->
+    <!ELEMENT fixme (%content.mix;)*>
+    <!-- the "author" attribute should match the "key" attribute of the
+         <author> element -->
+    <!ATTLIST fixme author CDATA #REQUIRED
+                    %common.att;>
+
+    <!-- ==================================================== -->
+    <!-- Tables -->
+    <!-- ==================================================== -->
+
+    <!-- Attributes that indicate the spanning of the table cell -->
+    <!ENTITY % cell.span 
+        'colspan CDATA "1"
+         rowspan CDATA "1"'>
+
+    <!-- Table element -->
+    <!ELEMENT table (caption?, tr+)>
+    <!ATTLIST table %common.att;>
+
+        <!-- The table title -->
+        <!ELEMENT caption (%content.mix;)*>
+        <!ATTLIST caption %common.att;>
+
+        <!-- The table row element -->
+        <!ELEMENT tr (th|td)+>
+        <!ATTLIST tr %common.att;>
+
+            <!-- The table row header element -->
+            <!ELEMENT th (%content.mix;)*>
+            <!ATTLIST th %common.att;
+                         %cell.span;>
+
+            <!-- The table row description element -->
+            <!ELEMENT td (%content.mix;)*>
+            <!ATTLIST td %common.att;
+                         %cell.span;>
+
+    <!-- ==================================================== -->
+    <!-- Lists -->
+    <!-- ==================================================== -->
+
+    <!-- Unordered list (typically bulleted) -->
+    <!ELEMENT ul (li|%lists;)+>
+    <!--    spacing attribute:
+            Use "normal" to get normal vertical spacing for items;
+            use "compact" to get less spacing.  The default is dependent
+            on the stylesheet. -->
+    <!ATTLIST ul
+            %common.att;
+            spacing         (normal|compact)        #IMPLIED>
+
+    <!-- Ordered list (typically numbered) -->
+    <!ELEMENT ol (li|%lists;)+>
+    <!--    spacing attribute:
+            Use "normal" to get normal vertical spacing for items;
+            use "compact" to get less spacing.  The default is dependent
+            on the stylesheet. -->
+    <!ATTLIST ol
+            %common.att;
+            spacing         (normal|compact)        #IMPLIED>
+
+    <!-- Simple list (typically with no mark) -->
+    <!ELEMENT sl (li|%lists;)+>
+    <!ATTLIST sl %common.att;>
+
+        <!-- List item -->
+        <!ELEMENT li (%content.mix;|%lists;)*>
+        <!ATTLIST li %common.att;>
+
+    <!-- Definition list (typically two-column) -->
+    <!ELEMENT dl (dt,dd)+>
+    <!ATTLIST dl %common.att;>
+
+        <!-- Definition term -->
+        <!ELEMENT dt (%content.mix;)*>
+        <!ATTLIST dt %common.att;>
+
+        <!-- Definition description -->
+        <!ELEMENT dd (%content.mix;)*>
+        <!ATTLIST dd %common.att;>
+
+    <!-- ==================================================== -->
+    <!-- Special Blocks -->
+    <!-- ==================================================== -->
+
+    <!-- Image Block (typically a separated and centered image) -->
+    <!-- FIXME (SM): should we have the notion of soft links even here
+         for inlined objects? -->
+    <!ELEMENT figure EMPTY>
+    <!ATTLIST figure src    CDATA  #REQUIRED
+                     alt    CDATA  #REQUIRED
+                     height CDATA  #IMPLIED
+                     width  CDATA  #IMPLIED
+                     usemap CDATA  #IMPLIED
+                     ismap  (ismap) #IMPLIED
+                     %common.att;>
+
+
+
+
+
+<!-- =============================================================== -->
+<!-- Document -->
+<!-- =============================================================== -->
+
+<!ELEMENT document (header?, body, footer?)>
+<!ATTLIST document %common.att;>
+
+    <!-- ==================================================== -->
+    <!-- Header -->
+    <!-- ==================================================== -->
+
+    <!ENTITY % local.headers "">
+
+    <!ELEMENT header (title, subtitle?, version?, type?, authors,
+                      notice*, abstract? %local.headers;)>
+    <!ATTLIST header %common.att;>
+
+    <!ELEMENT title (%text;)>
+    <!ATTLIST title %common.att;>
+
+    <!ELEMENT subtitle (%text;)>
+    <!ATTLIST subtitle %common.att;>
+
+    <!ELEMENT version (%text;)>
+    <!ATTLIST version %common.att;>
+
+    <!ELEMENT type (%text;)>
+    <!ATTLIST type %common.att;>
+
+    <!ELEMENT authors (person+)>
+    <!ATTLIST authors %common.att;>
+
+    <!ELEMENT notice (%content.mix;)*>
+    <!ATTLIST notice %common.att;>
+
+    <!ELEMENT abstract (%content.mix;)*>
+    <!ATTLIST abstract %common.att;>
+
+    <!-- ==================================================== -->
+    <!-- Body -->
+    <!-- ==================================================== -->
+
+    <!ENTITY % local.sections "">
+
+    <!ENTITY % sections "s1|anchor %local.sections;">
+
+    <!ELEMENT body (%sections;)+>
+    <!ATTLIST body %common.att;>
+
+        <!ELEMENT s1 (s2|%blocks;)*>
+        <!ATTLIST s1 %title.att; %common.att;>
+
+            <!ELEMENT s2 (s3|%blocks;)*>
+            <!ATTLIST s2 %title.att; %common.att;>
+
+                <!ELEMENT s3 (s4|%blocks;)*>
+                <!ATTLIST s3 %title.att; %common.att;>
+
+                    <!ELEMENT s4 (%blocks;)*>
+                    <!ATTLIST s4 %title.att; %common.att;>
+
+    <!-- ==================================================== -->
+    <!-- Footer -->
+    <!-- ==================================================== -->
+
+    <!ENTITY % local.footers "">
+
+    <!ELEMENT footer (legal %local.footers;)>
+
+        <!ELEMENT legal (%content.mix;)*>
+        <!ATTLIST legal %common.att;>
+
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

src/documentation/xdocs/dtd/faq-v10.dtd

@@ -0,0 +1,77 @@
+<!-- ===================================================================
+     
+     Apache FAQ DTD (Version 1.0)
+
+PURPOSE:
+  This DTD was developed to create a simple yet powerful document 
+  type for software FAQ's for use with the Apache projects.  
+  It is an XML-compliant DTD and it's maintained by the Apache XML 
+  project.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE document PUBLIC
+       "-//APACHE//DTD FAQ Vx.yz//EN"
+       "http://xml.apache.org/DTD/faq-vxyz.dtd">
+
+  where 
+  
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+      
+NOTES:  
+  FAQs represent a powerful knowledge base and a very good way of solving
+  common user problems reducing messages on mail lists and reducing the effort
+  required for software installation and usage. Thid DTD want to be a common
+  format for FAQ interchange to allow FAQ-O-Matic-type workgroup services to 
+  be published in other formats as well as enhancing data interchange.
+  
+AUTHORS:
+  Stefano Mazzocchi <stefano@apache.org>
+  
+FIXME:
+
+CHANGE HISTORY:
+  19991129 Initial version. (SM)
+    
+COPYRIGHT:
+  Copyright (c) @year@ The Apache Software Foundation.
+  
+  Permission to copy in any form is granted provided this notice is 
+  included in all copies. Permission to redistribute is granted 
+  provided this file is distributed untouched in all its parts and 
+  included files.
+  
+==================================================================== -->
+
+<!-- =============================================================== -->
+<!-- Extend the Documentation DTD -->
+<!-- =============================================================== -->
+
+<!-- FIXME (SM): this is hardcoding. Find a better way of doing this
+     possibly using public identifiers -->
+<!ENTITY % document-dtd SYSTEM "document-v10.dtd">
+%document-dtd;
+
+
+<!-- =============================================================== -->
+<!-- Document Type Definition -->
+<!-- =============================================================== -->
+
+<!ELEMENT faqs (authors?, faq)+>
+<!ATTLIST faqs %common.att; 
+               %title.att;>
+
+    <!ELEMENT faq (question, answer)>
+    <!ATTLIST faq %common.att;>
+    
+        <!ELEMENT question (%content.mix;)*>
+        <!ATTLIST question %common.att;>
+            
+        <!ELEMENT answer (%blocks;)*>
+        <!ATTLIST answer author IDREF #IMPLIED>
+
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

src/documentation/xdocs/dtd/javadoc-v04draft.dtd

@@ -0,0 +1,254 @@
+<!-- ===================================================================
+     
+     Apache JavaDoc DTD (version 0.4-draft)
+
+PURPOSE:
+  This DTD is designed to capture the output of JavaDoc as an XML document
+  through the use of the JavaDocXML Doclet. The hope is that by having the
+  JavaDoc documentation in an XML format, it will be easier for application
+  developers working with XML to treat their java source documentation in the
+  same way they treat any other XML document within their publication framework.
+  
+  This DTD should reflect the information contained within the RootDoc object 
+  passed to the JavaDocXML Doclet by JavaDoc. The RootDoc object and the rest 
+  of the javaDoc Doclet API is specified at
+  
+  http://java.sun.com/products/jdk/1.2/docs/tooldocs/javadoc/doclet/index.html
+  
+  The only information that appears to be difficult to derive from this DTD
+  that is easy to obtain from the RootDoc object is the information about 
+  serialization. However, this information should be derivable by manually 
+  looking for the correct serialization methods and other related structures.
+  
+TYPICAL INVOCATION:
+
+  <!DOCTYPE document PUBLIC
+       "-//APACHE//DTD JavaDoc Vx.yz//EN"
+       "http://xml.apache.org/DTD/javadoc-vxyz.dtd">
+
+  where 
+  
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+      
+NOTES:  
+  The authors would like to thank the Cocoon's mail list subscribers for 
+  providing such great support and feedback for this DTD.
+  
+AUTHORS:
+  Kenneth Murphy <murphyk@umsystem.edu>
+  
+FIXME:
+
+CHANGE HISTORY:
+  199909?? Original idea of XML doclet. (KM)
+  199910?? Initial version of this DTD. (KM)
+  19991129 Cleaned up DTD. (SM)
+    
+COPYRIGHT:
+  Copyright (c) @year@ The Apache Software Foundation.
+  
+  Permission to copy in any form is granted provided this notice is 
+  included in all copies. Permission to redistribute is granted 
+  provided this file is distributed untouched in all its parts and 
+  included files.
+  
+==================================================================== -->
+
+<!-- =============================================================== -->
+<!-- Common Attribute Entities -->
+<!-- =============================================================== -->
+
+<!ENTITY % name 'name CDATA #REQUIRED'>
+<!ENTITY % dimension 'dimension CDATA #REQUIRED'>
+
+<!ENTITY % abstract 'abstract (true | false) "false"'>
+<!ENTITY % anonymous 'anonymous (true | false) "false"'>
+<!ENTITY % synthetic 'synthetic (true | false) "false"'>
+<!ENTITY % static 'static (true | false) "false"'>
+<!ENTITY % final 'final (true | false) "false"'>
+<!ENTITY % transient 'transient (true | false) "false"'>
+<!ENTITY % volatile 'volatile (true | false) "false"'>
+<!ENTITY % native 'native (true | false) "false"'>
+<!ENTITY % synchronized 'synchronized (true | false) "false"'>
+
+<!ENTITY % access 'access (private | package | protected | public) "package"'>
+<!ENTITY % class.access 'access (package | public) "package"'>
+
+<!ENTITY % extensibility 'extensibility (abstract | final | default) "default"'>
+
+
+<!-- =============================================================== -->
+<!-- Javadoc -->
+<!-- =============================================================== -->
+
+<!ELEMENT javadoc (package*, class*, interface*)>
+
+<!-- =============================================================== -->
+<!-- Package -->
+<!-- =============================================================== -->
+
+<!ELEMENT package (doc?, package*, class*, interface*)>
+<!ATTLIST package %name;>
+
+<!-- =============================================================== -->
+<!-- Class -->
+<!-- =============================================================== -->
+
+<!ELEMENT class (doc?,
+                 extends_class?,
+                 implements?,
+                 field*, 
+                 constructor*, 
+                 method*,
+                 innerclass*)>
+<!ATTLIST class
+          %name;
+          %extensibility;
+          %class.access;>
+
+<!ELEMENT extends_class (classref+)>
+          
+<!ELEMENT innerclass (doc?,
+                      extends?,
+                      implements?,
+                      field*, 
+                      constructor*, 
+                      method*)>
+<!ATTLIST innerclass
+          %name;
+          %access;
+          %abstract;
+          %anonymous;
+          %final;
+          %static;>
+          
+<!-- =============================================================== -->
+<!-- Interface -->
+<!-- =============================================================== -->
+          
+<!ELEMENT interface (doc?,
+                     extends_interface?,
+                     field*,
+                     method*)>
+<!ATTLIST interface
+          %name;
+          %access;>
+          
+<!ELEMENT extends_interface (interfaceref+)>
+
+<!-- =============================================================== -->
+<!-- Elements -->
+<!-- =============================================================== -->
+
+<!ELEMENT implements (interfaceref+)>
+
+<!ELEMENT throws (classref)+>
+
+<!ELEMENT classref EMPTY>
+<!ATTLIST classref %name;>
+          
+<!ELEMENT interfaceref EMPTY>
+<!ATTLIST interfaceref %name;>
+          
+<!ELEMENT methodref EMPTY>
+<!ATTLIST methodref %name;>
+          
+<!ELEMENT packageref EMPTY>
+<!ATTLIST packageref %name;>
+          
+<!ELEMENT primitive EMPTY>
+<!ATTLIST primitive
+          type (void | boolean | int | long | byte | short | double | float | char) #REQUIRED>
+          
+<!ELEMENT field (doc?, (classref | interfaceref | primitive))>
+<!ATTLIST field
+          %name;
+          %access;
+          %dimension;
+          %synthetic;
+          %static;
+          %final;
+          %transient;
+          %volatile;>
+          
+<!ELEMENT constructor (doc?, parameter*, throws*)>
+<!ATTLIST constructor
+          %name;
+          %access;
+          %synthetic;>
+          
+<!ELEMENT method (doc?, returns, parameter*, throws*)>
+<!ATTLIST method
+          %name;
+          %access;
+          %extensibility;
+          %native;
+          %synthetic;
+          %static;
+          %synchronized;>
+          
+<!ELEMENT returns (classref | interfaceref | primitive)>
+<!ATTLIST returns %dimension;>
+          
+<!ELEMENT parameter (classref | interfaceref | primitive)>
+<!ATTLIST parameter
+          %name;
+          %final;
+          %dimension;>
+          
+<!ELEMENT dimension (#PCDATA)>
+
+<!ELEMENT doc (#PCDATA | 
+               linktag |
+               authortag |
+               versiontag |
+               paramtag |
+               returntag |
+               exceptiontag |
+               throwstag |
+               seetag |
+               sincetag |
+               deprecatedtag |
+               serialtag |
+               serialfieldtag |
+               serialdatatag)*>
+               
+<!ELEMENT linktag (#PCDATA)>
+<!ATTLIST linktag
+          src CDATA #REQUIRED>
+          
+<!ELEMENT authortag (#PCDATA | linktag)*>
+
+<!ELEMENT versiontag (#PCDATA | linktag)*>
+
+<!ELEMENT paramtag (#PCDATA | linktag)*>
+<!ATTLIST paramtag %name;>
+          
+<!ELEMENT returntag (#PCDATA | linktag)*>
+
+<!ELEMENT exceptiontag (#PCDATA | classref | linktag)*>
+
+<!ELEMENT throwstag (#PCDATA | classref | linktag)*>
+
+<!ELEMENT seetag (#PCDATA | linktag)*>
+<!ATTLIST seetag
+          src CDATA #REQUIRED>
+          
+<!ELEMENT sincetag (#PCDATA | linktag)*>
+
+<!ELEMENT deprecatedtag (#PCDATA | linktag)*>
+
+<!ELEMENT serialtag (#PCDATA | linktag)*>
+
+<!ELEMENT serialfieldtag (#PCDATA | linktag)*>
+<!ATTLIST serialfieldtag
+          fieldname CDATA #REQUIRED
+          fieldtype CDATA #REQUIRED>
+          
+<!ELEMENT serialdatatag (#PCDATA | linktag)*>
+
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

src/documentation/xdocs/dtd/sitemap-v02.dtd

@@ -0,0 +1,341 @@
+<!-- ===================================================================
+
+     Apache Cocoon Sitemap DTD (Version 0.2)
+
+PURPOSE:
+  INITIAL DRAFT DTD for the Cocoon2 sitemap.xmap files.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE map:sitemap PUBLIC
+       "-//APACHE//DTD Cocoon Sitemap Vx.yz//EN"
+       "sitemap-vxyz.dtd">
+
+  where
+
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+
+NOTES:
+* ATTENTION: This initial DTD was reverse-engineered from the various
+  sitemap.xmap instances included in the current distribution. This is
+  just an attempt to document the existing rules for sitemap structure.
+  In many cases a very lax content model is used, simply to get around
+  validation issues.
+  A proper design process is still required.
+* Needed by XML editing tools for creation of reliable documents.
+* Can generate XSD once DTD is locked down.
+* We need to synchronise this DTD with the relax-ng work
+  by <Bruno.Dumon@the-ecorp.com> ... cocoon-dev 2001-07-18
+  http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=99545886226916&w=2
+* This DTD has been tested with various XML validating parsers.
+* The big questions (still) are: 
+  "What possibilities were not included in the examples?" and 
+  "What in the example sitemap.xmap files is mandatory versus optional?"
+
+AUTHORS:
+  Jeffrey Ricker NG (Usonia Holdings) <rickerng@usonia.net>
+  David Crossley <crossley@indexgeo.com.au>
+
+FIXME:
+  - map:act is used in various contexts, so it has a loose definition
+  - Completely rewrite this DTD looking from the application
+    point-of-view (do not rely on this temporary initial DTD)
+  - map:when and map:otherwise are shown in xdocs/sitemap.xml but are
+    not used in the sitemap.xmap files
+  - align elements and attributes with sitemap*.xsl
+  - review all xdocs/userdocs/generators/*.xml etc. and sync with this DTD
+
+CHANGE HISTORY:
+  20010715 V0.1 Initial version. (RNG)
+  20011106 V0.2 Reviewed all */sitemap.xmap and added definitions (DC)
+  20011106 V0.2 All elements now have "map:" prefix. (DC)
+  20011106 V0.2 Incorporated comments Bruno Dumon cocoon-dev 20010718 (DC)
+  20011116 V0.2 Changes from label/view discussion cocoon-dev 20011115 (DC)
+  20011219 V0.2 Deprecated 'redirect-to resource'. Added 'map:call resource'(CH)
+
+==================================================================== -->
+
+<!ELEMENT map:sitemap (map:components, map:views?, map:resources?,
+                       map:action-sets?, map:pipelines)>
+<!ATTLIST map:sitemap
+        xmlns:map CDATA #FIXED "http://apache.org/cocoon/sitemap/1.0"
+>
+
+<!-- =============================================================== -->
+<!-- Components -->
+<!-- =============================================================== -->
+
+<!ELEMENT map:components (map:generators, map:transformers, map:readers,
+                          map:serializers, map:selectors?, map:matchers?,
+                          map:actions?)>
+<!-- RNG: must they appear in this order?
+          must they all appear, even if they are empty? -->
+<!-- DC: it seems that some sitemaps do not contain all components
+         e.g. documentation/sitemap.xmap does not have map:selectors -->
+
+  <!-- Generators ======================================== -->
+<!ELEMENT map:generators (map:generator*)>
+<!ATTLIST map:generators
+        default CDATA #IMPLIED
+>
+<!ELEMENT map:generator EMPTY>
+<!ATTLIST map:generator
+        name CDATA #REQUIRED
+        src CDATA #REQUIRED
+        label CDATA #IMPLIED
+        pool-max CDATA #IMPLIED
+        pool-min CDATA #IMPLIED
+        pool-grow CDATA #IMPLIED
+>
+
+<!-- RNG: with all attributes, which are required and which are implied? -->
+
+  <!-- Transformers ====================================== -->
+<!ELEMENT map:transformers (map:transformer*)>
+<!ATTLIST map:transformers
+        default CDATA #IMPLIED
+>
+<!ELEMENT map:transformer ANY>
+<!-- RNG: surely the content is not ANY. However, there were so many
+          children here that I did not know where to begin -->
+<!-- DC: here are some that are currently used -->
+<!ELEMENT use-store (#PCDATA)>
+<!ELEMENT use-request-parameters (#PCDATA)>
+<!ELEMENT use-browser-capabilities-db (#PCDATA)>
+<!ELEMENT catalogue-name (#PCDATA)>
+<!ELEMENT catalogue-location (#PCDATA)>
+<!ATTLIST map:transformer
+        name CDATA #REQUIRED
+        src CDATA #REQUIRED
+        label CDATA #IMPLIED
+        pool-max CDATA #IMPLIED
+        pool-min CDATA #IMPLIED
+        pool-grow CDATA #IMPLIED
+>
+
+  <!-- Readers =========================================== -->
+<!ELEMENT map:readers (map:reader*)>
+<!ATTLIST map:readers
+        default CDATA #IMPLIED
+>
+<!ELEMENT map:reader EMPTY>
+<!-- RNG: does reader ever have children? Its peers do. -->
+<!ATTLIST map:reader
+        name CDATA #REQUIRED
+        src CDATA #REQUIRED
+>
+
+  <!-- Serializers ======================================= -->
+<!ELEMENT map:serializers (map:serializer*)>
+<!ATTLIST map:serializers
+        default CDATA #IMPLIED
+>
+<!ELEMENT map:serializer (doctype-public|doctype-system|encoding|
+                          omit-xml-declaration|parameter)*>
+<!-- RNG: are these the only children of serializer? -->
+<!ATTLIST map:serializer
+        name CDATA #REQUIRED
+        mime-type CDATA #REQUIRED
+        src CDATA #REQUIRED
+        pool-max CDATA #IMPLIED
+        pool-min CDATA #IMPLIED
+        pool-grow CDATA #IMPLIED
+>
+<!ELEMENT doctype-public (#PCDATA)>
+<!ELEMENT doctype-system (#PCDATA)>
+<!ELEMENT encoding (#PCDATA)>
+<!ELEMENT omit-xml-declaration (#PCDATA)>
+<!ELEMENT parameter EMPTY>
+<!ATTLIST parameter
+        name CDATA #REQUIRED
+        value CDATA #REQUIRED
+        type CDATA #IMPLIED
+>
+
+  <!-- Selectors ========================================= -->
+<!ELEMENT map:selectors (map:selector*)>
+<!ATTLIST map:selectors
+        default CDATA #IMPLIED
+>
+<!ELEMENT map:selector (browser*)>
+<!ATTLIST map:selector
+        name CDATA #REQUIRED
+        src CDATA #REQUIRED
+>
+<!ELEMENT browser EMPTY>
+<!ATTLIST browser
+        name CDATA #REQUIRED
+        useragent CDATA #REQUIRED
+>
+
+  <!-- Matchers ========================================== -->
+<!ELEMENT map:matchers (map:matcher*)>
+<!ATTLIST map:matchers
+        default CDATA #IMPLIED
+>
+<!ELEMENT map:matcher (attribute-name|parameter-name|header-name)*>
+<!ATTLIST map:matcher
+        name CDATA #REQUIRED
+        src CDATA #REQUIRED
+>
+<!ELEMENT attribute-name (#PCDATA)>
+<!ELEMENT parameter-name (#PCDATA)>
+<!ELEMENT header-name (#PCDATA)>
+
+  <!-- Actions =========================================== -->
+<!ELEMENT map:actions (map:action*)>
+<!ATTLIST map:actions
+        default CDATA #IMPLIED
+>
+<!ELEMENT map:action EMPTY>
+<!ATTLIST map:action
+        name CDATA #REQUIRED
+        src CDATA #REQUIRED
+>
+
+<!-- =============================================================== -->
+<!-- Views -->
+<!-- =============================================================== -->
+
+<!ELEMENT map:views (map:view*)>
+<!ELEMENT map:view (map:transform*,map:serialize)>
+<!ATTLIST map:view
+        name CDATA #REQUIRED
+        from-label CDATA #IMPLIED
+        from-position (first|last) "last"
+>
+<!ELEMENT map:serialize (map:parameter*)>
+<!ATTLIST map:serialize
+        type CDATA #REQUIRED
+        mime-type CDATA #IMPLIED
+        status-code CDATA #IMPLIED
+>
+
+<!-- =============================================================== -->
+<!-- Resources -->
+<!-- =============================================================== -->
+
+<!ELEMENT map:resources (map:resource*)>
+<!ELEMENT map:resource ((map:generate,map:transform+,map:serialize) | map:act)>
+<!ATTLIST map:resource
+        name CDATA #REQUIRED
+>
+<!-- generate and transform defined in PIPELINE section -->
+
+<!-- =============================================================== -->
+<!-- Action Sets -->
+<!-- =============================================================== -->
+
+<!ELEMENT map:action-sets (map:action-set*)>
+<!ELEMENT map:action-set (map:act+)>
+<!ATTLIST map:action-set
+        name CDATA #REQUIRED
+>
+<!ELEMENT map:act (map:parameter|map:redirect-to|map:call|map:generate|
+                   map:transform|map:serialize|map:act|map:match)*>
+<!ATTLIST map:act
+        type CDATA #IMPLIED
+        action CDATA #IMPLIED
+        set CDATA #IMPLIED
+>
+
+<!-- =============================================================== -->
+<!-- Pipelines -->
+<!-- =============================================================== -->
+
+<!ELEMENT map:pipelines (map:pipeline*)>
+<!ELEMENT map:pipeline (map:match*, map:handle-errors?)>
+
+<!ELEMENT map:match (map:mount | map:redirect-to | map:call | map:generate |
+                     map:transform | map:serialize | map:read |
+                     map:aggregate | map:act | map:match)*>
+<!-- RNG: It seemed from the example that match should be defined as
+  match (map:mount*|map:redirect-to*|(map:generate*,map:transform*,map:serialize*)*|map:read*|map:aggregate*)
+  but I have no way of knowing.
+-->
+<!-- DC: Now map:act complicates the content model even further -->
+<!ATTLIST map:match
+        type CDATA #IMPLIED
+        pattern CDATA #REQUIRED
+>
+
+<!-- map:act is already defined in the Action Sets section -->
+
+<!ELEMENT map:mount EMPTY>
+<!ATTLIST map:mount
+        uri-prefix CDATA #REQUIRED
+        src CDATA #REQUIRED
+        reload-method (synchron|asynchron) "asynchron"
+        check-reload (true|false|yes|no) "no"
+>
+
+<!ELEMENT map:redirect-to EMPTY>
+<!ATTLIST map:redirect-to
+        uri CDATA #IMPLIED
+        session (true|false|yes|no) "no"
+>
+<!-- CH: redirects to resources are now deprecated
+<!ATTLIST map:redirect-to
+        uri CDATA #IMPLIED
+        resource CDATA #IMPLIED
+        target CDATA #IMPLIED
+        session (true|false|yes|no) "no"
+>
+-->
+
+<!ELEMENT map:call (map:parameter*)>
+<!ATTLIST map:call
+        resource CDATA #REQUIRED
+>
+
+<!ELEMENT map:generate (map:parameter*)>
+<!ATTLIST map:generate
+        type CDATA #IMPLIED
+        src CDATA #IMPLIED
+        label CDATA #IMPLIED
+>
+<!ELEMENT map:parameter EMPTY>
+<!ATTLIST map:parameter
+        name CDATA #REQUIRED
+        value CDATA #REQUIRED
+>
+
+<!ELEMENT map:transform (map:parameter*)>
+<!ATTLIST map:transform
+        type CDATA #IMPLIED
+        src CDATA #IMPLIED
+        label CDATA #IMPLIED
+>
+
+<!-- map:serialize is already defined in VIEWS section -->
+
+<!ELEMENT map:read EMPTY>
+<!ATTLIST map:read
+        src CDATA #REQUIRED
+        mime-type CDATA #REQUIRED
+        type CDATA #IMPLIED
+>
+
+<!ELEMENT map:aggregate (map:part*)>
+<!ATTLIST map:aggregate
+        element CDATA #IMPLIED
+        prefix CDATA #IMPLIED
+        ns CDATA #IMPLIED
+        label CDATA #IMPLIED
+>
+<!ELEMENT map:part EMPTY>
+<!ATTLIST map:part
+        src CDATA #IMPLIED
+        element CDATA #IMPLIED
+        ns CDATA #IMPLIED
+        strip-root CDATA #IMPLIED
+        label CDATA #IMPLIED
+>
+
+<!ELEMENT map:handle-errors (map:generate*,map:transform*,map:serialize*)>
+
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

src/documentation/xdocs/dtd/specification-v10.dtd

@@ -0,0 +1,85 @@
+<!-- ===================================================================
+     
+     Apache Specification DTD (Version 1.0)
+
+PURPOSE:
+  This DTD was developed to create a simple yet powerful document 
+  type for software specifications for use with the Apache projects.  
+  It is an XML-compliant DTD and it's maintained by the Apache XML 
+  project.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE document PUBLIC
+       "-//APACHE//DTD Specification Vx.yz//EN"
+       "http://xml.apache.org/DTD/specification-vxyz.dtd">
+
+  where 
+  
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+      
+NOTES:  
+
+AUTHORS:
+  Stefano Mazzocchi <stefano@apache.org>
+  
+FIXME:
+
+CHANGE HISTORY:
+  19991129 Initial version. (SM)
+    
+COPYRIGHT:
+  Copyright (c) @year@ The Apache Software Foundation.
+  
+  Permission to copy in any form is granted provided this notice is 
+  included in all copies. Permission to redistribute is granted 
+  provided this file is distributed untouched in all its parts and 
+  included files.
+  
+==================================================================== -->
+
+<!-- =============================================================== -->
+<!-- Extend the Documentation DTD -->
+<!-- =============================================================== -->
+
+<!-- extend the local.xxx entities -->
+<!ENTITY % local.lists "|bl">
+
+<!-- FIXME (SM): this is hardcoding. Find a better way of doing this
+     possibly using public identifiers -->
+<!ENTITY % document-dtd SYSTEM "document-v10.dtd">
+%document-dtd;
+
+<!-- =============================================================== -->
+<!-- Document Type Definition -->
+<!-- =============================================================== -->
+
+<!ELEMENT specification (header?, body, appendices?, footer?)>
+<!ATTLIST specification %common.att;>
+
+    <!ELEMENT appendices (%sections;)+>
+    <!ATTLIST appendices %common.att;>
+
+<!-- =============================================================== -->
+<!-- Bibliography List -->
+<!-- =============================================================== -->
+
+    <!-- Bibliography list -->
+    <!ELEMENT bl (bi)+>
+    <!ATTLIST bl %common.att;>
+
+        <!-- Book item -->
+        <!ELEMENT bi EMPTY>
+        <!ATTLIST bi %common.att;
+                     %name.att;
+                     %title.att;
+                     %xlink-simple.att;
+                     %xlink-user-new.att;
+                     authors CDATA #REQUIRED
+                     date    CDATA #IMPLIED>
+
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

src/documentation/xdocs/dtd/svg-cocoon-v11.dtd

@@ -0,0 +1,82 @@
+<!--
+
+PURPOSE:
+This is a minimal SVG DTD intended solely for Apache Cocoon internal use.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE svg PUBLIC
+       "-//APACHE//DTD Cocoon SVG minimal Vx.yz//EN"
+       "http://xml.apache.org/DTD/svg-cocoon-vxyz.dtd">
+
+  where 
+  
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+
+NOTES:
+The Official SVG DTD is using some entities that cannot yet be resolved
+so this is a hack DTD to get us started. We are only using this DTD to
+enable validation during "build docs" because every XML instance must
+declare its ruleset.
+
+This initial minimal DTD has been reverse-engineered from the structure
+of the current documents at documentation/svg/*.xml
+
+See:
+http://www.w3.org/TR/2001/REC-SVG-20010904/
+http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd
+
+CHANGE HISTORY:
+  20011031 1.0 Initial version (DC)
+  20011102 1.1 Added more elements for new svg/*.xml from Klaus (DC)
+-->
+
+<!ELEMENT svg (defs|image|g|rect|text)*>
+<!ELEMENT defs (filter)*>
+<!ELEMENT filter (feGaussianBlur)*>
+<!ELEMENT feGaussianBlur EMPTY>
+<!ELEMENT g (path)*>
+<!ELEMENT path EMPTY>
+<!ELEMENT image EMPTY>
+<!ELEMENT rect EMPTY>
+<!ELEMENT text (label?)>
+<!ELEMENT label EMPTY>
+
+<!ATTLIST svg height CDATA #REQUIRED
+              width CDATA #REQUIRED
+              xmlns:xlink CDATA #IMPLIED
+>
+ <!--  yikes ... this breaks build docs                            -->
+ <!--            just like hacking the official DTD to add <label> -->
+ <!--            see email 2001-11-08                              -->
+ <!--              xmlns CDATA #FIXED "http://www.w3.org/2000/svg" -->
+
+<!ATTLIST filter id ID #IMPLIED
+>
+<!ATTLIST feGaussianBlur in CDATA #IMPLIED
+              stdDeviation CDATA #IMPLIED
+>
+<!ATTLIST g transform CDATA #IMPLIED
+>
+<!ATTLIST path style CDATA #REQUIRED
+              d CDATA #REQUIRED
+>
+<!ATTLIST image width CDATA #REQUIRED
+              height CDATA #REQUIRED
+              xlink:href CDATA #IMPLIED
+>
+<!ATTLIST rect width CDATA #REQUIRED
+              height CDATA #REQUIRED
+              x CDATA #IMPLIED
+              y CDATA #IMPLIED
+              fill CDATA #IMPLIED
+              style CDATA #IMPLIED
+>
+<!ATTLIST text style CDATA #REQUIRED
+              x CDATA #REQUIRED
+              y CDATA #REQUIRED
+              text-anchor CDATA #IMPLIED
+              fill CDATA #IMPLIED
+>

src/documentation/xdocs/dtd/todo-v10.dtd

@@ -0,0 +1,90 @@
+<!-- ===================================================================
+     
+     Apache Todos DTD (Version 1.0)
+
+PURPOSE:
+  This DTD was developed to create a simple yet powerful document 
+  type for software development todo lists for use with the Apache projects.  
+  It is an XML-compliant DTD and it's maintained by the Apache XML 
+  project.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE document PUBLIC
+       "-//APACHE//DTD Todo Vx.yz//EN"
+       "http://xml.apache.org/DTD/todo-vxyz.dtd">
+
+  where 
+  
+    x := major version
+    y := minor version
+    z := status identifier (optional)
+      
+NOTES:  
+  It is important, expecially in open developped software projects, to keep
+  track of software changes that need to be done, planned features, development
+  assignment, etc. in order to allow better work parallelization and create
+  an entry point for people that want to help. This DTD wants to provide
+  a solid foundation to provide such information and to allow it to be
+  published as well as distributed in a common format.
+
+AUTHORS:
+  Stefano Mazzocchi <stefano@apache.org>
+  
+FIXME:
+  - do we need anymore working contexts? (SM)
+
+CHANGE HISTORY:
+  19991129 Initial version. (SM)
+  19991225 Added actions element for better structure (SM)
+    
+COPYRIGHT:
+  Copyright (c) @year@ The Apache Software Foundation.
+  
+  Permission to copy in any form is granted provided this notice is 
+  included in all copies. Permission to redistribute is granted 
+  provided this file is distributed untouched in all its parts and 
+  included files.
+  
+==================================================================== -->
+
+<!-- =============================================================== -->
+<!-- Extend the Documentation DTD -->
+<!-- =============================================================== -->
+
+<!-- FIXME (SM): this is hardcoding. Find a better way of doing this
+     possibly using public identifiers -->
+<!ENTITY % document-dtd SYSTEM "document-v10.dtd">
+%document-dtd;
+
+<!-- =============================================================== -->
+<!-- Common entities -->
+<!-- =============================================================== -->
+
+<!ENTITY % priorities "showstopper|high|medium|low|wish|dream">
+
+<!ENTITY % contexts "build|docs|code|admin|design">
+
+<!-- =============================================================== -->
+<!-- Document Type Definition -->
+<!-- =============================================================== -->
+
+<!ELEMENT todo (devs, actions*)>
+<!ATTLIST todo %common.att; 
+               %title.att;>
+
+    <!ELEMENT devs (person+)>
+    <!ATTLIST devs %common.att;>
+
+    <!ELEMENT actions (action+)>
+    <!ATTLIST actions %common.att;
+                     priority     (%priorities;)  #IMPLIED>
+
+        <!ELEMENT action (%content.mix;)*>
+        <!ATTLIST action %common.att;
+                         assigned-to  IDREF           #IMPLIED
+                         context      (%contexts;)    #REQUIRED>
+    
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

src/documentation/xdocs/faq.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "dtd/faq-v10.dtd">
+
+<faqs title="Frequently Asked Questions">
+<faq>
+  <question>
+    Why does nothing happen?
+  </question>
+  <answer>
+    <p>
+      You might want to check a few things:
+    </p>
+    <ul>
+      <li>
+        one
+      </li>
+      <li>
+        two
+      </li>
+      <li>
+        three
+      </li>
+    </ul>
+    <note>This is a note.</note>
+  </answer>
+</faq>
+
+</faqs>

src/documentation/xdocs/hdf/book.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
+
+<book software="Poi Project" 
+      title="HDF" 
+      copyright="@year@ Poi Project">
+
+  <menu label="Navigation">
+    <menu-item label="Main" href="../index.html"/>
+  </menu>
+
+</book>
+
+

src/documentation/xdocs/hdf/index.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>HDF</title>
+  <subtitle>Overview</subtitle>
+  <authors>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>     
+   <person name="Andrew C. Oliver" email="acoliver@apache.org"/>   
+  </authors>
+ </header>
+
+ <body>
+ <s1 title="Overview">
+
+  <p>HDF will be the name of OUR port of the Microsoft Word 97(-2002) file format to
+     pure Java.</p>
+  <p>HDF is still in early development. If you want to help us, you can 
+     follow development on the poi-dev mailing list.</p>
+
+
+  </s1>
+ </body>
+</document>

src/documentation/xdocs/historyandfuture.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+  <header>
+    <title></title>
+    <authors>
+      <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
+    </authors>
+  </header>
+  
+  <body>
+
+
+    <s1 title="Brief Project History">
+
+        <p>The POI project was dreamed up back around April 2001, when Andy Oliver landed a short term contract to do Java-based reporting to Excel. He'd done this project a few times before and knew right were to look for the tools He needed. Ironically the API he used to use had skyrocketed from around $300 ($US) to around $10K ($US). He figured it would take two people around six months to write an Excel port so he recommended the client fork out the $10K.
+        </p>
+
+        <p>Around July, he started thinking how great it would be to have an open source Java tool to do this and, while he had some spare time, he started on the project and learned about OLE 2 Compound Document Format. After hitting some real stumpers he realized he'd need help. He posted a message to his local Java User's Group (JUG) and asked if anyone else would be interested. He lucked out and the most talented Java programmer he'd ever met, Marc Johnson, joined the project. He ran rings around Andy at porting OLE 2 CDF and rewrote his skeletal code into a more sophisticated library. It took Marc a few iterations to get something they were happy with.
+        </p>
+
+        <p>While Marc worked on that, Andy ported XLS to Java, based on Marc's library. Several users wrote in asking to read XLS (not just write as had originally been scoped) and one user had special requests for a different use for POIFS. Before long the project scope had tripled.  POI 1.0 was released a month late, but with far more features. Marc quickly wrote the serializer framework and HSSF Serializer in record time and Andy banged out more documentation and worked on making people aware of the project
+        </p>
+
+        <p> 
+          Shortly before the release POI was fortunate to come into contact with Nicola -Ken- Barrozzi who gave them samples 
+for the HSSF Serializer and help uncover its unfortunate bugs (which were promptly fixed).  More recently Ken ported most of the
+POI project documentation to XML from Andy's crappy HTML docs he wrote with Star Office :-p.  
+        </p>
+
+        <p>
+          Around the same time as the release, Glen Stampoultzis joined the project.  Glen was ticked off at Andy's flippant 
+attitude towards adding graphing to HSSF.  Glen got so ticked off he decided to gab a hammer and do it himself.  Glen has 
+already become an integral part of the POI development community, his contributions to HSSF have already started making waves.
+        </p>
+
+        <p>
+         Somewhere in there we decided to finally submit the project to 
+         <link href="http://xml.apache.org/cocoon">The Apache Cocoon Project</link> only to discover the project had outgrown
+         fitting nicely into just Cocoon long ago.  Furthermore, Andy started eyeing other projects he'd like to see POI 
+         functionality added to.  So it was decided to donate the Serializers and Generators to Cocoon, other POI integration
+         components to other projects, and the POI APIs would become part of Jakarta.  It was a bumpy road but it looks like
+         everything turned out since you're reading this!
+        </p>
+
+    </s1>
+
+    <s1 title="What's next for POI">
+        <p>First we'll tackle this from a project standpoint: Well, we made an offer to Microsoft and Actuate (tongue in cheek ... well mostly) that we'd quit the project and retire if they'd simply write us each a really large check. I've yet to get a phone call or email so I'm assuming they're not going to pay us to go away.
+        </p>
+        <p>Next, we've got some work to do here at Jakarta to finish integrating POI into the community.  Furthermore, we're 
+           still transitioning the Serializer to Cocoon.
+        </p>
+        <p>HSSF, during the 2.0 cycle, will undergo a few optimizations. We'll also be adding new features like a full implementation of Formulas and custom text formats. We're hoping to be able to generate smaller files by adding write-support for RK, MulRK and MulBlank records. I'm also going to work on a Cocoon 2 Generator. Currently, reading is not very efficient in HSSF. This is mainly because in order to write or modify, one needs to be able to update upstream pointers to downstream data. To do this you have to have everything between in memory. A Generator would allow SAX events to be processed instead. (This will be based on the low level structures). One of the great things about this is that, you'll not only have a more efficient way to read the file, you'll have a great way to use spreadsheets as XML data sources.
+        </p>
+        <p>The HSSF Serializer, will further separate into a general framework for creating serializers for other formats and the HSSF Serializer specific implementation. (This is largely already true). We'll also be adding support for features already supported by HSSF (styles, fonts, text formats). We're hoping to add support for formulas during this cycle.
+        </p>
+        <p>We're beginning to expand our scope yet again. If we could do all of this for XLS files, what about Doc files or PPT files? We're thinking that our next component (HDF - Horrible Document Format) should follow the same pattern. We're hoping that new blood will join the team and allow us to tackle this even faster (in part because POIFS is already finished). But maybe what we need most is you!
+        </p>    
+      </s1>
+
+    </body>
+  <footer>
+    <legal>
+      Copyright (c) @year@ The Apache Software Foundation All rights reserved.
+      $Revision$ $Date$
+    </legal>
+  </footer>
+
+
+</document>

src/documentation/xdocs/hssf/book.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
+
+<book software="Poi Project" 
+      title="HSSF" 
+      copyright="@year@ Poi Project">
+
+  <menu label="Navigation">
+    <menu-item label="Main" href="../index.html"/>
+  </menu>
+
+  <menu label="HSSF">
+    <menu-item label="HOWTO" href="how-to.html"/>
+    <menu-item label="Use Case" href="use-case.html"/>
+  </menu>
+
+</book>

src/documentation/xdocs/hssf/how-to.xml

@@ -0,0 +1,554 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd"> 
+     
+<document>
+  <header>
+   <title>The New Halloween Document</title>
+   <authors>
+    <person email="acoliver2@users.sourceforge.net" name="Andrew C. Oliver" id="AO"/>
+   </authors>
+  </header>
+  <body>
+    <s1 title="How to use the HSSF prototype API">
+
+    <s2 title="Recent revision history">
+      <ul>
+	      <li>12.30.2001 - revised for poi	1.0-final - minor revisions</li>
+        <li>01.03.2001 - revised for poi 1.1-devel</li>
+      </ul>
+    </s2>  
+
+    <s2 title="Capabilities">
+    <p>This release of the how-to outlines functionality included in a
+	development build of HSSF.  Those looking for information on the the
+	release edition should look in the poi-src for the release or at a
+	previous edition in CVS tagged for that release.</p>
+  <p>
+	This release allows numeric and string cell values to be written to
+	or read from an XLS file. Also in this release is row and column
+	sizing, cell styling (bold, italics, borders,etc), and support for
+	built-in data formats.  New to this release is an event-based API
+	for reading XLS files.  It differs greatly from the read/write API
+	and is intended for intermediate developers who need a smaller
+	memory footprint.  It will also serve as the basis for the HSSF
+	Generator.</p>
+      </s2>  
+    <s2 title="Target Audience">
+    <p>This release is intended for developers, java-fanatics and the
+just generally all around impatient. HSSF has not yet been
+extensively tested in a high load multi-threaded situation. This
+release is not considered to be &quot;golden&quot; as it has new
+features that have not been extensively tested, and is an early 2.0
+build that could be restructured significantly in the future (not
+that there are necessarily plans to do so, just that you're better
+off basing your code on 1.0 and sticking with it if you don't need
+2.0 stuff bad enough to deal with us pulling the rug out from under
+you regularly).</p>
+</s2>
+    <s2 title="General Use">
+        <s3 title="User API">
+                <s4 title="Writing a new one">
+
+<p>The high level API (package: org.apache.poi.hssf.usermodel)
+is what most people should use. Usage is very simple. 
+</p>
+<p>Workbooks are created by creating an instance of
+org.apache.poi.hssf.usermodel.HSSFWorkbook. 
+</p>
+<p>Sheets are created by calling createSheet() from an existing
+instance of HSSFWorkbook, the created sheet is automatically added in
+sequence to the workbook. In this release there will always be at
+least three sheets generated regardless of whether you have three
+sheets. More than three sheets is probably not supported. Sheets do
+not in themselves have a sheet name (the tab at the bottom), you set
+the name associated with a sheet by calling
+HSSFWorkbook.setSheetName(sheetindex,&quot;SheetName&quot;).</p>
+<p>Rows are created by calling createRow(rowNumber) from an existing
+instance of HSSFSheet. Only rows that have cell values should be
+added to the sheet. To set the row's height, you just call
+setRowHeight(height) on the row object. The height must be given in
+twips, or 1/20th of a point. If you prefer, there is also a
+setRowHeightInPoints method. 
+</p>
+<p>Cells are created by calling createCell(column, type) from an
+existing HSSFRow. Only cells that have values should be added to the
+row. Cells should have their cell type set to either
+HSSFCell.CELL_TYPE_NUMERIC or HSSFCell.CELL_TYPE_STRING depending on
+whether they contain a numeric or textual value. Cells must also have
+a value set. Set the value by calling setCellValue with either a
+String or double as a parameter. Individual cells do not have a
+width, you must call setColumnWidth(colindex, width) (use units of
+1/256th of a character) on the HSSFSheet object. (You can't do it on
+an individual basis in the GUI either).</p>
+<p>Cells are styled with HSSFCellStyle objects which in turn contain
+a reference to an HSSFFont object. These are created via the
+HSSFWorkbook object by calling createCellStyle() and createFont().
+Once you create the object you must set its parameters (colors,
+borders, etc). To set a font for an HSSFCellStyle call
+setFont(fontobj). 
+</p>
+<p>Once you have generated your workbook, you can write it out by
+calling write(outputStream) from your instance of Workbook, passing
+it an OutputStream (for instance a FileOutputStream or
+ServletOutputStream). You must close the OutputStream yourself. HSSF
+does not close it for you. 
+</p>
+<p>Here is some example code (excerpted and adapted from
+org.apache.poi.hssf.dev.HSSF test class):</p>
+<source>        FileOutputStream out    = new FileOutputStream(&quot;/home/me/myfile.xls&quot;);  // create a new file
+        HSSFWorkbook     wb     = new HSSFWorkbook();                           // create a new workbook
+        HSSFSheet        s      = wb.createSheet();                             // create a new sheet
+        HSSFRow          r      = null;                                         // declare a row object reference
+        HSSFCell         c      = null;                                         // declare a cell object reference
+        HSSFCellStyle    cs     = wb.createCellStyle();                         // create 3 cell styles
+        HSSFCellStyle    cs2    = wb.createCellStyle();        
+        HSSFCellStyle    cs3    = wb.createCellStyle();          
+        HSSFFont         f      = wb.createFont();                              // create 2 fonts objects
+        HSSFFont         f2     = wb.createFont();                              
+        
+        f.setFontHeightInPoints((short)12);                                    //set font 1 to 12 point type
+        f.setColor((short)0xA);                                                //make it red
+        f.setBoldweight(f.BOLDWEIGHT_BOLD);                                   // make it bold
+                                                                             //arial is the default font
+        
+        f2.setFontHeightInPoints((short)10);                                   //set font 2 to 10 point type
+        f2.setColor((short)0xf);                                               //make it the color at palette index 0xf (white)
+        f2.setBoldweight(f2.BOLDWEIGHT_BOLD);                                 //make it bold
+        
+        cs.setFont(f);                                                        //set cell stlye 
+        cs.setDataFormat(HSSFDataFormat.getFormat(&quot;($#,##0_);[Red]($#,##0)&quot;));//set the cell format see HSSFDataFromat for a full list
+        
+        cs2.setBorderBottom(cs2.BORDER_THIN);                                 //set a thin border
+        cs2.setFillPattern((short)1);                                         //fill w fg fill color
+        cs2.setFillForegroundColor((short)0xA);                               // set foreground fill to red
+
+        cs2.setFont(f2);                                                      // set the font
+
+        wb.setSheetName(0,&quot;HSSF Test&quot;);                                       // set the sheet name to HSSF Test
+        for (rownum = (short)0; rownum &lt; 300; rownum++)                       // create a sheet with 300 rows (0-299)
+        { 
+            r = s.createRow(rownum);                                          // create a row 
+            if ( (rownum % 2) == 0) {                                         // on every other row 
+                r.setHeight((short)0x249);                                    // make the row height bigger  (in twips - 1/20 of a point)
+            }
+            
+            //r.setRowNum(( short ) rownum);
+            for (short cellnum = (short)0; cellnum &lt; 50; cellnum += 2)       // create 50 cells (0-49) (the += 2 becomes apparent later
+            {
+                c = r.createCell(cellnum,HSSFCell.CELL_TYPE_NUMERIC);        // create a numeric cell
+                c.setCellValue(rownum * 10000 + cellnum                      // do some goofy math to demonstrate decimals 
+                               + ((( double ) rownum / 1000)
+                                  + (( double ) cellnum / 10000)));
+          
+                if ( (rownum % 2) == 0) {                                    // on every other row
+                    c.setCellStyle(cs);                                      // set this cell to the first cell style we defined
+                }
+
+
+                c = r.createCell((short)(cellnum+1),HSSFCell.CELL_TYPE_STRING);              // create a string cell (see why += 2 in the
+                                                                                             // for loop (we want 2 cells per loop)
+                c.setCellValue(&quot;TEST&quot;);                                                      // set the cell's string value to &quot;TEST&quot;
+                s.setColumnWidth((short)(cellnum+1), (short)((50*8) / ((double)1/20)) );     // make this column a bit wider
+                
+                if ( (rownum % 2) == 0) {                                                    // on every other row
+                    c.setCellStyle(cs2);                                                     // set this to the white on red cell style
+                }                                                                            // we defined above
+                
+            }           
+        }
+        
+        
+        //draw a thick black border on the row at the bottom using BLANKS
+        rownum++;                                                                            // advance 2 rows
+        rownum++;
+        
+        r = s.createRow(rownum);
+        
+      
+        
+        cs3.setBorderBottom(cs3.BORDER_THICK);                                                // define the third style to be the default
+                                                                                              // except with a thick black border at the bottom        
+              
+        for (short cellnum = (short)0; cellnum &lt; 50; cellnum++) {                             //create 50 cells
+            c = r.createCell(cellnum,HSSFCell.CELL_TYPE_BLANK);                               //create a blank type cell (no value)
+            c.setCellStyle(cs3);                                                              // set it to the thick black border style
+        }
+        
+        //end draw thick black border
+        
+        
+                                                                                             //demonstrate adding/naming and deleting a sheet
+                                                                                            // create a sheet, set its title then delete it
+        s = wb.createSheet();  
+        wb.setSheetName(1,&quot;DeletedSheet&quot;);
+        wb.removeSheetAt(1);
+        //end deleted sheet
+        
+        
+        wb.write(out);                                                                   // write the workbook to the output stream
+        out.close();                                                                     // close our file (don't blow out our file handles
+        </source>
+        </s4>
+                <s4 title="Reading or modifying an existing file">
+
+<p>Reading in a file is equally simple. To read in a file create a
+new instance of org.apache.poi.poifs.Filesystem passing in the
+filename of your XLS to the constructor. Construct a new instance of
+org.apache.poi.hssf.usermodel.HSSFWorkbook passing the
+Filesystem instance to the constructor. From there you have access to
+all of the high level model objects through their assessor methods
+(workbook.getSheet(sheetNum), sheet.getRow(rownum), etc). 
+</p>
+<p>Modifying the file you have read in is simple. You retrieve the
+object via an assessor method, remove it via a parent object's remove
+method (sheet.removeRow(hssfrow)) and create objects just as you
+would if creating a new xls. When you are done modifying cells just
+call workbook.write(outputstream) just as you did above.</p>
+<p>An example of this can be seen in
+org.apache.poi.hssf.dev.HSSF.  See
+<link href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/poi/poi/production/src/net/sourceforge/poi/hssf/dev/HSSF.java?rev=HEAD&amp;content-type=text/plain">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/poi/poi/production/src/net/sourceforge/poi/hssf/dev/HSSF.java?rev=HEAD&amp;content-type=text/plain</link>.</p>
+         </s4>       </s3>
+                <s3 title="Event API">
+
+<p>The event API is brand new.  It is intended for intermediate
+developers who are willing to learn a little bit of the low level API
+structures.  Its relatively simple to use, but requires a basic
+understanding of the parts of an Excel file (or willingness to
+learn).  The advantage provided is that you can read an XLS with a
+relatively small memory footprint.  
+</p>
+<p>To use this API you construct an instance of
+org.apache.poi.hssf.eventmodel.HSSFRequest register a class you
+create that supports the
+org.apache.poi.hssf.eventmodel.HSSFListener interface using the
+HSSFRequest.addListener(yourlistener, recordsid).  The recordsid
+should be a static reference number (such as BOFRecord.sid) contained
+in the classes in org.apache.poi.hssf.record.  The trick is you
+have to know what these records are.  Alternatively you can call
+HSSFRequest.addListenerForAllRecords(mylistener).  In order to learn
+about these records you can either all of the javadoc in the
+org.apache.poi.hssf.record package or you can just hack up a
+copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your
+needs.  TODO: better documentation on records.</p>
+<p>Once you've registered your listeners in the HSSFRequest object
+you can construct an instance of
+org.apache.poi.poifs.filesystem.Filesystem (see POIFS howto) and
+pass it your XLS file inputstream.  You can either pass this along
+with the request you constructed to an instance of HSSFEventFactory
+via the HSSFEventFactory.processWorkbookEvents(request, Filesystem)
+method or you can get an instance of DocumentInputStream from
+Filesystem.createDocumentInputStream(&quot;Workbook&quot;) and pass
+it to HSSFEventFactory.processEvents(request, inputStream).  Once you
+make this call the listeners that you constructed receive calls to
+their processRecord(Record) methods with each Record they are
+registered to listen for until the file has been completely read.  
+</p>
+<p>A code excerpt from org.apache.poi.hssf.dev.EFHSSF (which is
+in CVS or the source distribution) is reprinted below with excessive
+comments:</p>
+<source>class EFHSSFListener implements HSSFListener {  //this non-public class implements the required interface 
+    EFHSSF efhssf;                              // we construct it with a copy of its container class...this is cheap but effective 
+    public EFHSSFListener(EFHSSF efhssf) {      
+        this.efhssf = efhssf;
+    }
+    
+    public void processRecord(Record record) {  // we just use this as an adapter so we pass the record to the method in the container class
+        efhssf.recordHandler(record);
+    }
+}
+
+     //here is an excerpt of the main line execution code from EFHSSF
+    public void run() throws IOException {
+        FileInputStream fin = new FileInputStream(infile);              // create a new file input stream with the input file specified 
+                                                                        // at the command line
+        Filesystem poifs = new Filesystem(fin);                         // create a new org.apache.poi.poifs.filesystem.Filesystem
+        InputStream din  = poifs.createDocumentInputStream(&quot;Workbook&quot;); // get the Workbook (excel part) stream in a InputStream
+        HSSFRequest req = new HSSFRequest();                            // construct out HSSFRequest object
+        req.addListenerForAllRecords(new EFHSSFListener(this));         // lazy listen for ALL records with the listener shown above
+        HSSFEventFactory factory = new HSSFEventFactory();              // create our event factory
+        factory.processEvents(req,din);                                 // process our events based on the document input stream
+        fin.close();                                                    // once all the events are processed close our file input stream
+        din.close();                                                    // and our document input stream (don't want to leak these!)
+        FileOutputStream fout = new FileOutputStream(outfile);          // create a new output stream from filename specified at the command line
+        workbook.write(fout);                                           // write the HSSFWorkbook (class member) we created out to the file.
+        fout.close();                                                   // close our file output stream
+        System.out.println(&quot;done.&quot;);                                    // print done.  Go enjoy your copy of the file.
+    }
+
+
+    //here is an excerpt of the recordHander called from our listener.
+    public void recordHandler(Record record) {  // the record handler in the container class is intent on just rewriting the fire         
+        HSSFRow row = null;                          
+        HSSFCell cell = null;
+        int sheetnum = -1;
+        switch (record.getSid()) {
+            case BOFRecord.sid:                 // the BOFRecord can represent either the beginning of a sheet or the workbook 
+                BOFRecord bof = (BOFRecord) record;
+                if (bof.getType() == bof.TYPE_WORKBOOK) {
+                    workbook = new HSSFWorkbook();                    //if its the workbook then create a new HSSFWorkbook 
+                } else if (bof.getType() == bof.TYPE_WORKSHEET) {     // assigned to the class level member
+                    sheetnum++;
+                    cursheet = workbook.getSheetAt(sheetnum);         // otherwise if its a sheet increment the sheetnum index 
+                }                                                     // get the sheet at that index and assign it to method variable 
+            break;                                                    // cursheet (the sheet was created when the BoundSheetRecord record occurred
+            case BoundSheetRecord.sid:                               
+                BoundSheetRecord bsr = (BoundSheetRecord) record;     // when we find a boundsheet record create a new sheet in the workbook and 
+                workbook.createSheet(bsr.getSheetname());             // assign it the name specified in this record. 
+            break;
+            case RowRecord.sid:                                       // if this is a row record add the row to the current sheet 
+                RowRecord rowrec = (RowRecord) record;
+                cursheet.createRow(rowrec.getRowNumber());            // assign our row the rownumber specified in the Row Record
+            break;
+            case NumberRecord.sid:                                    // if this is a NumberRecord (RKRecord, MulRKRecord get converted to Number
+                NumberRecord numrec = (NumberRecord) record;          // records) then get the row specified in the number record from the current
+                row = cursheet.getRow(numrec.getRow());               // sheet.  With this instance of HSSFRow create a new HSSFCell with the column
+                cell = row.createCell(numrec.getColumn(),HSSFCell.CELL_TYPE_NUMERIC); //number specified in the record and assign it type NUMERIC
+                cell.setCellValue(numrec.getValue());                 // set the HSSFCell's value to the value stored in the NumberRecord
+            break;
+            case SSTRecord.sid:                                       // if this is the SSTRecord (occurs once in the workbook) then add all of its 
+                SSTRecord sstrec = (SSTRecord) record;                // strings to our workbook.  We'll look them up later when we add LABELSST records.
+                for (int k = 0; k &lt; sstrec.getNumUniqueStrings(); k++) {
+                    workbook.addSSTString(sstrec.getString(k));
+                }
+            break;
+            case LabelSSTRecord.sid:                                  // if this is a LabelSSTRecord then get the row specified in the LabelSSTRecord from
+                LabelSSTRecord lrec = (LabelSSTRecord) record;        // the current sheet.  With this instance of HSSFRow create a new HSSFCell with the
+                row = cursheet.getRow(lrec.getRow());                 // column nubmer specified in the record and set the type to type STRING.  
+                cell = row.createCell(lrec.getColumn(),HSSFCell.CELL_TYPE_STRING);
+                cell.setCellValue(workbook.getSSTString(lrec.getSSTIndex())); //set the cells value to the string in our workbook object (added in the case
+            break;                                                            //above) at the index specified by the LabelSSTRecord.
+        }
+    }</source>
+     </s3>
+                <s3 title="Low Level APIs">
+
+<p>The low level API is not much to look at. It consists of lots of
+&quot;Records&quot; in the org.apache.poi.hssf.record.* package,
+and set of helper classes in org.apache.poi.hssf.model.*. The
+record classes are consistent with the low level binary structures
+inside a BIFF8 file (which is embedded in a POIFS file system). You
+probably need the book: &quot;Microsoft Excel 97 Developer's Kit&quot;
+from Microsoft Press in order to understand how these fit together
+(out of print but easily obtainable from Amazon's used books). In
+order to gain a good understanding of how to use the low level APIs
+should view the source in org.apache.poi.hssf.usermodel.* and
+the classes in org.apache.poi.hssf.model.*. You should read the
+documentation for the POIFS libraries as well.</p>
+     </s3>
+                <s3 title="HSSF Class/Test Application">
+
+<p>The HSSF application is nothing more than a test for the high
+level API (and indirectly the low level support). The main body of
+its code is repeated above. To run it: 
+</p>
+<ul>
+	<li>download the poi-alpha build untar it (tar xvzf
+	tarball.tar.gz) 
+	</li>
+	<li>set up your classpath as follows:
+	<code>export HSSFDIR={wherever you put HSSF's jar files}
+export LOG4JDIR={wherever you put LOG4J's jar files}
+export CLASSPATH=$CLASSPATH:$HSSFDIR/hssf.jar:$HSSFDIR/poi-poifs.jar:$HSSFDIR/poi-util.jar:$LOG4JDIR/jog4j.jar</code>
+	</li><li>type:
+	<code>java org.apache.poi.hssf.dev.HSSF ~/myxls.xls write</code></li>
+</ul>
+<p>This should generate a test sheet in your home directory called <code>&quot;myxls.xls&quot;</code>.  </p>
+<ul>
+	<li>Type:
+	<code>java org.apache.poi.hssf.dev.HSSF ~/input.xls output.xls
+This is the read/write/modify test.  It reads in the spreadsheet modifies a cell and writes it back out.  Failing this test is not necessarily a bad thing.  If HSSF tries to modify a non-existant sheet then this will most likely fail.  Such is no big deal.  </code></li>
+</ul>
+     </s3>
+                <s3 title="HSSF Logging facility">
+<p>HSSF now has a logging facility (using log4j - thanks jakarta!)
+that will record massive amounts of debugging information. Its mostly
+useful to us hssf-developing geeks, but might be useful in tracking
+down problems. By default we turn this off because it results in
+massive performance degradation when fully turned on! Using it is
+simple. You need an hssflog.properties file (example listed below,
+those familiar with log4j can customize this as they wish). You can
+either put this in your home directory (or wherever the default
+directory is on windows which I suspect is c:\windows) or you can put
+it wherever you want and set the HSSF.log to the path ending in &quot;/&quot;
+(or &quot;\\&quot; on windows). If for any reason HSSF can't find it,
+you get no logging. If the log configuration dictates the logging be
+turned off, you get no logging.</p>
+<p>Here is an example hssflog.properties (actually its not an example
+its mine):
+<code># Set root category priority to DEBUG and its only appender to A1.
+log4j.rootCategory=DEBUG, A1
+  
+# A1 is set to be a ConsoleAppender. 
+log4j.appender.A1=org.apache.log4j.ConsoleAppender
+  
+# A1 uses PatternLayout.
+log4j.appender.A1.layout=org.apache.log4j.PatternLayout
+log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
+#uncomment below to change the level to WARN to disable debugging information.  This effectively turns off logging.
+#the default level is DEBUG (and changing it to DEBUG is the basically the same thing as leaving it commented out).
+#log4j.category.org.apache.poi=WARN</code></p>
+
+     </s3>
+                <s3 title="HSSF Developer's tools">
+
+<p>HSSF has a number of tools useful for developer's to debug/develop
+stuff using HSSF (and more generally XLS files). We've already
+discussed the app for testing HSSF read/write/modify capabilities;
+now we'll talk a bit about BiffViewer. Early on in the development of
+HSSF, it was decided that knowing what was in a record, what was
+wrong with it, etc. was virtually impossible with the available
+tools. So we developed BiffViewer. You can find it at
+org.apache.poi.hssf.dev.BiffViewer. It performs two basic
+functions and a derivative. 
+</p>
+<p>The first is &quot;biffview&quot;. To do this you run it (assumes
+you have everything setup in your classpath and that you know what
+you're doing enough to be thinking about this) with an xls file as a
+parameter. It will give you a listing of all understood records with
+their data and a list of not-yet-understood records with no data
+(because it doesn't know how to interpret them). This listing is
+useful for several things. For one you can look at the values and SEE
+what is wrong in quasi-English. For two, you can send the output to a
+file and compare it. 
+</p>
+<p>The second function is &quot;big freakin dump&quot;, just pass a
+file and a second argument matching &quot;bfd&quot; exactly. This
+will just make a big hexdump of the file. 
+</p>
+<p>Lastly, there is &quot;mixed&quot; mode which does the same as
+regular biffview, only it includes hex dumps of certain records
+intertwined. To use that just pass a file with a second argument
+matching &quot;on&quot; exactly.</p>
+<p>In the next release cycle we'll also have something called a
+FormulaViewer. The class is already there, but its not very useful
+yet. When it does something, I'll document it.</p>
+
+     </s3>
+                <s3 title="What's Next?">
+
+<p>This release contains code that supports &quot;internationalization&quot;
+or more accurately non-US/UK languages; however, it has not been
+tested with the new API changes (please help us with this). We've
+shifted focus a bit for this release in recognition of the
+international support we've gotten. We're going to focus on western
+European languages for our first beta. We're more than happy to
+accept help in supporting non-Western European languages if someone
+who knows what they're doing in this area is willing to pitch in!
+(There is next to no documentation on what is necessary to support
+such a move and its really hard to support a language you don't even
+know the alphabet too).</p>
+<p>This release of HSSF does not yet support Formulas. I've been
+focusing on the requests I've gotten in. That being said, if we get
+more user feedback on what is most useful first we'll aim for that.
+As a general principal, HSSF's goal is to support HSSF-Serializer
+(meaning an emphasis on write). We would like to hear from you! How
+are you using HSSF/POIFS? How would you like to use it? What features
+are most important first? 
+</p>
+<p>This release is near feature freeze for the 1.0-beta. All
+priorities refer to things we'll be adding in the next release
+(probably 2.0). The 1.0-beta is scheduled for release in the mid to
+late December timeframe. While its way to early to say when the
+2.0-beta will be released, my &quot;gut&quot; feeling is to aim for
+around March and have at least the first three items.</p>
+<p>Current list of priorities:</p>
+<ol>
+	<li>Helper class for fonts, etc.</li>
+	<li>Add Formulas.</li>
+	<li>Implement more record types (for other things....not sure
+	what this will mean yet).</li>
+	<li>Add more dummy checks (for when API user's do things they
+	&quot;can't&quot; do)</li>
+	<li>Add support for embedded graphics and stuff like that.</li>
+	<li>Create new adapter object for handling MulBlank, MulRk, Rk
+	records.</li>
+</ol>
+     </s3>
+                <s3 title="Changes">
+                                <s4 title="1.1.0">
+
+<ol>
+	<li>Created new event model</li>
+	<li>Optimizations made to HSSF including aggregate records for
+	values, rows, etc.</li>
+	<li>predictive sizing, offset based writing (instead of lots of
+	array copies)</li>
+	<li>minor re-factoring and bug fixes.</li>
+</ol>
+</s4>
+<s4 title="1.0.0">
+
+<ol>
+	<li>Minor documentation updates.</li>
+</ol>
+</s4>
+<s4 title="0.14.0">
+<ol>
+	<ol>
+		<li>Added DataFormat helper class and exposed set and get format
+		on HSSFCellStyle</li>
+		<li>Fixed column width apis (unit wise) and various javadoc on
+		the subject</li>
+		<li>Fix for Dimensions record (again)... (one of these days I'll
+		write a unit test for this ;-p).</li>
+		<li>Some optimization on sheet creation.</li>
+	</ol>
+</ol>
+</s4>
+<s4 title="0.13.0">
+<p>- NO WAY!</p>
+</s4>
+<s4 title="0.12.0">
+<ol>
+	<li>Added MulBlank, Blank, ColInfo</li>
+	<li>Added log4j facility and removed all sys.out type logging</li>
+	<li>Added support for adding font's, styles and corresponding
+	high level api for styling cells</li>
+	<li>added support for changing row height, cell width and default
+	row height/cell width.</li>
+	<li>Added fixes for internationalization (UTF-16 should work now
+	from HSSFCell.setStringValue, etc when the encoding is set)</li>
+	<li>added support for adding/removing and naming sheets.</li>
+</ol>
+</s4>
+<s4 title="0.11.0">
+<ol>
+	<li>Bugfix release. We were throwing an exception when reading
+	RKRecord objects.</li>
+</ol>
+</s4>
+<s4 title="0.10.0">
+<ol>
+	<li>Got continuation records to work (read/write)</li>
+	<li>Added various pre-support for formulas</li>
+	<li>Massive API reorganization, repackaging.</li>
+	<li>BiffViewer class added for validating HSSF &amp; POI and/or
+	HSSF Output.</li>
+	<li>Better API support for modification.</li>
+</ol>
+</s4>
+<s4 title="0.7 (and interim releases)">
+<ol>
+	<li>Added encoding flag to high and low level api to use utf-16
+	when needed (HSSFCell.setEncoding())</li>
+	<li>added read only support for Label records (which are
+	reinterpreted as LabelSST when written)</li>
+	<li>Broken continuation record implementation (oops)</li>
+	<li>BiffViewer class added for validating HSSF &amp; POI and/or
+	HSSF Output.</li>
+</ol>
+</s4>
+<s4 title="0.6 (release)">
+<ol>
+	<li>Support for read/write and modify.</li>
+	<li>Read only support for MulRK records (converted to Number when
+	writing) 
+	</li>
+</ol>
+</s4>
+</s3>
+</s2>
+
+</s1>
+</body>
+</document>

src/documentation/xdocs/hssf/index.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>HSSF</title>
+  <subtitle>Overview</subtitle>
+  <authors>
+   <person name="Andrew C. Oliver" email="acoliver@apache.org"/>     
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>     
+  </authors>
+ </header>
+
+ <body>
+ <s1 title="Overview">
+
+  <p>HSSF is the POI Project's pure Java implementation of the Excel '97(-2002) file format.</p>
+  <p>Please see the HOWTO for usage information.</p>
+  <p>TODO: turn this page into a meaningful summary.</p>
+
+  </s1>
+ </body>
+</document>

src/documentation/xdocs/hssf/use-case.xml

@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd"> 
+     
+<document>
+  <header>
+   <title>The New Halloween Document</title>
+   <authors>
+    <person email="marc.johnson@yahoo.com" name="Marc Johnson" id="MJ"/>
+   </authors>
+  </header>
+  <body>
+    <s1 title="HSSF Use Cases">
+    <s2 title="Use Case 1: Read existing HSSF">
+
+<p><strong>Primary Actor:</strong> HSSF client</p>
+<p><strong>Scope:</strong> HSSF</p>
+<p><strong>Level:</strong> Summary</p>
+<p><strong>Stakeholders and Interests:</strong></p>
+<ul>
+	<li>HSSF client- wants to read content
+	of HSSF file</li>
+	<li>HSSF - understands HSSF file</li>
+	<li>POI - understands underlying POI
+	file system</li>
+</ul>
+<p><strong>Precondition:</strong> None</p>
+<p><strong>Minimal Guarantee:</strong> None</p>
+<p><strong>Main Success Guarantee:</strong></p>
+<ol>
+	<li>HSSF client requests HSSF to read
+	a HSSF file, providing an InputStream
+	containing HSSF file in question.</li>
+	<li>HSSF requests POI to read the HSSF
+	file, passing the InputStream
+	object to POI (POI use case 1, read existing file system)</li>
+	<li>HSSF reads the &quot;Workbook&quot;
+	file (use case 4, read workbook entry)</li>
+</ol>
+<p><strong>Extensions:</strong></p>
+<p>2a. Exceptions
+thrown by POI will be passed on to the HSSF client.</p>
+</s2>
+    <s2 title="Use Case 2: Write HSSF file">
+
+<p><strong>Primary Actor:</strong> HSSF client</p>
+<p><strong>Scope:</strong> HSSF</p>
+<p><strong>Level:</strong> Summary</p>
+<p><strong>Stakeholders and Interests:</strong></p>
+<ul>
+	<li>HSSF client- wants to write file
+	out.</li>
+	<li>HSSF - knows how to write file
+	out.</li>
+	<li>POI - knows how to write file
+	system out.</li>
+</ul>
+<p><strong>Precondition:</strong></p>
+<ul>
+	<li>File has been
+	read (use case 1, read existing HSSF file) and subsequently modified
+	or file has been created (use case 3, create HSSF file)</li>
+</ul>
+<p><strong>Minimal Guarantee:</strong> None</p>
+<p><strong>Main Success Guarantee:</strong></p>
+<ol>
+	<li>HSSF client
+	provides an OutputStream to
+	write the file to.</li>
+	<li>HSSF writes
+	the &quot;Workbook&quot; to its associated POI file system (use case
+	5, write workbook entry)</li>
+	<li>HSSF
+	requests POI to write its file system out, using the OutputStream
+	obtained from the HSSF client (POI use case 2, write file system).</li>
+</ol>
+<p><strong>Extensions:</strong></p>
+<p>3a. Exceptions
+from POI are passed to the HSSF client.</p>
+
+</s2>
+    <s2 title="Use Case 3:Create HSSF file">
+
+<p><strong>Primary Actor:</strong> HSSF client</p>
+<p><strong>Scope:</strong> HSSF</p>
+<p>
+<strong>Level:</strong> Summary</p>
+<p><strong>Stakeholders and Interests:</strong></p>
+<ul>
+	<li>HSSF client- wants to create a new
+	file.</li>
+	<li>HSSF - knows how to create a new
+	file.</li>
+	<li>POI - knows how to creat a new
+	file system.</li>
+</ul>
+<p><strong>Precondition:</strong></p>
+<p><strong>Minimal Guarantee:</strong> None</p>
+<p><strong>Main Success Guarantee:</strong></p>
+<ol>
+	<li>HSSF requests
+	POI to create a new file system (POI use case 3, create new file
+	system)</li>
+</ol>
+<p><strong>Extensions:</strong>
+None</p>
+
+</s2>
+    <s2 title="Use Case 4: Read workbook entry">
+<p><strong>Primary Actor:</strong> HSSF</p>
+<p><strong>Scope:</strong> HSSF</p>
+<p>
+<strong>Level:</strong> Summary</p>
+<p><strong>Stakeholders and Interests:</strong></p>
+<ul>
+	<li>HSSF - knows how to read the
+	workbook entry</li>
+	<li>POI - knows how to manage the file
+	system.</li>
+</ul>
+<p><strong>Precondition:</strong></p>
+<ul>
+	<li>The file
+	system has been read (use case 1, read existing HSSF file) or has
+	been created and written to (use case 3, create HSSF file system;
+	use case 5, write workbook entry).</li>
+</ul>
+<p><strong>Minimal
+Guarantee:</strong> None</p>
+<p><strong>Main Success Guarantee:</strong></p>
+<ol>
+	<li>
+	HSSF requests POI for the &quot;Workbook&quot; file</li>
+	<li>POI returns
+	an InputStream for the file.</li>
+	<li>HSSF reads
+	from the InputStream provided by POI</li>
+	<li>HSSF closes
+	the InputStream provided by POI</li>
+</ol>
+<p><strong>Extensions:</strong></p>
+<p>3a. Exceptions
+thrown by POI will be passed on</p>
+</s2>
+    <s2 title="Use Case 5: Write workbook entry">
+
+
+<p><strong>Primary Actor:</strong> HSSF</p>
+<p><strong>Scope:</strong> HSSF</p>
+<p>
+<strong>Level:</strong> Summary</p>
+<p><strong>Stakeholders and Interests:</strong></p>
+<ul>
+	<li>HSSF - knows how to manage the
+	write the workbook entry.</li>
+	<li>POI - knows how to manage the file
+	system.</li>
+</ul>
+<p><strong>Precondition:</strong> 
+</p>
+<ul>
+	<li>Either an existing HSSF file has
+	been read (use case 1, read existing HSSF file) or an HSSF file has
+	been created (use case 3, create HSSF file).</li>
+</ul>
+<p><strong>Minimal Guarantee:</strong> None</p>
+<p><strong>Main Success Guarantee:</strong></p>
+<ol>
+	<li>HSSF
+	checks the POI file system directory for the &quot;Workbook&quot;
+	file (POI use case  8, read file system directory)</li>
+	<li>If &quot;Workbook&quot; is in the directory, HSSF requests POI to
+	replace it with the new workbook entry (POI use case 4, replace file
+	in file system). Otherwise, HSSF requests POI to write the new
+	workbook file, with the name &quot;Workbook&quot; (POI use case 6,
+	write new file to file system)</li>
+</ol>
+<p><strong>Extensions:</strong>None</p>
+</s2>
+
+</s1>
+</body>
+</document>

src/documentation/xdocs/index.xml

@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+  <header>
+    <title></title>
+    <authors>
+      <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
+    </authors>
+  </header>
+  
+  <body>
+    <s1 title="Purpose">
+      <p>The POI project aims to provide both the framework for porting and actual ports of file 
+            formats based on Microsoft's OLE 2 Compound Document Format (tm) to pure Java (tm). 
+           This includes all post-1997 MS Office (tm) file formats.
+      </p>
+      <p>
+         As a general policy we try to collaborate as much as possible with other projects to 
+         provide this functionality.  Examples include: <link href="http://xml.apache.org/cocoon">Cocoon</link> for 
+         which you'll soon find generators and serializers for our projects;
+         <link href="http://www.openoffice.org">Open Office.org</link> with whom we collaborate in documenting the 
+         XLS format; and <link href="http://jakarta.apache.org/lucene">Lucene</link> for which we'll soon have file 
+         format interpretors.  When practical, we donate components directly to those projects for POI-enabling them.
+      </p>
+      <s2 title="Why/when would I use POI">
+        <p>
+ We'll tackle this on a component level. POI refers to the whole project.
+        </p> 
+        <p>
+So why should you use POIFS or HSSF?
+        </p> 
+        <p>
+You'd use POIFS if you had a document written in OLE 2 Compound Document Format, probably written using MFC, that you needed to read in Java. Alternatively, you'd use POI to write OLE 2 Compound Document Format if you needed to inter-operate with software running on the Windows platform. We are not just bragging when we say that POIFS is the most complete and correct port of this file format to date!
+        </p> 
+        <p>
+You'd use HSSF if you needed to read or write an XLS (Excel) file using Java. You can also read and modify spreadsheets using this API, although right now writing is more mature.
+        </p> 
+      </s2>
+      
+      <s2 title="What does POI stand for?">
+        <p>
+POI stands for Poor Obfuscation Implementation. Why would we name our project such a derogatory name? Well, Microsoft's OLE 2 Compound Document Format is a poorly conceived thing. It is essentially an archive structured much like the old DOS FAT filesystem. Redmond chose, instead of using tar, gzip, zip or arc, to invent their own archive format that does not provide any standard encryption or compression, is not very appendable and is prone to fragmentation.
+        </p>
+      <p>
+Poi is also a Hawaiian delicacy that <link href="http://www.m-w.com">Merriam Webster's dictionary</link> defines as: "A Hawaiian food of taro root cooked, pounded, and kneaded to a paste and often allowed to ferment." This seemed strangely descriptive of the file format.  
+        </p>
+      <p>
+So if you like acronyms, then POI is an acronym.  If you hate them, then we just used the name of the food for our project.  If
+you wish to signify your love or hate for acronyms, use POI or Poi to refer to the project respectively.  
+      </p>
+      </s2>
+
+    </s1>
+
+
+    <s1 title="Components To Date">
+        <s2 title="Overview">
+             A common misconception is that POI writes Excel files.  POI is the name of the project.  POI contains several
+             components, one of which, HSSF, writes Excel files.  The following are components of the entire POI project
+             and a brief summary of their purpose.
+        </s2>
+        <s2 title="POIFS">
+             POIFS is the oldest and most stable part of the project.  It is our port of the OLE 2 Compound Document Format to
+             pure Java.  It supports both read and write functionality.  All of our components ultimately rely on it by 
+             definition.  Please see <link href="./poifs/index.html">the POIFS project page</link> for more information.
+        </s2>
+        <s2 title="HSSF">
+             HSSF is our port of the Microsoft Excel 97(-2002) file format (BIFF8) to pure Java.  It supports read and write 
+             capability.  Please see <link href="./hssf/index.html">the HSSF project page</link> for more information.
+        </s2>
+        <s2 title="HDF">
+             HDF is our port of the Microsoft Word 97 file format to pure Java.  It supports read and write capability.
+             Please see <link href="./hdf/index.html">the HDF project page for more information</link>.  This component is 
+             in the early stages of design.  Jump in!
+        </s2>
+
+     </s1>
+
+    <s1 title="What happened to the HSSF Serializer?">
+	The HSSF Serializer, which was part of our 1.0 release and last builds on 
+        <link href="http://www.sourceforge.net/projects/poi">Sourceforge</link>, has been donated to the Cocoon project.  We're
+        currently in the process of porting it over.
+    </s1> 
+
+    <s1 title="Contributing ">
+        <p>So you'd like to contribute to the project? Great! We need enthusiastic, hard-working, talented folks to help us on the project in several areas. The first is bug reports and feature requests! The second is documentation - we'll be at your every beck and call if you've got a critique or you'd like to contribute or otherwise improve the documentation. We could especially use some help documenting the HSSF file format! Last, but not least, we could use some binary crunching Java coders to chew through the convolution that characterizes Microsoft's file formats and help us port new ones to a superior Java platform!
+        </p>
+        <p>So if you're motivated, ready, and have the time, join the mail lists and we'll be happy to help you get started on the
+           project!
+        </p>
+
+
+    </s1>
+  </body>
+  <footer>
+    <legal>
+      Copyright (c) @year@ The Apache Software Foundation All rights reserved.
+      $Revision$ $Date$
+    </legal>
+  </footer>
+</document>

src/documentation/xdocs/license.xml

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>The POI Project Software License</title>
+  <authors>
+   <person name="Andrew C. Oliver" email="acoliver2@users.sourceforge.net"/>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>   
+  </authors>
+ </header>
+
+<body>
+<s1 title="POI Project Software License">
+<source><![CDATA[
+ / ========================================================================= 
+                                                                            
+                  The POI Project Software License,  Version 1.1            
+                            (based on APL 1.1)                              
+          Copyright (c) 2001 SuperLink Software, Inc. and Marcus Johnson    
+                            All rights reserved.                            
+                                                                            
+  ========================================================================= 
+                                                                            
+  Redistribution and use in source and binary forms,  with or without modi- 
+  fication, are permitted provided that the following conditions are met:   
+                                                                            
+  1. Redistributions of source code  must retain the above copyright notice 
+     notice, this list of conditions and the following disclaimer.          
+                                                                            
+  2. Redistributions  in binary  form  must  reproduce the  above copyright 
+     notice,  this list of conditions  and the following  disclaimer in the 
+     documentation and/or other materials provided with the distribution.   
+                                                                            
+  3. The end-user documentation  included with the redistribution,  if any, 
+     must include the following acknowlegement:                             
+                                                                            
+        "This product includes  software developed  by SuperLink            
+         Software, Inc. <www.superlinksoftware.com> and Marcus Johnson as   
+         well as other POI project <poi.sourceforge.net> contributers"      
+                                                                            
+     Alternately, this acknowlegement may appear in the software itself, if 
+     and wherever such third-party acknowlegements normally appear.         
+                                                                            
+  4. The names  "POI",  "HSSF", "SuperLink Software, Inc." and "Marcus      
+     Johnson"  must not be used  to endorse or promote  products derived    
+     from this  software without  prior  written  permission.  For  written 
+     permission, please contact <andyoliver at yahoo dot com>.              
+                                                                            
+  5. Products derived from this software may not be called "POI" nor may    
+     "POI" appear in their names without prior written permission of        
+     SuperLink Software, Inc.                                               
+                                                                            
+  THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES 
+  INCLUDING, BUT NOT LIMITED TO,  THE IMPLIED WARRANTIES OF MERCHANTABILITY 
+  AND FITNESS FOR  A PARTICULAR PURPOSE  ARE DISCLAIMED.  IN NO EVENT SHALL 
+  THE SUPERLINK SOFTWARE, INC., ANDREW C. OLIVER OR  THE   CONTRIBUTORS  TO 
+  THE POI PROJECT BE LIABLE  FOR ANY  DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+  EXEMPLARY, OR  CONSEQUENTIAL DAMAGES (INCLUDING,  BUT    NOT   LIMITED TO,
+  PROCUREMENT   OF   SUBSTITUTE  GOODS  OR  SERVICES; LOSS OF USE, DATA, OR 
+  PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND  ON ANY  THEORY OF 
+  LIABILITY,  WHETHER IN  CONTRACT, STRICT LIABILITY, OR   TORT  (INCLUDING 
+  NEGLIGENCE OR OTHERWISE)  ARISING  IN ANY  WAY  OUT OF  THE  USE OF  THIS 
+  SOFTWARE,  EVEN  IF  ADVISED  OF THE POSSIBILITY OF SUCH DAMAGE.          
+                                                                            
+  ========================================================================= 
+                                                                            
+  This software  consists of voluntary  contributions made  by many indivi- 
+  duals on behalf of  SuperLink Software, Inc.  For more information        
+  on the SuperLink Software, Inc, please see                                
+  <http://www.superlinksoftware.com/>.  For more information on the POI     
+  project see <www.sf.net/projects/poi>.                                    
+                                                                            
+  ========================================================================= /
+
+
+]]></source>
+</s1>
+</body>
+</document>

src/documentation/xdocs/livesites.xml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Live Sites using Poi</title>
+  <authors>
+   <person name="Donald Ball" email="balld@webslingerZ.com"/>
+   <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
+   <person name="Robin Green" email="greenrd@hotmail.com"/>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
+  </authors>
+ </header>
+ 
+ <body><s1 title="Live Sites using Poi">
+   <p>Here is a list of some of the web sites that are proudly using Poi 1.X (in no particular order):
+   </p>
+   <!--
+   <ul>
+    <li><link href=""></link></li>
+   </ul>
+  </s1>
+   -->
+  <p>
+    If you do not find your site here, make sure you tell us
+    (use the word &quot;Livesites&quot; in the email subject, confirm that
+    you want to be listed publicly, say which version of Poi, and do not
+    forget to tell us the URL).
+    We would like to see this list grow bigger every day :-)
+   </p>
+  </s1>
+ </body>
+</document>

src/documentation/xdocs/mail-archives.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Mail Archives</title>
+  <authors>
+   <person name="Robin Green" email="greenrd@hotmail.com"/>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>   
+  </authors>
+ </header>
+
+ <body>
+
+ <s1 title="Mailing List Archives">
+  <p>
+   There are a number of mailing list archives available.
+  </p>
+
+  <table>
+   <tr>
+    <td><strong>Poi-general-user</strong></td>
+    <td><strong>Poi-devel</strong></td>
+    <td><strong>Regularly updated?</strong></td>
+    <td><strong>Searchable?</strong></td>
+    <td><strong>Speed</strong></td>
+    <td><strong>Other features?</strong></td>
+   </tr>
+   <tr>
+    <td><link href="http://sourceforge.net/mailarchive/forum.php?forum_id=2802">
+    Sourceforge</link></td>
+    <td><link href="http://sourceforge.net/mailarchive/forum.php?forum_id=4380">
+    Sourceforge</link></td>
+    <td>Yes</td>
+    <td>Onsite, by subject/author/body</td>
+    <td>4/5</td>
+    <td>all Sourceforge features</td>
+   </tr>
+   <tr>
+    <td><link href="http://www.geocrawler.com/redir-sf.php3?list=poi-general-user">
+    GeoCrawler</link></td>
+    <td><link href="http://www.geocrawler.com/redir-sf.php3?list=poi-devel">
+    GeoCrawler</link></td>
+    <td>?</td>
+    <td>?</td>
+    <td>?</td>
+    <td>?</td>
+   </tr>   
+  </table>
+ </s1>
+
+</body>
+</document>

src/documentation/xdocs/mail-lists.xml

@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Mailing Lists</title>
+  <authors>
+   <person name="Robin Green" email="greenrd@hotmail.com"/>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>   
+  </authors>
+ </header>
+
+ <body><s1 title="Important Notice">
+   <p><strong>IMPORTANT: Before posting a question or problem to any mailing list,
+    </strong>please first look at the following resources in this order:</p>
+   <ol>
+    <li><connect href="faq.html">FAQs</connect></li>
+    <li><link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">ODP XML links</link>
+     - a wealth of general XML information.</li>
+    <li><connect href="mail-archives.html">Mailing list archives</connect> - 
+     a veritable goldmine of Poi-specific information - if you know where to look!</li>
+   </ol>
+
+   <p><strong>IMPORTANT:</strong> Careful postings please.
+    These are high-volume lists, so we all needs ways to help us all
+    work smarter.
+    See tips for <link href="contrib.html#tips">Contributing</link>
+   </p>
+  </s1>
+
+  <s1 title="Poi Users">
+   <p><link href="http://lists.sourceforge.net/lists/listinfo/poi-general-user">Subscribe</link>
+      <link href="http://lists.sourceforge.net/lists/listinfo/poi-general-user">Unsubscribe</link>
+   </p>
+
+   <p>The general list, for problems, bug reports, asking for advice on how
+    best to implement a site, comparisons with other frameworks, etc.
+    But don't forget to look in the FAQ first, please!</p>
+
+   <p><strong>This is also not an appropriate list for general Java questions.</strong>
+    Instead try <link href="news:comp.lang.java.help">news:comp.lang.java.help</link>
+    or <link href="http://hotdispatch.com/">http://hotdispatch.com/</link>, for
+    example.</p>
+    
+   <p><strong>This is not an appropriate list for general XML questions.</strong> 
+    Instead
+    look at the <link href="http://dmoz.org/">ODP</link> for 
+    <link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">XML/XSL links</link>
+    (such as the excellent <link href="http://www.zvon.org/xxl/XSLTutorial/Books/Book1/index.html">
+    XSL tutorial at Zvon.org</link>) or try the 
+    <link href="http://www.mulberrytech.com/xsl/">Mulberrytech XSL list</link>.</p>
+
+   <p><strong>IMPORTANT:</strong> If you are posting about a problem you are having
+    (as most people do), it will aid in finding a speedy resolution if you provide
+    full configuration details (especially the <strong>version number</strong>,
+    but also your operating system, JDK version, and servlet engine), and full details
+    of any errors encountered (including full error messages and stack traces).</p>
+
+   <p>Please also have some consideration for the other users on the list - this is a
+    busy list and we do not appreciate getting the exact same message posted impatiently
+    several times a day/week! Doing so is only likely to make your question answered more
+    slowly, or not at all, not faster.</p>
+  </s1>
+
+  <s1 title="Poi Dev">
+   <p><link href="http://lists.sourceforge.net/lists/listinfo/poi-devel">Subscribe</link>
+      <link href="http://lists.sourceforge.net/lists/listinfo/poi-devel">Unsubscribe</link>
+   </p>
+
+   <p>This list is for developers <strong>working on</strong> or wanting to work on
+    Poi itself (not developers merely working <strong>with</strong> Poi),
+    for code patches to Poi to be posted (please use <code>diff -u</code> format),
+    and for general Poi questions.</p>
+
+   <p>Note this is <strong>NOT</strong> for general Poi questions like "Why
+    isn't Poi working on my machine?" - 
+    please ask those sorts of questions on users list (after reading the
+    FAQ first, of course).</p>
+  </s1>
+
+  <s1 title="Related Mailing Lists">
+
+   <p>(See also <link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">
+    ODP XML links</link> for related websites.)</p>
+   <ul>
+    <li><link href="http://xml.apache.org/mail.html">XML Apache Projects</link> -
+      list of mailing lists for all the projects on xml.apache.org.</li>
+    <li>Some servlet engines have their own mailing lists for servlet-engine
+     configuration questions, such as
+     <link href="mailto:tomcat-user-subscribe@jakarta.apache.org">tomcat-user</link> (note it is "user"
+     and not "users").</li>
+   </ul>
+  </s1>
+ </body>
+</document>

src/documentation/xdocs/overview.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+  <header>
+    <title>Overview</title>
+    <authors>
+      <person id="AO" name="Andrew C. Oliver" email="acoliver2@users.sourceforge.net"/>
+    </authors>
+  </header>
+  
+  <body>
+    <s1 title="What is it?">
+      <p>The POI project is the master project for developing pure Java ports of those
+        file formats based on Microsoft's OLE 2 Compound Document Format.  OLE 2 
+        Compound Document Format is by Microsoft Office Documents, as well as 
+        programs using MFC property sets to serialize their document objects.
+      </p>
+    </s1>
+    <s1 title="Sub-Projects">
+      <p>
+        There following are ports, packages or components contained in the POI project.
+      </p>
+      <s2 title="POIFS">
+        <p>
+          <link href="poifs/index.html">POIFS</link> is the set of APIs 
+          for reading and writing OLE 2 Compound Document Formats using (only) Java.
+        </p> 
+      </s2>
+      
+      <s2 title="HSSF">
+        <p>
+          <link href="hssf/index.html">HSSF</link> is the set of APIs 
+ 	  for reading and writing Microsoft Excel 97(-XP) spreadsheet using (only) Java.
+        </p>
+      </s2>
+
+      <s2 title="HDF">
+        <p>
+          <link href="hdf/index.html">HDF</link>  is the set of APIs                   
+          for reading and writing Microsoft Word 97(-XP) spreadsheet using (only) Java.
+        </p>
+      </s2>
+
+      <s2 title="POI-Utils">
+        <p>
+          <link href="utils/index.html">POI-Utils</link> are general purpose artifacts
+	  from POI development that have not yet been implemented elsewhere.  We're 
+          always looking to donate these and maintain them as part of a general library
+          used in another project.  These are things we need to complete our mission but
+          are generally outside of it.  
+        </p>
+      </s2>
+    </s1>
+  </body>
+  <footer>
+    <legal>
+      Copyright (c) @year@ The Poi Project All rights reserved.
+      $Revision$ $Date$
+    </legal>
+  </footer>
+</document>

src/documentation/xdocs/patches.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+      
+        <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" 
+         "dtd/document-v10.dtd">
+      
+    <document><header><title>Patch Queue</title><authors><person email="greenrd@hotmail.com" name="Robin Green"/><person email="barozzi@nicolaken.com" name="Nicola Ken Barozzi"/></authors></header><body><s1 title="Introduction"><p>
+       This is an <strong>informal</strong> list - in chronological order -
+       of some of the noteworthy patches that have been posted
+       to the <code>developers</code> mailing list.
+       These patches are not (yet) part of the Poi project, but need reviewing for possible
+       inclusion. This system was instituted because, due to the large volume of mail and
+       the lack of time of the committers, some patches tended to get forgotten about. This
+       queue does not guarantee that any patch will be reviewed within a reasonable time frame,
+       but it does at least make them easier to find!
+      </p><p><strong>Reviewers wanted!</strong> - If you have time to review and/or test these patches,
+       we would be grateful for your time. Please post comments to the dev mailing lists.
+      </p><p>
+       Before submitting a patch, please read the page on <connect href="contrib.xml">Third-Party
+       Contributions</connect>. The preferred submission method for patches is:
+      </p><ul><li>Post to Poi developers list</li><li>Describe the patch, the reason for it and (if necessary) why this is important.</li><li>Generate the patch in <code>diff -u</code> format from CVS</li><li>Also generate a documentation patch or new file, if this is something that should be documented.
+       </li><li>Post as an attachment rather than inline (unless it is trivially small).</li></ul><p>Following the above guidelines will facilitate your patch being reviewed
+       and applied efficiently.</p></s1><s1 title="Patch Queue"><p><strong> [Under Construction] </strong> Archive links will be added later.
+       <strong>Please do not bother the patch submitters/authors</strong> without first reading the 
+        relevant post(s) in the <connect href="mail-archives.xml">mailing list archives.</connect></p><p>Vapourware will not be listed.</p><table><tr><th>id</th><th>Summary</th><th>Reviewer</th><th>Resolution</th><th>Status</th></tr></table><p>See also additional list of patches to be added in <connect href="todo.xml">To Do</connect>.
+      </p></s1></body></document>

src/documentation/xdocs/plan/POI10Vision.xml

@@ -0,0 +1,514 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>POI 1.0 Vision Document</title>
+  <authors>
+   <person name="Andrew C. Oliver" email="acoliver2@users.sourceforge.net"/>
+   <person name="Marcus W. Johnson" email="marcus_johnson27591@hotmail.com"/>   
+   </authors>
+ </header>
+
+ <body>
+
+ <s1 title="Preface"> 
+        <p> 
+		(21-Jan-02) While this document is just full of useful project 
+		introductory information and I do suggest those interested in getting
+		involved in the project read it, it is woefully out of date.
+	</p>
+	<p>
+		We deliberately allowed this document to run out of date because it 
+		is a good reflection of what the original vision was for POI 1.0.
+		You'll note that some of the terminology is not used in quite the same 
+		way any longer.  I've made some minor corrections where reading this
+		confused me.  An example: in some places this document may refer to
+		POI API instead of POIFS API.  When this vision was written we had 
+		an incomplete understanding of the project.  
+	</p>
+	<p>
+		Lastly, the scope of the project expanded dramatically near the end 
+		of the 1.0 cycle.  Our vision at the time was to focus merely on the
+		Excel port (having no idea how the project would grow or be received)
+		and provide the OLE 2 Compound Document port for others to port later
+		formats.  We now plan to spearhead these ports under the umbrella of 
+		the POI project.  So, you've been warned.  Read on, but just realize
+		that we had a fuzzy view of things to come, and hindsight is 20-20.
+	</p>
+	<p>
+		If I recall major holes were: a complete understanding of the format 
+		of OLE 2 Compound Document format, Excel file format, and exactly how
+		Cocoon 2 Serializers worked.  (that just about covers the whole range
+		huh?)
+	</p>
+ </s1>
+
+ <s1 title="1. Introduction">
+  <s2 title="1.1 Purpose of this document">
+	<p>
+		The purpose of this document is to
+		collect, analyze and define high-level requirements, user needs and
+		features of the HSSF Serializer for Cocoon 2 and related libraries.
+		The HSSF Serializer is a java class supporting the Serializer
+		interface from the Cocoon 2 project and outputting in a compatible
+		format of that used by the spreadsheet program Microsoft Excel '97.
+		The HSSF Serializer will be responsible for converting XML
+		spreadsheet-like documents into Excel-compatible XLS spreadsheets.
+	</p>
+  </s2>
+  
+
+  <s2 title="1.2 Project Overview">
+	<p>
+		Many web apps today hit a brick wall
+		when it comes to the user request that they be able to easily
+		manipulate their reports and data extracts in the popular Microsoft
+		Excel spreadsheet format. This often causes inferior technologies to be
+		chosen for the project simply because they easily support this
+		format. This project seeks to extend existing XML, Java and Apache
+		Cocoon 2 project technologies by: 	  
+	</p>
+	
+		<ul>
+			<li>
+				providing an extensible library
+				(POIFS) which reads/writes in a compatable format to OLE 2 Compound
+				Document Format (aka Structured Storage Format) for easy
+			  	implementation of other document types;
+			</li>
+			<li>
+				providing a library (HSSF) for
+				manipulating spreadsheet data and outputting it in a compatible
+				format to Microsoft Excel XLS format;
+			</li>
+			<li>
+				and providing a Cocoon 2
+				Serializer (HSSFSerializer) for serializing XML documents as
+				Excel-compatible spreadsheets.
+			</li>
+		</ul>
+	
+  </s2>
+ </s1>
+ <s1 title="2. User Description">
+   <s2 title="2.1 User/Market Demographics">
+	<p>
+		There are a number of enthusiastic
+		users of XML, UNIX and Java technology. Secondly, the Microsoft
+		solution for outputting Office Document formats often involves
+		actually manipulating the software as an OLE Server. This method
+		provides extremely low performance, extremely high overhead and is
+		only capable of handing one document at a time. 
+	</p>
+	<ol>
+		<li>
+		Our intended audience for the HSSF
+		Serializer portion of this project are developers writing reports or
+		data extracts in XML format. 
+		</li>
+		<li>
+		Our intended audience for the HSSF
+		library portion of this project is ourselves as we are developing
+		the serializer and anyone who needs to write to Excel spreadsheets
+		in a non-XML Java environment or who has specific needs not
+		addressed by the Serializer.
+		</li>
+		<li>
+		Our intended audience for the
+		&quot;POIFS&quot; OLE 2 Compound Document format reader/writer is
+		ourselves as we are writing the HSSF library and secondly, anyone
+		wishing to provide other libraries for reading/writing OLE 2
+		Compound Document Format in Java.
+		</li>
+	</ol>
+   </s2>
+   <s2 title="2.2. User environment">
+	<p>
+		The users of this software shall be
+		developers in a Java environment on any Operating System or power
+		users who are capable of XML document generation/deployment.		
+	</p>
+   </s2>
+   <s2 title="2.3. Key User Needs">
+	<p>
+		The OLE 2 Compound Document format is
+		undocumented for all practical purposes and cryptic for all
+		impractical purposes. Developer needs in this area include
+		documentation and an easy to use library for reading and writing in
+		this format without requiring the developer to have intimate
+		knowledge of the format. 		
+	</p>
+	<p>
+		There is currently no good way to write
+		to Microsoft Excel documents from Java or from a non-Microsoft
+		Windows based platform for that matter. Developers need an easy to
+		use library that supports a reasonable feature set and allows
+		seperation of data from formatting/stylistic concerns.
+	</p>
+	<p>
+		There is currently no good way to
+		transform XML data to Microsoft Excel. Apache's Cocoon 2 project
+		supplies a complete framework for XML, but nothing for outputting in
+		Excel's XLS format. Developers and power users alike need a simple
+		method to output XML documents to Excel through server-side
+		processing.
+	</p>
+	
+
+   </s2>
+   <s2 title="2.4. Alternatives and Competition">
+	<p>
+		The alternative to this project is to
+		buy the $10,000 Formula 1 library (<link href="http://www.tidestone.com/">www.tidestone.com</link>)
+		and accept its crude api and limitations. As a second alternative,
+		give up XML and write Visual Basic code on a Microsoft Windows based
+		Environment or output in Microsoft's beta and primarily undocumented
+		XML for office format.
+	</p>
+   </s2>
+ </s1>
+ <s1 title="3. Project Overview">
+   <s2 title="3.1. Project Perspective">
+	<p>
+		The produced code shall be licensed by
+		the Apache License as used by the Cocoon 2 project and maintained on
+		a project page until such time as the Cocoon 2 developers accept it
+		as a donation (at which time the copyright will be turned over to
+		them).	
+	</p>
+   </s2>
+   <s2 title="3.2. Project Position Statement">
+	<p>
+		For developers on a Java and/or XML
+		environment this project will provide all the tools necessary for
+		outputting XML data in the Microsoft Excel format. This project seeks
+		to make the use of Microsoft Windows based servers unnecessary for
+		file format considerations and to fully document the OLE 2 Compound
+		Document format. The project aims not only to provide the tools for
+		serializing XML to Excel's file format and the tools for writing to
+		that file format from Java, but also to provide the tools for later
+		projects to convert other OLE 2 Compound Document formats to pure
+		Java APIs.
+	</p>
+   </s2>
+   <s2 title="3.3. Summary of Capabilities">
+	<p>
+		HSSF Serializer for Apache Cocoon 2
+	</p>
+	<table>
+		<tr>
+			<td>
+				Benefit
+			</td>
+			<td>
+				Supporting Features
+			</td>
+		</tr>
+		<tr>
+			<td>
+				Standard XML tag language for sheet data
+			</td>
+			<td>
+				Serializer will transform documents utilizing a defined tag
+				language
+			</td>
+		</tr>
+		<tr>
+			<td>
+				Utilize XML to output in Excel
+			</td>
+			<td>
+				Serializer will output in Excel
+			</td>
+		</tr>
+		<tr>
+			<td>
+				Java API to output in Excel on any platform
+			</td>
+			<td>
+				The project will develop an API that outputs in Excel using
+				pure Java.
+			</td>
+		</tr>
+		<tr>
+			<td>
+				Make it easy for developers to port other OLE 2 Compound
+				Document-based formats to Java.
+			</td>
+			<td>
+				The POIFS library will contain both a high-level abstraction
+				along with low-level constructs. The project will fully document
+				the OLE 2 Compound Document Format.
+			</td>
+		</tr>
+	</table>   
+   </s2>
+   <s2 title="3.4. Assumptions and Dependencies">
+	<ul>
+		<li>
+			The HSSF Serializer will run on
+			any Java 2 supporting platform with Apache Cocoon 2 installed along
+			with the HSSF and POIFS APIs.
+		</li>
+		<li>
+			The HSSF API requires a Java 2
+			implementation and the POI API.
+		</li>
+		<li>
+			The POIFS API requires a Java 2
+			implementation.
+		</li>
+	</ul>	
+   </s2>
+ </s1>
+ <s1 title="4. Project Features">
+	<p> 
+		The POIFS API will include:
+	</p>
+	<ul>
+		<li>
+			Low level structures representing
+			the structures in a POI filesystems.
+		</li>
+		<li>
+			A low-level API for
+			creating/manipulating POI filesystems.
+		</li>
+		<li>
+			A set of high level interfaces
+			abstracting the user from the POI filesystem constructs and
+			representing it as a standard filesystem (Files, directories, etc)
+		</li>
+	</ul>	
+	<p>
+		The HSSF API will include:
+	</p>
+	<ul>
+		<li>
+			Low level structures representing
+			the structures in an Excel file.
+		</li>
+		<li>
+			A low-level API for creating and
+			manipulating Excel files and writing them into POI filesystems.
+		</li>
+		<li>
+			A high level model and style
+			interface for manipulating spreadsheet data without knowing anything
+			about the Excel format itself.
+		</li>
+	</ul>	
+   <s2 title="4.1 POI Filesystem API">
+	<p>
+		The POI Filesystem API includes:
+	</p>
+	<ul>
+		<li>An implementation of Big Blocks</li>
+		<li>An implementation of Small Blocks</li>
+		<li>An implementation of Header Blocks</li>
+		<li>An implementation of Block Allocation Tables</li>
+		<li>An implementation of Property Sets</li>
+		<li>An implementation of the POI 
+		filesystem including functions to get and set the above constructs;
+		compound functions for reading/writing files/directories.
+		</li>
+		<li>An abstraction of the POI
+		filesystem providing interfaces representing Files, Directories,
+		FileSystems in normal terminology and encapulating the above
+		constructs.
+		</li>
+		<li>Full documentation of the POI file
+		format.
+		</li>
+		<li>Full documentation of the APIs and
+		interfaces provided through Javadoc, user documentation (aimed at
+		developers using the APIs)
+		</li>
+		<li>Examples aimed at teaching the
+		user to write code using POI. (titled: recipes for POI)
+		</li>
+		<li>Performance specifications.
+		(Example POI filesystems rated by some measure of complexity along
+		with system specifications and execution times for given operations)
+		</li>
+	</ul>
+   </s2>
+   <s2 title="4.2 HSSF API">
+	<p>
+		The HSSF API includes:
+	</p>
+	<ul>
+		<li>An implementation of Record
+		(binary 2 byte type followed by 2 byte size (n) followed by n bytes)</li>
+		<li>Implementations of many standard
+		record types mapping the data bytes to fields along with methods to
+		reserialize those fields</li>
+		<li>An implementation of the HSSF File
+		including functions to get/set the above constructs, create a blank
+		file with the minimum required record types and mappings between
+		getting/setting data and style in a workbook to the creation of
+		record types, and read HSSF files.</li>
+		<li>An abstraction of the HSSF file
+		format providing interfaces representing the HSSF File, HSSF
+		Workbook, HSSF Sheet, HSSF Column, HSSF Formulas in a manner
+		seperating the data from the styling and encapsulating the above
+		constructs.</li>
+		<li>Full documentation of the HSSF
+		file format (which will be a subset of the Excel '97 File format).
+		This must be done with care for legal reasons.</li>
+		<li>Full documentation of the APIs and
+		interfaces provided through Javadoc, user documentation (aimed at
+		developers using the apis).</li>
+		<li>Examples aimed at teaching
+		developers to use the APIs. 
+		</li>
+		<li>Performance specifications.
+		(Example files rated by some measure of complexity along with system
+		specifications and execution times for given operations - possibly
+		the same files used for POI's tests)</li>
+	</ul>
+   </s2>
+   <s2 title="4.3 HSSF Serializer">
+	<p>
+		The HSSF Serializer subproject:
+	</p>
+	<ul>
+		<li>A class supporting the Cocoon 2
+		Serializer Interface.</li>
+		<li>An interface between the SAX
+		events and the HSSF APIs.</li>
+		<li>A specified tag language for using
+		with the Serializer.</li>
+		<li>Documentation on the tag language
+		for the HSSF Serializer</li>
+		<li>Normal javadocs.</li>
+		<li>Example XML files</li>
+		<li>Performance specifications.
+		(Example XML docs and stylesheets rated by some measure of
+		complexity along with system specifications and execution times)</li>
+	</ul>	
+   </s2>
+ </s1>
+ <s1 title="5. Other Product Requirements">
+   <s2 title="5.1. Applicable Standards">
+	<p>
+		All Java code will be 100% pure Java.
+	</p>
+   </s2>
+   <s2 title="5.2. System Requirements">
+	<p>
+		The minimum system requirements for POIFS are:
+	</p>
+	<ul>
+		<li>64 Mbytes memory</li>
+		<li>Java 2 environment</li>
+		<li>Pentium or better processor (or equivalent on other platforms)</li>
+	</ul>	
+	<p>
+		The minimum system requirements for HSSF are:
+	</p>
+	<ul>
+		<li>64 Mbytes memory</li>
+		<li>Java 2 environment</li>
+		<li>Pentium or better processor (or equivalent on other platforms)</li>
+		<li>POIFS API</li>
+	</ul>	
+	<p>
+		The minimum system requirements for the HSSF Serializer are:
+	</p>
+	<ul>
+		<li>64 Mbytes memory</li>
+		<li>Java 2 environment</li>
+		<li>Pentium or better processor (or equivalent on other platforms)</li>
+		<li>Cocoon 2</li>
+		<li>HSSF API</li>
+		<li>POI API</li>
+	</ul>	
+   </s2>
+   <s2 title="5.3. Performance Requirements">
+	<p>
+		All components must perform well enough
+		to be practical for use in a webserver environment (especially
+		Cocoon2/Tomcat/Apache combo)
+	</p>
+   </s2>
+   <s2 title="5.4. Environmental Requirements">
+	<p>
+		The software will run primarily in
+		developer environments. We should make some allowances for
+		not-highly-technical users to write XML documents for the HSSF
+		Serializer. All other components will assume intermediate Java 2
+		knowledge. No XML knowledge will be required except for using the
+		HSSF Serializer. As much documentation as is practical shall be
+		required for all components as XML is relatively new, and the
+		concepts introduced for writing spreadsheets and to POI filesystems
+		will be brand new to Java and many Java developers.
+	</p>
+   </s2>
+ </s1>
+ <s1 title="6. Documentation Requirements">
+   <s2 title="6.1 POI Filesystem">
+	<p>
+		The filesystem as read and written by
+		POI shall be fully documented and explained so that the average Java
+		developer can understand it.
+	</p>
+   </s2>
+   <s2 title="6.2. POI API">
+	<p>
+		The POI API will be fully documented
+		through Javadoc. A walkthrough of using the high level POI API shall
+		be provided. No documentation outside of the Javadoc shall be
+		provided for the low-level POI APIs.	
+	</p>
+   </s2>
+   <s2 title="6.3. HSSF File Format">
+	<p>
+		The HSSF File Format as implemented by
+		the HSSF API will be fully documented. No documentation will be
+		provided for features that are not supported by HSSF API that are
+		supported by the Excel 97 File Format. Care will be taken not to
+		infringe on any &quot;legal stuff&quot;.	
+	</p>
+   </s2>
+   <s2 title="6.4. HSSF API">
+	<p>
+		The HSSF API will be documented by
+		javadoc. A walkthrough of using the high level HSSF API shall be
+		provided. No documentation outside of the Javadoc shall be provided
+		for the low level HSSF APIs.	
+	</p>
+   </s2>
+
+   <s2 title="6.5. HSSF Serializer">
+	<p>
+		The HSSF Serializer will be documented
+		by javadoc. 	
+	</p>
+   </s2>
+
+   <s2 title="6.6 HSSF Serializer Tag language">
+	<p>
+		The XML tag language along with
+		function and usage shall be fully documented. Examples will be
+		provided as well.
+	</p>
+   </s2>
+ </s1>
+ <s1 title="7. Terminology">
+   <s2 title="7.1 Filesystem">
+	<p>
+		filesystem shall refer only to the POI formatted archive.
+	</p>
+   </s2>
+   <s2 title="7.2 File">
+	<p>
+		file shall refer to the embedded data stream within a 
+		POI filesystem. This will be the actual embedded document. 
+	</p>
+   </s2>
+ </s1>
+</body>
+</document>
+

src/documentation/xdocs/plan/book.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
+
+<book software="Poi Project" 
+      title="Poi Project planning" 
+      copyright="@year@ Poi Project">
+
+  <menu label="Navigation">
+    <menu-item label="Main" href="../index.html"/>
+  </menu>
+
+  <menu label="Planning Documents">
+    <menu-item label="Release Plan" href="POI10Vision.html"/>
+  </menu>
+</book>
+
+

src/documentation/xdocs/plan/index.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Planning Documentation</title>
+  <subtitle>Overview</subtitle>
+  <authors>
+   <person name="David Crossley" email="crossley@apache.org"/>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>     
+  </authors>
+ </header>
+
+ <body>
+ <s1 title="Overview">
+
+  <p>This is a collection of notes to assist with long-term planning and
+   development.
+  </p>
+
+  <p>There is much discussion of issues and research topics (RT) threads on
+   the <code>dev</code> mailing list (and elsewhere). However, details
+   get lost in the sheer volume. This is the place to document the summary of
+   discussions on some key topics. Some new and complex capabilities will take
+   lots of design and specification before they can be implemented.
+  </p>
+
+  <p>Another use for this collection of notes is as a place to quickly store
+   a snippet from an email discussion or even a link to a discussion thread.
+   The concepts can then be fleshed-out over time.
+  </p>
+
+  <p>Anyone can participate in this process. Please get involved in discussion
+   on <code>dev</code> and contribute patches for these summary planning
+   documents via the normal <link href="../contrib.html">contribution</link>
+   process.
+  </p>
+
+  <p>These planning documents are intended to be concise notes only. They are
+   also ever-evolving, because as issues are addressed these notes will be
+   revised.
+  </p>
+ </s1>
+
+ <s1 title="Topics and Issues">
+
+  <ul>
+   <li><link href="release.html">Release Plan</link>
+    - major things to do before the 2.0 release</li>
+   <li><link href="doc.html">Documentation</link>
+    - revisions and additions are required</li>
+   <li>See the general <link href="../todo.html">To Do</link> list 
+    and the <code>dev</code> email archives for other issues</li>
+  </ul>
+ </s1>
+
+ </body>
+</document>

src/documentation/xdocs/plan/release.xml

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Release Plan 2.0</title>
+  <subtitle>Planning Documentation</subtitle>
+  <authors>
+   <person name="David Crossley" email="crossley@apache.org"/>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>   
+  </authors>
+ </header>
+
+ <body>
+ <s1 title="Preparation for release of Poi">
+   <p>Todo</p>
+<!-- NKB todo
+  <p>The 2.0 final release is scheduled for the end of November 2001.
+  </p>
+
+  <p>
+   The following is extracted from the thread
+   [C2]: Release Candidate 2 ... 2001-10-29
+  </p>
+
+<source><![CDATA[
+> The question is now, what has to be done until then?
+>
+> 1) We have many open bugs in bugzilla. These must be reviewed
+>    and then solved (or declared invalid etc).
+>
+> 2) Documentation updates (this area lacks most)
+>    We could move this to the final release.
+Documentation must be happening all the time, and not left
+until last.
+
+> 3) Decide what to backport from the 2.1 head.
+>    I'm +1 on removing the CodeFactories completly in 2.0, too.
+>    This would avoid any backcompatibility problems.
+>
+> 4) Layout the distribution
+>    This is a point we haven't discussed yet. Currently our
+>    distribution is a mixture of a source and a binary one.
+>    We deliver the source and a compiled version, but in order
+>    to run Cocoon, the user has to build a war file.
+>    I propose to split this: one source distribution which is
+>    similar to the current one but without the precompiled
+>    cocoon jar and a binary distribution containing only the
+>    war file. This war file should work in most servlet engines,
+>    perhaps not in all.
+>
+> So anything missing here?
+
+5) Ensure that licensing requirements have been met.
+  update jars.xml, ensure proper banner in *.java header,
+  verify the current LICENSE* files, ensure that external
+  components have suitable licensing requirements.
+]]></source>
+-->
+ </s1>
+
+ </body>
+</document>

src/documentation/xdocs/poifs/book.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
+
+<book software="Poi Project" 
+      title="PoiFS" 
+      copyright="@year@ Poi Project">
+
+  <menu label="Navigation">
+    <menu-item label="Main" href="../index.html"/>
+  </menu>
+
+</book>
+
+

src/documentation/xdocs/poifs/html/POIFSFormat.html

@@ -0,0 +1,837 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+    <HEAD>
+        <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
+        <TITLE></TITLE>
+        <META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Linux)">
+        <META NAME="AUTHOR" CONTENT=" ">
+        <META NAME="CREATED" CONTENT="20010728;10223600">
+        <META NAME="CHANGEDBY" CONTENT="Marc Johnson">
+        <META NAME="CHANGED" CONTENT="20010810;13415800">
+        <STYLE>
+	    <!--
+		@page { margin-left: 1.25in; margin-right: 1.25in; margin-top: 1in; margin-bottom: 1in }
+		H1 { margin-bottom: 0.08in; font-size: 16pt }
+		TD P { margin-bottom: 0.08in }
+		H2 { margin-bottom: 0.08in; font-size: 14pt; font-style: italic }
+		H3 { margin-bottom: 0.08in }
+		H4 { margin-bottom: 0.08in; font-size: 11pt; font-style: italic }
+		P { margin-bottom: 0.08in }
+	    -->
+        </STYLE>
+    </HEAD>
+    <BODY>
+        <H1>POI Filesystem format</H1>
+        <H2>Introduction</H2>
+        <P STYLE="margin-bottom: 0in; font-weight: medium">
+            The POI file format is essentially an archive wrapper
+            around files. It is intended to mimic a filesystem. For
+            the remainder of this document it is referred to as a
+            filesystem in order to avoid confusion with the
+            &quot;files&quot; it contains.
+        </P>
+        <P STYLE="margin-bottom: 0in; font-weight: medium; text-decoration: none">
+            POI filesystems are compatible with those document formats
+            used by a well-known software company's popular office
+            productivity suite and programs outputting compatible
+            data. Because the POI filesystem does not provide
+            compression, encryption or any other worthwhile feature,
+            its not a good choice unless you require interoperability
+            with these programs.
+        </P>
+        <P STYLE="margin-bottom: 0in; font-weight: medium">
+            The POI filesystem does not encode the documents
+            themselves. For example, if you had a word processor file
+            with the extension &quot;.doc&quot;, you would actually
+            have a POI filesystem with a document file archived inside
+            of the filesystem.
+        </P>
+        <H2>Document Conventions</H2>
+        <P STYLE="margin-bottom: 0in">
+            This document utilizes the numeric types as described by
+            the Java Language Specification, which can be found at
+            java.sun.com. In short:
+        </P>
+        <UL>
+            <LI>
+                <P STYLE="margin-bottom: 0in">
+                    a byte is an 8 bit signed integer ranging from
+                    (-128) to 127.
+                </P>
+            </LI>
+            <LI>
+                <P STYLE="margin-bottom: 0in">
+                    a short is a 16 bit signed integer ranging from
+                    (-32768) to 32767
+                </P>
+            </LI>
+            <LI>
+                <P STYLE="margin-bottom: 0in">
+                    an int is a 32 bit signed integer ranging from
+                    (-2.14e+9) to 2.14e+9
+                </P>
+            </LI>
+            <LI>
+                <P STYLE="margin-bottom: 0in">
+                    a long is a 64 bit signed integer ranging from
+                    (-9.22e+18) to 9.22e+18
+                </P>
+            </LI>
+        </UL>
+        <P STYLE="margin-bottom: 0in">
+            The Java Language Specification spells out a number of
+            other types that are not referred to by this document.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            Where this document makes references to &quot;endian
+            conversion&quot; it is referring to the byte order of
+            stored numbers. Numbers in &quot;little-endian order&quot;
+            are stored with the LEAST significant byte first. In order
+            to properly read a short, for example, you'd read two
+            bytes and then shift the second byte 8 bits to the left
+            before performing an <CODE>or</CODE> operation to it
+            against the first byte while stripping the
+            &quot;sign&quot; from the first byte. The following code
+            illustrates this method:
+        </P>
+        <P STYLE="text-decoration: none">
+            <FONT FACE="Courier, monospace"><FONT
+            SIZE=2><B>public int getShort (byte[ ] rec)
+            {</B></FONT></FONT>
+        </P>
+        <P>
+            <FONT FACE="Courier, monospace"><FONT SIZE=2><B>return (
+            (rec[1] &lt;&lt; 8) | (rec[0] &amp; 0xff)
+            );</B></FONT></FONT>
+        </P>
+        <P>
+            <FONT FACE="Courier, monospace"><FONT
+            SIZE=2><B>}</B></FONT></FONT>
+        </P>
+        <H2>Filesystem Introduction</H2>
+        <P STYLE="margin-bottom: 0in">
+            POI filesystems are essentially normal files stored on a
+            Java-compatible platform's native filesystem. They are
+            identified by names ending in a four character identifier
+            noting what type of data they contain. For example, a file
+            ending in &quot;.xls&quot; would likely contain
+            spreadsheet data, and a file ending in &quot;.doc&quot;
+            would probably contain a word processing document. POI
+            filesystems are called &quot;filesystem&quot;, because
+            they contain multiple embedded files in a manner similar
+            to traditional filesystems. Along functional lines, it
+            would be more accurate to call these POI archives.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            POI filesystems do not provide encryption, compression, or
+            any other feature of a modern archive and are therefore a
+            poor choice for implementing new file formats. It is
+            suggested that POI filesystems are most useful for
+            interoperability with legacy applications that use a
+            compatible file format.
+        </P>
+        <H2>Filesystem Walkthrough</H2>
+        <P STYLE="margin-bottom: 0in">
+            This is a walkthrough of a POI filesystem and how it is
+            put together. It is not intended to give a concise
+            description but to give a &quot;big picture&quot; of the
+            general structure and how it's interpreted.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            A POI filesystem begins with a <A
+            HREF="HeaderBlock"><B><I>header</I></B></A>.  This header
+            identifies locations in the file by function and provides
+            a sanity check identifying a native filesystem file as
+            indeed a POI filesystem.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            The first 64 bits of the header compose a <B><I>magic
+            number identifier.</I></B> This identifier tells the
+            client software that this is indeed a POI filesystem and
+            that it should be treated as such. This is a &quot;sanity
+            check&quot; to make sure this is a POI filesystem and not
+            some other format. The header also contains an <B><I>array
+            of block numbers</I></B>.  These block numbers refer to
+            blocks in the file. When these blocks are read together
+            they form the <A HREF="#BAT"><B><I>Block Allocation
+            Table</I></B></A>. The header also contains a pointer to
+            the first element in the <A
+            HREF="#PropertyTable"><B><I>property table</I></B></A>
+            also known as the <A HREF="RootEntry"><B><I>root
+            element</I></B></A>, and a pointer to the <B>small Block
+            Allocation Table (SBAT)</B>.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            The <A HREF="#BAT"><B><I>block allocation
+            table</I></B></A> or <B><I>BAT</I></B>, along with the <A
+            HREF="#PropertyTable"><B><I>property table</I></B></A>
+            specify which blocks in the filesystem belong to which
+            files. It is somewhat hard to conceptualize the Block
+            Allocation Table at first.  The block allocation table is
+            essentially an array of integers that point at each
+            other. These elements form chains.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            To read the <A HREF="#BAT"><B><I>block allocation
+            table</I></B></A> you must first read the <B><I>start
+            block </I></B>of the file from the <A
+            HREF="#PropertyTable"><B><I>property
+            table</I></B></A>. This is both your index for the next
+            element in the <B><I>BAT </I></B>array as well as the
+            index of the first block in your file.  For instance: if
+            the <B><I>start block</I></B> from your file's property is
+            0 then you read block 0 (the first block after the header)
+            from your filesystem as the first block of your file. You
+            also read element 0 from the <B><I>BAT array</I></B>.
+            Supposing this element has a value equal to 2, you'd read
+            block 2 from your filesystem as the next block of your
+            file and element 2 from your <B><I>BAT array</I></B>.
+            This will be covered further later in this document.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            The <A HREF="#PropertyTable"><B><I>Property
+            Table</I></B></A> is essentially the directory structure
+            for the filesystem. It consists of the name of the file or
+            directory, its <B><I>start block</I></B> in both the
+            filesystem and <B><I>BAT</I></B>, and its actual size.
+            The first property in the <A
+            HREF="#PropertyTable">property table</A> is the <A
+            HREF="RootEntry"><B><I>root element</I></B></A>. Its real
+            purpose is to hold the start block for the <B><I>small
+            blocks.</I></B>
+        </P>
+        <H3>Filesystem Structure</H3>
+        <P STYLE="margin-bottom: 0in; font-weight: medium">
+            All values in the POI filesystem are stored in
+            &quot;little-endian&quot; order, meaning you must reverse
+            the order of the bytes before assigning them to
+            variables. Assume the values you see below are originally
+            stored backwards.
+        </P>
+        <P STYLE="margin-bottom: 0in; font-weight: medium">
+            The POI filesystem is divided into 512 byte blocks. Each
+            block has an implicit block-type. The order and
+            description of these is described below.
+        </P>
+        <A NAME="HeaderBlock"><H3>Header Block</H3></A>
+        <P STYLE="margin-bottom: 0in; font-weight: medium">
+            The POI filesystem begins with a <B><I>header
+            block</I></B>. The first 64 bits of the header form a long
+            <B><I>file type id</I></B> or <B><I>magic number
+            identifier</I></B> of
+            <CODE>0xE11AB1A1E011CFD0L</CODE>. This is basically a
+            sanity check. If this isn't the first thing in the header
+            (and consequently the filesystem) then this is not a POI
+            filesystem and should be read with some other library.
+        </P>
+        <P STYLE="margin-bottom: 0in; font-weight: medium">
+            It's important to know the most important parts of the
+            header. These are discussed in the rest of this
+            section.
+        </P>
+        <H4>BATs</H4>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x2c</B> is an int specifying the number of
+            elements in the <B><I>BAT array</I></B>. The array at
+            <B>0x4c</B> an array of ints. This array contains the
+            indices of every block in the <A HREF="#BAT">Block
+            Allocation Table</A>.
+        </P>
+        <H4><I><B>XBATs</B></I></H4>
+        <P STYLE="margin-bottom: 0in">
+            Very large POI archives may have more blocks than can be
+            addressed by the BAT blocks enumerated in the header
+            block. How large? Well, the BAT array in the header can
+            contain up to 109 BAT block indices; each BAT block
+            references up to 128 blocks, and each block is 512 bytes,
+            so we're talking about 109 * 128 * 512 = 6.8MB. That's a
+            pretty respectable document! But, you could have much more
+            data than that, and in today's world of cheap gigabyte
+            drives, why not? So, the BAT may be extended in that
+            event. The integer value at offset <B>0x44</B> of the
+            header is the index of the first <B><I>extended BAT (XBAT)
+            block</I></B>. At offset <B>0x48</B> of the header, there
+            is an int value that specifies how many XBAT blocks there
+            are. The XBAT blocks begin at the specified index into the
+            array of blocks making up the POI filesystem, and continue
+            in sequence for the specified count of XBAT blocks.
+	</p>
+	<p>
+	    Each XBAT block contains the indices of up to 128 BAT
+            blocks, so the document size can be expanded by another
+            8MB for each XBAT block. The BAT blocks indexed by an XBAT
+            block are appended to the end of the list of BAT blocks
+            enumerated in the header block. Thus the BAT blocks
+            enumerated in the header block are BAT blocks 0 through
+            108, the BAT blocks enumerated in the first XBAT block are
+            BAT blocks 109 through 236, the BAT blocks enumerated in
+            the second XBAT block are BAT blocks 237 through 364, and
+            so on.
+        </P>
+	<p>
+	    Through the use of XBAT blocks, the limit on the overall
+	    document size is that imposed by the 4-byte block indices;
+	    if the indices are unsigned ints, the maximum file size is
+	    2 terabytes, 1 terabyte if the indices are treated as
+	    signed ints. Either way, I have yet to see a disk drive
+	    large enough to accommodate such a file on the shelves at
+	    the local office supply stores.
+	</p>
+        <H4>SBATs</H4>
+        <P STYLE="margin-bottom: 0in">
+            If a file contained in a POI archive is smaller than 4096
+            bytes, it is stored in small blocks. Small blocks are 64
+            bytes in length and are contained within big blocks, up to
+            8 to a big block. As the main BAT is used to navigate the
+            array of big blocks, so the <B><I>small block allocation
+            table</I></B> is used to navigate the array of small
+            blocks. The SBAT's start block index is found at offset
+            <B>0x3C</B> of the header block, and remaining blocks
+            constituting the SBAT are found by walking the main BAT as
+            if it were an ordinary file in the POI filesystem (this
+            process is described below).
+        </P>
+        <H4>Property Table Start Index</H4>
+        <P STYLE="margin-bottom: 0in">
+            An integer at address <B>0x30</B> specifies the start
+            index of the <A HREF="#PropertyTable">property
+            table</A>. This integer is specified as a
+            <B><I>&quot;block index&quot;. </I></B>The <A
+            HREF="#PropertyTable">Property Table</A> is stored, as is
+            almost everything in a POI file system, in big blocks and
+            walked via the BAT. The <A HREF="#PropertyTable">Property
+            Table</A> is described below.
+        </P>
+        <A NAME="PropertyTable"><H3>Property Table</H3></A>
+        <P STYLE="margin-bottom: 0in">
+            The property table is essentially nothing more than the
+            directory system. Properties are 128 byte records
+            contained within the 512 byte blocks. The first property
+            is always the <A HREF="RootEntry">Root Entry</A>. The
+            following applies to individual properties within a
+            property table:
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x00</B> in the property is the
+            &quot;<B><I>name</I></B>&quot;. This is stored as an
+            uncompressed 16 bit unicode string. In short every other
+            byte corresponds to an &quot;ASCII&quot; character. The
+            size of this string is stored at offset <B>0x40</B>
+            (<B><I>string size</I></B>) as a short.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x42</B> is the <B><I>property type</I></B>
+            (byte). The type is 1 for directory, 2 for file or 5 for
+            the Root Entry.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x43</B> is the <B><I>node color</I></B>
+            (byte). The color is either 1, (black), or 0,
+            (red). Properties are apparently meant to be arranged in a
+            red-black binary tree, subject to the following rules:
+	    <A name="node_rules"></A>
+	    <OL>
+	        <LI>The root of the tree is always black
+		<LI>Two consecutive nodes cannot both be red
+		<LI>A property is less than another property if its
+		    name length is less than the other property's name
+		    length
+		<LI>If two properties have the same name length, the
+		    sort order is determined by the sort order of the
+		    properties' names.
+	    </OL>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x44</B> is the index (int) of the
+            <B><I>previous property</I></B>.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x48</B> is the index (int) of the <B><I>next
+            property</I></B>.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x4C</B> is the index (int) of the
+            <B><I>first directory entry</I></B>.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x74</B> is an integer giving the <B><I>start
+            block</I></B> for the file described by this
+            property. This index corresponds to an index in the array
+            of indices that is the Block Allocation Table (or the
+            Small Block Allocation Table) as well as the index of the
+            first block in the file.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            At offset <B>0x78</B> is an integer giving the total
+            <B><I>actual size</I></B> of the file pointed at by this
+            property. If the file size is less than 4096, the file is
+            stored in small blocks and the SBAT is used to walk the
+            small blocks making up the file. If the file size is 4096
+            or larger, the file is stored in big blocks and the main
+            BAT is used to walk the big blocks making up the file. The
+            exception to this rule is the <B><I>Root Entry</I></B>,
+            which, regardless of its size, is ALWAYS stored in big
+            blocks and the main BAT is used to walk the big blocks
+            making up this special file.
+        </P>
+        <A NAME="RootEntry"><H3>Root Entry</H3></A>
+        <P STYLE="margin-bottom: 0in">
+            The <B><I>Root Entry</I></B> in the <A
+            HREF="#PropertyTable"><B><I>Property Table</I></B></A>
+            contains the information necessary to read and write small
+            files, which are files less than 4096 bytes long. The
+            start block field of the Root Entry is the start index of
+            the <B><I>Small Block Array</I></B>, which is read like
+            any other file in the POI filesysstem. Since the SBAT
+            cannot be used without the Small Block Array, the Root
+            Entry MUST be read or written using the <A
+            HREF="#BAT"><B><I>Block Allocation Table</I></B></A>. The
+            blocks making up the Small Block Array are divided into
+            64-byte small blocks, up to the size indicated in the Root
+            Entry (which should always be a multiple of 64)
+        </P>
+        <H3>Walking the Nodes of the <A HREF="#PropertyTable">Property
+            Table</A></H3>
+        <P STYLE="margin-bottom: 0in">
+            The individual properties form a directory tree, with the
+            <B><I>Root Entry</I></B> as the directory tree's root, as
+            shown in the accompanying drawing. Note the numbers in
+            parentheses in each node; they represent the node's index
+            in the array of properties. The <B>NEXT_PROP</B>,
+            <B>PREVIOUS_PROP</B>, and <B>CHILD_PROP</B> fields hold
+            these indices, and are used to navigate the tree.
+        </P>
+        <P>
+            <IMG SRC="PropertySet.jpg">
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            Each <A NAME="directoryEntry">directory entry</A> (i.e., a
+            property whose type is <B><I>directory</I></B> or
+            <B><I>root entry</I></B>) uses its <B>CHILD_PROP</B> field
+            to point to one of its subordinate (child) properties. It
+            doesn't seem to matter which of its children it points
+            to. Thus in the previous drawing, the Root Entry's
+            CHILD_PROP field may contain 1, 4, or the index of one of
+            its other children.  Similarly, the directory node (index
+            1) may have, in its CHILD_PROP field, 2, 3, or the index
+            of one of its other children.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            The children of a given <A
+            HREF="#directoryEntry">directory property</A> point to
+            each other in a similar fashion by using their
+            <B>NEXT_PROP</B> and <B>PREVIOUS_PROP</B> fields. The
+            ordering of the children is governed by rules described <a
+            href="#node_rules">here</a>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            Unused <B>NEXT_PROP</B>, <B>PREVIOUS_PROP</B>, and
+            <B>CHILD_PROP</B> fields contain the marker value of
+            -1. All file properties have a value of -1 for their
+            CHILD_PROP fields for example.
+        </P>
+        <A NAME="BAT"><H3>Block Allocation Table</H3></A>
+        <P STYLE="margin-bottom: 0in">
+            The <B><I>BAT blocks</I></B> are pointed at by the bat
+            array contained in the <A HREF="HeaderBlock">header</A>
+            and supplemented, if necessary, by the <B><I>XBAT
+            blocks</I></B>. These blocks form a large table of
+            integers. These integers are block numbers. The
+            <B><I>Block Allocation Table</I></B> holds chains of
+            integers. These chains are terminated with -2. The
+            elements in these chains refer to blocks in the files. The
+            starting block of a file is NOT specified in the BAT.  It
+            is specified by the <B><I>property</I></B> for a given
+            file. The elements in this BAT are both the block number
+            (within the file minus the header) AND the number of the
+            next BAT element in the chain. This can be thought of as a
+            linked list of blocks. The BAT array contains the links
+            from one block to the next, including the end of chain
+            marker.
+        </P>
+        <P>
+            Here's an example: Let's assume that the BAT begins as
+            follows:
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <FONT FACE="Courier, monospace"><B>BAT[ 0 ] = 2</B></FONT>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <FONT FACE="Courier, monospace"><B>BAT[ 1 ] = 5</B></FONT>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <FONT FACE="Courier, monospace"><B>BAT[ 2 ] = 3</B></FONT>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <FONT FACE="Courier, monospace"><B>BAT[ 3 ] = 4</B></FONT>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <FONT FACE="Courier, monospace"><B>BAT[ 4 ] = 6</B></FONT>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <FONT FACE="Courier, monospace"><B>BAT[ 5 ] =
+            -2</B></FONT>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <FONT FACE="Courier, monospace"><B>BAT[ 6 ] = 7</B></FONT>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <FONT FACE="Courier, monospace"><B>BAT[ 7 ] =
+            -2</B></FONT>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            <B>...</B>
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            Now, if we have a file whose <A
+            HREF="#PropertyTable">Property Table</A> entry says it
+            begins with index 0, we walk the BAT array and see that
+            the file consists of blocks 0 (because the start block is
+            0), 2 (because BAT[ 0 ] is 2), 3 (BAT[ 2 ] is 3), 4 (BAT[
+            3 ] is 4), 6 (BAT[ 4 ] is 6), and 7 (BAT[ 6 ] is 7). It
+            ends at block 7 because BAT[ 7 ] is -2, which is the end
+            of chain marker.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            Similarly, a file beginning at index 1 consists of
+            blocks 1 and 5.
+        </P>
+        <P STYLE="margin-bottom: 0in">
+            Other special numbers in a BAT array are:
+        </P>
+        <UL>
+            <LI>
+                <P STYLE="margin-bottom: 0in">
+                    -1, which indicates an unused block
+                </P>
+            </LI>
+            <LI>
+                <P STYLE="margin-bottom: 0in">
+                    -3, which indicates a &quot;special&quot; block,
+                    such as a block used to make up the Small Block
+                    Array, the <A HREF="#PropertyTable">Property
+                    Table</A>, the main BAT, or the SBAT
+                </P>
+            </LI>
+        </UL>
+        <H2>Filesystem Structures</H2>
+        <P>
+            The following outlines the basic filesystem structures. 
+        </P>
+        <H3>Header (block 1) -- 512 (0x200) bytes</H3>
+        <TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0>
+	    <TR VALIGN=TOP>
+		<TD><B>Field</B></TD>
+		<TD><B>Description</B></TD>
+		<TD><B>Offset</B></TD>
+		<TD><B>Length</B></TD>
+		<TD><B>Default value or const</B></TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>FILETYPE</TD>
+		<TD>Magic number identifying this as a POI
+		    filesystem.</TD>
+		<TD>0x0000</TD>
+		<TD>Long</TD>
+		<TD>0xE11AB1A1E011CFD0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK1</TD>
+		<TD>Unknown constant</TD>
+		<TD>0x0008</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK2</TD>
+		<TD>Unknown Constant</TD>
+		<TD>0x000C</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK3</TD>
+		<TD>Unknown Constant</TD>
+		<TD>0x0014</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK4</TD>
+		<TD>Unknown Constant (revision?)</TD>
+		<TD>0x0018</TD>
+		<TD>Short</TD>
+		<TD>0x003B</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK5</TD>
+		<TD>Unknown Constant (version?)</TD>
+		<TD>0x001A</TD>
+		<TD>Short</TD>
+		<TD>0x0003</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK6</TD>
+		<TD>Unknown Constant</TD>
+		<TD>0x001C</TD>
+		<TD>Short</TD>
+		<TD>-2</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>LOG_2_BIG_BLOCK_SIZE</TD>
+		<TD>Log, base 2, of the big block size</TD>
+		<TD>0x001E</TD>
+		<TD>Short</TD>
+		<TD>9 (2 ^ 9 = 512 bytes)</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>LOG_2_SMALL_BLOCK_SIZE</TD>
+		<TD>Log, base 2, of the small block size</TD>
+		<TD>0x0020</TD>
+		<TD>Integer</TD>
+		<TD>6 (2 ^ 6 = 64 bytes)</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK7</TD>
+		<TD>Unknown Constant</TD>
+		<TD>0x0024</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK8</TD>
+		<TD>Unknown Constant</TD>
+		<TD>0x0028</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>BAT_COUNT</TD>
+		<TD>Number of elements in the BAT array</TD>
+		<TD>0x002C</TD>
+		<TD>Integer</TD>
+		<TD>required</TD>
+	    </TR>
+	    <TR VALIGN=TOP>
+		<TD>PROPERTIES_START</TD>
+		<TD>Block index of the first block of the <A
+		    HREF="#PropertyTable">property table</A></TD>
+		<TD>0x0030</TD>
+		<TD>Integer</TD>
+		<TD>required</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK9</TD>
+		<TD>Unknown Constant</TD>
+		<TD>0x0034</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK10</TD>
+		<TD>Unknown Constant</TD>
+		<TD>0x0038</TD>
+		<TD>Integer</TD>
+		<TD>0x00001000</TD>
+	    </TR>
+	    <TR VALIGN=TOP>
+		<TD>SBAT_START</TD>
+		<TD>Block index of first big block containing the
+		    small block allocation table (SBAT)</TD>
+		<TD>0x003C</TD>
+		<TD>Integer</TD>
+		<TD>-2</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>UK11</TD>
+		<TD>Unknown Constant</TD>
+		<TD>0x0040</TD>
+		<TD>Integer</TD>
+		<TD>1</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>XBAT_START</TD>
+		<TD>Block index of the first block in the Extended
+		    Block Allocation Table (XBAT)</TD>
+		<TD>0x0044</TD>
+		<TD>Integer</TD>
+		<TD>-2</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>XBAT_COUNT</TD>
+		<TD>Number of elements in the Extended Block
+		    Allocation Table (to be added to the BAT)</TD>
+		<TD>0x0048</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>BAT_ARRAY</TD>
+		<TD>Array of block indicies constituting the <A
+		    HREF="#BAT">Block Allocation Table (BAT)</A></TD>
+		<TD>0x004C, 0x0050, 0x0054 ... 0x01FC</TD>
+		<TD>Integer[ ]</TD>
+		<TD>-1 for unused elements, at least first element
+		    must be filled.</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>N/A</TD>
+		<TD>Header block data not otherwise described in this
+ 		    table</TD>
+		<TD>N/A</TD>
+		<TD>N/A</TD>
+		<TD>-1</TD>
+	    </TR>
+        </TABLE>
+        <A HREF="#BAT"><H3><B>Block Allocation Table Block -- 512
+           (0x200) bytes</B></H3></A>
+        <TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0>
+	    <TR VALIGN=TOP>
+		<TD><B>Field</B></TD>
+		<TD><B>Description</B></TD>
+		<TD><B>Offset</B></TD>
+		<TD><B>Length</B></TD>
+		<TD><B>Default value or const</B></TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>BAT_ELEMENT</TD>
+		<TD>Any given element in the BAT block</TD>
+		<TD>0x0000, 0x0004, 0x0008, ... 0x01FC</TD>
+		<TD>Integer</TD>
+		<TD>-1 = unused<BR>
+		    -2 = end of chain<BR>
+		    -3 = special (e.g., BAT block)<BR>
+                    All other values point to the next element in the
+		    chain and the next index of a block composing the
+		    file.</TD>
+	    </TR>
+        </TABLE>
+        <H3>Property Block -- 512 (0x200) byte block</H3>
+        <TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0>
+	    <TR VALIGN=TOP>
+		<TD><B>Field</B></TD>
+		<TD><B>Description</B></TD>
+		<TD><B>Offset</B></TD>
+		<TD><B>Length</B></TD>
+		<TD><B>Default value or const</B></TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>Properties[ ]</TD>
+		<TD>This block contains the properties.</TD>
+		<TD>0x0000, 0x0080, 0x0100, 0x0180</TD>
+		<TD>128 bytes</TD>
+		<TD>All unused space is set to -1.</TD>
+	    </TR>
+        </TABLE>
+        <H3>Property -- 128 (0x80) byte block</H3>
+        <TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0>
+	    <TR VALIGN=TOP>
+		<TD><B>Field</B></TD>
+		<TD><B>Description</B></TD>
+		<TD><B>Offset</B></TD>
+		<TD><B>Length</B></TD>
+		<TD><B>Default value or const</B></TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>NAME</TD>
+		<TD>A unicode null-terminated uncompressed 16bit
+		    string (lose the high bytes) containing the name
+                    of the property.</TD>
+		<TD>0x00, 0x02, 0x04, ... 0x3E</TD>
+		<TD>Short[ ]</TD>
+		<TD>0x0000 for unused elements, field required, 32
+		    (0x40) element max</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>NAME_SIZE</TD>
+		<TD>Number of characters in the NAME field</TD>
+		<TD>0x40</TD>
+		<TD>Short</TD>
+		<TD>Required</TD>
+	    </TR>
+	    <TR VALIGN=TOP>
+		<TD>PROPERTY_TYPE</TD>
+		<TD>Property type (directory, file, or root)</TD>
+		<TD>0x42</TD>
+		<TD>Byte</TD>
+		<TD>1 (directory), 2 (file), or 5 (root entry)</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>NODE_COLOR</TD>
+		<TD>Node color</TD>
+		<TD>0x43</TD>
+		<TD>Byte</TD>
+		<TD>0 (red) or 1 (black)</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>PREVIOUS_PROP</TD>
+		<TD>Previous property index</TD>
+		<TD>0x44</TD>
+		<TD>Integer</TD>
+		<TD>-1</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>NEXT_PROP</TD>
+		<TD>Next property index</TD>
+		<TD>0x48</TD>
+		<TD>Integer</TD>
+		<TD>-1</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>CHILD_PROP</TD>
+		<TD>First child property index</TD>
+		<TD>0x4c</TD>
+		<TD>Integer</TD>
+		<TD>-1</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>SECONDS_1</TD>
+		<TD>Seconds component of the created timestamp?</TD>
+		<TD>0x64</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>DAYS_1</TD>
+		<TD>Days since epoch component of the created
+		    timestamp?</TD>
+		<TD>0x68</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>SECONDS_2</TD>
+		<TD>Seconds component of the modified timestamp?</TD>
+		<TD>0x6C</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>DAYS_2</TD>
+                <TD>Days since epoch component of the modified
+                    timestamp?</TD>
+		<TD>0x70</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>START_BLOCK</TD>
+		<TD>Starting block of the file, used as the first
+		    block in the file and the pointer to the next
+                    block from the BAT</TD>
+		<TD>0x74</TD>
+		<TD>Integer</TD>
+		<TD>Required</TD>
+	    </TR>
+            <TR VALIGN=TOP>
+		<TD>SIZE</TD>
+		<TD>Actual size of the file this property points
+		    to. (used to truncate the blocks to the real
+		    size).</TD>
+		<TD>0x78</TD>
+		<TD>Integer</TD>
+		<TD>0</TD>
+	    </TR>
+        </TABLE>
+    </BODY>
+</HTML>

src/documentation/xdocs/poifs/html/POIFSUseCases.html

@@ -0,0 +1,449 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
+	<TITLE></TITLE>
+	<META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Linux)">
+	<META NAME="AUTHOR" CONTENT="Marc Johnson">
+	<META NAME="CREATED" CONTENT="20010803;14524700">
+	<META NAME="CHANGEDBY" CONTENT="Marc Johnson">
+	<META NAME="CHANGED" CONTENT="20010807;15355200">
+	<STYLE>
+	<!--
+		@page { margin-left: 1.25in; margin-right: 1.25in; margin-top: 1in; margin-bottom: 1in }
+		P { margin-bottom: 0.08in }
+	-->
+	</STYLE>
+</HEAD>
+<BODY>
+<P ALIGN=CENTER><B>POI Use Cases</B></P>
+<P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 1:</B> Read existing file
+system</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in"><B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to read content
+	of file system</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - understands POI file system</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in">POI client requests POI to read a
+	POI file system, providing an <FONT FACE="Courier, monospace">InputStream</FONT>
+	containing POI file system in question.</P>
+	<LI><P STYLE="margin-bottom: 0in">POI reads from the <FONT FACE="Courier, monospace">InputStream</FONT>
+	in 512 byte blocks</P>
+	<LI><P STYLE="margin-bottom: 0in">POI verifies that the first block
+	begins with the well known signature (0xE11AB1A1E011CFD0)</P>
+	<LI><P STYLE="margin-bottom: 0in">POI reads the Block Allocation
+	Table from the first block and, if necessary, from the XBAT blocks.</P>
+	<LI><P STYLE="margin-bottom: 0in">POI obtains the start block of the
+	Property Table and reads the Property Table (use case 9, read file)</P>
+	<LI><P STYLE="margin-bottom: 0in">POI reads the individual entries
+	in the Property Table</P>
+	<LI><P STYLE="margin-bottom: 0in">POI obtains the start block of the
+	Small Block Allocation Table and reads the Small Block Allocation
+	Table (use case 9, read file)</P>
+	<LI><P STYLE="margin-bottom: 0in">POI obtains the start block of the
+	Small Block store from the first entry in the Property Table and
+	reads the Small Block Array (use case 9, read file)</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">2a. If the last
+block read is not a 512 byte block, the <FONT FACE="Courier, monospace">InputStream</FONT>
+is not that of a POI file system, and POI throws an appropriate
+exception.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">3a. If the
+signature is incorrect, the <FONT FACE="Courier, monospace">InputStream</FONT>
+is not that of a POI file system, and POI throws an appropriate
+exception.</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 2:</B> Write file system</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to write file
+	system out.</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - knows how to write file
+	system out.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">File system
+	has been read (use case 1, read existing file system) and
+	subsequently modified (use case 4, replace file in file system; use
+	case 5, delete file from file systen; or use case 6, write new file
+	to file system; in any combination)</P>
+</UL>
+<P STYLE="margin-bottom: 0in; font-weight: medium">or</P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">File system
+	has been created (use case 3, create new file system)</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI client
+	provides an <FONT FACE="Courier, monospace">OutputStream</FONT> to
+	write the file system to.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI gets the
+	sizes of the Property Table and each file in the file system.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">If any files
+	in the file system requires storage in a Small Block Array, POI
+	creates a Small Block Array of sufficient size to hold all of the
+	small files.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI
+	calculates the number of big blocks needed to hold all of the large
+	files, the Property Table, and, if necessary, the Small Block Array
+	and the Small Block Allocation Table.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI creates a
+	set of big blocks sufficient to store the Block Allocation Table</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI creates
+	and writes the header block</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI writes
+	out the XBAT blocks, if needed.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI writes
+	out the Small Block Array, if needed</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI writes
+	out the Small Block Allocation Table, if needed</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI writes
+	out the Property Table</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI writes
+	out the large files, if needed</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI closes
+	the OutputStream.</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">6a. Exceptions
+writing to the <FONT FACE="Courier, monospace">OutputStream</FONT>
+will be propagared back to the POI client.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">7a. Exceptions
+writing to the <FONT FACE="Courier, monospace">OutputStream</FONT>
+will be propagared back to the POI client.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">8a. Exceptions
+writing to the <FONT FACE="Courier, monospace">OutputStream</FONT>
+will be propagared back to the POI client.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">9a. Exceptions
+writing to the <FONT FACE="Courier, monospace">OutputStream</FONT>
+will be propagared back to the POI client.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">10a. Exceptions
+writing to the <FONT FACE="Courier, monospace">OutputStream</FONT>
+will be propagared back to the POI client.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">11a. Exceptions
+writing to the <FONT FACE="Courier, monospace">OutputStream</FONT>
+will be propagared back to the POI client.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">12a. Exceptions
+closing the <FONT FACE="Courier, monospace">OutputStream</FONT> will
+be propagared back to the POI client.</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 3:</B> Create new file
+system</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to create a new
+	file system.</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - knows how to create a new
+	file system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B></P>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI creates
+	an empty Property Table.</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B><SPAN STYLE="font-weight: medium">
+None</SPAN></P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 4:</B> Replace file in file
+system</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to replace an
+	existing file in the file system</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - knows how to manage the file
+	system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">Either</P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">The file system has been read (use
+	case 1, read existing file system) and a file has been extracted
+	from the file system (use case 7, read existing file from file
+	system), or</P>
+	<P STYLE="margin-bottom: 0in">the file system has been created (use
+	case 3, create new file system) and a file has been written to the
+	file system (use case 6, write new file to file system)</P>
+	<LI><P STYLE="margin-bottom: 0in">The file already exists in the
+	file system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI discards
+	storage of the existing file.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI updates
+	the existing file's entry in the Property Table</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI stores
+	the new file's data</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">1a. POI throws an
+exception if the file does not exist.</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 5:</B> Delete file from
+file system</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to remove a file
+	from a file system</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - knows how to manage the file
+	system</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">The file system has been read (use
+	case 1, read existing file system) and a file has been extracted
+	from the file system (use case 7, read existing file from file
+	system), or</P>
+	<P STYLE="margin-bottom: 0in">the file system has been created (use
+	case 3, create new file system) and a file has been written to the
+	file system (use case 6, write new file to file system)</P>
+	<LI><P STYLE="margin-bottom: 0in">The file already exists in the
+	file system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI discards
+	the specified file's storage</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI discards
+	the file's Property Table entry</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">1a. POI throws an
+exception if the file does not exist.</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 6:</B> Write new file to
+file system</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to add a new
+	file to the file system</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - knows how to manage the file
+	system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B> 
+</P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">The specified file does not yet
+	exist in the file system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The POI
+	client provides a file name</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI creates a
+	new Property Table entry for the new file</P>
+	<LI><P STYLE="margin-bottom: 0in"><SPAN STYLE="font-weight: medium">POI
+	provides the POI client with an <FONT FACE="Courier, monospace">Output</FONT></SPAN><FONT FACE="Courier, monospace">Stream</FONT>
+	to write to.</P>
+	<LI><P STYLE="margin-bottom: 0in">The POI client writes data to the
+	provided <FONT FACE="Courier, monospace">OutputStream</FONT>.</P>
+	<LI><P STYLE="margin-bottom: 0in">The POI client closes the provided
+	<FONT FACE="Courier, monospace">OutputStream</FONT></P>
+	<LI><P STYLE="margin-bottom: 0in">POI updates the Property Table
+	entry with the new file's size</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">1a. POI throws an
+exception if a file with the specified name already exists in the
+file system.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">1b. POI throws an
+exception if the file name is too long. The limit on file name length
+is 32 characters.</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 7:</B> Read existing file
+from file system</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to read a file
+	from the file system.</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - knows how to manage the file
+	system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The file
+	system is has been read (use case 1, read existing file system) or
+	has been created and written to (use case 3, create new file system;
+	use case 6, write new file to file system.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The specified
+	file exists in the file system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The POI
+	client provides the name of a file to be read</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI provides
+	an InputStream to read from.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The POI
+	client reads from the <FONT FACE="Courier, monospace">InputStream</FONT>.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The POI
+	client closes the <FONT FACE="Courier, monospace">InputStream</FONT>.</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">1a. POI throws an
+exception if no file with the specified name exists.</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 8:</B> Read file system
+directory</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to know what
+	files exist in the file system.</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - POI knows how to manage the
+	file system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The file
+	system has been read (use case 1, read existing file system) or
+	created (use case 3, create new file system)</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The POI
+	client requests the file system directory.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI returns
+	an <FONT FACE="Courier, monospace">Iterator</FONT>. The <FONT FACE="Courier, monospace">Iterator</FONT>
+	will not include the root entry in the Property Table, and may be an
+	<FONT FACE="Courier, monospace">Iterator</FONT> over an empty
+	<FONT FACE="Courier, monospace">Collection</FONT>.</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B><SPAN STYLE="font-weight: medium">
+None</SPAN></P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 9:</B> Read file</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI - POI needs to read a file, or
+	something resembling a file (i.e., the Property Table, the Small
+	Block Array, or the Small Block Allocation Table)</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI begins
+	with a start block, a file size, and a flag indicating whether to
+	use the Big Block Allocation Table or the Small Block Allocation
+	Table</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI returns
+	an InputStream.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">Reads from
+	the InputStream are performed by walking the specified Block
+	Allocation Table and reading the blocks indicated.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI closes
+	the InputStream when finished reading the file, or its client wants
+	to close the InputStream.</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">3a. An exception
+will be thrown if the specified Block Allocation Table is corrupt, as
+evidenced by an index pointing to a non-existent block, or by a chain
+extending past the known size of the file.</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"><B>Use Case 10:</B> Rename existing
+file in file system</P>
+<P STYLE="margin-bottom: 0in"><B>Primary Actor:</B> POI client</P>
+<P STYLE="margin-bottom: 0in"><B>Scope:</B> POI</P>
+<P STYLE="margin-bottom: 0in; page-break-before: auto; page-break-after: auto">
+<B>Level:</B> Summary</P>
+<P STYLE="margin-bottom: 0in"><B>Stakeholders and Interests:</B></P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in">POI client- wants to rename an
+	existing file in the file system.</P>
+	<LI><P STYLE="margin-bottom: 0in">POI - knows how to manage the file
+	system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Precondition:</B> 
+</P>
+<UL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The file
+	system is has been read (use case 1, read existing file system) or
+	has been created and written to (use case 3, create new file system;
+	use case 6, write new file to file system.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The specified
+	file exists in the file system.</P>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">The new name
+	for the file does not duplicate another file in the file system.</P>
+</UL>
+<P STYLE="margin-bottom: 0in"><B>Minimal Guarantee:</B> None</P>
+<P STYLE="margin-bottom: 0in"><B>Main Success Guarantee:</B></P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in; font-weight: medium">POI updates
+	the Property Table entry for the specified file with its new name.</P>
+</OL>
+<P STYLE="margin-bottom: 0in"><B>Extensions:</B></P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">1a. If the old
+file name is not in the file system, POI throws an exception.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">1b. If the new
+file name already exists in the file system, POI throws an exception.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium">1c. If the new
+file name is too long (the limit is 32 characters), POI throws an
+exception.</P>
+<P STYLE="margin-bottom: 0in; font-weight: medium"><BR>
+</P>
+</BODY>
+</HTML>

src/documentation/xdocs/poifs/html/how-to.html

@@ -0,0 +1,190 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
+	<TITLE></TITLE>
+	<META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Linux)">
+	<META NAME="CREATED" CONTENT="20011031;14571450">
+	<META NAME="CHANGEDBY" CONTENT=" ">
+	<META NAME="CHANGED" CONTENT="20011230;13132100">
+</HEAD>
+<BODY>
+<H1>POIFS HOW TO</H1>
+<H2>How to use POIFS directly</H2>
+<H3>Andrew C. Oliver - December 14, 2001</H3>
+<DL>
+	<DD STYLE="margin-bottom: 0.2in">10.31.2001- initial revision for
+	build POI 0.12.3 
+	</DD><DD STYLE="margin-bottom: 0.2in">
+	12.15.2001 - minor revisions - thread safety, entry modification,
+	name restrictions, and so on.</DD><DD STYLE="margin-bottom: 0.2in">
+	12.30.2001 - revised for POI 1.0-final - minor revisions 
+	</DD></DL>
+<H2>
+Capabilities</H2>
+<DL>
+	<DD STYLE="margin-bottom: 0.2in">This release of POIFS contains the
+	full functionality to read, write and modify (by recreation) files
+	in the format most commonly referred to as OLE 2 Compound Document
+	Format (proabably tm - Microsoft). 
+	</DD></DL>
+<H2>
+Target Audience</H2>
+<P>This release candidate is intended for general use. It is
+considered to be production-ready. It has not yet been extensively
+tested (especially in a high load multi-threaded server situation),
+though it's been unit tested quite a bit. This release is considered
+to be &quot;golden&quot; as it has been used by HSSF and other users
+without problems for some time, and has not changed recently. 
+</P>
+<H2>General Use</H2>
+<H3>User API</H3>
+<H4>High level description and overview</H4>
+<P>Files written with the POIFS library are referred to as POIFS file
+systems (or sometimes archives). The OLE 2 Compound Document format
+is designed to mimic many of the characteristics of a pre-modern file
+system (most similar to FAT). We make the distinction between POIFS
+written files and &quot;native&quot; written OLE 2 Compound Document
+Format files because while we believe POIFS to be a full, correct and
+complete implementation, most of this was accomplished through
+researching other open source implementations and flat out guesses.</P>
+<P>This overview is in no way intended to be complete (for a more
+intense discussion please see POIFSFormat.html in this same
+directory), it should give you a good idea into the principals of a
+POIFS file system. Please note that specific file formats such as XLS
+(HSSF) or DOC utilize POIFS file systems to contain their data, POIFS
+itself does not know how to interpret the archived data.</P>
+<P>Every POIFS file system contains a hierarchy of directories
+starting with the root (there is always one, and only one, root).
+Each directory, including the root, may contain one or more
+directories and/or documents. Every directory and document has a
+name. The root directory has a name, but unlike other directories,
+its name is fixed and cannot be renamed.</P>
+<P><STRONG>The POIFS API was not designed to be, and is not,
+thread-safe.</STRONG> Only one thread of control should ever
+manipulate a specific POIFS file system over that file system's
+lifetime. You can, of course, have multiple threads, each
+manipulating a distinct POIFS file system instance.</P>
+<H4>Writing a new one</H4>
+<P>To create a new (from scratch) POIFS file system for writing to,
+you simply create an instance of
+<CODE>net.sourceforge.poi.poifs.filesystem.Filesystem</CODE> using
+the default constructor (no arguments). Initially this POIFS file
+system will be empty except for containing the essential root
+directory.</P>
+<P>From there you can create a directory entry by calling&nbsp;<CODE>
+Filesystem.createDirectory(name)</CODE>, and passing in the name of
+the directory. This will return an instance
+of&nbsp;<CODE>net.sourceforge.poi.poifs.filesystem.DirectoryEntry</CODE>
+. You can also create a document within the root directory by
+calling&nbsp;<CODE> Filesystem.createDocument(name, inputstream)</CODE>,
+and passing the name of the document and an instance
+of&nbsp;<CODE>java.io.InputStream</CODE> from which the document's
+data can be obtained. It is noted that, the most commonly used file
+formats of the Microsoft Corporation such as DOC, XLS, etc. are all
+POIFS-compatible file systems with documents stored in the root
+directory.</P>
+<P>Supposing the document is to be stored in a directory other than
+the root, you take the instance of&nbsp;<CODE>DirectoryEntry</CODE>
+that you created and call&nbsp;<CODE>createDocument(name,
+inputstream)</CODE> on it instead. You can also create a child
+directory by calling&nbsp;<CODE> createDirectory(name)</CODE>.
+Alternatively you can call&nbsp;<CODE>Filesystem.getRoot()</CODE> and
+use it just like any other directory entry.</P>
+<P>When you've finished creating entries in the filesystem, simply
+call&nbsp;<CODE> Filesystem.writeFilesystem(stream)</CODE> passing in
+an instance of&nbsp;<CODE> java.io.OutputStream</CODE>. Be sure you
+close the stream when you're done.</P>
+<H5><A NAME="Names"></A>Names</H5>
+<P>The POIFS file system imposes two limitations on document and
+directory names:</P>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in">The names of documents and
+	directories must be unique within their containing directory. Pretty
+	obvious. 
+	</P>
+	<LI><P>Names are restricted to 31 characters. If you create a
+	directory or document with a name longer than that, it will be
+	silently truncated. When truncated, it may conflict with the name of
+	another directory or document, and the create operation will fail. 
+	</P>
+</OL>
+<H5>Why not Readers and Writers?</H5>
+<P>The POIFS file system uses Streams because HSSF, and virtually all
+other applications that would use POIFS, deals with binary files,
+which Streams handle correctly. Readers and Writers deal with text
+and know how to handle 16-bit characters. If there is a demand for
+providing support for Readers and Writers, let us know.</P>
+<P>Here is some example code (excerpted and adapted from
+net.sourceforge.poi.hssf.usermodel.Workbook class):</P>
+<PRE>        byte[]     bytes        = getBytes();                                             // get the bytes for the document (elsewhere in the class)
+        FileOutputStream stream = new FileOutputStream(&quot;/home/reportsys/test/text.xls&quot;);  // create a new FileOuputStream
+        Filesystem fs           = new Filesystem();                                       // create a new POIFS Filesystem object
+        fs.createDocument(new ByteArrayInputStream(bytes), &quot;Workbook&quot;);                   // create a new document in the root directory of the POIFS filesystem
+                                                                                          // close on ByteArrayInputStream is a no-op so we don't bother, no real file handle is used
+        fs.writeFilesystem(stream);                                                       // write the filesystem to the output stream.
+        Stream.close();                                                                   // close our stream (don't leak file handles its bad news)</PRE><H4>
+Reading or modifying an existing file</H4>
+<P>Reading in an exising POIFS file system is equally simple. Create
+a new instance of <CODE>net.sourceforge.poi.poifs.filesystem.Filesystem</CODE>
+by calling the <CODE>Filesystem(java.io.InputStream)</CODE>
+constructor and passing in your file system's data (this would
+probably be a <CODE>FileInputStream</CODE> , but it doesn't matter).
+From there you can get documents from the root directory by calling
+<CODE>Filesystem.createDocumentInputStream(name)</CODE> and passing a
+string representing that document's name.</P>
+<P>If you wish to walk the filesystem, the easiest thing to do is
+<CODE>DirectoryEntry.getEntries()</CODE>. This will give you a
+<CODE>java.util.Iterator</CODE> of <CODE>Entry</CODE> instances
+(<CODE>DirectoryEntry </CODE>and <CODE>DocumentEntry</CODE> are
+extensions of <CODE>Entry</CODE>) contained by the <CODE>DirectoryEntry</CODE>
+. For instance you could call <CODE>Filesystem.getRoot()</CODE> to
+retrieve a <CODE>DirectoryEntry</CODE> instance. From there you could
+call <CODE>DirectoryEntry.getEntries()</CODE> and retrieve an
+<CODE>Iterator</CODE> of those entries. Iterating through these
+entries, you'd call <CODE>getName()</CODE> to check the name of the
+entry and <CODE>isDocumentEntry()</CODE> or <CODE>isDirectoryEntry()</CODE>
+to determine its type. Going the other way, given an <CODE>Entry</CODE>,
+you can walk back up the directory chain by calling <CODE>getParent()</CODE>,
+which returns the <CODE>Entry</CODE>'s containing <CODE>DirectoryEntry</CODE>
+(calling <CODE>getParent()</CODE> on the root directory returns a
+<SAMP>null</SAMP> reference).</P>
+<P>With a <CODE>DocumentEntry</CODE>, you can create an instance of
+<CODE>net.sourceforge.poi.poifs.filesystem.DocumentInputStream</CODE>
+, by passing the <CODE>DocumentEntry</CODE> as the only argument to
+the constructor of <CODE>DocumentInputStream.</CODE>The
+<CODE>DocumentInputStream</CODE> class is a simple extension of
+<CODE>java.io.InputStream</CODE> that fully supports the <CODE>InputStream</CODE>
+API, including the <CODE>mark</CODE> , <CODE>reset</CODE>, and <CODE>skip</CODE>
+methods, providing a form of random access I/O.</P>
+<P>To modify the file you would simply walk through the entries and
+follow the same instructions for writing a POIFS file system from
+scratch. There are also methods to delete an <CODE>Entry</CODE>
+(note: you cannot delete the root directory, nor can you delete a
+<CODE>DirectoryEntry</CODE> unless it's empty) and to rename an <CODE>Entry</CODE>
+(but see the <A HREF="#Names">notes</A> above). 
+</P>
+<H3>POIFS Logging facility</H3>
+<P>POIFS does not yet use log4j style logging.</P>
+<P>Here is an example 
+</P>
+<PRE STYLE="margin-bottom: 0.2in">Paste log config example</PRE><H3>
+POIFS Developer's Tools</H3>
+<P>POIFS does not yet have developer's tools. 
+</P>
+<H3>What's Next?</H3>
+<OL>
+	<LI><P STYLE="margin-bottom: 0in">Refactoring of the API to more
+	cleanly separate write from read. 
+	</P>
+	<LI><P STYLE="margin-bottom: 0in">Add logging/tracing code 
+	</P>
+	<LI><P STYLE="margin-bottom: 0in">Add tree viewer (probably Andy) 
+	</P>
+	<LI><P>Read/write support for creation and modification time stamps 
+	</P>
+</OL>
+<P><BR><BR>
+</P>
+</BODY>
+</HTML>

src/documentation/xdocs/poifs/index.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>PoiFS</title>
+  <subtitle>Overview</subtitle>
+  <authors>
+   <person name="Andrew C. Oliver" email="acoliver@apache.org"/>     
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>     
+  </authors>
+ </header>
+
+ <body>
+ <s1 title="Overview">
+
+  <p>POIFS is a pure Java implementation of the OLE 2 Compound Document format.</p>
+  <p> TODO: copy POIFS docs and port to XML.  For now please reference <link href="http://poi.sourceforge.net">old site</link>.
+  </p>
+  </s1>
+ </body>
+</document>

src/documentation/xdocs/todo.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE todo PUBLIC "-//APACHE//DTD Todo V1.0//EN" "src/documentation/xdocs/dtd/todo-v10.dtd">
+
+<todo title="Things To Do for Poi">
+
+ <devs>
+  <!-- in strict alphabetical order -->
+  <person id="AO"  name="Andrew C. Oliver"   email="acoliver2@users.sourceforge.net"/>
+  <person id="GS"  name="Glen Stampoultzis"  email="gstamp@iprimus.com.au"/>  
+  <person id="MJ"  name="Marc Johnson"       email="mjohnson at apache dot org"/>
+  <person id="NKB" name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
+  <person id="open" name="Poi Developers"    email="poi-devel@lists.sourceforge.net"/>
+ </devs>
+
+ <actions priority="high">
+  <action context="code" assigned-to="NKB">
+    do it
+  </action>
+
+ </actions>
+
+ <actions priority="medium">
+  <action context="code">
+   do it
+  </action>
+ </actions>
+
+</todo>

src/documentation/xdocs/utils/book.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
+
+<book software="Poi Project" 
+      title="Poi Utils" 
+      copyright="@year@ Poi Project">
+
+  <menu label="Navigation">
+    <menu-item label="Main" href="../index.html"/>
+  </menu>
+
+</book>
+
+

src/documentation/xdocs/utils/index.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Poi Utils</title>
+  <subtitle>Overview</subtitle>
+  <authors>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>     
+  </authors>
+ </header>
+
+ <body>
+ <s1 title="Overview">
+
+  <p>This is Poi Utils.</p>
+
+  </s1>
+ </body>
+</document>

src/documentation/xdocs/who.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
+
+<document>
+ <header>
+  <title>Who we are</title>
+  <authors>
+   <person name="Davanum Srinivas" email="dims@yahoo.com"/>
+   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>   
+   </authors>
+ </header>
+
+ <body>
+
+ <s1 title="Who we are">
+  <p>
+    The Poi Project operates on a meritocracy: the more you do, the more 
+    responsibility you will obtain. This page lists all of the people who have 
+    gone the extra mile and are Committers. If you would like to get involved, 
+    the first step is to join the mailing lists. 
+  </p>
+
+  <p>
+    We ask that you please do not send us emails privately asking for support. 
+    We are non-paid volunteers who help out with the project and we do not 
+    necessarily have the time or energy to help people on an individual basis. 
+    Instead, we have setup mailing lists which often contain hundreds of 
+    individuals who will help answer detailed requests for help. The benefit of 
+    using mailing lists over private communication is that it is a shared 
+    resource where others can also learn from common mistakes and as a 
+    community we all grow together. 
+  </p>
+  
+  <s2 title="Advisors">
+    <ul>
+       <li><link href="http://jakarta.apache.org/avalon/authors/stefano.html">Stefano Mazzocchi</link> (stefano at apache dot org)
+       </li>
+    </ul>
+  </s2>
+
+  <s2 title="Committers">
+    <ul>
+      <li><link href="http://trilug.org/~acoliver">Andrew C. Oliver</link> (acoliver at apache dot org)</li>
+      <li>Marc Johnson (mjohnson at apache dot org)</li>
+    </ul>
+  </s2>
+  <s2 title="Developers">
+    <ul>
+      <li>Glen Stampoultzis (gstamp at iprimus dot com dot au)</li>
+      <li>Nicola Ken Barozzi (barozzi at nicolaken dot com)</li>
+    </ul>
+  </s2>
+ </s1>
+
+</body>
+</document>
+