<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
<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>
<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>
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>
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>
<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
</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>
<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>
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>
<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>
<title>Settings</title>
<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
<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>
</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>
<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
<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>
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>
</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>
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
projects / xmlgraphics-fop.git / commitdiff