keiron 02/04/22 06:19:51
Modified: docs/design/understanding area_tree.xml renderers.xml
Log:
more understanding docs
converted from mailing list to xml doc
Submitted by: Cyril Rognon <[EMAIL PROTECTED]>
Revision Changes Path
1.2 +116 -12 xml-fop/docs/design/understanding/area_tree.xml
Index: area_tree.xml
===================================================================
RCS file: /home/cvs/xml-fop/docs/design/understanding/area_tree.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- area_tree.xml 17 Mar 2002 17:21:52 -0000 1.1
+++ area_tree.xml 22 Apr 2002 13:19:51 -0000 1.2
@@ -1,13 +1,117 @@
-<?xml version="1.0" standalone="no"?>
-<!-- Overview -->
-<document>
- <header>
- <title>Area Tree</title>
- <subtitle>All you wanted to know about the Area Tree !</subtitle>
- <authors> <person name="Keiron Liddle" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body><s1 title="Area Tree">
- <p>Yet to come :))</p>
- <note>The series of notes for developers has started but it has not
yet gone so far ! Keep watching</note></s1>
+<?xml version="1.0" standalone="no"?>
+<!-- Overview -->
+<document>
+ <header>
+ <title>Area Tree</title>
+ <subtitle>All you wanted to know about the Area Tree !</subtitle>
+ <authors> <person name="Keiron Liddle" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body><s1 title="Area Tree">
+<s2 title="Area Tree">
+<p>The Area Tree is an internal representation of the result document. This
+is a set of java classes that can put together a set of objects that
+represent the pages and their contents.</p>
+<p>This information is created by the layout managers and is rendered to the
+output using a renderer.</p>
+<p>The Area Tree follows the description of the area tree in the XSL:FO
+specification.</p>
+<p>The Area Tree consists of a set of pages, the actual implemenation places
+these in
+a set of page sequences.</p></s2>
+
+<s2 title="Pages">
+<p>A page consists of a page+viewport pair.</p>
+<p>The PageViewPort and Page with the regions is created by the
+LayoutMasterSet. The contents are then placed by the layout managers. Once
+the layout of a page is complete then it is added to the Area Tree.</p>
+<p>Inside the page is a set of RegionViewport+Region pairs for each region on
+the page.</p></s2>
+
+
+<s2 title="Blocks">
+<p>Block level areas contain either other blocks or line areas (which is a
+special block area).</p><p>
+A block is either positoned or stacked with other block areas.</p>
+</s2>
+
+<s2 title="Inline Areas">
+<p>Inline areas are stacked in a line area. Inline areas are objects such as
+character, viewport, inline-container, leader and space. A special inline
+area Word is also used for a group of consecutive characters.</p>
+<p>The image and instream foreign object areas are placed inside a viewport.
+The leader (with use content) and unresolved page number areas are
+resolved to other inline areas.</p>
+<p>Once a LineArea is filled with inline areas then the inline areas need to
+be aligned and adjusted to fill the line properly.</p></s2>
+
+
+<s2 title="Traits">
+
+<p>A trait is information associated with an area. This could be information
+such as text colour or is-first.</p>
+<p>Traits provide information about an area. The traits are derived from
+properties on the formatting object or are generated during the layout
+process. Many of the layout traits do not have actual values but can be
+derived from the Area Tree. Other traits that apply when rendering the
+areas are set on the area. Since setting the same value on every area
+would use a lot of memory then the traits are derived from default or
+parent values.</p>
+<p>A dominant trait on a block area is set, for example font colour, so that
+every line area with the same dominant value can derive it. The text
+inline areas then get the font colour set on the inline area or from the
+line area or from the block area.</p></s2>
+
+
+<s2 title="Forward References">
+<p>The Area Tree maintains a set of mappings from the reference to pages.</p>
+<p>The PageViewPort holds the list of forward references that need resolving
+so that if a references is resolved during layout the page can be easily
+found and then fixed. Once all the forward references are resolved then
+the page is ready to be rendered.</p>
+<p>To layout a page any areas that cannot be resolved need to reserve space.
+Once the inline area is resolved then the complete line should be adjusted
+to accomodate any change in space used by the area.</p></s2>
+
+
+<s2 title="Caching">
+<p>We may need to cache pages due to forward references or when keeping all
+pages.</p>
+<p>This is done by serializing the Page. The PageViewport is retained to be
+used as a key for page references and backward references.
+The Page is serialized to an object stream and then all of the page
+contents are released. The Page is then recoved by reading from the object
+stream.</p>
+<p>The PageViewport retains information about id areas for easy access.</p>
+</s2>
+
+<s2 title="Extensions">
+<p>The Area Tree holds the Output Document extensions. This is information
+such as pdf bookmarks or other output document specific information that
+is not handled by XSL:FO.</p>
+<p>It is also possible to create custom areas that extend a normal area. The
+actual data that is rendered could be set in a different way or depend on
+resolving a forward reference.</p>
+</s2>
+
+<s2 title="Area Tree Handlers">
+<p>To handle different situations the handler for the Area Tree handles each
+page as it is added.</p><p>
+The RenderPagesModel sends the page directly to the renderer if the page
+is ready to be rendered. Once a page is rendered it is discarded.
+The StorePagesModel stores all the pages so that any page can be later
+accessed.</p>
+<p>The Area Tree retains the concept of page sequences (this is not in the
+area tree in the spec) so that this information can be passed to the
+renderer. This is useful for setting the title and organising the groups
+of page sequences.</p></s2>
+
+
+<s2 title="Associated Tasks">
+<ul><li>Sort out extensions concept, access to AreaTree.</li>
+<li>Sort out trait handling.</li>
+<li>Caching implementation.</li></ul></s2>
+
+
+ </s1>
</body></document>
1.2 +114 -12 xml-fop/docs/design/understanding/renderers.xml
Index: renderers.xml
===================================================================
RCS file: /home/cvs/xml-fop/docs/design/understanding/renderers.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- renderers.xml 17 Mar 2002 17:21:52 -0000 1.1
+++ renderers.xml 22 Apr 2002 13:19:51 -0000 1.2
@@ -1,13 +1,115 @@
-<?xml version="1.0" standalone="no"?>
-<!-- Overview -->
-<document>
- <header>
- <title>Renderers</title>
- <subtitle>All you wanted to know about the Renderers !</subtitle>
- <authors> <person name="Keiron Liddle" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body><s1 title="Renderers">
- <p>Yet to come :))</p>
- <note>The series of notes for developers has started but it has not
yet gone so far ! Keep watching</note></s1>
+<?xml version="1.0" standalone="no"?>
+<!-- Overview -->
+<document>
+ <header>
+ <title>Renderers</title>
+ <subtitle>All you wanted to know about the Renderers !</subtitle>
+ <authors> <person name="Keiron Liddle" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body><s1 title="Renderers">
+
+<s2 title="Renderers">
+
+
+<p>A renderer is used to convert the Area Tree into the output document.
+The renderer is given the tree one page at a time. All pages are supplied
+in the order they appear in the document. In order to save memory it is
+possble to render the pages out of order. Any page that is not reeady to
+be rendered is setup by the renderer first so that it can reserve a space
+or reference for when the page is ready to be rendered.</p>
+<p>The AbstractRenderer does most of the work to iterate through the area
+tree parts. This means that the most renderers simply need to implement
+the specific parts with inserting text, images and lines. The methods can
+easily be overridden to handle things in a different way or do some extra
+processing.</p></s2>
+
+
+<s2 title="Fonts">
+<p>The fonts are setup by the renderer being used. The font metrics are used
+during the layout process to determine the size of characters.</p>
+</s2>
+
+<s2 title="Render Context">
+<p>The render context is used by handlers. It contains information about the
+current state of the renderer. Such as the page, the position and any
+other miscellanous objects that are required to draw into the page.</p></s2>
+
+
+<s2 title="XML Handling">
+
+<p>A document may contain information in the form of XML for an image or
+instream foreign object. This XML is handled
+through the user agent. A standard extension for PDF is the SVG handler.</p><p>
+If there is XML in the SVG namespace it is given to the handler which
+renders the SVG into the pdf document at the given location.
+This separation means that other XML handlers can easily be added.</p></s2>
+
+
+<s2 title="Extensions">
+<p>Document level extensions are handled with an extension handler. This
+handles the information from the AreaTree and adds renders it to the
+document. An example is the pdf bookmarks. This information first needs to
+have all references resolved. Then the extension handler is ready to put
+the information into the pdf document.</p></s2>
+
+
+<s2 title="Types">
+
+
+<s3 title="PDF">
+<p>This uses the PDFDocument classes to create a PDF document. This supports
+out of order rendering as it is possible to reserve a pdf page object that
+can be later filled. Most of the work is to insert text or create lines.
+SVG is handled by the XML handler that uses the PDFGraphics2D and batik to
+draw the svg into the pdf page.</p><p>
+This also allows for font embedding.</p>
+</s3>
+<s3 title="SVG">
+<p>This creates a single svg document that contains all the pages rendered
+with page sequences horizontally and pages vertically. This also adds
+links between the pages so that it can be viewed by clicking on the page
+to go to the next page.</p></s3>
+
+<s3 title="TXT">
+<p>This simply outputs to a text document.</p></s3>
+<s3 title="AWT">
+<p>This draws the pages into an AWT graphic.</p></s3>
+
+<s3 title="PS and PCL">
+<p>Similar to PDF.</p></s3>
+
+<s3 title="XML">
+<p>Creates an XML file that represents the AreaTree.</p>
+</s3>
+<s3 title="Print">
+<p>This prints the document using the java printing facitlities. The AWT
+rendering is used to draw the pages onto the printjob.
+</p></s3>
+<s3 title="RTF and MIF">
+<p>These formats do not use this rendering mechanism.</p></s3>
+</s2>
+
+<s2 title="Adding a Renderer">
+<p>It is also possible to add other renderers. The renderer simply needs to
+implement the Renderer interface. The AbstractRenderer does most of what
+is needed so it is better to extend this. This means that you only need to
+implement the basic functionality such as text and lines.
+</p></s2>
+
+<s2 title="Multiple Renderers">
+<p>The layout of the document depends mainly on the font being used.
+If two renderers have the same font metrics then it is possible to render
+the Area Tree in each renderer. This can be handled by the AreaTree
+Handler.</p></s2>
+
+
+<s2 title="Associated Tasks">
+
+<ul><li>Sort out multiple renderers concept.</li></ul>
+</s2>
+
+</s1>
+
+
</body></document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
