new design documentation using docbook

uml diagrams will be svg in future


git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@194454 13f79535-47bb-0310-9956-ffa450edef68

22 files changed, 911 insertions, 0 deletions

diff --git a/docs/design/README b/docs/design/README
new file mode 100644
index 000000000..b419caf2a
--- /dev/null
+++ b/docs/design/README
@@ -0,0 +1,11 @@
+These documents are written for docbook
+http://sourceforge.net/projects/docbook
+
+To convert to pdf:
+- place the docbook files in a directory name "docbook"
+- place docbookx package in a directory name "docbookx"
+the files are avaialable here:
+http://www.oasis-open.org/docbook/xml/4.1.2/index.shtml
+
+- run the build script
+
diff --git a/docs/design/apps.gif b/docs/design/apps.gif
deleted file mode 100644
index 2484105f4..000000000
--- a/docs/design/apps.gif
+++ /dev/null
diff --git a/docs/design/areas.xml b/docs/design/areas.xml
new file mode 100644
index 000000000..201fb6035
--- /dev/null
+++ b/docs/design/areas.xml
@@ -0,0 +1,13 @@
+<?xml version = "1.0" encoding = "UTF-8"?>
+<section id="areatree">
+ <title>Area Tree</title>
+	<para>
+The code to implement the area tree will attempt to match the areas
+defined in the specification. A number of optimisations may be possible
+for similar areas and groups of areas.
+  </para>
+  <para>
+
+  </para>
+
+</section>
diff --git a/docs/design/build.sh b/docs/design/build.sh
new file mode 100644
index 000000000..3222894f1
--- /dev/null
+++ b/docs/design/build.sh
@@ -0,0 +1,23 @@
+#! /bin/sh
+# $Id$
+
+LIBDIR=../../lib  
+TARGET_CLASSPATH=$LIBDIR/ant.jar:\
+$LIBDIR/buildtools.jar:\
+$LIBDIR/xalan-1.2.2.jar:\
+$LIBDIR/xerces-1.2.3.jar:\
+$LIBDIR/bsf.jar:\
+../../build/fop.jar:\
+$LIBDIR/logkit-1.0b4.jar:\
+$LIBDIR/avalon-framework-4.0.jar:\
+$LIBDIR/batik.jar:\
+$LIBDIR/optional.jar:\
+$LIBDIR/jimi-1.0.jar:
+
+if [ "$JAVA_HOME" != "" ] ; then
+   TARGET_CLASSPATH=$TARGET_CLASSPATH:$JAVA_HOME/lib/tools.jar
+else
+   echo "Error: The JAVA_HOME environment variable is not set."
+fi
+            
+java -classpath $TARGET_CLASSPATH -Djboss.home=$JBOSS_HOME org.apache.tools.ant.Main $*
diff --git a/docs/design/build.xml b/docs/design/build.xml
new file mode 100644
index 000000000..999e7bfb6
--- /dev/null
+++ b/docs/design/build.xml
@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+
+<!-- ======================================================================= -->
+<!-- JBoss documentation build file                                          -->
+<!-- ======================================================================= -->
+
+<project name="FOPDocs" default="docs" basedir="./">
+ 	<target name="init">
+		<property name="Name" value="FOPDocs"/>
+		<property name="name" value="fopdocs"/>
+		<property name="version" value="0.1"/>
+	
+		<property name="lib.dir" value="${basedir}/lib"/>
+
+      <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop"/>
+    </target>
+  
+  <!-- =================================================================== -->
+  <!-- Generate a help screen                                              -->
+  <!-- =================================================================== -->
+  <target name="help" depends="init">
+  	
+    <echo message="${name}-${version} build file, available targets:" />
+    <echo message="------------------------------------------------------------" />
+    <echo message="main            : Compile and prepare deployment directory. " />
+    <echo message="pdf             : Compile and prepare pdf user docs. "/>
+    <echo message="clean           : Clean deployment and distribution. " />
+    <echo message="------------------------------------------------------------" />
+    <echo message="	 USAGE: build &lt;target&gt; " />
+    
+  </target>
+  
+  <!-- =================================================================== -->
+  <!-- Prepares the build directory                                        -->
+  <!-- =================================================================== -->
+  <target name="prepare" depends="init">
+  </target>
+  
+  <!-- =================================================================== -->
+  <!-- Generates the pdf documentation                                     -->
+  <!-- =================================================================== -->
+  <target name="pdf" depends="prepare">
+    <echo message="Building pdf documentation. Please wait ..."/>
+    <delete file="fop.fo"/>
+    <style basedir="./" 
+           destdir="./" 
+           style="docbook/fo/docbook.xsl" 
+           extension=".fo" 
+           includes="fop.xml"/>
+    <fop fofile="fop.fo" pdffile="fop.pdf"/>
+<!--    <delete file="fop.fo"/>-->
+  </target>
+
+  <!-- =================================================================== -->
+  <!-- Generates pdf and html documentation                                -->
+  <!-- =================================================================== -->
+  <target name="docs" depends="pdf"/>
+
+  <!-- =================================================================== -->
+  <!-- Cleans up generated stuff                                           -->
+  <!-- =================================================================== -->
+  <target name="clean" depends="init">
+    <delete file="fop.fo"/>
+    <delete file="fop.pdf"/>
+  </target>
+</project>
+
diff --git a/docs/design/datatypes.gif b/docs/design/datatypes.gif
deleted file mode 100644
index 09dc9eb03..000000000
--- a/docs/design/datatypes.gif
+++ /dev/null
diff --git a/docs/design/float.svg b/docs/design/float.svg
new file mode 100755
index 000000000..7bef863a2
--- /dev/null
+++ b/docs/design/float.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20001102//EN"
+	"http://www.w3.org/TR/2000/CR-SVG-20001102/DTD/svg-20001102.dtd">
+<svg width="420" height="300">
+	<defs>
+		<marker id="measure" viewBox="0 0 10 10" refX="0" refY="5" markerWidth="4"
+			markerHeight="3" orient="auto">
+			<path d="M0 0 L5 10 L10 0 z"/>
+			<path d="M0 10 L10 10 L10 9 L0 9 z"/>
+		</marker>
+	</defs>
+	<rect x="12" y="-29" width="307" height="371" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="12" y="19" width="307" height="170" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(58,53,255);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="13" y="201" width="307" height="126" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(33,75,255);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="13" y="71" width="140" height="202" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(255,169,33);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M11.5 219 L320.5 219" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(36,239,21);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<text x="0" y="216" style="font-family:Arial;font-size:12;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:1;fill:rgb(0,0,0);opacity:1">flow limit</text>
+	<text x="72" y="139" style="font-family:Arial;font-size:12;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:1;fill:rgb(0,0,0);opacity:1">float</text>
+	<text x="337.565" y="144" style="font-family:Arial;font-size:12;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:1;fill:rgb(0,0,0);opacity:1">effective height</text>
+	<path d="M330.5 63 L330.5 271" style="marker-end:url(#measure);marker-start:url(#measure);stroke-miterlimit:4;stroke-linejoin:miter;
+		stroke-linecap:round;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);fill-opacity:1;
+		fill:rgb(0,0,0);opacity:1"/>
+	<text x="349" y="157" style="font-family:Arial;font-size:12;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:1;fill:rgb(0,0,0);opacity:1">of float line</text>
+	<rect x="12" y="18" width="306" height="22" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(166,166,166);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="12" y="45" width="306" height="20" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(166,166,166);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="154" y="72" width="164" height="16" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(166,166,166);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="153" y="97" width="166" height="15" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(166,166,166);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="154" y="123" width="132" height="16" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(166,166,166);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="220" y="71" width="6" height="17" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(247,255,9);
+		fill-opacity:1;fill:rgb(255,255,0);opacity:1"/>
+	<text x="232" y="91" style="font-family:Arial;font-size:12;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:1;fill:rgb(0,0,0);opacity:1">float anchor</text>
+</svg>
+
diff --git a/docs/design/flow.gif b/docs/design/flow.gif
deleted file mode 100644
index 1301cbfa0..000000000
--- a/docs/design/flow.gif
+++ /dev/null
diff --git a/docs/design/fo.gif b/docs/design/fo.gif
deleted file mode 100644
index ada937797..000000000
--- a/docs/design/fo.gif
+++ /dev/null
diff --git a/docs/design/fop.gif b/docs/design/fop.gif
deleted file mode 100644
index 52547bb6c..000000000
--- a/docs/design/fop.gif
+++ /dev/null
diff --git a/docs/design/fop.xml b/docs/design/fop.xml
new file mode 100644
index 000000000..0b6d9bfbd
--- /dev/null
+++ b/docs/design/fop.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx/docbookx.dtd" [
+	<!ENTITY intro.xml SYSTEM "intro.xml">
+  <!ENTITY layout.xml SYSTEM "layout.xml">
+  <!ENTITY areas.xml SYSTEM "areas.xml">
+  <!ENTITY optimise.xml SYSTEM "optimise.xml">
+  <!ENTITY useragent.xml SYSTEM "useragent.xml">
+]>
+<book>
+	<bookinfo>
+		<title>FOP documentation</title>
+		<copyright>
+			<year>2001</year>
+			<holder>The Apache Software Foundation. All rights reserved.</holder>
+		</copyright>
+	</bookinfo>
+&intro.xml;
+<chapter id="fop">
+  <title>FOP</title>
+&layout.xml;
+</chapter>
+<chapter id="areas">
+  <title>Areas</title>
+&areas.xml;
+</chapter>
+<chapter id="areas">
+  <title>Optimising</title>
+&optimise.xml;
+</chapter>
+<chapter id="useragent">
+  <title>User Agent</title>
+&useragent.xml;
+</chapter>
+</book>
diff --git a/docs/design/image.gif b/docs/design/image.gif
deleted file mode 100644
index fc5be83eb..000000000
--- a/docs/design/image.gif
+++ /dev/null
diff --git a/docs/design/intro.xml b/docs/design/intro.xml
new file mode 100644
index 000000000..671748c4a
--- /dev/null
+++ b/docs/design/intro.xml
@@ -0,0 +1,18 @@
+<?xml version = "1.0" encoding = "UTF-8"?>
+<preface>
+	<title>About this Document</title>
+	<para>
+This document is written in docbook with the hope that it will
+provide a good test case of a common usage of FO created by
+docbook. The information is then processed by fop to produce
+a PDF document.
+	</para>
+	<para>
+It is hoped that this document can be used as a basis for designing
+a new layout system for FOP so that it can handle all necessary
+situations when deciding line breaks, page breaks and spacing.
+It should also allow for the easy implementation of different
+writing modes and character sets.
+  </para>
+
+</preface>
diff --git a/docs/design/layout.gif b/docs/design/layout.gif
deleted file mode 100644
index 09f04af3a..000000000
--- a/docs/design/layout.gif
+++ /dev/null
diff --git a/docs/design/layout.xml b/docs/design/layout.xml
new file mode 100644
index 000000000..0c426e0c0
--- /dev/null
+++ b/docs/design/layout.xml
@@ -0,0 +1,464 @@
+<?xml version = "1.0" encoding = "UTF-8"?>
+<section id="layout">
+	<title>FO Layout</title>
+  <para>
+The aim of the layout system is to be self contained and allow for
+easy changes or extensions for future development. For example the
+line breaking should be decided at a particular point in the process
+that makes it easier to handle other languages.
+  </para>
+	<para>
+The layout begins once the hierarchy of FO objects has been constructed.
+Note: it may be possible to start immediately after a block formatting
+object has been added to the flow but this is not currently in the scope
+of the layout. It is also possible to layout all pages in a page sequence
+after each page sequence has been added from the xml.
+	</para>
+  <para>
+The layout process is handled by a set of layout managers. The block
+level layout managers are used to create the block areas which are
+added to the region area of a page.
+  </para>
+ <section>
+ <title>Layout Managers</title>
+  <para>
+The layout managers are set up from the hierarchy of the formatting
+object tree. A manager represents a hierachy of area producing objects.
+A manager is able to handle the block area(s) that it creates and
+organise or split areas for page breaks.
+  </para>
+  <para>
+Normally any object that creates a block area will have an associated
+layout manager. Other cases are tables and lists, these objects will
+also have layout managers that will manager the group of layout managers
+that make up the object.
+  </para>
+  <para>
+A layout manager is also able to determine height (min/max/optimum)
+and keep status. This will be used when organising the layout on
+a page. The manager will be able to determine the next place a break
+can be made and then be able to organise the height.
+  </para>
+  <para>
+A layout manager is essentially a bridge between the formatting objects
+and the area tree. It will keep a list of line areas inside block areas.
+Each line area will contain a list of inline areas that is able to be
+adjusted if the need arises.
+  </para>
+  <para>
+The objects in the area tree that are organised by the manager will mostly
+contain the information about there layout such as spacing and keeps, this
+information will be thrown away once the layout for a page is finalised.
+  </para>
+</section>
+
+ <section>
+ <title>Creating Managers</title>
+  <para>
+The managers are created by the page sequence. The top level manager
+is the Page manager. This asks the flow to add all managers in this
+page sequence.
+  </para>
+  <para>
+For block level objects they have a layout manager. Neutral objects
+don't represent any areas but are used to contain a block level
+area and as such these objects will ask the appropriate child to
+create a layout manager.
+  </para>
+  <para>
+Any nested block areas or inline areas may be handled by the layout
+manager at a later stage.
+  </para>
+</section>
+
+ <section>
+ <title>Using Managers</title>
+  <para>
+Block area layout managers are used to create a block area, other block
+level managers may ask their child layout managers to create block areas
+which are then added to the area tree (subset).
+  </para>
+  <para>
+A manager is used to add areas to a page until the page is full,
+then the manages contain all the information necessary to make
+the decision about page break and spacing. A manager can split an
+area that it has created will keep a status about what has been
+added to the current area tree.
+  </para>
+</section>
+
+ <section>
+ <title>Page Layout</title>
+  <para>
+Once the Page layout manager, belonging to the page sequence, is ready
+then we can start laying out each page. The page sequence will create
+the current page to put the page data, the next page and if it exists
+a last page.
+  </para>
+  <para>
+The current page will have the areas added to it from the block layout
+managers. The next page will be used when splitting a block that goes
+over the page break. Note: any page break overrides the layout decided
+here. The last page will be necessary if the last block area is added
+to this page. The size of the last page will be considered and the
+areas will be added to the last page instead.
+  </para>
+  <para>
+The first step is to add areas to the current page until the area is full
+and the lines of the last block area contain at least n(orphans) and at least
+n(orphans) + n(widows) in total. This will only be relevant for areas at
+the start or end of a particular reference area.
+  </para>
+  <para>
+    <mediaobject>
+  <imageobject>
+   <imagedata fileref = "page.svg"/>
+        </imageobject>
+     </mediaobject>
+  </para>
+  <para>
+The spacing between the areas (including spacing in block areas inside
+an inline-container) will be set to the minimum values. This will allow
+the page to have at least all the information it needs to organise the
+page properly.
+  </para>
+  <para>
+The spacing and keep information is stored so that the area positions
+and sizes can be adjusted.
+  </para>
+ <section>
+ <title>Balancing Page</title>
+  <para>
+The page is vertically justified so that it distributes the areas
+on the page for the best result when considering keeps and spacing.
+  </para>
+ <section>
+ <title>Finding Break</title>
+  <para>
+First the keeps are checked. The available space on the page may have
+changed due to the presence of before floats or footnotes. The page break
+will need to be at a height &lt;= the available space on the page.
+  </para>
+  <para>
+A page break should be made at the first available position that
+has the lowest keep value when searching from the bottom. Once the first
+possible break is found then the next possible break, with equally low
+keep value, is considered. If the height of the page is closer to the
+optimal spacing then this break will be used instead.
+  </para>
+  <para>
+Keep values include implicit and explicit values when trying to
+split a block area into more than one area. Implicit keeps may
+be such things as widows/orphans.
+  </para>
+  <para>
+If the page contains before floats or footnotes then as each area or line
+area is removed the float/footnote should also be removed. This will
+change the available space and is a one way operation. The footnote
+should be removed first as a footnote may be placed on the next page.
+The lowest keep value may need to be reassessed as each conditional
+area is removed.
+  </para>
+  <para>
+The before float and footnote regions are managed so that the separator
+regions will be present if it contains at least one area.
+	</para>
+</section>
+ <section>  
+ <title>Optimising</title>
+  <para>
+Once the areas for the page are finalised then the spacing will
+need to be adjusted. The available height on the page is compared
+with the min and max spacing. All of the spacing in all the areas
+on the page is then adjusted by the appropriate percentage value.
+  </para>
+</section>
+
+ <section>
+ <title>Multi-Column Pages</title>
+  <para>
+In the case of multi-column pages the column breaks and eventually
+the page break must be found in a slightly different way.
+  </para>
+  <para>
+The columns need to be layed out completely from first to last but
+this can only be done after a rough estimate of all the elements
+on the page in case of before floats or footnotes.
+  </para>
+  <para>
+So first the complete page is layed out with all columns filled
+with areas and the spacing at a minimum. Then if there are any
+before floats or footnotes then the availabe space is adjusted.
+Then each the best break is found for each column starting from
+the first column. If any before floats or footnotes are removed
+as a result of the new breaks and optimised spacing then all the
+columns should still be layed out for the same column height.
+  </para>
+</section>
+
+</section>
+</section>
+
+ <section>
+ <title>Completing Page</title>
+  <para>
+After the region body has been finished the static areas can be
+layed out. The width of the static area is set and the height is
+inifinite, that is all block areas should be placed in the area
+and their visibility is controlled be other factors.
+  </para>
+  <para>
+The area tree for the region body will contain the information
+about markers that may be necessary for the retrieve marker.
+  </para>
+  <para>
+The ordering of the area tree must be adjusted so that the areas are
+before, start, body, end and after in that order. The body region
+should be in the order before float, main then footnote.
+  </para>
+</section>
+
+ <section>
+ <title>Line Areas</title>
+  <para>
+Creating a line areas uses a similair concept. Each inline area
+is placed across the available space until there is no room left.
+The line is then split by considering all keeps and spacing.
+  </para>
+  <para>
+Each word (group of adjacent character inline areas) will have keeps
+based on hyphenation. The line break is at the lowest keep value
+starting from the end of the line.
+  </para>
+  <para>
+Once a line has been layed out for a particular width
+then that line is fixed for the page (except for unresolved
+page references).
+  </para>
+</section>
+
+ <section>
+ <title>Before Floats and Footnotes</title>
+  <para>
+The before float region and footnote region are handled by the page
+layoutmanger. These regions will handle the addition and removal
+of the separator regions when before floats/footnotes area added
+and removed.
+  </para>
+</section>
+
+ <section>
+ <title>Side Floats</title>
+  <para>
+If a float anchor is present in a particular line area then the available
+space for that line (and other in the block) will be reduced. The side float
+adds to the height of the block area and this height also depends
+on the clear value of subsequent blocks. The keep status of the block is
+also effected as there must be enough space on the page to fit the
+side float.
+  </para>
+  <para>
+    <mediaobject>
+  <imageobject>
+   <imagedata fileref = "float.svg"/>
+        </imageobject>
+     </mediaobject>
+  </para>
+</section>
+
+ <section>
+ <title>Unresolved Areas</title>
+  <para>
+Once the layout of the page is complete there may be unresolved areas.
+  </para>
+  <para>
+Page number citations and links may require following pages to be
+layed out before they can be resolved. These will remain in the
+area tree as unresolved areas.
+  </para>
+  <para>
+As each page is completed the list of unresolved id's will be checked
+and if the id can be resolved it will be. Once all id's are resolved
+then the page can be rendered.
+  </para>
+  <para>
+Each page contains a map of all unresolved id's and the corresponding
+areas.
+  </para>
+  <para>
+In the case of page number citations. The areas reserves the equivalent
+of 3 number nines in the current font. When the area is resolved
+then the area is adjusted to its proper size and the line area is
+re-aligned to accomodate the change.
+  </para>
+</section>
+
+ <section>
+ <title>ID and Link Areas</title>
+  <para>
+Any formatting object that has an ID or any inline link defines an area
+that will be required when rendering and resolving id references.
+  </para>
+  <para>
+This area is stored in the parent area and may be a shape that exists
+in more than one page, for example over a page break. This shape consists
+of the boundary of all inline (or block) areas that the shape is defined
+for.
+  </para>
+</section>
+
+ <section>
+ <title>Inline Areas</title>
+  <para>
+This is the definition of all inline areas that will exist in the
+area.
+  </para>
+ <section>
+ <title>Fixed Areas</title>
+  <para>
+instream-foreign-object, external-graphic, inline-container
+  </para>
+  <para>  
+These areas have a fixed width and height. They also have a viewport.
+  </para>
+</section>
+ <section>
+ <title>Stretch Areas</title>
+  <para>
+leader, inline space
+  </para>
+  <para>
+These areas have a fixed height but the width may vary.
+  </para>
+</section>
+ <section>
+ <title>Character Areas</title>
+  <para>
+character
+  </para>
+  <para>
+This is an simple character that has fixed properties according to
+the current font. There are implicit keeps with adjacent characters.
+  </para>
+</section>
+ <section>
+ <title>Anchor Areas</title>
+  <para>
+float anchor, footnote anchor
+  </para>
+  <para>
+This area has no size. It keeps the position for footnotes and floats
+and has a keep with the associated inline area.
+  </para>
+</section>
+ <section>
+ <title>Unresolved Page Numbers</title>
+  <para>
+page-number-citation
+  </para>
+  <para>
+A page number area that needs resolving, behaves as a character and
+has the space of 3 normal characters reserved. The size will adjust
+when the value is resolved.
+  </para>
+</section>
+
+</section>
+
+ <section>
+ <title>Block Areas</title>
+  <para>
+The block area has info about the following:
+       <itemizedlist>
+       <listitem><para>
+all anchors including which lines they are on
+       </para></listitem>
+       <listitem><para>
+unresolved page references with line info
+       </para></listitem>
+       <listitem><para>
+id and link areas
+       </para></listitem>
+       <listitem><para>
+height (min/max/optimum) or area including floats
+       </para></listitem>
+       <listitem><para>
+holds space before/after and keep information
+       </para></listitem>
+       <listitem><para>
+widows and orphans
+       </para></listitem>
+       </itemizedlist>
+  </para>
+  <para>
+Once the layout has been finalised then this information can be
+discarded.
+  </para>
+</section>
+
+ <section>
+ <title>Page Areas</title>
+  <para>
+Contains inforamtion about all the block areas in the body,
+before area and footer area.
+  </para>
+  <para>
+Has a list of the unresolved page references and a list of id refences
+that can be used to obtain the area associated with that id.
+  </para>
+</section>
+
+ <section>
+ <title>Test Cases</title>
+  <para>
+Here a few layout possibilities areas explored to determine how the
+layout process will handle these situations.
+  </para>
+ <section>
+ <title>Simple Pages</title>
+  <para>
+All blocks (including nested) are placed on the page with minimum spacing
+and the last block has the minimum number of lines past the page end.
+The lowest keep value is then found within the body area limits. Then the next
+equally low keep is found to determine if the spacing will be closer to
+the optimum values.
+  </para>
+ </section>
+ <section>
+ <title>Before Floats/Footnotes</title>
+  <para>
+After filling the page with the block areas then the new body height
+is used to find the best position to break. Before each line area or block
+area is remove any associated before floats and footnotes are removed.
+This will then adjust the available space on the page and may allow
+for a different breaking point. Areas are removed towards the new
+breaking point until the areas fit on the page. When finding the
+optimum spacing the removal of before floats and footnotes must also
+be considered.
+  </para>
+ </section>
+ <section>
+ <title>Multicolumn</title>
+  <para>
+First the page is filled with all columns for the intial page area.
+Then each column is adjusted for the new height starting from the
+first column. The best break for the column is found then the next
+column is considered, any left over areas a pre-pended to the next
+column. Once all the columns are finished then all the columns are
+adjusted to fit in the same height columns. This handles the situation
+where before floats or footnotes may have been removed.
+  </para>
+ </section>
+ <section>
+ <title>Last Page</title>
+  <para>
+If in the process of adding areas to a page it is found that there
+are no more areas in the flow then this page will need to be changed to
+the last page (if applicable). The areas are then placed on a last
+page.
+  </para>
+ </section>
+
+</section>
+
+</section>
diff --git a/docs/design/messaging.gif b/docs/design/messaging.gif
deleted file mode 100644
index 88b700064..000000000
--- a/docs/design/messaging.gif
+++ /dev/null
diff --git a/docs/design/optimise.xml b/docs/design/optimise.xml
new file mode 100644
index 000000000..291481436
--- /dev/null
+++ b/docs/design/optimise.xml
@@ -0,0 +1,37 @@
+<?xml version = "1.0" encoding = "UTF-8"?>
+<section id="optimise">
+ <title>Process Optimisations</title>
+	<para>
+FOP should be able to handle very large documents. A document can be
+supplied using SAX and the information should be passed entirely through
+the system, from fo elements to rendered output as soon as possible.
+  </para>
+  <para>
+A top level block area, immediately below the flow, can be added to the
+page layout as soon as the element is complete.
+  </para>
+  <para>
+The fo elements used to construct a page can be discarded as soon as the
+layout for the page is complete. Some information may be stored in the
+area tree of the page in order to handle unresolved page references
+and links.
+  </para>
+  <para>
+Once the layout of a page has been completed, all elements are fully
+resolved, then the page can be rendered. Some renderers may support
+out of order rendering of pages.
+  </para>
+  <para>
+The main problem that will remain is that any page with forward
+references will need to be stored until the refence is resolved.
+This means that the information contained in the page should be 
+as minimal as possible.
+  </para>
+  <para>
+Line areas can be optimised once the layout for the line has
+been finalised. Consecutive characters with the same properties
+can be combined into a "word" to hold the infomration with
+limited overhead.
+  </para>
+
+</section>
diff --git a/docs/design/page.svg b/docs/design/page.svg
new file mode 100755
index 000000000..48b4a941a
--- /dev/null
+++ b/docs/design/page.svg
@@ -0,0 +1,50 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20001102//EN"
+	"http://www.w3.org/TR/2000/CR-SVG-20001102/DTD/svg-20001102.dtd">
+<svg width="440" height="250">
+	<rect x="5" y="5" width="151" height="239" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="260" y="6" width="151" height="239" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<polygon
+		points="219.67,112 247,127 219.67,142 219.67,132.882 163,132.882 163,120.824 219.67,120.824" style="
+		stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M4.5 31 L155.5 31" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(0,0,0);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M260.5 32 L411.5 32" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(0,0,0);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M5.5 222 L156.5 222" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(0,0,0);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M261.5 220 L412.5 220" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(0,0,0);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M23.5 32 L23.5 222" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(0,0,0);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M133.5 32 L133.5 222" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(0,0,0);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M282.5 31 L282.5 221" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(0,0,0);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M389.5 31 L389.5 221" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(0,0,0);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="283" y="33" width="106" height="32" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(58,53,255);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="283" y="71" width="106" height="27" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(58,53,255);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="283" y="107" width="106" height="28" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(58,53,255);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="283" y="143" width="106" height="32" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(58,53,255);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="282" y="187" width="108" height="13" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(58,53,255);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<rect x="282" y="208" width="108" height="27" rx="0" ry="0" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-width:1;stroke-opacity:1;stroke:rgb(58,53,255);
+		fill-opacity:0;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M282.5 50 L389.5 50" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(36,239,21);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<path d="M283.5 195 L390.5 195" style="stroke-miterlimit:4;stroke-linejoin:miter;stroke-linecap:round;stroke-width:1;stroke-opacity:1;
+		stroke:rgb(36,239,21);fill-opacity:1;fill:rgb(0,0,0);opacity:1"/>
+	<text x="361" y="46" style="font-family:Arial;font-size:12;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:1;fill:rgb(0,0,0);opacity:1">Before Float</text>
+	<text x="379.157" y="211" style="font-family:Arial;font-size:12;stroke-width:1;stroke-opacity:1;stroke:rgb(0,0,0);
+		fill-opacity:1;fill:rgb(0,0,0);opacity:1">Footnote</text>
+</svg>
+
diff --git a/docs/design/pagination.gif b/docs/design/pagination.gif
deleted file mode 100644
index a82658f70..000000000
--- a/docs/design/pagination.gif
+++ /dev/null
diff --git a/docs/design/pdf.gif b/docs/design/pdf.gif
deleted file mode 100644
index 324424c1a..000000000
--- a/docs/design/pdf.gif
+++ /dev/null
diff --git a/docs/design/render_pdf.gif b/docs/design/render_pdf.gif
deleted file mode 100644
index 79dc3aa60..000000000
--- a/docs/design/render_pdf.gif
+++ /dev/null
diff --git a/docs/design/useragent.xml b/docs/design/useragent.xml
new file mode 100644
index 000000000..5900e97db
--- /dev/null
+++ b/docs/design/useragent.xml
@@ -0,0 +1,146 @@
+<?xml version = "1.0" encoding = "UTF-8"?>
+<section id="useragent-use">
+ <title>Usage</title>
+	<para>
+The user agent is used by the formatting process to determine
+certain user definable values.
+  </para>
+  <para>
+It will enable the customisation of values for generating and
+rendering the document.
+  </para>
+  <para>
+The user agent must be available to the layout processor and
+the renderer. Users can supply their own user agent or use
+the default one for a particular renderer.
+	</para>
+
+  <para>
+Standard Features:
+       <itemizedlist>
+       <listitem><para>
+adjusting length values (eg. for borders) to renderable values
+       </para></listitem>
+       <listitem><para>
+available fonts
+       </para></listitem>
+       <listitem><para>
+converting cm/in to pt (dpi)
+       </para></listitem>
+       <listitem><para>
+active state for multi properties
+       </para></listitem>
+       <listitem><para>
+title, used to identify a set of pages (in a page sequence)
+       </para></listitem>
+       <listitem><para>
+the width (in inline-progression-dimension) of a character with
+trea-word-as-space true
+       </para></listitem>
+       <listitem><para>
+maximum space used by conditional areas from region-reference-area
+       </para></listitem>
+       <listitem><para>
+if there should be "hot links" to before floats or footnotes
+       </para></listitem>
+       <listitem><para>
+when to clear side floats if space in inline-progression-dimension
+is not enough
+       </para></listitem>
+       <listitem><para>
+placement of left over footnotes on a page with a region-body
+       </para></listitem>
+       <listitem><para>
+using color property as border colour
+       </para></listitem>
+       <listitem><para>
+interpretting all border styles (except outset) as solid
+       </para></listitem>
+       <listitem><para>
+thin, medium and thick values for border width
+       </para></listitem>
+       <listitem><para>
+initial font-family value
+       </para></listitem>
+       <listitem><para>
+absolute font sizes (eg, xx-small, x-small etc.)
+       </para></listitem>
+       <listitem><para>
+relative font sizes (eg. larger, smaller)
+       </para></listitem>
+       <listitem><para>
+small caps simulation
+       </para></listitem>
+       <listitem><para>
+font weight mapping
+       </para></listitem>
+       <listitem><para>
+baseline info for a font if not available
+       </para></listitem>
+       <listitem><para>
+determining sub/superscript when another baseline is dominant
+       </para></listitem>
+       <listitem><para>
+scaling method for external-graphic and instream-foreign-object
+       </para></listitem>
+       <listitem><para>
+the width of a replaced element
+       </para></listitem>
+       <listitem><para>
+"normal" line height value
+       </para></listitem>
+       <listitem><para>
+text alignment (stretching the line with letter and word spacing)
+       </para></listitem>
+       <listitem><para>
+text transform
+       </para></listitem>
+       <listitem><para>
+initial color
+       </para></listitem>
+       <listitem><para>
+rendering intent of auto
+       </para></listitem>
+       <listitem><para>
+dot character for leader
+       </para></listitem>
+       <listitem><para>
+line breaking with leaders, use optimum length when breaking the line
+       </para></listitem>
+       <listitem><para>
+page height/width of auto
+       </para></listitem>
+       <listitem><para>
+left and right caption widths
+       </para></listitem>
+       <listitem><para>
+glyph orientation vertical of auto
+       </para></listitem>
+       <listitem><para>
+rendering processor of content-type (mime type)
+       </para></listitem>
+       </itemizedlist>
+  </para>
+
+  <para>
+Interactive Features:
+       <itemizedlist>
+       <listitem><para>
+inline and block scroll amount
+       </para></listitem>
+       <listitem><para>
+dynamic effects, links and property sets
+       </para></listitem>
+       <listitem><para>
+initial "pause-after", "pause-before" and "voice-family" value
+       </para></listitem>
+       <listitem><para>
+treating fixed as scroll on background attachement
+       </para></listitem>
+       <listitem><para>
+media usage of auto
+       </para></listitem>
+       </itemizedlist>
+  </para>
+
+</section>