From eb328349433beebe9441d6b89c7a554e11f0f198 Mon Sep 17 00:00:00 2001
From: Keiron Liddle <keiron@apache.org>
Date: Mon, 2 Dec 2002 10:19:43 +0000
Subject: [PATCH] initial conversion of alt.design docs

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195701 13f79535-47bb-0310-9956-ffa450edef68
---
 .../alt.design/AbsolutePosition.png.xml       |  21 +
 .../alt.design/BorderCommonStyle.png.xml      |  20 +
 .../xdocs/design/alt.design/PropNames.png.xml |  19 +
 .../design/alt.design/Properties.png.xml      |  20 +
 .../design/alt.design/PropertyConsts.png.xml  |  20 +
 .../design/alt.design/VerticalAlign.png.xml   |  20 +
 .../design/alt.design/alt.properties.xml      | 172 ++++
 .../content/xdocs/design/alt.design/book.xml  |  37 +
 .../design/alt.design/classes-overview.xml    | 203 ++++
 .../design/alt.design/compound-properties.xml | 218 +++++
 .../xdocs/design/alt.design/coroutines.xml    | 118 +++
 .../xdocs/design/alt.design/footnotes.xml     | 140 +++
 .../xdocs/design/alt.design/galleys.xml       | 216 +++++
 .../content/xdocs/design/alt.design/index.xml |  84 ++
 .../content/xdocs/design/alt.design/keeps.xml | 110 +++
 .../design/alt.design/properties-classes.xml  | 143 +++
 .../design/alt.design/propertyExpressions.xml | 343 +++++++
 .../xdocs/design/alt.design/spaces.xml        | 179 ++++
 .../xdocs/design/alt.design/traits.xml        | 369 +++++++
 .../design/alt.design/user-agent-refs.xml     | 909 ++++++++++++++++++
 .../xdocs/design/alt.design/xml-parsing.xml   | 228 +++++
 .../content/xdocs/design/book.xml             |   4 +
 22 files changed, 3593 insertions(+)
 create mode 100644 src/documentation/content/xdocs/design/alt.design/AbsolutePosition.png.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/BorderCommonStyle.png.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/PropNames.png.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/Properties.png.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/PropertyConsts.png.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/VerticalAlign.png.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/alt.properties.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/book.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/classes-overview.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/compound-properties.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/coroutines.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/footnotes.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/galleys.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/index.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/keeps.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/properties-classes.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/propertyExpressions.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/spaces.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/traits.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/user-agent-refs.xml
 create mode 100644 src/documentation/content/xdocs/design/alt.design/xml-parsing.xml

diff --git a/src/documentation/content/xdocs/design/alt.design/AbsolutePosition.png.xml b/src/documentation/content/xdocs/design/alt.design/AbsolutePosition.png.xml
new file mode 100644
index 000000000..46a6999a3
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/AbsolutePosition.png.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>AbsolutePosition diagram</title>
+    <authors>
+      <person id="pbw" name="Peter B. West"
+        email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Properties$AbsolutePosition</title>
+      <figure src="AbsolutePosition.png" alt="AbsolutePosition diagram"/>
+    </section>
+
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/BorderCommonStyle.png.xml b/src/documentation/content/xdocs/design/alt.design/BorderCommonStyle.png.xml
new file mode 100644
index 000000000..e9fad3d77
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/BorderCommonStyle.png.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>BorderCommonStyle diagram</title>
+    <authors>
+      <person id="pbw" name="Peter B. West"
+        email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Properties$BorderCommonStyle</title>
+      <figure src="BorderCommonStyle.png" alt="BorderCommonStyle diagram"/>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/PropNames.png.xml b/src/documentation/content/xdocs/design/alt.design/PropNames.png.xml
new file mode 100644
index 000000000..6f552009b
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/PropNames.png.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>..fo.PropNames diagram</title>
+      <person id="pbw" name="Peter B. West"
+        email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>PropNames.class</title>
+      <figure src="PropNames.png" alt="PropNames.class diagram"/>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/Properties.png.xml b/src/documentation/content/xdocs/design/alt.design/Properties.png.xml
new file mode 100644
index 000000000..8bcf88943
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/Properties.png.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>..fo.Properties diagram</title>
+    <authors> 
+      <person id="pbw" name="Peter B. West"
+        email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Properties.class</title>
+      <figure src="Properties.png" alt="Properties.class diagram"/>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/PropertyConsts.png.xml b/src/documentation/content/xdocs/design/alt.design/PropertyConsts.png.xml
new file mode 100644
index 000000000..2e2763026
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/PropertyConsts.png.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>..fo.PropertyConsts diagram</title>
+    <authors>
+      <person id="pbw" name="Peter B. West"
+        email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>PropertyConsts.class</title>
+      <figure src="PropertyConsts.png" alt="PropertyConsts.class diagram"/>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/VerticalAlign.png.xml b/src/documentation/content/xdocs/design/alt.design/VerticalAlign.png.xml
new file mode 100644
index 000000000..400d43cf7
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/VerticalAlign.png.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>VerticalAlign diagram</title>
+    <authors>
+      <person id="pbw" name="Peter B. West"
+        email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Properties$VerticalAlign</title>
+      <figure src="VerticalAlign.png" alt="VerticalAlign diagram"/>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/alt.properties.xml b/src/documentation/content/xdocs/design/alt.design/alt.properties.xml
new file mode 100644
index 000000000..a1e7fcf09
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/alt.properties.xml
@@ -0,0 +1,172 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Implementing Properties</title>
+    <authors>
+       <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>An alternative properties implementation</title>
+      <note> 
+  The following discussion focusses on the relationship between
+  Flow Objects in the Flow Object tree, and properties.  There
+  is no (or only passing) discussion of the relationship between
+  properties and traits, and by extension, between properties
+  and the Area tree.  The discussion is illustrated with some
+  pseudo-UML diagrams.
+      </note>
+      <p>
+  Property handling is complex and expensive. Varying numbers of
+  properties apply to individual Flow Objects
+  <strong>(FOs)</strong> in the <strong>FO
+  tree </strong> but any property may effectively be
+  assigned a value on any element of the tree.  If that property
+  is inheritable, its defined value will then be available to
+  any children of the defining FO.
+      </p>
+      <note>
+  <em>(XSL 1.0 Rec)</em> <strong>5.1.4 Inheritance</strong>
+  ...The inheritable properties can be placed on any formatting
+  object.
+      </note>
+      <p>
+  Even if the value is not inheritable, it may be accessed by
+  its children through the <code>inherit</code> keyword or the
+  <code>from-parent()</code> core function, and potentially by
+  any of its descendents through the
+  <code>from-nearest-specified-value()</code> core function.
+      </p>
+      <p>
+  In addition to the assigned values of properties, almost every
+  property has an <strong>initial value</strong> which is used
+  when no value has been assigned.
+      </p>
+      <section>
+        <title>The history problem</title>
+      <p>
+  The difficulty and expense of handling properties comes from
+  this univeral inheritance possibility.  The list of properties
+  which are assigned values on any particular <em>FO</em>
+  element will not generally be large, but a current value is
+  required for each property which applies to the <em>FO</em>
+  being processed.
+      </p>
+      <p>
+  The environment from which these values may be selected
+  includes, for each <em>FO</em>, for each applicable property,
+  the value assigned on this <em>FO</em>, the value which
+  applied to the parent of this <em>FO</em>, the nearest value
+  specified on an ancestor of this element, and the initial
+  value of the property.
+      </p>
+      </section>
+      <section>
+        <title>Data requirement and structure</title>
+  <p>
+    This determines the minimum set of properties and associated
+    property value assignments that is necessary for the
+    processing of any individual <em>FO</em>.  Implicit in this
+    set is the set of properties and associated values,
+    effective on the current <em>FO</em>, that were assigned on
+    that <em>FO</em>.
+  </p>
+  <p>
+    This minimum requirement - the initial value, the
+    nearest ancestor specified value, the parent computed value
+    and the value assigned to the current element -
+    suggests a stack implementation.
+  </p>
+      </section>
+      <section>
+        <title>Stack considerations</title>
+  <p>
+    One possibility is to push to the stack only a minimal set
+    of required elements.  When a value is assigned, the
+    relevant form or forms of that value (specified, computed,
+    actual) are pushed onto the stack.  As long as each
+    <em>FO</em> maintains a list of the properties which were
+    assigned from it, the value can be popped when the focus of
+    FO processing retreats back up the <em>FO</em> tree.
+  </p>
+  <p>
+    The complication is that, for elements which are not
+    automatically inherited, when an <em>FO</em> is encountered
+    which does <strong>not</strong> assign a value to the
+    property, the initial value must either be already at the
+    top of the stack or be pushed onto the stack.
+  </p>
+  <p>
+    As a first approach, the simplest procedure may be to push a
+    current value onto the stack for every element - initial
+    values for non-inherited properties and the parental value
+    otherwise.  Then perform any processing of assigned values.
+    This simplifies program logic at what is hopefully a small
+    cost in memory and processing time.  It may be tuned in a
+    later iteration.
+  </p>
+  <section>
+    <title>Stack implementation</title>
+    <p>
+      Initial attempts at this implementation have used
+      <code>LinkedList</code>s as the stacks, on the assumption
+      that
+    </p>
+    <sl>
+      <!-- one of (dl sl ul ol li) -->
+      <li>random access would not be required</li>
+      <li>
+        pushing and popping of list elements requires nearly
+        constant (low) time
+      </li>
+      <li> no penalty for first addition to an empty list</li>
+      <li>efficient access to both bottom and top of stack</li>
+    </sl>
+    <p>
+      However, it may be required to perform stack access
+      operations from an arbitrary place on the stack, in which
+      case it would probably be more efficient to use
+      <code>ArrayList</code>s instead.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>Class vs instance</title>
+  <p>
+    An individual stack would contain values for a particular
+    property, and the context of the stack is the property class
+    as a whole.  The property instances would be represented by
+    the individual values on the stack.  If properties are to be
+    represented as instantiations of the class, the stack
+    entries would presumably be references to, or at least
+    referenced from, individual property objects.  However, the
+    most important information about individual property
+    instances is the value assigned, and the relationship of
+    this property object to its ancestors and its descendents.
+    Other information would include the ownership of a property
+    instance by a particular <em>FO</em>, and, in the other
+    direction, the membership of the property in the set of
+    properties for which an <em>FO</em> has defined values.
+  </p>
+  <p>
+    In the presence of a stack, however, none of this required
+    information mandates the instantiation of properties.  All
+    of the information mentioned so far can be effectively
+    represented by a stack position and a link to an
+    <em>FO</em>.  If the property stack is maintained in
+    parallel with a stack of <em>FOs</em>, even that link is
+    implicit in the stack position.
+  </p>
+      </section>
+      <p>
+  <strong>Next:</strong> <link href="classes-overview.html"
+  >property classes overview.</link>
+      </p>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/book.xml b/src/documentation/content/xdocs/design/alt.design/book.xml
new file mode 100644
index 000000000..2324a6d33
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/book.xml
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-cocoon2/src/documentation/xdocs/dtd/book-cocoon-v10.dtd">
+
+<book software="FOP"
+    title="ALT Design"
+    copyright="@year@ The Apache Software Foundation"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+
+    <menu label="Index">
+      <menu-item label="FOP Home" href="../../index.html"/>
+      <menu-item label="Design" href="../index.html"/>
+    </menu>
+    <menu label="About">
+      <menu-item label="Alt Design" href="index.html"/>
+      <menu-item label="co-routines" href="coroutines.html"/>
+      <menu-item label="galleys" href="galleys.html"/>
+      <menu-item label="footnotes" href="footnotes.html"/>
+      <menu-item label="keeps" href="keeps.html"/>
+      <menu-item label="space-specifiers" href="spaces.html"/>
+      <menu-item label="alt.properties" href="alt.properties.html"/>
+      <menu-item label="Classes overview" href="classes-overview.html"/>
+      <menu-item label="Properties classes" href="properties-classes.html"/>
+      <menu-item label="Properties" href="Properties.png.html"/>
+      <menu-item label="PropertyConsts" href="PropertyConsts.png.html"/>
+      <menu-item label="PropNames" href="PropNames.png.html"/>
+      <menu-item label="AbsolutePosition" href="AbsolutePosition.png.html"/>
+      <menu-item label="VerticalAlign" href="VerticalAlign.png.html"/>
+      <menu-item label="BorderCommonStyle" href="BorderCommonStyle.png.html"/>
+      <menu-item label="XML parsing" href="xml-parsing.html"/>
+      <menu-item label="Property parsing" href="propertyExpressions.html"/>
+      <menu-item label="Compound properties" href="compound-properties.html"/>
+      <menu-item label="Traits" href="traits.html"/>
+      <menu-item label="User agent refs" href="user-agent-refs.html"/>
+    </menu>
+</book>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/classes-overview.xml b/src/documentation/content/xdocs/design/alt.design/classes-overview.xml
new file mode 100644
index 000000000..b5e2be845
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/classes-overview.xml
@@ -0,0 +1,203 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Property classes overview</title>
+    <authors>
+      <person id="pbw" name="Peter B. West"
+        email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Classes overview</title>
+      <section>
+        <title>The class of all properties</title>
+  <p>
+    If individual properties can have a "virtual reality" on the
+    stack, where is the stack itself to be instantiated?  One
+    possibility is to have the stacks as <code>static</code>
+    data structures within the individual property classes.
+    However, the reduction of individual property instances to
+    stack entries allows the possibility of further
+    virtualization of property classes.  If the individual
+    properties can be represented by an integer, i.e. a
+    <code>static final int</code>, the set of individual
+    property stacks can be collected together into one array.
+    Where to put such an overall collection?  Creating an 
+    über-class to accommodate everything that applies to
+    property classes as a whole allows this array to be defined
+    as a <em><code>static final</code> something[]</em>.
+  </p>
+      </section>
+      <section>
+        <title>The overall property classes</title>
+  <p>
+    This approach has been taken for the experimental code.
+    Rather than simply creating a overall class containing
+    common elements of properties and acting as a superclass,
+    advantage has been taken of the facility for nesting of
+    top-level classes.  All of the individual property classes
+    are nested within the <code>Properties</code> class.
+    This has advantages and disadvantages.
+  </p>
+  <dl>
+    <dt>Disadvantages</dt>
+    <dd>
+      The file becomes extremely cumbersome.  This can cause
+      problems with "intelligent" editors.  E.g.
+      <em>XEmacs</em>  syntax highlighting virtually grinds to a
+      halt with the current version of this file.<br/> <br/>
+
+      Possible problems with IDEs.  There may be speed problems
+      or even overflow problems with various IDEs.  The current
+      version of this and related files had only been tried with
+      the <em>[X]Emacs JDE</em>  environment, without difficulties
+      apart from the editor speed problems mentioned
+      above.<br/> <br/>
+
+      Retro look and feel.  Not the done Java thing.<br/> <br/>
+    </dd>
+    <dt>Advantages</dt>
+    <dd>
+      Everything to do with properties in the one place (more or
+      less.)<br/> <br/>
+
+      Eliminates the need for a large part of the (sometimes)
+      necessary evil of code generation.  The One Big File of
+      <code>foproperties.xml</code>, with its ancillary xsl, is
+      absorbed into the One Bigger File of
+      <code>Properties.java</code>.  The huge advantage of this
+      is that it <strong>is</strong>  Java.
+    </dd>
+  </dl>
+      </section>
+      <section>
+        <title>The property information classes</title>
+  <p>
+    In fact, in order to keep the size of the file down to more
+    a more manageable level, the property information classes of
+    static data and methods have been split tentatively into
+    three:
+  </p>
+  <figure src="PropertyStaticsOverview.png" alt="Top level
+    property classes"/>
+  <dl>
+    <dt><link href="PropNames.html">PropNames</link></dt>
+    <dd>
+      Contains an array, <code>propertyNames</code>, of the names of
+      all properties, and a set of enumeration constants, one
+      for each property name in the <code>PropertyNames</code>
+      array.  These constants index the name of the properties
+      in <code>propertyNames</code>, and must be manually kept in
+      sync with the entries in the array. (This was the last of
+      the classes split off from the original single class;
+      hence the naming tiredness.)
+      <br/> <br/>
+    </dd>
+    <dt><link href="PropertyConsts.html">PropertyConsts</link></dt>
+    <dd>
+      Contains two basic sets of data:<br/>
+      Property-indexed arrays and property set
+      definitions.<br/> <br/>
+
+      <strong>Property-indexed arrays</strong>  are elaborations
+      of the property indexing idea discussed in relation to the
+      arrays of property stacks.  One of the arrays is<br/> <br/>
+
+      <code>public static final LinkedList[]
+      propertyStacks</code><br/> <br/>
+
+      This is an array of stacks, implemented as
+      <code>LinkedList</code>s, one for each property.<br/> <br/>
+
+      The other arrays provide indexed access to fields which
+      are, in most cases, common to all of the properties.  An
+      exception is<br/> <br/>
+
+      <code>public static final Method[]
+        complexMethods</code><br/> <br/>
+
+      which contains a reference to the method
+      <code>complex()</code>  which is only defined for
+      properties which have complex value parsing requirements.
+      It is likely that a similar array will be defined for
+      properties which allow a value of <em>auto</em>.<br/> <br/>
+
+      The property-indexed arrays are initialized by
+      <code>static</code>  initializers in this class.  The
+      <code>PropNames</code>  class and
+      <code>Properties</code>
+      nested classes are scanned in order to obtain or derive
+      the data necessary for initialization.<br/> <br/>
+
+      <strong>Property set definitions</strong>  are
+      <code>HashSet</code>s of properties (represented by
+      integer constants) which belong to each of the categories
+      of properties defined.  They are used to simplify the
+      assignment of property sets to individual FOs.
+      Representative <code>HashSet</code>s include
+      <em>backgroundProps</em>  and
+      <em>tableProps</em>.<br/> <br/>
+    </dd>
+    <dt><link href="Properties.html">Properties</link></dt>
+    <dd>
+       <br/>
+      This class contains only sets of constants for use by the
+      individual property classes, but it also importantly
+      serves as a container for all of the property classes, and
+      some convenience pseudo-property classes.<br/> <br/>
+
+      <strong>Constants sets</strong>  include:<br/> <br/>
+
+      <em>Datatype constants</em>. A bitmap set of
+      integer constants over a possible range of 2^0 to 2^31
+      (represented as -2147483648).  E.g.<br/>
+      INTEGER = 1<br/>
+      ENUM = 524288<br/> <br/>
+      Some of the definitions are bit-ORed
+      combinations of the basic values.  Used to set the
+      <em>dataTypes</em>  field of the property
+      classes.<br/> <br/>
+
+      <em>Trait mapping constants</em>. A bitmap set of
+      integer constants over a possible range of 2^0 to 2^31
+      (represented as -2147483648), representing the manner in
+      which a property maps into a <em>trait</em>.  Used to set
+      the <code>traitMapping</code>  field of the property
+      classes.<br/> <br/>
+
+      <em>Initial value constants</em>. A sequence of
+      integer constants representing the datatype of the initial
+      value of a property.  Used to set the
+      <code>initialValueType</code>  field of the property
+      classes.<br/> <br/>
+
+      <em>Inheritance value constants</em>. A sequence
+      of integer constants representing the way in which the
+      property is normally inherited.  Used to set the
+      <code>inherited</code>  field of the property
+      classes.<br/> <br/>
+
+      <strong>Nested property classes</strong>.  The
+      <em>Properties</em>  class serves as the holding pen for
+      all of the individual property classes, and for property
+      pseudo-classes which contain data common to a number of
+      actual properties, e.g. <em>ColorCommon</em>.
+    </dd>
+  </dl>
+      </section>
+      <p>
+  <strong>Previous:</strong> <link href=
+  "alt.properties.html" >alt.properties</link>
+      </p>
+      <p>
+  <strong>Next:</strong> <link href=
+  "properties-classes.html" >Properties classes</link>
+      </p>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/compound-properties.xml b/src/documentation/content/xdocs/design/alt.design/compound-properties.xml
new file mode 100644
index 000000000..bd326a4da
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/compound-properties.xml
@@ -0,0 +1,218 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Compound properties</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Compound properties in XSLFO</title>
+      <table>
+  <tr>
+    <th>Property type</th> 
+    <th>Section</th>
+    <th>Inherited</th>
+    <th>'inherit'</th>
+  </tr>
+  <tr>
+    <th>&lt;length-range&gt;</th>
+  </tr>
+  <tr>
+    <th>minimum</th>
+  </tr>
+  <tr>
+    <th>optimum</th>
+  </tr>
+  <tr>
+    <th>maximum</th>
+  </tr>
+  <tr>
+    <td>block-progression-dimension</td>
+    <td>7.14.1</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>inline-progression-dimension</td>
+    <td>7.14.5</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>leader-length</td>
+    <td>7.21.4</td>
+    <td>yes</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <th>&lt;length-conditional&gt;</th>
+  </tr>
+  <tr>
+    <th>length</th>
+  </tr>
+  <tr>
+    <th>conditionality</th>
+  </tr>
+  <tr>
+    <td>border-after-width</td>
+    <td>7.7.12</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>border-before-width</td>
+    <td>7.7.9</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+   <tr>
+    <td>border-end-width</td>
+    <td>7.7.18</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+   <tr>
+    <td>border-start-width</td>
+    <td>7.7.15</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>padding-after</td>
+    <td>7.7.32</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>padding-before</td>
+    <td>7.7.31</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+   <tr>
+    <td>padding-end</td>
+    <td>7.7.34</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+   <tr>
+    <td>padding-start</td>
+    <td>7.7.33</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <th>&lt;length-bp-ip-direction&gt;</th>
+  </tr>
+  <tr>
+    <th>block-progression-direction</th>
+  </tr>
+  <tr>
+    <th>inline-progression-direction</th>
+  </tr>
+  <tr>
+    <td>border-separation</td>
+    <td>7.26.5</td>
+    <td>yes</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <th>&lt;space&gt;</th>
+  </tr>
+  <tr>
+    <th>minimum</th>
+  </tr>
+  <tr>
+    <th>optimum</th>
+  </tr>
+  <tr>
+    <th>maximum</th>
+  </tr>
+  <tr>
+    <th>precedence</th>
+  </tr>
+  <tr>
+    <th>conditionality</th>
+  </tr>
+  <tr>
+    <td>letter-spacing</td>
+    <td>7.16.2</td>
+    <td>yes</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>line-height</td>
+    <td>7.15.4</td>
+    <td>yes</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>space-after</td>
+    <td>7.10.6</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>space-before</td>
+    <td>7.10.5</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>space-end</td>
+    <td>7.11.1</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>space-start</td>
+    <td>7.11.2</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>word-spacing</td>
+    <td>7.16.8</td>
+    <td>yes</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <th>&lt;keep&gt;</th>
+  </tr>
+  <tr>
+    <th>within-line</th>
+  </tr>
+  <tr>
+    <th>within-column</th>
+  </tr>
+  <tr>
+    <th>within-page</th>
+  </tr>
+  <tr>
+    <td>keep-together</td>
+    <td>7.19.3</td>
+    <td>yes</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>keep-with-next</td>
+    <td>7.19.4</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+  <tr>
+    <td>keep-with-previous</td>
+    <td>7.19.5</td>
+    <td>no</td>
+    <td>yes</td>
+  </tr>
+      </table>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/coroutines.xml b/src/documentation/content/xdocs/design/alt.design/coroutines.xml
new file mode 100644
index 000000000..31613ef52
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/coroutines.xml
@@ -0,0 +1,118 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Implementing co-routines</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Implementing Co-routines in FOP</title>
+      <p>
+  All general page layout systems have to solve the same
+  fundamental problem: expressing a flow of text with its own
+  natural structure as a series of pages corresponding to the
+  physical and logical structure of the output medium.  This
+  simple description disguises many complexities.  Version 1.0
+  of the Recommendation, in Section 3, <em>Introduction to
+  Formatting </em>, includes the following comments.
+      </p>
+      <note>
+  [Formatting] comprises several steps, some of which depend on
+  others in a non-sequential way.<br/> ...and...<br/>
+  [R]efinement is not necessarily a straightforward, sequential
+  procedure, but may involve look-ahead, back-tracking, or
+  control-splicing with other processes in the formatter.
+      </note>
+      <p>Section 3.1, <em>Conceptual Procedure</em>, includes:</p>
+      <note>
+  The procedure works by processing formatting objects. Each
+  object, while being processed, may initiate processing in
+  other objects. While the objects are hierarchically
+  structured, the processing is not; processing of a given
+  object is rather like a co-routine which may pass control to
+  other processes, but pick up again later where it left off.
+      </note>
+      <section>
+        <title>Application of co-routines</title>
+  <p>
+    If one looks only at the flow side of the equation, it's
+    difficult to see what the problem might be.  The ordering of
+    the elements of the flow is preserved in the area tree, and
+    where elements are in an hierarchical relationship in the
+    flow, they will generally be in an hierarchical relationship
+    in the area tree.  In such circumstances, the recursive
+    processing of the flow seems quite natural.
+  </p>
+  <p>
+    The problem becomes more obvious when one thinks about the
+    imposition of an unrelated page structure over the
+    hierarchical structure of the document content.  Take, e.g.,
+    the processing of a nested flow structure which, at a certain
+    point, is scanning text and generating line-areas, nested
+    within other block areas and possibly other line areas.  The
+    page fills in the middle of this process.  Processing at the
+    lowest level in the tree must now suspend, immediately
+    following the production of the line-area which filled the
+    page.  This same event, however, must also trigger the closing
+    and flushing to the area tree of every open area of which the last
+    line-area was a descendant.
+  </p>
+  <p>
+    Once all of these areas have been closed, some dormant process
+    or processes must wake up, flush the area sub-tree
+    representing the page, and open a new page sub-tree in the
+    area tree.  Then the whole nested structure of flow objects
+    and area production must be re-activated, at the point in
+    processing at which the areas of the previous page were
+    finalised, but with the new page environment.  The most
+    natural way of expressing the temporal relationship of these
+    processes is by means of co-routines.
+  </p>
+  <p>
+    Normal sub-routines (methods) display a hierarchical
+    relationship where process A suspends on invoking process B,
+    which on termination returns control to A which resumes from
+    the point of suspension. Co-routines instead have a parallel
+    relationship.  Process A suspends on invoking process B, but
+    process B also suspends on returning control to process A.  To
+    process B, this return of control appears to be an invocation
+    of process A.  When process A subsequently invokes B and
+    suspends, B behaves as though its previous invocation of A has
+    returned, and it resumes from the point of that invocation.
+    So control bounces between the two, each one resuming where it
+    left off.<br/><br/>
+    <strong>Figure 1</strong>
+  </p>
+  <figure src="coroutines.png" alt="Co-routine diagram"/>
+  <p>
+    For example, think of a page-production method working on a
+    complex page-sequence-master.
+  </p>
+  <source>
+    void makePages(...) {
+    ...
+      while (pageSequence.hasNext()) {
+        ...
+        page = generateNextPage(...);
+        boolean over = flow.fillPage(page);
+        if (over) return;
+      }
+    }
+  </source>
+  <p>
+    The <code>fillPage()</code> method, when it fills a page, will
+    have unfinished business with the flow, which it will want to
+    resume at the next call; hence co-routines.  One way to
+    implement them in Java is by threads synchronised on some
+    common argument-passing object.
+  </p>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/footnotes.xml b/src/documentation/content/xdocs/design/alt.design/footnotes.xml
new file mode 100644
index 000000000..16179c5f9
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/footnotes.xml
@@ -0,0 +1,140 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Implementing footnotes</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Implementing footnotes in FOP</title>
+      <p>  
+  Footnotes present difficulties for page layout primarily
+  because their point of invocation in the flow is different
+  from their point of appearance in the area tree.  All of the
+  content lines of a footnote may appear on the same page as its
+  invocation point, all may appear on a following page, or the
+  lines may be split over a page or pages.  (This characteristic
+  leads to another problem when a footnote overflows the last
+  page of flow content, but that difficulty will not be 
+  discussed here.)  This note considers some aspects of the
+  implementation of footnotes in a galley-based design.
+      </p>
+      <section>
+        <title>Footnotes and galleys</title>
+  <p>
+    In the structure described in the <link href=
+    "../galleys.html" >introduction to FOP galleys</link>,
+    footnotes would be pre-processed as galleys themselves, but
+    they would remain attached as subtrees to their points of 
+    invocation in the main text.  Allocation to a
+    footnote-reference-area would only occur in the resolution
+    to Area nodes. 
+  </p>
+  <p>
+    When footnotes are introduced, the communication between
+    galleys and layout manager, as mentioned <link href=
+    "../galleys.html#pre-processing" >above</link>, would be
+    affected.  The returned information would two b-p-d values: 
+    the primary line-area b-p-d impact and the footnote b-p-d
+    impact.  The distinction is necessary for two reasons; to
+    alert the layout manager to the first footnote of the page,
+    and because the footnote b-p-d will always impact the
+    main-reference-area b-p-d, whereas the primary inline-area
+    may not, e.g. in the case of multiple span-areas.
+  </p>
+      </section>
+      <section>
+        <title>Multiple columns and footnotes</title>
+  <note> 
+    A possible method for multi-column layout and balancing
+    with footnotes, using a galley-based approach.
+  </note>
+  <p>
+    This note assumes a galley, as discussed <link href=
+    "../galleys.html" >elsewhere</link>, flowing text with
+    footnotes and possibly other blocks into a possibly
+    multi-column area.  The logic of flowing into multiple
+    columns is trivially applied to a single column.  The galley
+    is manipulated within the context of the <em>layout
+    tree</em>.
+  </p>
+  <p>
+    Associated with the galley are two sets of data.
+    One contains the maps of all "natural" break-points and
+    the of all hyphenation break-points.  This set is
+    constructed at the time of construction of the galley and
+    is a constant for a given galley.  The second contains
+    dynamic data which represents one possible attempt to lay
+    out the galley.  There may be multiple sets of such data
+    to reflect varying attempts.  The data of this set are,
+    essentially, representations of line-areas, with the supporting
+    information necessary to determine these line-areas.
+  </p>
+  <p>
+    The line-area data includes the boundaries within the
+    galley of each line-area, the boundaries of each column
+    and the boundaries of the "page", or main area.  When a
+    line-area boundary occurs at a hyphenation point, a
+    "virtual hyphen" is assumed and accounted for in the
+    i-p-d.  As mentioned, individual footnote galleys will
+    hang from the parent galley.  The associated data of the
+    footnote galleys is similar: a once-only break-points map,
+    and one or more line-area maps.  No column boundaries are
+    required, but a page boundary is required at the end of
+    the last footnote or where a footnote breaks across a page
+    boundary.
+  </p>
+  <p>
+    A number of b-p-d values are also maintained.  For each
+    line-area, the b-p-d, the main area b-p-d increment, the
+    footnote b-p-d increment and the footnote's page-related
+    b-p-d increment are required.  The main-area b-p-d
+    increments for any particular line-area are dependent on
+    the column position of the line-area.  Total b-p-d's are
+    also kept: total footnote b-p-d, total main area b-p-d,
+    and totals for each column.<br/><br/>
+    <strong>Figure 1</strong> Columns before first footnote.
+  </p>
+  <figure src="initial-column-values.png" alt="Columns before
+    first footnote"/>
+      </section>
+      <section>
+        <title>Balancing columns</title>
+  <p>
+    <strong>Figure 2</strong> Adding a line area with first
+    footnote.
+  </p>
+  <figure src="line-area-5.png"
+    alt="Columns after adding first footnote"/>
+  <p>
+    Columns are balanced dynamically in the galley preliminary
+    layout.  While the galley retains its basic linear
+    structure, the accompanying data structures accomplish
+    column distribution and balancing.  As each line-area is
+    added, the columns are re-balanced.  <strong>N.B.</strong>
+    This re-balancing involves only some of the dynamic data
+    associated with the participating galley(s).  The data
+    structures associating breakpoints with the beginning and
+    end of individual line areas does not change in
+    re-balancing; only the association of line-area with column,
+    and, possibly, the various impact values for each line-area.
+    <br/><br/>
+    <strong>Figure 3</strong> Adding a line area with next
+    footnote.
+  </p>
+  <figure src="line-area-6.png"
+    alt="Columns after adding next footnote"/>
+      </section>
+      <section>
+        <title>Layout managers in the flow of control</title>
+  <note>To be developed.</note>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/galleys.xml b/src/documentation/content/xdocs/design/alt.design/galleys.xml
new file mode 100644
index 000000000..f7ae3cbb9
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/galleys.xml
@@ -0,0 +1,216 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Galleys</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Layout galleys in FOP</title>
+      <section>
+        <title>Galleys in Lout</title>
+  <p>
+    Jeffrey H. Kingston, in <link href =
+    "http://snark.niif.spb.su/~uwe/lout/design.pdf" ><em>The
+    Design and Implementation of the Lout Document Formatting
+    Language</em> Section 5</link>, describes the
+    <strong>galley</strong> abstraction which he implemented in
+    <em>Lout</em>.  A document to be formatted is a stream of
+    text and symbols, some of which are <strong>receptive 
+    symbols</strong>.  The output file is the first receptive
+    symbol; the formatting document is the first galley.  The
+    archetypical example of a receptive symbol is
+    <strong>@FootPlace</strong> and its corresponding galley
+    definition, <strong>@FootNote</strong>.
+  </p>
+  <p>
+    Each galley should be thought of as a concurrent process, and
+    each is associated with a semaphore (or synchronisation
+    object.)  Galleys are free to "promote" components into
+    receptive targets as long as</p>
+  <ul>
+    <li>
+      an appropriate target has been encountered in the file,
+    </li> 
+    <li>
+      the component being promoted contains no unresolved galley
+      targets itself, and
+    </li>
+    <li>
+      there is sufficient room for the galley component at the
+      target.
+    </li>
+  </ul>
+  <p>
+    If these conditions are not met, the galley blocks on its
+    semaphore.  When conditions change so that further progress
+    may be possible, the semaphore is signalled.  Note that the
+    galleys are a hierarchy, and that the processing and
+    promotion of galley contents happens <em>bottom-up</em>.
+  </p>
+      </section>
+      <section>
+        <title>Some features of galleys</title>
+  <p>
+    It is essential to note that galleys are self-managing; they
+    are effectively layout <em>bots</em> which require only a
+    receptive area.  If a galley fills a receptive area (say, at
+    the completion of a page), the galley will wait on its
+    semaphore, and will remain stalled until a new receptive
+    area is uncovered in the continued processing (say, as the
+    filled page is flushed to output and a new empty page is
+    generated.)
+  </p>
+  <p>
+    Difficulties with this approach become evident when there
+    are mutual dependencies between receptive areas which
+    require negotiation between the respective galleys, and, in
+    some cases, arbitrary deadlock breaking when there is no
+    clear-cut resolution to conflicting demands.  Footnote
+    processing and side floats are examples.  A thornier example
+    is table column layout in <em>auto</em> mode, where the
+    column widths are determined by the contents.  In
+    implementing galleys in FOP, these difficulties must be
+    taken into account, and some solutions proposed.
+  </p>
+  <p>
+    Galleys model the whole of the process of creating the final
+    formatted output; the document as a whole is regarded as a
+    galley which flushes in to the output file.
+  </p>
+      </section>
+      <section>
+        <title>The layout tree</title>
+  <anchor id="layout-tree"/>
+  <p>
+    This proposal for implementing galleys in FOP makes use of a
+    <strong>layout tree</strong>.  As with the <link href=
+    "../layout.html" >layout managers</link><em></em> already
+    proposed, the layout tree acts as a bridge between the <link
+    href= "../fotree.html" >FO Tree</link> and the <link href=
+    "../areatree.html" >Area Tree</link>.  If the elements of
+    the FO Tree are FO nodes, and the elements of the Area Tree
+    are Area nodes, representing areas to be drawn on the output
+    medium, the elements of the layout tree are <strong>galley
+    nodes</strong> and <strong>area tree fragments</strong>.
+    The area tree fragments are the final stages of the
+    resolution of the galleys; the output of the galleys will be
+    inserted directly into the Area Tree.  The tree structure
+    makes it clear that the whole of the formatting process in
+    FOP, under this model, is a hierarchical series of galleys.
+    The dynamic data comes from fo:flow and fo:static-content,
+    and the higher-level receptive areas are derived from the
+    <em>layout-master-set</em>.
+  </p>
+      </section>
+      <section>
+        <title>Processing galleys</title>
+  <p>
+    Galleys are processed in two basic processing environments:
+  </p>
+  <section>
+    <title>Inline- and block-progression dimensions known</title>
+    <p>
+      The galley at set-up is provided with both an
+      <em>inline-progression-dimension</em> (<em>i-p-d</em>) and
+      a <em>block-progression-dimension</em> (<em>b-p-d</em>).
+      In this case, no further intervention is necessary to lay
+      out the galley.  The galley has the possibility of laying
+      itself out, creating all necessary area nodes.  This does
+      not preclude the possibility that some children of this
+      galley will not be able to be so directly laid out, and
+      will fall into the second category.
+    </p>
+    <p>
+      While the option of "automatic" layout exists, to use
+      such a method would relinquish the possibility of
+      monitoring the results of such layout and performing
+      fine-tuning.
+    </p>
+  </section>
+  <section>
+    <title>Inline- ior block-progression-dimensions unknown</title>
+    <p>
+      The galley cannot immediately be provided with an i-p-d
+      ior a b-p-d.  This will occur in some of the difficult
+      cases mentioned earlier.  In these cases, the parent
+      galley acts as a layout manager, similar to the sense used
+      in <link href= "../layout.html" >another
+      discussion</link>.  The children, lacking full receptive
+      area dimensions, will proceed with galley pre-processing,
+      a procedure which will, of necessity, be followed
+      recursively by all of its children down to the atomic
+      elements of the galley.  These atomic elements are the
+      individual <em>fo:character</em> nodes and images of fixed
+      dimensions.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>Galley pre-processing</title>
+  <anchor id="pre-processing"/>
+  <p>
+    Galley pre-processing involves the spatial resolution of
+    objects from the flows to the greatest extent possible
+    without information on the dimensions of the target area.
+    Line-areas have a block progression dimension which is
+    determined by their contents. To achieve full generality in
+    layouts of indeterminate dimensions, the contents of
+    line-areas should be laid out as though their inline
+    progression dimension were limited only by their content.
+    In terms of inline-areas, galleys would process text and
+    resolve the dimensions of included images.  Text would be
+    collected into runs with the same alignment
+    characteristics. In the process, all possible "natural" and
+    hyphenation break-points can be determined.  Where a
+    line-area contains mixed fonts or embedded images, the b-p-d
+    of the individual line-areas which are eventually stacked
+    will, in general, depend on the line break points, but the
+    advantage of this approach is that such actual selections
+    can be backed out and new break points selected with a
+    minimum of re-calculation.  This can potentially occur
+    whenever a first attempt at page layout is backed out.
+    <br/><br/>
+    <strong>Figure 1</strong>
+  </p>
+  <figure src="galley-preprocessing.png" alt="Galley
+    pre-processing diagram"/>
+  <p>
+    Once this pre-processing has been achieved, it is
+    envisaged that a layout manager might make requests to the
+    galley of its ability to fill an area of a given
+    inline-progression-dimension.  A positive response would
+    be accompanied by the block-progression-dimension.  The
+    other possibilities are a partial fill, which would also
+    require b-p-d data, and a failure due to insufficient
+    i-p-d, in which case the minimum i-p-d requirement would
+    be returned.  Note that decisions about the
+    actual dimensions of line-areas to be filled can be
+    deferred until all options have been tested.
+  </p>
+  <p>
+    The other primary form of information provided by a
+    pre-processed galley is its minimum and maximum i-p-d, so
+    that decisions can be made by the parent on the spacing of
+    table columns.  Apart from information requests,
+    higher-level processes can either make requests of the
+    galleys for chunks of nominated sizes, or simply provide the
+    galley with an i-p-d and b-p-d, which will trigger the
+    flushing of the galley components into Area nodes.  Until
+    they have flushed, the galleys must be able to respond to a
+    sequence of information requests, more or less in the manner
+    of a request iterator, and separately manage the flushing of
+    objects into the area tree.  The purpose of the "request
+    iterator" would be to support "incremental" information
+    requests like <em>getNextBreakPosition</em>.
+  </p>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/index.xml b/src/documentation/content/xdocs/design/alt.design/index.xml
new file mode 100644
index 000000000..08e60f059
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/index.xml
@@ -0,0 +1,84 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+    <title>FOP Alternative Design</title>
+    <subtitle>Alternative Design Approach to FOP</subtitle>
+    <version>$Revision$ $Name$</version>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Alternative Design</title>
+      <p>
+  This section of the FOP web site contains notes on approaches
+  to an alternative design for FOP.  The individual documents
+  here are fragmentary, being notes of particular issues,
+  without an overall framework as yet. 
+      </p>
+      <p>
+  The main aims of this redesign effort are:
+      </p>
+      <ul>
+  <li>full conformance with the Recommendation</li>
+  <li>increased performance</li> 
+  <li>reduced memory footprint</li> 
+  <li>no limitation on the size of files</li>
+      </ul>
+      <p>
+  In order to achieve these aims, the primary areas
+  of design interest are:
+      </p>
+      <ul>
+  <li>
+    Representing properties, for most purposes, as integers.
+  </li>
+  <li>
+    Distributing FOP processing over a number of threads with
+    single-point downstream communication and flow control by
+    means of traditional producer/consumer queues.  The threads
+    so far under consideration are:
+    <ul>
+      <li>XML parser</li>
+      <li>FO tree builder</li>
+      <li>layout engine</li>
+      <li>Area tree builder</li>
+    </ul>
+  </li>
+  <li>
+    Representing trees with explicit Tree objects, rather than
+    as implicit relationships among other objects.
+  </li>
+  <li>
+    Caching integrated into the tree node access methods.
+  </li>
+      </ul>
+      <section>
+        <title>Status and availability</title> 
+  <p>
+    The <em>ALT DESIGN</em> effort is not taking place on the
+    main line of development, represented by the <em>HEAD</em>
+    tag on the CVS trunk.  The source is available via the
+    FOP_0-20-0_Alt-Design tag.  This code has only a crude,
+    non-<em>Ant</em> build environment, and is expected only to
+    compile at this stage.  Only the parser stage and the first
+    stage of FO tree building is present.  However, the first
+    example of producer/consumer binding is working, the Tree
+    class with inner Tree.Node and inner
+    Tree.Node.<em>iterators</em> classes are available and
+    working.  Property handling is quite advanced, and is likely
+    to be almost complete some time in July, 2002.
+  </p>
+  <p>
+    Only <link href="mailto:pbwest@powerup.com.au">Peter
+    West</link> is working on the ALT DESIGN sub-project.
+  </p>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/keeps.xml b/src/documentation/content/xdocs/design/alt.design/keeps.xml
new file mode 100644
index 000000000..ffb29f5f1
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/keeps.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Keeps and breaks</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Keeps and breaks in layout galleys</title>
+      <p>
+  The <link href= "galleys.html" >layout galleys</link> and the
+  <link href= "galleys.html#layout-tree" >layout tree</link>
+  which is their context have been discussed elsewhere.  Here we
+  discuss a possible method of implementing keeps and breaks
+  within the context of layout galleys and the layout tree.
+      </p>
+      <section>
+        <title>Breaks</title>
+  <p> 
+    Breaks may be handled by inserting a column- or page-break
+    pseudo-object into the galley stream.  For break-before, the
+    object would be inserted before the area in which the flow
+    object, to which the property is attached, is leading.  If
+    the flow object is leading in no ancestor context, the
+    pseudo-object is inserted before the object itself.
+    Corresponding considerations apply for break-after. 
+    Selection of the position for these objects will be further
+    examined in the discussion on keeps.
+  </p>
+      </section>
+      <section>
+        <title>Keeps</title>
+  <p> 
+    Conceptually, all keeps can be represented by a
+    keep-together pseudo-area.  The keep-together property
+    itself is expressed during layout by wrapping all of the
+    generated areas in a keep-together area.  Keep-with-previous
+    on formatting object A becomes a keep-together area spanning
+    the first non-blank normal area leaf node, L, generated by A
+    or its offspring, and the last non-blank normal area leaf
+    node preceding L in the area tree.  Likewise, keep-with-next
+    on formatting object A becomes a keep-together area spanning
+    the last non-blank normal area leaf node, L, generated by A
+    or its offspring, and the first non-blank normal area leaf
+    node following L in the area tree.
+    <br/>TODO REWORK THIS for block vs inline
+  </p>
+  <p>
+    The obvious problem with this arrangement is that the
+    keep-together area violate the hierarachical arrangement of
+    the layout tree.  They form a concurrent structure focussed
+    on the leaf nodes.  This seems to be the essential problem
+    of handling keep-with-(previous/next); that it cuts across
+    the otherwise tree-structured flow of processing.  Such
+    problems are endemic in page layout. 
+  </p>
+  <p>
+    In any case, it seems that the relationships between areas
+    that are of interest in keep processing need some form of
+    direct expression, parallel to the layout tree itself.
+    Restricting ourselves too block-level elements, and looking
+    only at the simple block stacking cases, we get a diagram
+    like the attached PNG.  In order to track the relationships
+    through the tree, we need four sets of links.
+  </p>
+  <p>
+    <strong>Figure 1</strong>
+  </p>
+  <anchor id="Figure1"/>
+  <figure src="block-stacking.png" alt="Simple block-stacking
+    diagram"/>
+  <p>
+    The three basic links are:
+  </p>
+  <ul>
+    <!-- one of (dl sl ul ol li) -->
+    <li>Leading edge to leading edge of first normal child.</li>
+    <li>Trailing edge to leading edge of next normal
+      sibling.</li>
+    <li>Trailing edge to trailing edge of parent.</li>
+  </ul>
+  <p>
+    Superimposed on the basic links are bridging links which
+    span adjacent sets of links.  These spanning links are the
+    tree violators, and give direct access to the areas which
+    are of interest in keep processing. They could be
+    implemented as double-linked lists, either within the layout
+    tree nodes or as separate structures.  Gaps in the spanning
+    links are joined by simply reproducing the single links, as
+    in the diagram. The whole layout tree for a page is
+    effectively threaded in order of interest, as far as keeps
+    are concerned.
+  </p>
+  <p>
+    The bonus of this structure is that it looks like a superset
+    of the stacking constraints.  It gives direct access to all
+    sets of adjacent edges and sets of edges whose space
+    specifiers need to be resolved. Fences can be easily enough
+    detected during the process of space resolution.
+  </p>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/properties-classes.xml b/src/documentation/content/xdocs/design/alt.design/properties-classes.xml
new file mode 100644
index 000000000..3345cadfa
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/properties-classes.xml
@@ -0,0 +1,143 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Properties$classes</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>fo.Properties and the nested properties classes</title>
+      <figure src="PropertyClasses.png" alt="Nested property and
+        top-level classes"/> 
+      <section>
+        <title>Nested property classes</title>
+  <p>
+    Given the intention that individual properties have only a
+    <em>virtual</em> instantiation in the arrays of
+    <code>PropertyConsts</code>, these classes are intended to
+    remain as repositories of static data and methods.  The name
+    of each property is entered in the
+    <code>PropNames.propertyNames</code> array of
+    <code>String</code>s, and each has a unique integer constant
+    defined, corresponding to the offset of the property name in
+    that array.
+  </p>
+  <section>
+    <title>Fields common to all classes</title>
+    <dl> 
+      <dt><code>final int dataTypes</code></dt>
+      <dd>
+        This field defines the allowable data types which may be
+        assigned to the property.  The value is chosen from the
+        data type constants defined in <code>Properties</code>, and
+        may consist of more than one of those constants,
+        bit-ORed together.
+      </dd>
+      <dt><code>final int traitMapping</code></dt>
+      <dd>
+        This field defines the mapping of properties to traits
+        in the <code>Area tree</code>. The value is chosen from the
+        trait mapping constants defined in <code>Properties</code>,
+        and may consist of more than one of those constants,
+        bit-ORed together.
+      </dd>
+      <dt><code>final int initialValueType</code></dt>
+      <dd>
+        This field defines the data type of the initial value
+        assigned to the property.  The value is chosen from the
+        initial value type constants defined in
+        <code>Properties</code>.
+      </dd>
+      <dt><code>final int inherited</code></dt>
+      <dd>
+        This field defines the kind of inheritance applicable to
+        the property.  The value is chosen from the inheritance
+        constants defined in <code>Properties</code>. 
+      </dd>
+    </dl>
+  </section>
+  <section>
+    <title>Datatype dependent fields</title>
+    <dl>
+      <dt>Enumeration types</dt>
+      <dd>
+        <strong><code>final String[] enums</code></strong><br/>
+        This array contains the <code>NCName</code>  text
+        values of the enumeration.  In the current
+        implementation, it always contains a null value at
+        <code>enum[0]</code>.<br/> <br/>
+
+        <strong><code>final String[]
+        enumValues</code></strong><br/> When the number of
+        enumeration values is small,
+        <code>enumValues</code>  is a reference to the
+        <code>enums</code>  array.<br/> <br/>
+
+        <strong><code>final HashMap
+        enumValues</code></strong><br/> When the number of
+        enumeration values is larger,
+        <code>enumValues</code>  is a
+        <code>HashMap</code>  statically initialized to
+        contain the integer constant values corresponding to
+        each text value, indexed by the text
+        value.<br/> <br/>
+
+        <strong><code>final int</code></strong>
+        <em><code>enumeration-constants</code></em><br/> A
+        unique integer constant is defined for each of the
+        possible enumeration values.<br/> <br/>
+      </dd>
+      <dt>Many types:
+        <code>final</code>  <em>datatype</em>
+        <code>initialValue</code></dt>
+      <dd>
+        When the initial datatype does not have an implicit
+        initial value (as, for example, does type
+        <code>AUTO</code>) the initial value for the property is
+        assigned to this field.  The type of this field will
+        vary according to the <code>initialValueType</code>
+        field.
+      </dd>
+      <dt>AUTO: <code>PropertyValueList auto(property,
+        list)></code></dt>
+      <dd>
+        When <em>AUTO</em>  is a legal value type, the
+        <code>auto()</code>  method must be defined in the property
+        class.<br/>
+        <em>NOT YET IMPLEMENTED.</em>
+      </dd>
+      <dt>COMPLEX: <code>PropertyValueList complex(property,
+        list)></code></dt>
+      <dd>
+        <em>COMPLEX</em>  is specified as a value type when complex
+        conditions apply to the selection of a value type, or
+        when lists of values are acceptable.  To process and
+        validate such a property value assignment, the
+        <code>complex()</code>  method must be defined in the
+        property class.
+      </dd>
+    </dl>
+  </section>
+      </section>
+      <section>
+        <title>Nested property pseudo-classes</title>
+  <p>
+    The property pseudo-classes are classes, like
+    <code>ColorCommon</code>  which contain values, particularly
+    <em>enums</em>, which are common to a number of actual
+    properties.
+  </p>
+      </section>
+      <p>
+  <strong>Previous:</strong> <link href= "classes-overview.html"
+  >property classes overview.</link>
+      </p>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/propertyExpressions.xml b/src/documentation/content/xdocs/design/alt.design/propertyExpressions.xml
new file mode 100644
index 000000000..90d67349f
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/propertyExpressions.xml
@@ -0,0 +1,343 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Property Expression Parsing</title>
+    <authors>
+       <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Property expression parsing</title>
+      <note>
+  The following discussion of the experiments with alternate
+  property expression parsing is very much a work in progress,
+  and subject to sudden changes.
+      </note>
+      <p>
+  The parsing of property value expressions is handled by two
+  closely related classes: <code>PropertyTokenizer</code> and its
+  subclass, <code>PropertyParser</code>.
+  <code>PropertyTokenizer</code>, as the name suggests, handles
+  the tokenizing of the expression, handing <em>tokens</em>
+  back to its subclass,
+  <code>PropertyParser</code>. <code>PropertyParser</code>, in
+    turn, returns a <code>PropertyValueList</code>, a list of
+  <code>PropertyValue</code>s.
+      </p>
+      <p>
+  The tokenizer and parser rely in turn on the datatype 
+  definition from the <code>org.apache.fop.datatypes</code>
+  package and the datatype <code>static final int</code>
+  constants from <code>PropertyConsts</code>.
+      </p>
+      <section>
+        <title>Data types</title>
+  <p>
+    The data types currently defined in
+    <code>org.apache.fop.datatypes</code> include:
+  </p>
+  <table>
+    <tr><th colspan="2">Numbers and lengths</th></tr>
+    <tr>
+      <th>Numeric</th>
+      <td colspan="3">
+        The fundamental numeric data type.  <em>Numerics</em> of
+        various types are constructed by the classes listed
+        below.
+      </td>
+    </tr>
+    <tr>
+      <td/>
+      <th colspan="3">Constructor classes for <em>Numeric</em></th>
+    </tr>
+    <tr>
+      <td/><td>Angle</td>
+      <td colspan="2">In degrees(deg), gradients(grad) or
+        radians(rad)</td>
+    </tr>
+    <tr>
+      <td/><td>Ems</td>
+      <td colspan="2">Relative length in <em>ems</em></td>
+    </tr>
+    <tr>
+      <td/><td>Frequency</td>
+      <td colspan="2">In hertz(Hz) or kilohertz(kHz)</td>
+    </tr>
+    <tr>
+      <td/><td>IntegerType</td><td/>
+    </tr>
+    <tr>
+      <td/><td>Length</td>
+      <td colspan="2">In centimetres(cm), millimetres(mm),
+        inches(in), points(pt), picas(pc) or pixels(px)</td>
+    </tr>
+    <tr>
+      <td/><td>Percentage</td><td/>
+    </tr>
+    <tr>
+      <td/><td>Time</td>
+      <td>In seconds(s) or milliseconds(ms)</td>
+    </tr>
+    <tr><th colspan="2">Strings</th></tr>
+    <tr>
+      <th>StringType</th>
+      <td colspan="3">
+        Base class for data types which result in a <em>String</em>.
+      </td>
+    </tr>
+    <tr>
+      <td/><th>Literal</th>
+      <td colspan="2">
+        A subclass of <em>StringType</em> for literals which
+        exceed the constraints of an <em>NCName</em>.
+      </td>
+    </tr>
+    <tr>
+      <td/><th>MimeType</th>
+      <td colspan="2">
+        A subclass of <em>StringType</em> for literals which
+        represent a mime type.
+      </td>
+    </tr>
+    <tr>
+      <td/><th>UriType</th>
+      <td colspan="2">
+        A subclass of <em>StringType</em> for literals which
+        represent a URI, as specified by the argument to
+        <em>url()</em>.
+      </td>
+    </tr>
+    <tr>
+      <td/><th>NCName</th>
+      <td colspan="2">
+        A subclass of <em>StringType</em> for literals which
+        meet the constraints of an <em>NCName</em>.
+      </td>
+    </tr>
+    <tr>
+      <td/><td/><th>Country</th>
+      <td>An RFC 3066/ISO 3166 country code.</td>
+    </tr>
+    <tr>
+      <td/><td/><th>Language</th>
+      <td>An RFC 3066/ISO 639 language code.</td>
+    </tr>
+    <tr>
+      <td/><td/><th>Script</th>
+      <td>An ISO 15924 script code.</td>
+    </tr>
+    <tr><th colspan="2">Enumerated types</th></tr>
+    <tr>
+      <th>EnumType</th>
+      <td colspan="3">
+        An integer representing one of the tokens in a set of
+        enumeration values.
+      </td>
+    </tr>
+    <tr>
+      <td/><th>MappedEnumType</th>
+      <td colspan="2">
+        A subclass of <em>EnumType</em>.  Maintains a
+        <em>String</em> with the value to which the associated
+        "raw" enumeration token maps.  E.g., the
+        <em>font-size</em> enumeration value "medium" maps to
+        the <em>String</em> "12pt".
+      </td>
+    </tr>
+    <tr><th colspan="2">Colors</th></tr>
+    <tr>
+      <th>ColorType</th>
+      <td colspan="3">
+        Maintains a four-element array of float, derived from
+        the name of a standard colour, the name returned by a
+        call to <em>system-color()</em>, or an RGB
+        specification.
+      </td>
+    </tr>
+    <tr><th colspan="2">Fonts</th></tr>
+    <tr>
+      <th>FontFamilySet</th>
+      <td colspan="3">
+        Maintains an array of <em>String</em>s containing a
+        prioritized list of possibly generic font family names.
+      </td>
+    </tr>
+    <tr><th colspan="2">Pseudo-types</th></tr>
+    <tr>
+      <td colspan="4">
+        A variety of pseudo-types have been defined as
+        convenience types for frequently appearing enumeration
+        token values, or for other special purposes.
+      </td>
+    </tr>
+    <tr>
+      <th>Inherit</th>
+      <td colspan="3">
+        For values of <em>inherit</em>.
+      </td>
+    </tr>
+    <tr>
+      <th>Auto</th>
+      <td colspan="3">
+        For values of <em>auto</em>.
+      </td>
+    </tr>
+    <tr>
+      <th>None</th>
+      <td colspan="3">
+        For values of <em>none</em>.
+      </td>
+    </tr>
+    <tr>
+      <th>Bool</th>
+      <td colspan="3">
+        For values of <em>true/false</em>.
+      </td>
+    </tr>
+    <tr>
+      <th>FromNearestSpecified</th>
+      <td colspan="3">
+        Created to ensure that, when associated with
+        a shorthand, the <em>from-nearest-specified-value()</em>
+        core function is the sole component of the expression.
+      </td>
+    </tr>
+    <tr>
+      <th>FromParent</th>
+      <td colspan="3">
+        Created to ensure that, when associated with
+        a shorthand, the <em>from-parent()</em>
+        core function is the sole component of the expression.
+      </td>
+    </tr>
+  </table>
+      </section>
+      <section>
+        <title>Tokenizer</title>
+  <p>
+    The tokenizer returns one of the following token
+    values:
+  </p>
+  <source>
+    static final int
+                 EOF = 0
+             ,NCNAME = 1
+           ,MULTIPLY = 2
+               ,LPAR = 3
+               ,RPAR = 4
+            ,LITERAL = 5
+      ,FUNCTION_LPAR = 6
+               ,PLUS = 7
+              ,MINUS = 8
+                ,MOD = 9
+                ,DIV = 10
+              ,COMMA = 11
+            ,PERCENT = 12
+          ,COLORSPEC = 13
+              ,FLOAT = 14
+            ,INTEGER = 15
+    ,ABSOLUTE_LENGTH = 16
+    ,RELATIVE_LENGTH = 17
+               ,TIME = 18
+               ,FREQ = 19
+              ,ANGLE = 20
+            ,INHERIT = 21
+               ,AUTO = 22
+               ,NONE = 23
+               ,BOOL = 24
+                ,URI = 25
+           ,MIMETYPE = 26
+            // NO_UNIT is a transient token for internal use only.  It is
+            // never set as the end result of parsing a token.
+            ,NO_UNIT = 27
+                     ;
+  </source>
+  <p>
+    Most of these tokens are self-explanatory, but a few need
+    further comment.
+  </p>
+  <dl>
+    <dt>AUTO</dt>
+    <dd>
+      Because of its frequency of occurrence, and the fact that
+      it is always the <em>initial value</em> for any property
+      which supports it, AUTO has been promoted into a
+      pseudo-type with its on datatype class.  Therefore, it is
+      also reported as a token.
+    </dd>
+    <dt>NONE</dt>
+    <dd>
+      Similarly to AUTO, NONE has been promoted to a pseudo-type
+      because of its frequency.
+    </dd>
+    <dt>BOOL</dt>
+    <dd>
+      There is a <em>de facto</em> boolean type buried in the
+      enumeration types for many of the properties.  It had been
+      specified as a type in its own right in this code.
+    </dd>
+    <dt>MIMETYPE</dt>
+    <dd>
+      The property <code>content-type</code> introduces this
+      complication.  It can have two values of the form
+      <strong>content-type:</strong><em>mime-type</em>
+      (e.g. <code>content-type="content-type:xml/svg"</code>) or
+      <strong>namespace-prefix:</strong><em>prefix</em>
+      (e.g. <code>content-type="namespace-prefix:svg"</code>).  The
+        experimental code reduces these options to the payload
+        in each case: an <code>NCName</code> in the case of a
+      namespace prefix, and a MIMETYPE in the case of a
+      content-type specification.  <code>NCName</code>s cannot
+      contain a "/".
+    </dd>
+  </dl>
+      </section>
+      <section>
+        <title>Parser</title>
+  <p>
+    The parser retuns a <code>PropertyValueList</code>,
+    necessary because of the possibility that a list of
+    <code>PropertyValue</code> elements may be returned from the
+    expressions of soem properties.
+  </p>
+  <p>
+    <code>PropertyValueList</code>s may contain
+    <code>PropertyValue</code>s or other
+    <code>PropertyValueList</code>s.  This latter provision is
+    necessitated for the peculiar case of of
+    <em>text-shadow</em>, which may contain whitespace separated
+    sublists of either two or three elements, separated from one
+    another by commas.  To accommodate this peculiarity, comma
+    separated elements are added to the top-level list, while
+    whitespace separated values are always collected into
+    sublists to be added to the top-level list.
+  </p>
+  <p>
+    Other special cases include the processing of the core
+    functions <code>from-parent()</code> and
+    <code>from-nearest-specified-value()</code> when these
+    function calls are assigned to a shorthand property, or used
+    with a shorthand property name as an argument.  In these
+    cases, the function call must be the sole component of the
+    expression.  The pseudo-element classes
+    <code>FromParent</code> and
+    <code>FromNearestSpecified</code> are generated in these
+    circumstances so that an exception will be thrown if they
+    are involved in expression evaluation with other
+    components. (See Rec. Section 5.10.4 Property Value
+    Functions.)
+  </p>
+  <p>
+    The experimental code is a simple extension of the existing
+    parser code, which itself borrowed heavily from James
+    Clark's XT processor.
+  </p>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/spaces.xml b/src/documentation/content/xdocs/design/alt.design/spaces.xml
new file mode 100644
index 000000000..f2426347b
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/spaces.xml
@@ -0,0 +1,179 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Keeps and space-specifiers</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Keeps and space-specifiers in layout galleys</title>
+      <p> 
+  The <link href= "galleys.html" >layout galleys</link> and the
+  <link href= "galleys.html#layout-tree" >layout tree</link>
+  which is the context of this discussion have been discussed 
+  elsewhere.  A <link href="keeps.html">previous document</link>
+  discussed data structures which might facilitate the lining of
+  blocks necessary to implement keeps.  Here we discuss the
+  similarities between the keep data structures and those
+  required to implement space-specifier resolution.
+      </p>
+      <section>
+        <title>Space-specifiers</title>
+  <note>
+    <strong>4.3 Spaces and Conditionality</strong>
+    ... Space-specifiers occurring in sequence may interact with
+    each other. The constraint imposed by a sequence of
+    space-specifiers is computed by calculating for each
+    space-specifier its associated resolved space-specifier in
+    accordance with their conditionality and precedence.
+  </note>
+  <note>
+    4.2.5 Stacking Constraints ... The intention of the
+    definitions is to identify areas at any level of the tree
+    which have only space between them. 
+  </note>
+  <p>
+    The quotations above are pivotal to understanding the
+    complex discussion of spaces with which they are associated,
+    all of which exists to enable the resolution of adjacent 
+    &lt;space&gt;s.  It may be helpful to think of <em>stacking
+    constraints</em> as <em>&lt;space&gt;s interaction</em> or
+    <em>&lt;space&gt;s stacking interaction</em>.
+  </p>
+      </section>
+      <section>
+        <title>Block stacking constraints</title>
+  <p>
+    In the discussion of block stacking constraints in Section
+    4.2.5, the notion of <em>fence</em> is introduced.  For
+    block stacking constraints, a fence is defined as either a
+    reference-area boundary or a non-zero padding or border
+    specification.  Fences, however, do not come into play 
+    when determining the constraint between siblings.  (See
+    <link href="#Figure1">Figure 1</link>.)
+  </p>
+  <p><strong>Figure 1</strong></p><anchor id="Figure1"/> 
+  <figure src="block-stacking-constraints.png" 
+    alt="block-stacking-constraints.png"/>
+  <note>
+    Figure 1 assumes a block-progression-direction of top to
+    bottom.
+  </note>
+  <p>
+    In <link href="#Figure1">Diagram a)</link>, block A has
+    non-zero padding and borders, in addition to non-zero
+    spaces.  Note, however, that the space-after of A is
+    adjacent to the space-before of block P, so borders and
+    padding on these siblings have no impact on the interaction
+    of their &lt;space&gt;s.  The stacking constraint A,P is
+    indicated by the red rectangle enclosing the space-after of
+    A and the space-before of P.
+  </p>
+  <p>
+    In <link href="#Figure1">Diagram b)</link>, block B is the
+    first block child of P.  The stacking constraint A,P is as
+    before; the stacking constraint P,B is the space-before of
+    B, as indicated by the enclosing magenta rectangle.  In this
+    case, however, the non-zero border of P prevents the
+    interaction of the A,P and P,B stacking constraints.  There
+    is a <em>fence-before</em> P.  The fence is notional; it has
+    no precise location, as the diagram may lead one to believe.
+  </p>
+  <p>
+    In <link href="#Figure1">Diagram c)</link>, because of the
+    zero-width borders and padding on block P, the fence-before
+    P is not present, and the adjacent &lt;space&gt;s of blocks
+    A, P and B are free to interact.  In this case, the stacking
+    constraints A,P and P,B are as before, but now there is an
+    additional stacking constraint A,B, represented by the light
+    brown rectangle enclosing the other two stacking
+    constraints.
+  </p>
+  <p>
+    The other form of fence occurs when the parent block is a
+    reference area.  Diagram b) of <link href="#Figure2">Figure
+    2</link> illustrates this situation.  Block C is a
+    reference-area, involving a 180 degree change of
+    block-progression-direction (BPD).  In the diagram, the
+    inner edge of block C represents the content rectangle, with
+    its changed BPD.  The thicker outer edge represents the
+    outer boundary of the padding, border and spaces of C.
+  </p>
+  <p>
+    While not every reference-area will change the
+    inline-progression-direction (IPD) and BPD of an area, no
+    attempt is made to discriminate these cases.  A
+    reference-area always a fence.  The fence comes into play in
+    analogous circumstances to non-zero borders or padding.
+    Space resolution between a reference area and its siblings
+    is not affected.
+  </p>
+  <p>
+    In the case of <link href="#Figure2">Diagram b)</link>,
+    these are block stacking constraints B,C and C,A.  Within
+    the reference-area, bock stacing constraints C,D and E,C are
+    unaffected.  However, the fence prevents block stacking
+    constraints such as B,E or D,A.  When there is a change of
+    BPD, as <link href="#Figure2">Diagram b)</link> makes
+    visually obvious, it is difficult to imagine which blocks
+    would have such a constraint, and what the ordering of the
+    constraint would be.
+  </p>
+  <p><strong>Figure 2</strong></p>
+  <anchor id="Figure2"/>
+  <figure src="block-stacking-keeps.png"
+    alt="block-stacking-keeps.png"/>
+      </section>
+      <section>
+        <title>Keep relationships between blocks</title>
+  <p>
+    As complicated as space-specifiers become when
+    reference-areas are involved, the keep relationships as
+    described in the <link
+    href="keeps.html#Figure1">keeps</link> document, are
+    unchanged.  This is also illustrated in <link
+    href="#Figure2">Figure 2</link>.  Diagram b) shows the
+    relative placement of blocks in the rendered output when a
+    180 degree change of BPD occurs, with blocks D and E
+    stacking in the reverse direction to blocks B and C.
+    Diagram c) shows what happens when the page is too short to
+    accommodate the last block.  D is still laid out, but E is
+    deferred to the next page.
+  </p>
+  <p>
+    Note that this rendering reality is expressed directly in
+    the area (and layout) tree view.  Consequently, any keep
+    relationships expressed as links threading through the
+    layout tree will not need to be modified to account for
+    reference-area boundaries, as is the case with similar
+    space-specifier edge links.  E.g., a keep-with-next
+    condition on block B can be resolved along the path of these
+    links (B->C->D) into a direct relationship of B->D,
+    irrespective of the reference-area boundary.
+  </p>
+  <p>
+    While the same relationships obviously hold when a reference
+    area induces no change of BPD, the situation for BPD changes
+    perpendicular to the parent's BPD may not be so clear.  In
+    general, it probably does not make much sense to impose keep
+    conditions across such a boundary, but there seems to be
+    nothing preventing such conditions.  They can be dealt with
+    in the same way, i.e., the next leaf block linked in area
+    tree order must be the next laid out.  If a keep condition
+    is in place, an attempt must be made to meet it.  A number
+    of unusual considerations would apply, e.g. the minimum
+    inline-progression-dimension of the first leaf block within
+    the reference-area as compared to the minimum IPD of
+    subsequent blocks, but <em>prima facie</em>, the essential
+    logic of the keeps links remains.
+  </p>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/traits.xml b/src/documentation/content/xdocs/design/alt.design/traits.xml
new file mode 100644
index 000000000..365540060
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/traits.xml
@@ -0,0 +1,369 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Traits</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>Traits</title>
+      <table>
+        <tr>
+          <th>Trait</th>
+          <th>Applies to</th>
+          <th>Refs</th>
+          <th>Derived from</th>
+        </tr>
+        <tr>
+          <th>Common Traits</th>
+        </tr>
+        <tr>
+          <td>block-progression-direction</td>
+          <td>All areas</td>
+          <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-common"
+      >4.2.2 Common Traits</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#writing-mode"
+            >7.27.7 writing-mode</link>
+          </td>
+          <td> 
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#reference-orientation"
+            >7.27.7 reference-orientation</link> 
+          </td> 
+        </tr>
+        <tr>
+          <td>inline-progression-direction</td>
+          <td>All areas</td>
+          <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-common"
+            >4.2.2 Common Traits</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#writing-mode"
+            >7.27.7 writing-mode</link>
+          </td>
+          <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#reference-orientation"
+            >7.27.7 reference-orientation</link> 
+          </td> 
+        </tr>
+        <tr>
+          <td>shift-direction</td>
+          <td>Inline areas</td> 
+        </tr>
+        <tr>
+          <td>glyph-orientation</td>
+          <td>Glyph-areas</td>
+          <td> 
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-common"
+            >4.2.2 Common Traits</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-glyph"
+            >4.6.2 Glyph-areas</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-linebuild"
+            >4.7.2 Line-building</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#rend-intrinsic"
+            >4.9.5 Intrinsic Marks</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#font-model"
+            >7.8.1 Fonts and Font Data</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#writing-mode-related"
+            >7.27 Writing-mode-related Properties</link>
+          </td>
+          <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#glyph-orientation-horizontal"
+            >7.27.2 glyph-orientation-horizontal</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#glyph-orientation-vertical"
+            >7.27.3 glyph-orientation-vertical</link><br/>
+             <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#direction"
+            >7.27.1 direction</link><br/>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice7.html#writing-mode"
+            >7.27.7 writing-mode</link>
+          </td>
+        </tr>
+        <tr>
+          <td>is-reference-area</td>
+          <td>All areas</td>
+          <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice5.html#section-N6691-Non-property-Based-Trait-Generation"
+            >5.6 Non-property Based Trait Generation</link>
+          </td>
+          <td>
+      Set "true" on:<br/>
+            simple-page-master<br/>
+            title<br/>
+            region-body<br/>
+            region-before<br/>
+            region-after<br/>
+            region-start<br/>
+            region-end<br/>
+            block-container<br/>
+            inline-container<br/>
+            table<br/>
+            table-caption<br/>
+            table-cell
+    </td>
+        </tr>
+        <tr>
+          <td>is-viewport-area</td>
+          <td></td>
+          <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-common"
+            >4.2.2 Common Traits</link>
+          </td>
+        </tr>
+        <tr>
+          <td>top-position</td>
+        </tr>
+        <tr>
+          <td>bottom-position</td>
+        </tr>
+        <tr>
+          <td>left-position</td>
+        </tr>
+        <tr>
+          <td>right-position</td>
+        </tr>
+        <tr>
+          <td>left-offset</td>
+        </tr>
+        <tr>
+          <td>top-offset</td>
+        </tr>
+        <tr>
+          <td>is-first</td>
+        </tr>
+        <tr>
+          <td>is-last</td>
+        </tr>
+        <tr>
+          <td>generated-by</td>
+        </tr>
+        <tr>
+          <td>returned-by</td>
+        </tr>
+        <tr>
+          <td>nominal-font</td>
+        </tr>
+        <tr>
+          <td>blink</td>
+          <td></td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration"
+              >5.5.6 Text-decoration Property
+            </link>
+          </td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice7.html#text-decoration"
+              >7.16.4 "text-decoration"
+            </link>
+          </td>
+        </tr>
+        <tr>
+          <td>underline-score</td>
+          <td></td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration"
+              >5.5.6 Text-decoration Property
+            </link>
+          </td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice7.html#text-decoration"
+              >7.16.4 "text-decoration"
+            </link>
+          </td>
+        </tr>
+        <tr>
+          <td>underline-score-color</td>
+          <td></td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration"
+              >5.5.6 Text-decoration Property
+            </link>
+          </td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice7.html#text-decoration"
+              >7.16.4 "text-decoration"
+            </link>
+          </td>
+        </tr>
+        <tr>
+          <td>overline-score</td>
+          <td></td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration"
+              >5.5.6 Text-decoration Property
+            </link>
+          </td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice7.html#text-decoration"
+              >7.16.4 "text-decoration"
+            </link>
+          </td>
+        </tr>
+        <tr>
+          <td>overline-score-color</td>
+          <td></td>
+
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration"
+              >5.5.6 Text-decoration Property
+            </link>
+          </td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice7.html#text-decoration"
+              >7.16.4 "text-decoration"
+            </link>
+          </td>
+        </tr>
+        <tr>
+          <td>through-score</td>
+          <td></td>
+
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration"
+              >5.5.6 Text-decoration Property
+            </link>
+          </td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice7.html#text-decoration"
+              >7.16.4 "text-decoration"
+            </link>
+          </td>
+        </tr>
+        <tr>
+          <td>through-score-color</td>
+          <td></td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration"
+              >5.5.6 Text-decoration Property
+            </link>
+          </td>
+          <td>
+            <link href=
+              "http://www.w3.org/TR/xsl/slice7.html#text-decoration"
+              >7.16.4 "text-decoration"
+            </link>
+          </td>
+        </tr>
+  <tr>
+    <th>Other Indirectly Derived Traits</th>
+  </tr>
+  <tr>
+    <td>alignment-point</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+  <tr>
+    <td>alignment-baseline</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+  <tr>
+    <td>baseline-shift</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+  <tr>
+    <td>dominant-baseline-identifier</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+  <tr>
+    <td>actual-baseline-table</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+  <tr>
+    <td>start-intrusion-adjustment</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+  <tr>
+    <td>end-intrusion-adjustment</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+  <tr>
+    <td>page-number</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+  <tr>
+    <td>script</td>
+    <td/>
+    <td>
+            <link href=
+            "http://www.w3.org/TR/xsl/slice4.html#area-intro"
+            >4.1 Introduction</link>
+    </td>
+  </tr>
+      </table>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/user-agent-refs.xml b/src/documentation/content/xdocs/design/alt.design/user-agent-refs.xml
new file mode 100644
index 000000000..47fe45f94
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/user-agent-refs.xml
@@ -0,0 +1,909 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>User agent refs</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>User Agent references in XSLFO</title>
+      <section>
+        <title>4.9.2 Viewport Geometry</title>
+  <p>
+    If the block-progression-dimension of the reference-area is
+    larger than that of the viewport-area and the overflow trait
+    for the reference-area is scroll, then the
+    inline-scroll-amount and block-scroll-amount are determined
+    by a scrolling mechanism, if any, provided by the
+    <strong>user agent</strong>. Otherwise, both are zero.
+  </p>
+      </section>
+      <section>
+        <title>5.1.3 Actual Values</title>
+  <p>
+    A computed value is in principle ready to be used, but a
+    user agent may not be able to make use of the value in a
+    given environment. For example, a <strong>user
+    agent</strong> may only be able to render borders with
+    integer pixel widths and may, therefore, have to adjust the
+    computed width to an integral number of media pixels.
+  </p>
+      </section>
+      <section>
+        <title>5.5.7 Font Properties</title>
+  <p>
+    There is no XSL mechanism to specify a particular font;
+    instead, a selected font is chosen from the fonts available
+    to the <strong>User Agent</strong> based on a set of
+    selection criteria. The selection criteria are the following
+    font properties: "font-family", "font-style",
+    "font-variant", "font-weight", "font-stretch", and
+    "font-size", plus, for some formatting objects, one or more
+    characters.
+  </p>
+      </section>
+      <section>
+        <title>5.9.13.1 Pixels</title>
+  <p>
+    If the <strong>User Agent</strong> chooses a measurement for
+    a 'px' that does not match an integer number of device dots
+    in each axis it may produce undesirable effects...
+  </p>
+      </section>
+      <section>
+        <title>5.10.4 Property Value Functions</title>
+  <section>
+    <title>Function: object merge-property-values( NCName)</title>
+    <p>
+      The merge-property-values function returns a value of the
+      property whose name matches the argument, or if omitted
+      for the property for which the expression is being
+      evaluated. The value returned is the specified value on
+      the last fo:multi-property-set, of the parent
+      fo:multi-properties, that applies to the <strong>User
+      Agent</strong> state. If there is no such value, the
+      computed value of the parent fo:multi-properties is
+      returned...
+    </p>
+    <p>
+      The test for applicability of a <strong>User
+      Agent</strong> state is specified using the "active-state"
+      property.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>6.3 Formatting Objects Summary</title>
+  <section>
+    <title>multi-property-set</title>
+    <p>
+      The fo:multi-property-set is used to specify an
+      alternative set of formatting properties that, dependent
+      on a <strong>User Agent</strong> state, are applied to the
+      content.
+    </p>
+  </section>
+  <section>
+    <title>title</title>
+    <p>
+      The fo:title formatting object is used to associate a
+      title with a given page-sequence. This title may be used
+      by an interactive <strong>User Agent</strong> to identify
+      the pages. For example, the content of the fo:title can be
+      formatted and displayed in a "title" window or in a "tool
+      tip".
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>6.4.1.2 Page-masters</title>
+  <p>
+    ... When pages are used with a <strong>User Agent</strong>
+    such as a Web browser, it is common that the each document
+    has only one page. The viewport used to view the page
+    determines the size of the page. When pages are placed on
+    non-interactive media, such as sheets of paper, pages
+    correspond to one or more of the surfaces of the paper.
+  </p>
+      </section>
+      <section>
+        <title>6.4.20 fo:title</title>
+  <section>
+    <title>Common Usage:</title>
+    <p>
+      ... This title may be used by an interactive <strong>User
+      Agent</strong> to identify the pages.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>6.6.3 fo:character</title>
+  <section>
+    <title>Constraints:</title>
+    <p>
+      The dimensions of the areas are determined by the font
+      metrics for the glyph.
+    </p>
+    <p>
+      When formatting an fo:character with a
+      "treat-as-word-space" value of "true", the <strong>User
+      Agent</strong> may use a different method for determining
+      the inline-progression-dimension of the area.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>6.9 Dynamic Effects: Link and Multi Formatting
+    Objects</title>
+  <section>
+    <title>6.9.1 Introduction</title>
+    <p>
+      Dynamic effects, whereby user actions (including
+      <strong>User Agent</strong> state) can influence the
+      behavior and/or representation of portions of a document,
+      can be achieved through the use of the formatting objects
+      included in this section:
+    </p>
+    <ul>
+      <li>One-directional single-target links.</li>
+      <li>
+        The ability to switch between the display of two or more
+        formatting object subtrees. This can be used for, e.g.,
+        expandable/collapsible table of contents, display of an
+        icon or a full table or graphic.
+      </li>
+      <li>
+        The ability to switch between different property values,
+        such as color or font-weight, depending on a
+        <strong>User Agent</strong> state, such as "hover".
+      </li>
+    </ul>
+  </section>
+      </section>
+      <section>
+        <title>6.10 Out-of-Line Formatting Objects</title>
+  <section>
+    <title>6.10.1.3 Conditional Sub-Regions</title>
+    <p>
+      ... There may be limits on how much space conditionally
+      generated areas can borrow from the
+      region-reference-area. It is left to the <strong>user
+      agent</strong> to decide these limits.
+    </p>
+    <p>
+      ... An interactive <strong>user agent</strong> may choose
+      to create "hot links" to the footnotes from the
+      footnote-citation, or create "hot links" to the
+      before-floats from an implicit citation, instead of
+      realizing conditional sub-regions.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>6.10.2 fo:float</title>
+  <section>
+    <title>Constraints:</title>
+    <p>
+      ... The <strong>user agent</strong> may make its own
+      determination, after taking into account the intrusion
+      adjustments caused by one or more overlapping side-floats,
+      that the remaining space in the
+      inline-progression-direction is insufficient for the next
+      side-float or normal block-area. The <strong>user
+      agent</strong> may address this by causing the next
+      side-float or normal block-area to "clear" one of the
+      relevant side-floats, as described in the "clear" property
+      description, so the intrusion adjustment is sufficiently
+      reduced. Of the side-floats that could be cleared to meet
+      this constraint, the side-float that is actually cleared
+      must be the one whose after-edge is closest to the
+      before-edge of the parent reference-area.
+    </p>
+    <p>
+            The <strong>user agent</strong> may determine sufficiency
+            of space by using a fixed length, or by some heuristic
+            such as whether an entire word fits into the available
+            space, or by some combination, in order to handle text and
+            images.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>6.10.3 fo:footnote</title>
+  <section>
+    <title>Constraints:</title>
+    <p>
+      ... The second block-area and any additional block-areas
+      returned by an fo:footnote must be placed on the
+      immediately subsequent pages to the page containing the
+      first block-area returned by the fo:footnote, before any
+      other content is placed. If a subsequent page does not
+      contain a region-body, the <strong>user agent</strong>
+      must use the region-master of the last page that did
+      contain a region-body to hold the additional block-areas.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.3 Reference Rectangle for Percentage Computations</title>
+  <p>...</p>
+  <section>
+    <title>Exceptions ...</title>
+    <p>
+      5. When the absolute-position is "fixed", the containing
+      block is defined by the nearest ancestor viewport area. If
+      there is no ancestor viewport area, the containing block
+      is defined by the <strong>user agent</strong>.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.6.5 "pause-after" 7.6.6 "pause-before" 7.6.17 "voice-family"</title>
+  <p>Initial: depends on <strong>user agent</strong></p>
+      </section>
+      <section>
+        <title>7.7.1 "background-attachment"</title>
+  <section>
+    <title>fixed</title>
+    <p>
+      ... <strong>User agents</strong> may treat fixed as
+      scroll. However, it is recommended they interpret fixed
+      correctly, at least for the HTML and BODY elements, since
+      there is no way for an author to provide an image only for
+      those browsers that support fixed.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.7.9 "border-before-width"</title>
+  <section>
+    <title>&lt;length-conditional&gt;</title>
+    <p>
+      ... If border-before-width is specified using one of the
+      width keywords the .conditional component is set to
+      "discard" and the .length component to a <strong>User
+      Agent</strong> dependent length.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.7.19 "border-top-color"</title>
+  <section>
+    <title>&lt;color&gt;</title>
+    <p>
+      ... If an element's border color is not specified with a
+      "border" property, <strong>user agents</strong> must use
+      the value of the element's "color" property as the
+      computed value for the border color.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.7.20 "border-top-style"</title>
+  <p>
+    Conforming HTML <strong>user agents</strong> may interpret
+    'dotted', 'dashed', 'double', 'groove', 'ridge', 'inset',
+    and 'outset' to be 'solid'.
+  </p>
+      </section>
+      <section>
+        <title>7.7.21 "border-top-width"</title>
+  <section>
+    <title>thin ... medium ... thick ...</title>
+    <p>
+      ... The interpretation of the first three values depends
+      on the <strong>user agent</strong>.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.8.2 "font-family"</title>
+  <p>Initial: depends on <strong>user agent</strong></p>
+      </section>
+      <section>
+        <title>7.8.3 "font-selection-strategy"</title>
+  <p>
+    There is no XSL mechanism to specify a particular font;
+    instead, a selected font is chosen from the fonts available
+    to the <strong>User Agent</strong> based on a set of
+    selection criteria. The selection criteria are the following
+    font properties: "font-family", "font-style",
+    "font-variant", "font-weight", "font-stretch", and
+    "font-size", plus, for some formatting objects, one or more
+    characters.
+  </p>
+  <p>
+    ... This fallback may be to seek a match using a
+    <strong>User Agent</strong> default "font-family", or it may
+    be a more elaborate fallback strategy where, for example,
+    "Helvetica" would be used as a fallback for "Univers".
+  </p>
+  <p>
+    If no match has been found for a particular character, there
+    is no selected font and the <strong>User Agent</strong>
+    should provide a visual indication that a character is not
+    being displayed (for example, using the 'missing character'
+    glyph).
+  </p>
+      </section>
+      <section>
+        <title>7.8.4 "font-size"</title>
+  <section>
+    <title>&lt;absolute-size&gt;</title>
+    <p>
+      An &lt;absolute-size&gt; keyword refers to an entry in a
+      table of font sizes computed and kept by the <strong>user
+      agent</strong>. Possible values are:<br/>[ xx-small |
+      x-small | small | medium | large | x-large | xx-large ]
+    </p>
+  </section>
+  <section>
+    <title>&lt;relative-size&gt;</title>
+    <p>
+      A &lt;relative-size&gt; keyword is interpreted relative to
+      the table of font sizes and the font size of the parent
+      element. Possible values are:<br/>[ larger | smaller
+      ]<br/>For example, if the parent element has a font size
+      of "medium", a value of "larger" will make the font size
+      of the current element be "large". If the parent element's
+      size is not close to a table entry, the <strong>user
+      agent</strong> is free to interpolate between table
+      entries or round off to the closest one. The <strong>user
+      agent</strong> may have to extrapolate table values if the
+      numerical value goes beyond the keywords.
+    </p>
+  </section>
+  <section>
+    <title>&lt;length&gt;</title>
+    <p>
+      A length value specifies an absolute font size (that is
+      independent of the <strong>user agent</strong>'s font
+      table).
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.8.8 "font-variant"</title>
+  <section>
+    <title>small-caps</title>
+    <p>
+      ... If a genuine small-caps font is not available,
+      <strong>user agents</strong> should simulate a small-caps
+      font...
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.8.9 "font-weight"</title>
+  <section>
+    <title>XSL modifications to the CSS definition:</title>
+    <p>
+      ... The association of other weights within a family to
+      the numerical weight values is intended only to preserve
+      the ordering of weights within that family. <strong>User
+      agents</strong> must map names to values in a way that
+      preserves visual order; a face mapped to a value must not
+      be lighter than faces mapped to lower values. There is no
+      guarantee on how a <strong>user agent</strong> will map
+      fonts within a family to weight values. However, the
+      following heuristics...
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.13.1 "alignment-adjust"</title>
+  <section>
+    <title>auto</title>
+    <p>
+      ... If the baseline-identifier does not exist in the
+      baseline-table for the glyph or other inline-area, then
+      the <strong>User Agent</strong> may either use heuristics
+      to determine where that missing baseline would be or may
+      use the dominant-baseline as a fallback.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.13.3 "baseline-shift"</title>
+  <section>
+    <title>sub/super</title>
+    <p>
+      ... Because in most fonts the subscript position is
+      normally given relative to the "alphabetic" baseline, the
+      <strong>User Agent</strong> may compute the effective
+      position for sub/superscripts <em>[sub: spec typo!]</em>
+      when some other baseline is dominant. ... If there is no
+      applicable font data the <strong>User Agent</strong> may
+      use heuristics to determine the offset.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.13.5 "dominant-baseline"</title>
+  <p>
+    ... If there is no baseline-table in the nominal font or if
+    the baseline-table lacks an entry for the desired baseline,
+    then the <strong>User Agent</strong> may use heuristics to
+    determine the position of the desired baseline.
+  </p>
+      </section>
+      <section>
+        <title>7.14.11 "scaling-method"</title>
+  <section>
+    <title>auto</title>
+    <p>
+      The <strong>User Agent</strong> is free to choose either
+      resampling, integer scaling, or any other scaling method.
+    </p>
+  </section>
+  <section>
+    <title>integer-pixels</title>
+    <p>
+      The <strong>User Agent</strong> should scale the image
+      such that each pixel in the original image is scaled to
+      the nearest integer number of device-pixels that yields an
+      image less-then-or-equal-to the image size derived from
+      the content-height, content-width, and scaling properties.
+    </p>
+  </section>
+  <section>
+    <title>resample-any-method</title>
+    <p>
+      The <strong>User Agent</strong> should resample the
+      supplied image to provide an image that fills the size
+      derived from the content-height, content-width, and
+      scaling properties. The <strong>user agent</strong> may
+      use any sampling method.
+    </p>
+  </section>
+  <p>
+    ... This is defined as a preference to allow the
+    <strong>user agent</strong> the flexibility to adapt to
+    device limitations and to accommodate over-constrained
+    situations involving min/max dimensions and scale factors.
+  </p>
+      </section>
+      <section>
+        <title>7.14.12 "width"</title>
+  <p>
+    ... The width of a replaced element's box is intrinsic and
+    may be scaled by the <strong>user agent </strong> if the
+    value of this property is different than 'auto'.
+  </p>
+      </section>
+      <section>
+        <title>7.15.4 "line-height"</title>
+  <section>
+    <title>normal</title>
+    <p>
+      Tells <strong>user agents</strong> to set the computed
+      value to a "reasonable" value based on the font size of
+      the element.
+    </p>
+  </s3>
+  <p>
+    ... When an element contains text that is rendered in more
+    than one font, <strong>user agents</strong> should determine
+    the "line-height" value according to the largest font size.
+  </p>
+      </section>
+      <section>
+        <title>7.15.9 "text-align"</title>
+  <p>
+    ... The actual justification algorithm used is <strong>user
+    agent</strong> and written language dependent.<br/>
+    Conforming <strong>user agents</strong> may interpret the
+    value 'justify' as 'left' or 'right', depending on whether
+    the element's default writing direction is left-to-right or
+    right-to-left, respectively.
+  </p>
+      </section>
+      <section>
+        <title>7.15.11 "text-indent"</title>
+  <p>
+    ... <strong>User agents</strong> should render this
+    indentation as blank space.
+  </p>
+      </section>
+      <section>
+        <title>7.16.2 "letter-spacing"</title>
+  <section>
+    <title>normal</title>
+    <p>
+      The spacing is the normal spacing for the current
+      font. This value allows the <strong>user agent</strong> to
+      alter the space between characters in order to justify
+      text.
+    </p>
+  </section>
+  <section>
+    <title>&lt;length&gt;</title>
+    <p>
+      This value indicates inter-character space in addition to
+      the default space between characters. Values may be
+      negative, but there may be implementation-specific
+      limits. <strong>User agents</strong> may not further
+      increase or decrease the inter-character space in order to
+      justify text.
+    </p>
+  </section>
+  <p>
+    Character-spacing algorithms are <strong>user agent</strong>
+    dependent. Character spacing may also be influenced by
+    justification (see the "text-align" property).<br/> When the
+    resultant space between two characters is not the same as
+    the default space, <strong>user agents</strong> should not
+    use ligatures.<br/> Conforming <strong>user agents</strong>
+    may consider the value of the 'letter-spacing' property to
+    be 'normal'.
+  </p>
+  <section>
+    <title>XSL modifications to the CSS definition:</title>
+    <p>
+      ...  For "normal": .optimum = "the normal spacing for the
+      current font" / 2, .maximum = auto, .minimum = auto,
+      .precedence = force, and .conditionality = discard. A
+      value of auto for a component implies that the limits are
+      <strong>User Agent</strong> specific.
+    </p>
+    <p>
+      ... The CSS statement that "Conforming <strong>user
+      agents</strong> may consider the value of the
+      'letter-spacing' property to be 'normal'." does not apply
+      in XSL, if the <strong>User Agent</strong> implements the
+      "Extended" property set.
+    </p>
+    <p>
+      ... The algorithm for resolving the adjusted values
+      between word spacing and letter spacing is <strong>User
+      Agent</strong> dependent.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.16.4 "text-decoration"</title>
+  <p>
+    ... If the element has no content or no text content (e.g.,
+    the IMG element in HTML), <strong>user agents</strong> must
+    ignore this property.
+  </p>
+  <section>
+    <title>blink</title>
+    <p>
+      ...  Conforming <strong>user agents</strong> are not
+      required to support this value.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.16.6 "text-transform"</title>
+  <p>
+    ... Conforming <strong>user agents</strong> may consider the
+    value of "text-transform" to be "none" for characters that
+    are not from the ISO Latin-1 repertoire and for elements in
+    languages for which the transformation is different from
+    that specified by the case-conversion tables of Unicode or
+    ISO 10646.
+  </p>
+      </section>
+      <section>
+        <title>7.16.8 "word-spacing"</title>
+  <p>
+    ... Word spacing algorithms are <strong>user
+    agent</strong>-dependent.
+  </p>
+  <section>
+    <title>XSL modifications to the CSS definition:</title>
+    <p>
+      ... The algorithm for resolving the adjusted values
+      between word spacing and letter spacing is <strong>User
+      Agent</strong> dependent.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.17.1 "color"</title>
+  <p>Initial: depends on <strong>user agent</strong></p>
+      </section>
+      <section>
+        <title>7.17.3 "rendering-intent"</title>
+  <section>
+    <title>auto</title>
+    <p>
+      This is the default behavior. The <strong>User
+      Agent</strong> determines the best intent based on the
+      content type. For image content containing an embedded
+      profile, it shall be assumed that the intent specified
+      within the profile is the desired intent. Otherwise, the
+      <strong>user agent</strong> shall use the current profile
+      and force the intent, overriding any intent that might be
+      stored in the profile itself.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.20.2 "overflow"</title>
+  <section>
+    <title>scroll</title>
+    <p>
+      This value indicates that the content is clipped and that
+      if the <strong>user agent</strong> uses a scrolling
+      mechanism that is visible on the screen (such as a scroll
+      bar or a panner), that mechanism should be displayed for a
+      box whether or not any of its content is clipped.
+    </p>
+  </section>
+  <section>
+    <title>auto</title>
+    <p>
+      The behavior of the "auto" value is <strong>user
+      agent</strong> dependent, but should cause a scrolling
+      mechanism to be provided for overflowing boxes.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.21.2 "leader-pattern"</title>
+  <section>
+    <title>dots</title>
+    <p>
+      ... The choice of dot character is dependent on the
+      <strong>user agent</strong>.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.21.4 "leader-length"</title>
+  <p>
+    ... <strong>User agents</strong> may choose to use the value
+    of "leader-length.optimum" to determine where to break the
+    line, then use the minimum and maximum values during line
+    justification.
+  </p>
+      </section>
+      <section>
+        <title>7.25.11 "media-usage"</title>
+  <section>
+    <title>auto</title>
+    <p>
+      The <strong>User Agent</strong> determines which value of
+      "media-usage" (other than the "auto" value) is used. The
+      <strong>User Agent</strong> may consider the type of media
+      on which the presentation is to be placed in making this
+      determination.<br/> NOTE:<br/> For example, the
+      <strong>User Agent </strong> could use the following
+      decision process. If the media is not continuous and is of
+      fixed bounded size, then the "paginate" (described below)
+      is used. Otherwise, the "bounded-in-one-dimension" is
+      used.
+    </p>
+  </section>
+  <section>
+    <title>bounded-in-one-dimension</title>
+    <p>
+      ... It is an error if more or less than one of
+      "page-height" or "page-width" is specified on the first
+      page master that is used. The <strong>User Agent</strong>
+      may recover as follows:...
+    </p>
+  </section>
+  <section>
+    <title>unbounded</title>
+    <p>
+      Only one page is generated per fo:page-sequence descendant
+      from the fo:root. Neither "page-height" nor "page-width"
+      may be specified on any page master that is used. If a
+      value is specified for either property, it is an error and
+      a <strong>User Agent</strong> may recover by ignoring the
+      specified value. ...
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.25.13 "page-height"</title>
+  <section>
+    <title>auto</title>
+    <p>
+      The "page-height" shall be determined, in the case of
+      continuous media, from the size of the <strong>User
+      Agent</strong> window...
+    </p>
+  </section>
+  <section>
+    <title>NOTE:</title>
+    <p>
+      A <strong>User Agent</strong> may provide a way to declare
+      the media for which formatting is to be done. This may be
+      different from the media on which the formatted result is
+      viewed. For example, a browser <strong>User Agent</strong>
+      may be used to preview pages that are formatted for sheet
+      media. In that case, the size calculation is based on the
+      media for which formatting is done rather than the media
+      being currently used.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.25.15 "page-width"</title>
+  <section>
+    <title>auto</title>
+    <p>
+      The "page-width" shall be determined, in the case of
+      continuous media, from the size of the <strong>User
+      Agent</strong> window...
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.26.5 "border-separation"</title>
+  <s3 title="&lt;length-bp-ip-direction&gt;">
+    <p>
+      ... Rows, columns, row groups, and column groups cannot
+      have borders (i.e., <strong>user agents</strong> must
+      ignore the border properties for those elements).
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.26.7 "caption-side"</title>
+  <p>
+    ... For a caption that is on the left or right side of a
+    table box, on the other hand, a value other than "auto" for
+    "width" sets the width explicitly, but "auto" tells the
+    <strong>user agent</strong> to chose a "reasonable width".
+  </p>
+      </section>
+      <section>
+        <title>7.27.2 "glyph-orientation-horizontal"</title>
+  <section>
+    <title>&lt;angle&gt;</title>
+    <p>
+      ... The <strong>User Agent</strong> shall round the value
+      of the angle to the closest of the permitted values.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.27.3 "glyph-orientation-vertical"</title>
+  <section>
+    <title>auto</title>
+    <p>
+      ... The determination of which characters should be
+      auto-rotated may vary across <strong>User Agents</strong>.
+    </p>
+  </section>
+  <section>
+    <title>&lt;angle&gt;</title>
+    <p>
+      ... The <strong>User Agent</strong> shall round the value
+      of the angle to the closest of the permitted values.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.27.6 "unicode-bidi"</title>
+  <section>
+    <title>XSL modifications to the CSS definition:</title>
+    <p>
+      ... Fallback:<br/> If it is not possible to present the
+      characters in the correct order, then the
+      <strong>UserAgent </strong> should display either a
+      'missing character' glyph or display some indication that
+      the content cannot be correctly rendered.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.28.1 "content-type"</title>
+  <p>
+    ... This property specifies the content-type and may be used
+    by a <strong>User Agent</strong> to select a rendering
+    processor for the object.
+  </p>
+  <section>
+    <title>auto</title>
+    <p>
+      No identification of the content-type. The <strong>User
+      Agent</strong> may determine it by "sniffing" or by other
+      means.
+    </p>
+  </section>
+      </section>
+      <section>
+        <title>7.29.5 "border-color"</title>
+  <p>
+    ... If an element's border color is not specified with a
+    "border" property, <strong>user agents</strong> must use the
+    value of the element's "color" property as the computed
+    value for the border color.
+  </p>
+      </section>
+      <section>
+        <title>7.29.9 "border-spacing"</title>
+  <p>
+    ... Rows, columns, row groups, and column groups cannot have
+    borders (i.e., <strong>user agents</strong> must ignore the
+    border properties for those elements).
+  </p>
+      </section>
+      <section>
+        <title>7.29.13 "font"</title>
+  <p>
+    ... If no font with the indicated characteristics exists on
+    a given platform, the <strong>user agent</strong> should
+    either intelligently substitute (e.g., a smaller version of
+    the "caption" font might be used for the "small-caption"
+    font), or substitute a <strong>user agent</strong> default
+    font.
+  </p>
+      </section>
+      <section>
+        <title>7.29.19 "pause"</title>
+  <p>Initial: depends on <strong>user agent</strong></p>
+      </section>
+      <section>
+        <title>7.29.21 "size"</title>
+  <p>
+    ... Relative page boxes allow <strong>user agents</strong>
+    to scale a document and make optimal use of the target size.
+  </p>
+  <p>
+    ... <strong>User agents</strong> may allow users to control
+    the transfer of the page box to the sheet (e.g., rotating an
+    absolute page box that's being printed).
+  </p>
+  <ul>
+    <li>
+      Rendering page boxes that do not fit a target sheet<br/>
+      If a page box does not fit the target sheet dimensions,
+      the <strong>user agent</strong> may choose to:
+      <ul>
+        <li>
+    Rotate the page box 90 degrees if this will make the
+    page box fit.
+        </li>
+        <li>Scale the page to fit the target.</li>
+      </ul>
+      The <strong>user agent</strong> should consult the user
+      before performing these operations.
+    </li>
+    <li>
+      Positioning the page box on the sheet<br/> When the page
+      box is smaller than the target size, the <strong>user
+      agent</strong> is free to place the page box anywhere on
+      the sheet.
+    </li>
+  </ul>
+      </section>
+      <section>
+        <title>7.29.23 "white-space"</title>
+  <section>
+    <title>normal</title>
+    <p>
+      This value directs <strong>user agents</strong> to
+      collapse sequences of whitespace, and break lines as
+      necessary to fill line boxes. ...
+    </p>
+  </section>
+  <section>
+    <title>pre</title>
+    <p>
+      This value prevents <strong>user agents</strong> from
+      collapsing sequences of whitespace. ...
+    </p>
+  </section>
+  <p>
+    ... Conforming <strong>user agents</strong> may ignore the
+    'white-space' property in author and user style sheets but
+    must specify a value for it in the default style sheet.
+  </p>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/alt.design/xml-parsing.xml b/src/documentation/content/xdocs/design/alt.design/xml-parsing.xml
new file mode 100644
index 000000000..6151dae74
--- /dev/null
+++ b/src/documentation/content/xdocs/design/alt.design/xml-parsing.xml
@@ -0,0 +1,228 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
+    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
+
+<document>
+    <header>
+        <title>Integrating XML Parsing</title>
+    <authors>
+      <person name="Peter B. West" email="pbwest@powerup.com.au"/>
+    </authors>
+    </header>
+    <body>
+    <section>
+      <title>An alternative parser integration</title>
+      <p>
+  This note proposes an alternative method of integrating the
+  output of the SAX parsing of the Flow Object (FO) tree into
+  FOP processing.  The pupose of the proposed changes is to
+  provide for better decomposition of the process of analysing
+  and rendering an fo tree such as is represented in the output
+  from initial (XSLT) processing of an XML source document.
+      </p>
+      <section>
+        <title>Structure of SAX parsing</title>
+  <p>
+    Figure 1 is a schematic representation of the process of SAX
+    parsing of an input source.  SAX parsing involves the 
+    registration, with an object implementing the 
+    <code>XMLReader</code> interface, of a
+    <code>ContentHandler</code> which contains a callback
+    routine for each of the event types encountered by the
+    parser, e.g., <code>startDocument()</code>,
+    <code>startElement()</code>, <code>characters()</code>,
+    <code>endElement()</code> and <code>endDocument()</code>.
+    Parsing is initiated by a call to the <code>parser()</code>
+    method of the <code>XMLReader</code>.  Note that the call to
+    <code>parser()</code> and the calls to individual callback
+    methods are synchronous: <code>parser()</code> will only
+    return when the last callback method returns, and each
+    callback must complete before the next is called.<br/><br/>
+    <strong>Figure 1</strong>
+  </p>
+  <figure src="SAXParsing.png" alt="SAX parsing schematic"/>
+  <p>
+    In the process of parsing, the hierarchical structure of the
+    original FO tree is flattened into a number of streams of
+    events of the same type which are reported in the sequence
+    in which they are encountered.  Apart from that, the API
+    imposes no structure or constraint which expresses the
+    relationship between, e.g., a startElement event and the
+    endElement event for the same element.  To the extent that
+    such relationship information is required, it must be
+    managed by the callback routines.
+  </p>
+  <p>
+    The most direct approach here is to build the tree
+    "invisibly"; to bury within the callback routines the
+    necessary code to construct the tree.  In the simplest case,
+    the whole of the FO tree is built within the call to
+    <code>parser()</code>, and that in-memory tree is subsequently
+    processed to (a) validate the FO structure, and (b)
+    construct the Area tree.  The problem with this approach is
+    the potential size of the FO tree in memory.  FOP has
+    suffered from this problem in the past.
+  </p>
+      </section>
+      <section>
+        <title>Cluttered callbacks</title>
+  <p>
+    On the other hand, the callback code may become increasingly
+    complex as tree validation and the triggering of the Area
+    tree processing and subsequent rendering is moved into the
+    callbacks, typically the <code>endElement()</code> method.
+    In order to overcome acute memory problems, the FOP code was
+    recently modified in this way, to trigger Area tree building
+    and rendering in the <code>endElement()</code> method, when
+    the end of a page-sequence was detected.
+  </p>
+  <p>
+    The drawback with such a method is that it becomes difficult
+    to detemine the order of events and the circumstances in
+    which any particular processing events are triggered.  When
+    the processing events are inherently self-contained, this is
+    irrelevant.  But the more complex and context-dependent the
+    relationships are among the processing elements, the more
+    obscurity is engendered in the code by such "side-effect"
+    processing.
+  </p>
+      </section>
+      <section>
+        <title>From passive to active parsing</title>
+  <p>
+    In order to solve the simultaneous problems of exposing the
+    structure of the processing and minimising in-memory
+    requirements, the experimental code separates the parsing of
+    the input source from the building of the FO tree and all
+    downstream processing.  The callback routines become
+    minimal, consisting of the creation and buffering of
+    <code>XMLEvent</code> objects as a <em>producer</em>.  All
+    of these objects are effectively merged into a single event
+    stream, in strict event order, for subsequent access by the
+    FO tree building process, acting as a
+    <em>consumer</em>.  In itself, this does not reduce the
+    footprint.  This occurs when the approach is generalised to
+    modularise FOP processing.<br/><br/> <strong>Figure 2</strong>
+  </p>
+  <figure src="XML-event-buffer.png" alt="XML event buffer"/>
+  <p>
+    The most useful change that this brings about is the switch
+    from <em>passive</em> to <em>active</em> XML element
+    processing.  The process of parsing now becomes visible to
+    the controlling process.  All local validation requirements,
+    all object and data structure building, is initiated by the
+    process(es) <em>get</em>ting from the queue - in the case
+    above, the FO tree builder.
+  </p>
+      </section>
+      <section>
+        <title>XMLEvent methods</title>
+  <anchor id="XMLEvent-methods"/>
+  <p>
+    The experimental code uses a class <strong>XMLEvent</strong>
+    to provide the objects which are placed in the queue.
+    <em>XMLEvent</em> includes a variety of methods to access
+    elements in the queue.  Namespace URIs encountered in
+    parsing are maintined in a <code>static</code>
+    <code>HashMap</code> where they are associated with a unique
+    integer index.  This integer value is used in the signature
+    of some of the access methods.
+  </p>
+  <dl>
+    <dt>XMLEvent getEvent(SyncedCircularBuffer events)</dt>
+    <dd>
+      This is the basis of all of the queue access methods.  It
+      returns the next element from the queue, which may be a
+      pushback element.
+    </dd>
+    <dt>XMLEvent getEndDocument(events)</dt>
+    <dd>
+      <em>get</em>  and discard elements from the queue
+      until an ENDDOCUMENT element is found and returned.
+    </dd>
+    <dt> XMLEvent expectEndDocument(events)</dt>
+    <dd>
+      If the next element on the queue is an ENDDOCUMENT event,
+      return it.  Otherwise, push the element back and throw an
+      exception.  Each of the <em>get</em>  methods (except
+      <em>getEvent()</em>  itself) has a corresponding
+      <em>expect</em>  method.
+    </dd>
+    <dt>XMLEvent get/expectStartElement(events)</dt>
+    <dd> Return the next STARTELEMENT event from the queue.</dd>
+    <dt>XMLEvent get/expectStartElement(events, String
+      qName)</dt>
+    <dd>
+      Return the next STARTELEMENT with a QName matching
+      <em>qName</em>.
+    </dd>
+    <dt>
+      XMLEvent get/expectStartElement(events, int uriIndex,
+      String localName)
+    </dt>
+    <dd>
+      Return the next STARTELEMENT with a URI indicated by the
+      <em>uriIndex</em> and a local name matching <em>localName</em>.
+    </dd>
+    <dt>
+      XMLEvent get/expectStartElement(events, LinkedList list)
+    </dt>
+    <dd>
+      <em>list</em>  contains instances of the nested class
+      <code>UriLocalName</code>, which hold a
+      <em>uriIndex</em>  and a <em>localName</em>.  Return
+      the next STARTELEMENT with a URI indicated by the
+      <em>uriIndex</em>  and a local name matching
+      <em>localName</em>  from any element of
+      <em>list</em>.
+    </dd>
+    <dt>XMLEvent get/expectEndElement(events)</dt>
+    <dd>Return the next ENDELEMENT.</dd>
+    <dt>XMLEvent get/expectEndElement(events, qName)</dt>
+    <dd>Return the next ENDELEMENT with QName
+      <em>qname</em>.</dd>
+    <dt>XMLEvent get/expectEndElement(events, uriIndex, localName)</dt>
+    <dd>
+      Return the next ENDELEMENT with a URI indicated by the
+      <em>uriIndex</em>  and a local name matching
+      <em>localName</em>.
+    </dd>
+    <dt>
+      XMLEvent get/expectEndElement(events, XMLEvent event)
+    </dt>
+    <dd>
+      Return the next ENDELEMENT with a URI matching the
+      <em>uriIndex</em>  and <em>localName</em>
+      matching those in the <em>event</em>  argument.  This
+      is intended as a quick way to find the ENDELEMENT matching
+      a previously returned STARTELEMENT.
+    </dd>
+    <dt>XMLEvent get/expectCharacters(events)</dt>
+    <dd>Return the next CHARACTERS event.</dd>
+  </dl>
+      </section>
+      <section>
+        <title>FOP modularisation</title>
+  <p>
+    This same principle can be extended to the other major
+    sub-systems of FOP processing.  In each case, while it is
+    possible to hold a complete intermediate result in memory,
+    the memory costs of that approach are too high.  The
+    sub-systems - xml parsing, FO tree construction, Area tree
+    construction and rendering - must run in parallel if the
+    footprint is to be kept manageable.  By creating a series of
+    producer-consumer pairs linked by synchronized buffers,
+    logical isolation can be achieved while rates of processing
+    remain coupled.  By introducing feedback loops conveying
+    information about the completion of processing of the
+    elements, sub-systems can dispose of or precis those
+    elements without having to be tightly coupled to downstream
+    processes.<br/><br/>
+    <strong>Figure 3</strong>
+  </p>
+  <figure src="processPlumbing.png" alt="FOP modularisation"/>
+      </section>
+    </section>
+    </body>
+</document>
+
diff --git a/src/documentation/content/xdocs/design/book.xml b/src/documentation/content/xdocs/design/book.xml
index 43e5e4834..4e38265b4 100644
--- a/src/documentation/content/xdocs/design/book.xml
+++ b/src/documentation/content/xdocs/design/book.xml
@@ -12,6 +12,7 @@
     </menu>
     <menu label="About">
       <menu-item label="Index" href="index.html"/>
+      <menu-item label="Understanding" href="understanding/index.html"/>
     </menu>
     <menu label="Overview">
       <menu-item label="Architecture" href="architecture.html"/>
@@ -33,5 +34,8 @@
     <menu label="Status">
       <menu-item label="Status" href="status.html"/>
     </menu>
+    <menu label="Alternate">
+      <menu-item label="ALT DESIGN" href="alt.design/index.html"/>
+    </menu>
 </book>
 
-- 
2.39.5