more ideas on the design, areas

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

docs/design/areas.xml

@@ -13,4 +13,180 @@ such as spacing and keeps will be held in such a way that it can be
 discarded once the layout is finalised.
   </para>
 
+<section>
+ <title>The Area Tree</title>
+  <para>
+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.
+  </para>
+</section>
+
+<section>
+ <title>Page</title>
+  <para>
+A page is made up of five area regions. These are before, start, body,
+end and after. Each region has a viewport and contains the areas
+produced from the children in the FO object heirarchy.
+  </para>
+  <para>
+For the body area there are more subdivisions for before floats,
+footnotes and the main reference area. The main reference area is
+made from span areas which have normal flow reference areas as
+children. The flow areas are then created inside these normal flow
+reference areas.
+  </para>
+  <para>
+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.
+  </para>
+</section>
+
+<section>
+ <title>Block Areas</title>
+  <para>
+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.
+  </para>
+  <para>
+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.
+  </para>
+</section>
+
+<section>
+ <title>Line Areas</title>
+  <para>
+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.
+  </para>
+  <para>
+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.
+  </para>
+</section>
+
+<section>
+ <title>Inline Areas</title>
+  <para>
+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.
+  </para>
+  <para>
+Unresolved areas can reserve some space to allow for possible
+sizes once it is resolved. Then the line can be re-justified
+and finalised.
+  </para>
+</section>
+
+<section>
+ <title>Cloning</title>
+  <para>
+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.
+  </para>
+  <para>
+Resolveable areas may be converted into an unresolved form.
+  </para>
+</section>
+
+<section>
+ <title>Classes</title>
+  <para>
+The following class structure will be used to represent the area
+tree.
+  </para>
+  <para>
+
+  </para>
+<section>
+ <title>Page Area Classes</title>
+  <para>
+The page area classes hold the top level layout of a page. The
+areas are created by the page master and should be ready to have
+flow areas added.
+  </para>
+</section>
+<section>
+ <title>Block Area Classes</title>
+  <para>
+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.
+  </para>
+  <para>
+Areas for tables and lists have their child block areas stacked
+in different ways. Lists also can have spacing between the block
+areas.
+  </para>
+</section>
+<section>
+ <title>Inline Area Classes</title>
+  <para>
+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.
+  </para>
+</section>
+
+</section>
+
+<section>
+ <title>Rendering Area Tree</title>
+  <para>
+The rendering of an area tree is done by rendering each page
+to a suitable output. The regions are rendered in order and each
+region is contained by a viewport.
+  </para>
+  <para>
+The relevent structures that will need to be rendered are:
+Page
+Viewport
+Region
+Span
+Block
+Line
+Inline
+  </para>
+  <para>
+The renderer will need to be able to:
+       <itemizedlist>
+       <listitem><para>
+render each individual page
+       </para></listitem>
+       <listitem><para>
+clip and align child areas to a viewport
+       </para></listitem>
+       <listitem><para>
+handle all types of inline area, text, image etc.
+       </para></listitem>
+       <listitem><para>
+draw various lines and rectangles
+       </para></listitem>
+       </itemizedlist>
+  </para>
+  <para>  
+An abstract renderer will be able to handle the generic positioning
+of child areas, iterating through areas that have child areas.
+  </para>
+</section>
+
 </section>

docs/design/build.sh

@@ -5,14 +5,13 @@ LIBDIR=../../lib
 TARGET_CLASSPATH=$LIBDIR/ant.jar:\
 $LIBDIR/buildtools.jar:\
 $LIBDIR/xalan-2.0.0.jar:\
-$LIBDIR/xalan-1.2.2.jar:\
 $LIBDIR/xerces-1.2.3.jar:\
 $LIBDIR/bsf.jar:\
 ../../build/fop.jar:\
 $LIBDIR/logkit-1.0b4.jar:\
 $LIBDIR/avalon-framework-4.0.jar:\
 $LIBDIR/batik.jar:\
-$LIBDIR/jimi-1.0.jar:
+$LIBDIR/jimi-1.0.jar
 
 if [ "$JAVA_HOME" != "" ] ; then
    TARGET_CLASSPATH=$TARGET_CLASSPATH:$JAVA_HOME/lib/tools.jar

docs/design/layout.xml

@@ -123,6 +123,16 @@ the page to have at least all the information it needs to organise the
 page properly.
   </para>
   <para>
+This should handle the situation where there are keeps on some
+block areas that go over the end of the page better. It is possible that
+fitting the blocks on the page using a spacing between min and optimum
+would give a closer value to the optimum than putting the blocks on the
+next page and the spacing being between optimum and max. So if the objects
+are placed first at optimum then you will need to keep going to see if
+there is a lower keep further on that has a spacing that is closer to the
+optimum.
+  </para>
+  <para>
 The spacing and keep information is stored so that the area positions
 and sizes can be adjusted.
   </para>

docs/design/optimise.xml

@@ -33,5 +33,11 @@ been finalised. Consecutive characters with the same properties
 can be combined into a "word" to hold the information with
 limited overhead.
   </para>
+  <para>
+If there are a large number of pages where forward references
+cannot be resolved the a method of writing a page onto disk
+could be used to save memory. The easiest way to achieve this
+is to make the page and all children serializable.
+  </para>
 
 </section>

docs/design/useragent.xml

@@ -23,6 +23,12 @@ resolution layout process and the renderer.
 Standard Features:
        <itemizedlist>
        <listitem><para>
+error handling, what to do if fo markup is invalid
+       </para></listitem>
+       <listitem><para>
+auto overflow value and handling error-if-overflow
+       </para></listitem>
+       <listitem><para>
 adjusting length values (eg. for borders) to renderable values
        </para></listitem>
        <listitem><para>