keiron      2003/01/02 04:59:30

  Modified:    src/documentation/content/xdocs/design architecture.xml
                        areas.xml book.xml embedding.xml extending.xml
                        fotree.xml
  Log:
  updated some information
  
  Revision  Changes    Path
  1.3       +44 -11    xml-fop/src/documentation/content/xdocs/design/architecture.xml
  
  Index: architecture.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/design/architecture.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- architecture.xml  19 Nov 2002 07:57:28 -0000      1.2
  +++ architecture.xml  2 Jan 2003 12:59:30 -0000       1.3
  @@ -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 @@
   <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>
   
  
  
  
  1.4       +39 -46    xml-fop/src/documentation/content/xdocs/design/areas.xml
  
  Index: areas.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/design/areas.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- areas.xml 29 Nov 2002 22:00:32 -0000      1.3
  +++ areas.xml 2 Jan 2003 12:59:30 -0000       1.4
  @@ -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 @@
   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 @@
   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 @@
   <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 @@
     </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 @@
   <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 @@
   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>
  
  
  
  1.5       +0 -3      xml-fop/src/documentation/content/xdocs/design/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/design/book.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- book.xml  2 Dec 2002 10:19:42 -0000       1.4
  +++ book.xml  2 Jan 2003 12:59:30 -0000       1.5
  @@ -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>
  
  
  
  1.3       +29 -11    xml-fop/src/documentation/content/xdocs/design/embedding.xml
  
  Index: embedding.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/design/embedding.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- embedding.xml     19 Nov 2002 07:57:28 -0000      1.2
  +++ embedding.xml     2 Jan 2003 12:59:30 -0000       1.3
  @@ -28,6 +28,18 @@
   <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 @@
   <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 @@
   </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 @@
   <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
  
  
  
  1.6       +14 -13    xml-fop/src/documentation/content/xdocs/design/extending.xml
  
  Index: extending.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/design/extending.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- extending.xml     23 Dec 2002 10:46:10 -0000      1.5
  +++ extending.xml     2 Jan 2003 12:59:30 -0000       1.6
  @@ -38,12 +38,16 @@
     <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 @@
   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>
  
  
  
  1.4       +2 -5      xml-fop/src/documentation/content/xdocs/design/fotree.xml
  
  Index: fotree.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/design/fotree.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- fotree.xml        29 Nov 2002 22:00:32 -0000      1.3
  +++ fotree.xml        2 Jan 2003 12:59:30 -0000       1.4
  @@ -35,10 +35,8 @@
   </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>
   
  @@ -50,7 +48,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
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Reply via email to