updated some information

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

6 files changed, 128 insertions, 89 deletions

diff --git a/src/documentation/content/xdocs/design/architecture.xml b/src/documentation/content/xdocs/design/architecture.xml
index f76fc9273..752bb394b 100644
--- a/src/documentation/content/xdocs/design/architecture.xml
+++ b/src/documentation/content/xdocs/design/architecture.xml
@@ -20,7 +20,7 @@
   <title>Introduction</title>
 <p>
 The overall process is controlled by <em>org.apache.fop.apps.Driver</em>.
-This class handles the FO Tree building, renderers, output and logging.
+This class handles the FO Tree building, structure handler, renderers, output and logging.
 </p>
 <p>
 The process in general is that the FO document is sent to the tree
@@ -39,22 +39,55 @@ actually constructing the FO tree. The key SAX events used are </p>
 <p><code>startElement()</code>,</p>
 <p><code>endElement()</code> and <code>characters()</code>.</p>
 
-<p>All formatting objects derive from abstract class
-<em>org.apache.fop.fo.FONode</em>. The other FO classes inherit from
-<em>FONode</em> as follows:</p>
+</section>
 
+<section>
+  <title>Layout</title>
+<p>
+The layout managers handle the layout. They take an FO tree and construct
+the area tree.
+The layout process involves finding out where line breaks and page
+breaks should be made. The areas are then added to the page. The
+static areas can the be done for all the static regions.
+Completed pages are then added to the area tree, the area tree can
+then deal with the page.
+</p>
+</section>
+
+<section>
+  <title>Area Tree</title>
+<p>
+The area tree is a data structure designed to hold the page areas.
+These pages are then filled with the page regions and various areas.
+The area tree is used primarily as a minimal structure that can be rendered
+by the renderers.
+</p>
+<p>
+The area tree is supported by an area tree model. This model
+handles the adding of pages to the area tree. It also handles
+page sequence starts, document level extensions, id references
+and unresolved id areas. This model allows the pages to be handled
+directly by a renderer or to store the pages for later use.
+</p>
 </section>
 
+
 <section>
   <title>Rendering</title>
 <p>
-This is a separate process. The <code>render()</code> method in
-<em>Driver</em> is invoked (say,
-by <em>CommandLine</em>) with the laid-out <em>AreaTree</em> and a
-<em>PrintWriter</em> as arguments.
-This actually calls the <code>render()</code> method in a specific implementation of
-the <em>Renderer</em> interface, typically <em>PDFRenderer</em> or
-<em>AWTRenderer</em>.
+The renderer receives pages from the area tree and renders those pages.
+If a renderer supports out of order rendering then it will either
+render or prepare a page in the correct order. Otherwise the
+pages are rendered in order.
+The task of the renderer is to take the pages and output them to
+the requested type.
+In the case of the AWTRenderer it needs to be able to view any page.
+</p>
+<p>
+When rendering a page it takes the page and renders each page region.
+The main work for a renderer implementation is to handle the viewports
+and inline areas. The inline areas need to be dran on the page in the
+correct place.
 </p>
 </section>
 
diff --git a/src/documentation/content/xdocs/design/areas.xml b/src/documentation/content/xdocs/design/areas.xml
index a7d4e4615..51b197534 100644
--- a/src/documentation/content/xdocs/design/areas.xml
+++ b/src/documentation/content/xdocs/design/areas.xml
@@ -15,15 +15,16 @@
 <section>
   <title>Area Tree</title>
 <p>
-The code to implement the area tree will attempt to match the areas
-defined in the specification. A number of optimisations may be possible
-for similar areas and groups of areas.
+The code to implement the area tree matches the areas
+defined in the specification. This makes it easier to understand and
+correspond with the specification.
   </p>
   <p>
-Since the area tree will be used during the layout by the layout managers
-it will need to store information that affects the layout. The information
-such as spacing and keeps will be held in such a way that it can be
-discarded once the layout is finalised.
+The area tree is created by the layout managers once the layout is decided
+for a page. Once a completed page is finished it can then be added to the
+area tree. The area tree model can then handle the new page. The data in
+the area tree must be minimal and independant. This means that the data
+uses less memory and can be serialized to an output stream if needed.
   </p>
 <section>
   <title>Structure</title>
@@ -31,7 +32,7 @@ discarded once the layout is finalised.
 The area tree is a root element that has a list of page-viewport-areas.
 Each page viewport has a page-reference-area which holds the contents of
 the page. To handle the processing better FOP does not maintain a list
-at the root level but lets another class handle each page as it is added.
+at the root level but lets the area tree model handle each page as it is added.
   </p>
   </section>
 <section>
@@ -52,25 +53,18 @@ reference areas.
 Since the layout is done inside a page, the page is created from the
 pagemaster with all the appropriate areas. The layout manager then
 uses the page to add areas into the normal flow reference areas
-and floats and footnotes. After the layout of the body region
-is complete then the other regions can be done.
+and floats and footnotes. After adding the areas for the body region
+then the other regions can be done layed out and added.
   </p>
   </section>
 <section>
   <title>Block Areas</title>
 <p>
 Block areas are created and/or returned by all top level elements
-in the flow. These areas have keep and spacing information that
-needs to be retained until the page is finalised. A block area
-is stacked with other block areas in a particular direction, it
-has a size and it contains either line areas made from a group
-of inline areas or block areas.
-  </p>
-  <p>
-A block area can also be split into two block areas by splitting
-between two line areas or splitting between two block areas (or
-groups) that are stacked in the block progression direction of
-the page. The split may also be in a child block area.
+in the flow. The spacing between block areas is handled by an
+empty block area. A block area is stacked with other block
+areas in a particular direction, it has a size and it contains
+line areas made from a group of inline areas and/or block areas.
   </p>
   </section>
 <section>
@@ -78,22 +72,22 @@ the page. The split may also be in a child block area.
 <p>
 A line areas is simply a collection of inline areas that are stacked
 in the inline progression direction. A line area has a height and
-width. It also contains information about floats and footnotes
-that are associated with the inline areas.
+a start position. The line area is rendered by handling each inline
+area.
   </p>
   <p>
 A line area gets a set of inline areas added until complete then
-it is justified and vertically aligned. If the line area contains
-unresolved areas it will retain the justification information
-until all areas are resolved.
+it is justified and vertically alignedi when adding the areas.
+If the line area contains unresolved areas then there will
+be a line resolver that retains the justification information until
+all areas in the line are resolved.
   </p>
   </section>
 <section>
   <title>Inline Areas</title>
 <p>
 There are a few different types of inline areas. All inline areas
-have a height. Their width may be variable until the line is
-finalised.
+have a height and width.
   </p>
   <p>
 Unresolved areas can reserve some space to allow for possible
@@ -102,15 +96,13 @@ and finalised.
   </p>
   </section>
 <section>
-  <title>Cloning</title>
+  <title>Repeated Areas</title>
 <p>
-Any subtree of the area tree should be cloneable so that for
-areas that are repeated the area tree can simply be copied rather
-than going through the layout again. This will only work if the
-width is the same.
-  </p>
-  <p>
-Resolveable areas may be converted into an unresolved form.
+There are cases where the same subtree could be repeated in the area
+tree. These areas will be returned by the same layout managers.
+So it is possible to put a flag on the created areas so that
+the subtree data can be cached in the output. Examples of this are:
+static areas, table header/footer, svg.
   </p>
   </section>
 <section>
@@ -130,23 +122,24 @@ flow areas added.
 <section>
   <title>Block Area Classes</title>
 <p>
-The block areas typically hold either a set of line areas or a set of
-block areas. The child areas are usually stacked in a particular
-direction.
+The block areas hold other block areas and/or line areas. The
+child areas are stacked in a particular direction.
   </p>
   <p>
-Areas for tables and lists have their child block areas stacked
-in different ways. Lists also can have spacing between the block
-areas.
+Areas for tables, lists and block container have their child
+block areas stacked in different ways. These areas a placed
+with an absolute positioning. The absolute positioning is where
+the blocks are placed with an offset from the parent reference area.
   </p>
   </section>
 <section>
   <title>Inline Area Classes</title>
 <p>
 The inline areas are used to make up a line area. An inline area
-typically has a height, width and some content. The alignment is
-used for block progression direction displacement and to determine
-the height of a line.
+typically has a height, width and some content. The inline area
+is offset from the baseline of the current line area. The content
+of the inline area can be other inline areas or a simple atomic
+object.
   </p>
   </section>
   </section>
@@ -169,7 +162,7 @@ Line
 Inline
   </p>
   <p>
-The renderer will need to be able to:
+A renderer implementation does the following:
   </p>
        <ul>
        <li>render each individual page</li>
diff --git a/src/documentation/content/xdocs/design/book.xml b/src/documentation/content/xdocs/design/book.xml
index 4e38265b4..8226fbcd9 100644
--- a/src/documentation/content/xdocs/design/book.xml
+++ b/src/documentation/content/xdocs/design/book.xml
@@ -31,9 +31,6 @@
       <menu-item label="Optimisations" href="optimise.html"/>
       <menu-item label="User Agent" href="useragent.html"/>
     </menu>
-    <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>
diff --git a/src/documentation/content/xdocs/design/embedding.xml b/src/documentation/content/xdocs/design/embedding.xml
index 42812b063..0198c3ad4 100644
--- a/src/documentation/content/xdocs/design/embedding.xml
+++ b/src/documentation/content/xdocs/design/embedding.xml
@@ -28,6 +28,18 @@ of a server side application such as <jump href="http://xml.apache.org/cocoon/in
 <section>
   <title>User Agent</title>
 <p>
+Possible meanings for a user agent:
+</p>
+<ul>
+<li>something that makes decisions where the specifiction indicates
+that the user agent should decide</li>
+<li>Fop as the user agent, represented by a class that handles
+various setup and decision values</li>
+<li>an class that handles context for a particular Fop conversion
+that can be configured/overridden when embedding</li>
+</ul>
+
+<p>
 The user agent is responsible for supplying user or context
 specific information. The list of user agent values can be found on the
 <jump href="useragent.html">User Agent</jump> page.
@@ -52,10 +64,9 @@ specific information. The list of user agent values can be found on the
 <section>
   <title>general options</title>
 <ul>
-<li>base directory</li>
+<li>base url</li>
 <li>uri resolvers</li>
-<li>which implementation of a particular</li>
-<li>LayoutManager to use</li>
+<li>which implementation of a particular LayoutManager to use</li>
 </ul>
   </section>
 <section>
@@ -75,21 +86,25 @@ for the PS renderer (eventually):
 </ul>
   </section>
 <section>
-  <title>User Agent</title>
+  <title>Render Results</title>
 <p>
-Output from FOP:
-- Generation statistics: Number of pages total, Number of pages of each
-  page-sequence, page-master used for each page (could be used to
-  control the paper bin to get paper from, important for me in
-  conjunction with PS Renderer).
+Generate Output statistics from FOP:
    </p>
+<ul>
+<li>Number of pages total</li>
+<li>Number of pages of each page-sequence</li>
+<li>page-master used for each page (could be used to control
+the paper bin to get paper from, important for me in conjunction
+with PS Renderer)</li>
+<li>recoverable errors such as overflow</li>
+</ul>
   </section>
 <section>
   <title>Setting Up</title>
 <p>
 The Driver handles the XML input.
 The user agent information is through the FOUserAgent.
-We could handle logging through the user agent.
+Handle logging through the user agent.
 Options could also be handled through the user agent, using mime type
 selection for renderer options.
 </p>
@@ -97,10 +112,13 @@ selection for renderer options.
 <section>
   <title>Others</title>
 <p>
-render to more than one renderer at once (maybe not from the command line).
+Render to more than one renderer at once (maybe not from the command line).
 For example you could generate a PDF for the archive
 and the PS for the printer in one run. It would probably be faster than
 converting the PDF to PostScript afterwards.
+Make the fo tree reuseable.
+If the fonts are the same then use the
+same area tree to output to different renderers.
 </p>
 <p>
 Several code pieces for resolving URLs and/or
diff --git a/src/documentation/content/xdocs/design/extending.xml b/src/documentation/content/xdocs/design/extending.xml
index 4f95297c2..9a0d1f80c 100644
--- a/src/documentation/content/xdocs/design/extending.xml
+++ b/src/documentation/content/xdocs/design/extending.xml
@@ -38,12 +38,16 @@ information directly to the output document.
   <p>
 Output Document - This is used to add document level information
 to the output result. Such an extension will set information that
-is passed to the output document. There needs to be a handler for
-the output information which creates a document level result.
+is passed to the output document. The area tree handles these
+extensions and passs along the information to the renderer.
+The extension may contain resolveable objects. The extension
+can be passed to the renderer once resolve either immediately,
+after the next page or at the end of the document. This is so that
+the extension can be handled according to other associated data.
   </p>
   <p>
-FO Area - This is where an extension creates an normal area in
-the Area Tree. This is useful when the normal FO objects
+FO Area - This is where an extension creates an normal or extended
+area in the Area Tree. This is useful when the normal FO objects
 cannot create the area in the way that is needed.
   </p>
   <p>
@@ -51,16 +55,13 @@ Resolveable - In some cases it may require information to be
 resolved for information such as page numbers. This can apply
 to the XML Document, FO Area or output document extensions.
    </p>
-  <p>
-- Add a string ['(Continued)'] to a table header if the table spans
+  <ul>
+<li>Add a string ['(Continued)'] to a table header if the table spans
 multiple pages. These tables are part of the content and can start
-anywhere in the page.
-   </p>
-  <p>
-- Separate page number display for a subsection. ie. - master document
-is page 4 of 7, but subsection is page 2 of 3.
-
-   </p>
+anywhere in the page.</li>
+  <li>Separate page number display for a subsection. ie. - master document
+is page 4 of 7, but subsection is page 2 of 3.</li>
+   </ul>
 </section>
 <section>
   <title>Examples</title>
diff --git a/src/documentation/content/xdocs/design/fotree.xml b/src/documentation/content/xdocs/design/fotree.xml
index e1573037b..f53f32394 100644
--- a/src/documentation/content/xdocs/design/fotree.xml
+++ b/src/documentation/content/xdocs/design/fotree.xml
@@ -35,10 +35,8 @@ constraints required by the FO hierarchy.
 </p>
 
 <p>
-FONode, among other things, ensures that FO's have a parent, that they
-have children, that they maintain a marker of where the layout was up to
-(for FObj's it is the child number, and for FOText's it is the character
-number), and that they have a <code>layout()</code> method.
+FONode, among other things, ensures that FO's have a parent and that they
+may have children.
 </p>
 </section>
 
@@ -51,7 +49,6 @@ represents an FO element. This is then added to the FO tree as a child
 of the current parent.
 </p>
 
-
 <p>
 Properties (recall that FO's have properties, areas have traits, and XML
 nodes have attributes) are also a concern of <em>FOTreeBuilder</em>. It