Finish restructuring.

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

1 files changed, 38 insertions, 51 deletions

diff --git a/src/documentation/content/xdocs/design/fotree.xml b/src/documentation/content/xdocs/design/fotree.xml
index f91c6117f..ced433044 100644
--- a/src/documentation/content/xdocs/design/fotree.xml
+++ b/src/documentation/content/xdocs/design/fotree.xml
@@ -18,8 +18,10 @@ The FO Tree is an intermediate structure which will later be <link href="layout.
     <section id="process">
       <title>Processing</title>
       <p>The SAX Events that are fired by the parsing process are caught by the FO Tree system.
-Events for starting an element, ending an element, and text data are assembled by the FO Tree system into a set of objects that represent the input FO document.</p>
+Events for starting an element, ending an element, and text data are assembled by the FO Tree system into a set of objects that represent the input FO document.
+A class exists for each element in the XSL-FO set, and an object in the appropriate class is created for each element in the input XSL-FO.</p>
       <p>For attributes attached to an XSL-FO element, a property list mapping is used to convert the attribute into properties of the object related to the element.</p>
+      <p>To the extent possible, validation is checked as the FO Tree is built. An appropriate error message is returned to the user, and processing continues if possible.</p>
       <p>Elements from <link href="parsing.html#namespaces">foreign namespaces</link> that are recognized by FOP fall into the following categories:</p>
       <ul>
         <li>Pass-thru: These are placed into a DOM object, which is then passed through FOP directly to the renderer. SVG is an example.</li>
@@ -53,21 +55,20 @@ There are at least three possible places that FO Tree fragments could be passed
         <title>page-master</title>
         <p>The first elements in a document are the elements for the page master setup.
 This is usually only a small number and will be used throughout the document to create new pages.
-These elements are kept as a factory to create the page and appropriate regions whenever a new page is requested by the layout.
-The objects in the FO Tree that represent these elements are themselves the factory.
-The root element keeps these objects as a factory for the page sequences.</p>
+The root element keeps these objects as a factory to create the page and appropriate regions whenever a new page is requested by the layout.
+The objects in the FO Tree that represent these elements are themselves the factory.</p>
       </section>
       <section id="flow">
         <title>flow</title>
-        <p>The elements that are in the flow of the document are a set of elements
-that is needed for the layout process. Each element is important in the
-creation of areas.</p>
+        <p>The elements within the flow of a page-sequence are those that are needed for the layout process.
+These element will later be used to create areas in the layout process.</p>
       </section>
       <section id="other-elements">
         <title>Other Elements</title>
         <p>The remaining FO Objects are things like page-sequence, title and color-profile.
-These are handled by their parent element; i.e. the root looks after the declarations and the declarations maintains a list of colour profiles.
-The page-sequences are direct descendents of root.</p>
+Each is handled by its parent element.
+The root handles declarations, and declarations maintains a list of colour profiles.
+The page-sequences are direct descendants of root.</p>
       </section>
     </section>
     <section id="implement">
@@ -75,35 +76,28 @@ The page-sequences are direct descendents of root.</p>
       <section id="fonode">
         <title>FONode</title>
         <p>The base class for all objects in the tree is FONode. The base class for
-all FO Objects is FObj.</p>
-        <p>The class inheritance described above only describes the nature of the
-content. Every FO in FOP also has a parent, and a Vector of children. The
-parent attribute (in the Java sense), in particular, is used to enforce
-constraints required by the FO hierarchy.</p>
-        <p>FONode, among other things, ensures that FO's have a parent and that they
-may have children.</p>
-        <p>Each xml element is represented by a java object. For pagination the
-classes are in <code>org.apache.fop.fo.pagination.*</code>, for elements in the flow
-they are in <code>org.apache.fop.fo.flow.*</code> and some others are in
-<code>org.apache.fop.fo.*.</code>
-        </p>
+all FO Objects is FObj (which is a subclass of FONode). Other FONode subclasses are for foreign and unknown XML.</p>
+        <p>Each FO in FOP has a parent (except root) and a Vector of children. Java inheritance (superclasses and subclasses) is used to enforce constraints required by the FO hierarchy.</p>
+        <p>FONode, among other things, ensures that each FO has a parent, and provides the mechanism for keeping track of its children.</p>
+        <p>Each xml element is represented by a java object.
+The classes for these objects are grouped into packages for convenience:</p>
+        <ul>
+          <li>pagination: <code>org.apache.fop.fo.pagination.*</code></li>
+          <li>flow: <code>org.apache.fop.fo.flow.*</code></li>
+          <li>other: <code>org.apache.fop.fo.*.</code></li>
+        </ul>
       </section>
       <section id="create-fo">
-        <title>Making FO's</title>
-        <p>There is a class for each element in the FO set. An object is created for
-each element in the FO Tree. This object holds the properties for the FO
-Object.</p>
-        <p>Some validity checking is done during these steps. The user can be warned of the error and processing can continue if possible.</p>
-        <p>When the object is created it is setup.
-It is given its element name, the FOUserAgent - for resolving properties etc. - the logger and the attributes.
-The methods <code>handleAttributes()</code> and <code>setuserAgent()</code>, common to <code>FONode</code>, are used in this process.
-The object will then be given any text data or child elements.
-Then the <code>end()</code> method is called.
-The end method is used by a number of elements to indicate that it can do certain processing since all the children have been added.</p>
-        <p>An FO maker is read from a hashmap lookup using the namespace and
-element name. This maker is then used to create a new class that
-represents an FO element. This is then added to the FO tree as a child
-of the current parent.</p>
+        <title>Creating FO Objects</title>
+        <p>The process of creating an FO Object is as follows (see <code>FOTreeBuilder.startElement()</code> for details):</p>
+        <ul>
+          <li>An FO maker is selected from a hashmap lookup using the namespace and
+element name.</li>
+          <li>This maker is then used to create the new object that represents the FO element.</li>
+          <li>The new object is given its element name, an FOUserAgent (for resolving properties, etc.), a logger and its attributes.</li>
+          <li>The new object is added to the FO tree as a child of the current parent.</li>
+          <li>Child elements are then processed. This is an iterative process: the child elements go through the same process here documented for their parent.</li>
+        </ul>
       </section>
       <section id="foreign">
         <title>Foreign XML</title>
@@ -113,26 +107,19 @@ DOM Element and the setting of attributes. It also can create a DOM
 Document if it is a top level element, class XMLElement.
 This class must be extended for the namespace of the XML elements. For
 unknown namespaces the class is UnknowXMLObj.</p>
-        <p>If some special processing is needed then the top level element can extend
+        <p>If some special processing is needed, then the top level element can extend
 the XMLObj. For example the SVGElement makes the special DOM required for
 batik and gets the size of the svg.</p>
-        <p>Foreign XML will usually be in an fo:instream-foreign-object, the XML will
-be passed to the render as a DOM where the render will be able to handle
-it. Other XML from an unknwon namespace will be ignored.</p>
-        <p>By using element mappings it is possible to read other XML and either</p>
-        <ul>
-          <li>set information on the area tree</li>
-          <li>create pseudo FO Objects that create areas in the area tree</li>
-          <li>create FO Objects</li>
-        </ul>
+        <p>Foreign XML will usually be in an fo:instream-foreign-object.
+The XML will be passed to the renderer as a DOM, which is expected to know how to handle it.
+XML from an unknown namespace will be ignored.</p>
+        <p>See <link href="parsing.html#namespaces">Input Parsing Namespaces</link> for more discussion and links to information about using foreign XML in FOP.</p>
       </section>
       <section id="unknown">
         <title>Unknown Elements</title>
-        <p>If an element is in a known namespace but the element is unknown then an
-Unknown object is created. This is mainly to provide information to the
-user.
-This could happen if the fo document contains an element from a different
-version or the element is misspelt.</p>
+        <p>If an element is in a known namespace but the element is unknown within that namespace, then an Unknown object is created.
+This generally indicates an input error: perhaps an element from an older version of the XSL-FO standard, or a misspelling.
+The Unknown object is mainly used to provide information to the user.</p>
       </section>
     </section>
   </body>