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

21 years ago · 016f7ba94d
--- a/src/documentation/content/xdocs/design/understanding/area_tree.xml
+++ b/src/documentation/content/xdocs/design/understanding/area_tree.xml
@@ -0,0 +1,126 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>Area Tree</title>
    </header>

    <body>
 <section>
  <title>Area Tree</title>
 <section>
  <title>Area Tree</title>
 <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>
 </section>

 <section>
  <title>Pages</title>
 <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></section>


 <section>
  <title>Blocks</title>
 <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>
 </section>

 <section>
  <title>Inline Areas</title>
 <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>
 </section>

 <section>
  <title>Traits</title>

 <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>
 </section>

 <section>
  <title>Forward References</title>
 <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>
 </section>

 <section>
  <title>Caching</title>
 <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>
 </section>

 <section>
  <title>Extensions</title>
 <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>
 </section>

 <section>
  <title>Area Tree Handlers</title>
 <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>
 </section>

  </section>

    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/book.xml
+++ b/src/documentation/content/xdocs/design/understanding/book.xml
@@ -0,0 +1,28 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-cocoon2/src/documentation/xdocs/dtd/book-cocoon-v10.dtd">

 <book software="FOP"
    title="Understanding FOP Design"
    copyright="@year@ The Apache Software Foundation"
    xmlns:xlink="http://www.w3.org/1999/xlink">

    <menu label="Index">
      <menu-item label="FOP Home" href="../../index.html"/>
    </menu>
    <menu label="Understanding the Design">
      <menu-item label="Understanding" href="index.html"/>
      <menu-item label="XML Parsing" href="xml_parsing.html"/>
      <menu-item label="FO Tree" href="fo_tree.html"/>
      <menu-item label="Properties" href="properties.html"/>
      <menu-item label="Layout Managers" href="layout_managers.html"/>
      <menu-item label="Area Tree" href="area_tree.html"/>
      <menu-item label="Renderers" href="renderers.html"/>
    </menu>
    <menu label="Extras">
      <menu-item label="Images" href="images.html"/>
      <menu-item label="PDF Library" href="pdf_library.html"/>
      <menu-item label="SVG" href="svg.html"/>
    </menu>
 </book>

--- a/src/documentation/content/xdocs/design/understanding/fo_tree.xml
+++ b/src/documentation/content/xdocs/design/understanding/fo_tree.xml
@@ -0,0 +1,144 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>FO Tree</title>
    </header>

    <body>
 <section>
  <title>FO Tree</title>
      <p>
        The FO Tree is a representation of the XSL:FO document. This
        represents the <strong>Objectify</strong> step from the
        spec. The <strong>Refinement</strong> step is part of reading
        and using the properties which may happen immediately or
        during the layout process.
      </p>

 <p>Each xml element is represented by a java object. For pagination the
 classes are in <code>org.apache.fop.fo.pagination.*</code>, for elements in the flow
 they are in <code>org.apache.fop.fo.flow.*</code> and some others are in
 <code>org.apache.fop.fo.*.</code></p>

 <p>The base class for all objects in the tree is FONode. The base class for
 all FO Objects is FObj.</p>

 <p>There is a class for each element in the FO set. An object is created for
 each element in the FO Tree. This object holds the properties for the FO
 Object.</p>

      <p>
        When the object is created it is setup. It is given its
        element name, the FOUserAgent - for resolving properties
        etc. - the logger and the attributes. The methods
        <code>handleAttributes()</code> and
        <code>setuserAgent()</code>, common to <code>FONode</code>,
        are used in this process. The object will then be given any
        text data or child elements.  Then the <code>end()</code>
        method is called.  The end method is used by a number of
        elements to indicate that it can do certain processing since
        all the children have been added.
      </p>

 <p>Some validity checking is done during these steps. The user can be warned of the error and processing can continue if possible.
 </p>

      <p>
        The FO Tree is simply a heirarchy of java objects that
        represent the fo elements from xml. The traversal is done by
        the layout or structure process only in the flow elements.
      </p> 

 <section>
  <title>Properties</title>

 <p>The XML attributes on each element are passed to the object. The objects
 that represent FO objects then convert the attributes into properties.
 </p>

 <p>Since properties can be inherited the PropertyList class handles resolving
 properties for a particular element.
 All properties are specified in an XML file. Classes are created
 automatically during the build process.
 </p>

 <p>In some cases the element may be moved to have a different parent, for
 example markers, or the inheritance could be different, for example
 initial property set.</p>
 </section>

 <section>
  <title>Foreign XML</title>

 <p>The base class for foreign XML is XMLObj. This class handles creating a
 DOM Element and the setting of attributes. It also can create a DOM
 Document if it is a top level element, class XMLElement.
 This class must be extended for the namespace of the XML elements. For
 unknown namespaces the class is UnknowXMLObj.</p>

 <p>If some special processing is needed then the top level element can extend
 the XMLObj. For example the SVGElement makes the special DOM required for
 batik and gets the size of the svg.
 </p>

 <p>Foreign XML will usually be in an fo:instream-foreign-object, the XML will
 be passed to the render as a DOM where the render will be able to handle
 it. Other XML from an unknwon namespace will be ignored.
 </p>

 <p>By using element mappings it is possible to read other XML and either</p>
 <ul><li>set information on the area tree</li>
 <li>create pseudo FO Objects that create areas in the area tree</li>
 <li>create FO Objects</li></ul>
 </section>

 <section>
  <title>Unknown Elements</title>
 <p>If an element is in a known namespace but the element is unknown then an
 Unknown object is created. This is mainly to provide information to the
 user.
 This could happen if the fo document contains an element from a different
 version or the element is misspelt.</p>
 </section>

 <section>
  <title>Page Masters</title>
        <p>
          The first elements in a document are the elements for the
          page master setup. This is usually only a small number and
          will be used throughout the document to create new pages.
          These elements are kept as a factory to create the page and
          appropriate regions whenever a new page is requested by the
          layout. The objects in the FO Tree that represent these
          elements are themselves the factory. The root element keeps
          these objects as a factory for the page sequences.
        </p>
 </section>

 <section>
  <title>Flow</title>
 <p>The elements that are in the flow of the document are a set of elements
 that is needed for the layout process. Each element is important in the
 creation of areas.</p>
 </section>

 <section>
  <title>Other Elements</title>

        <p>
          The remaining FO Objects are things like page-sequence,
          title and color-profile. These are handled by their parent
          element; i.e. the root looks after the declarations and the
          declarations maintains a list of colour profiles.  The
          page-sequences are direct descendents of root.
        </p>
      </section>

 </section>

    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/images.xml
+++ b/src/documentation/content/xdocs/design/understanding/images.xml
@@ -0,0 +1,135 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>Images</title>
    </header>
    <body>

  <section>
    <title>Images in FOP</title>

    <p>Images may only be needed to be loaded when the image is rendered to the
 output or to find the dimensions.<br/>
 An image url may be invalid, this can be costly to find out so we need to
 keep a list of invalid image urls.</p>
 <p>We have a number of different caching schemes that are possible.</p>
 <p>All images are referred to using the url given in the XSL:FO after
 removing "url('')" wrapping. This does
 not include any sort of resolving such as relative -> absolute. The
 external graphic in the FO Tree and the image area in the Area Tree only
 have the url as a reference.
 The images are handled through a static interface in ImageFactory.</p>

 <section>
  <title>Threading</title>

 <p>In a single threaded case with one document the image should be released
 as soon as the renderer caches it. If there are multiple documents then
 the images could be held in a weak cache in case another document needs to
 load the same image.</p>

 <p>In a multi threaded case many threads could be attempting to get the same
 image. We need to make sure an image will only be loaded once at a
 particular time. Once a particular document is finished then we can move
 all the images to a common weak cache.</p>
 </section>

 <section>
  <title>Caches</title>
 <section>
  <title>LRU</title>
 <p>All images are in a common cache regardless of context. To limit the size
 of the cache the LRU image is removed to keep the amount of memory used
 low. Each image can supply the amount of data held in memory.</p>
 </section>

 <section>
  <title>Context</title>
 <p>Images are cached according to the context, using the FOUserAgent as a key.
 Once the context is finished the images are added to a common weak hashmap
 so that other contexts can load these images or the data will be garbage
 collected if required.</p>
 <p>If images are to be used commonly then we cannot dispose of data in the
 FopImage when cached by the renderer. Also if different contexts have
 different base directories for resolving relative url's then the loading
 and caching must be separate. We can have a cache that shares images among
 all contexts or only loads an image for a context.</p>
 </section>

 <p>The cache uses an image loader so that it can synchronize the image
 loading on an image by image basis. Finding and adding an image loader to
 the cache is also synchronized to prevent thread problems.</p>
 </section>

 <section>
  <title>Invalid Images</title>

 <p>
 If an image cannot be loaded for some reason, for example the url is
 invalid or the image data is corrupt or an unknown type. Then it should
 only attempt to load the image once. All other attempts to get the image
 should return null so that it can be easily handled.<br/>
 This will prevent any extra processing or waiting.</p>
 </section>

 <section>
  <title>Reading</title>
 <p>Once a stream is opened for the image url then a set of image readers is
 used to determine what type of image it is. The reader can peek at the
 image header or if necessary load the image. The reader can also get the
 image size at this stage.
 The reader then can provide the mime type to create the image object to
 load the rest of the information.</p>
 </section>

 <section>
  <title>Data</title>

 <p>The data usually need for an image is the size and either a bitmap or the
 original data. Images such as jpeg and eps can be embedded into the
 document with the original data. SVG images are converted into a DOM which
 needs to be rendered to the PDF. Other images such as gif, tiff etc. are
 converted into a bitmap.
 Data is loaded by the FopImage by calling load(type) where type is the type of data to load.</p>
 </section>


 <section>
  <title>Rendering</title>

 <p>Different renderers need to have the information in different forms.</p>


 <section>
  <title>PDF</title>
 <dl><dt>original data</dt>  <dd>JPG, EPS</dd>
 <dt>bitmap</dt>  <dd>gif, tiff, bmp, png</dd>
 <dt>other</dt>  <dd>SVG</dd></dl>
 </section>

 <section>
  <title>PS</title>
 <dl><dt>bitmap</dt>  <dd>JPG, gif, tiff, bmp, png</dd>
 <dt>other</dt> <dd>SVG</dd></dl>
 </section>

 <section>
  <title>awt</title>
 <dl><dt>bitmap</dt> <dd>JPG, gif, tiff, bmp, png</dd>
 <dt>other</dt>  <dd>SVG</dd></dl>
 </section>

 <p>The renderer uses the url to retrieve the image from the ImageFactory and
 then load the required data depending on the image mime type. If the
 renderer can insert the image into the document and use that data for all
 future references of the same image then it can cache the reference in the
 renderer and the image can be released from the image cache.</p>
 </section>
 </section>

    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/index.xml
+++ b/src/documentation/content/xdocs/design/understanding/index.xml
@@ -0,0 +1,68 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>Understanding FOP Design</title>
        <subtitle>Tutorial series about Design Approach to FOP</subtitle>
    </header>

    <body>
 <section>
  <title>Introduction</title>
 <p>
          Welcome to the understanding series. This will be
          a series of notes for developers to understand how FOP
          works. We will
          attempt to clarify the processes involved to go from xml(fo)
          to pdf or other formats. Some areas will get more
          complicated as we proceed.
  </p>

    <section>
      <title>Overview</title>
      <p>FOP takes an xml file does its magic and then writes a document to a
       stream.</p>
      <p>xml -&gt; [FOP] -&gt; document</p>
      <p>The document could be pdf, ps etc. or directed to a printer or the
       screen. The principle remains the same. The xml document must be in the XSL:FO
       format.</p>
      <p>For convenience we provide a mechanism to handle XML+XSL as
       input.</p>
      <p>The xml document is always handled internally as SAX. The SAX events
       are used to read the elements, attributes and text data of the FO document.
       After the manipulation of the data the renderer writes out the pages in the
       appropriate format. It may write as it goes, a page at a time or the whole
       document at once. Once finished the document should contain all the data in the
       chosen format ready for whatever use.</p>
    </section>
    <section>
      <title>Stages</title>
      <p>The fo data goes through a few stages. Each piece
       of data will generally go through the process in the same way but some
       information may be used a number of times or in a different order. To reduce
       memory one stage will start before the previous is completed.</p>
      <p>SAX Handler -&gt; FO Tree -&gt; Layout Managers -&gt; Area Tree
       -&gt; Render -&gt; document</p>
      <p>In the case of rtf, mif etc. <br/>SAX Handler -&gt; FO Tree -&gt;
       Structure Renderer -&gt; document</p>
      <p>The FO Tree is constructed from the xml document. It is an internal
       representation of the xml document and it is like a DOM with some differences.
       The Layout Managers use the FO Tree do their layout stuff and create an Area
       Tree. The Area Tree is a representation of the final result. It is a
       representation of a set of pages containing the text and other graphics. The
       Area Tree is then given to a Renderer. The Renderer can read the Area Tree and
       convert the information into the render format. For example the PDF Renderer
       creates a PDF Document. For each page in the Area Tree the renderer creates a
       PDF Page and places the contents of the page into the PDF Page. Once a PDF Page
       is complete then it can be written to the output stream.</p>
      <p>For the structure documents the Structure listener will read
       directly from the FO Tree and create the document. These documents do not need
       the layout process or the Area Tree.</p>
    </section>

  </section>
    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/layout_managers.xml
+++ b/src/documentation/content/xdocs/design/understanding/layout_managers.xml
@@ -0,0 +1,65 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>Layout Managers</title>
    </header>
    <body>
 <section>
  <title>Layout Managers</title>

 <p>The role of the layout managers is to build the Area Tree by using the
 information from the FO Tree. The layout managers decide where information
 is placed in the area tree.</p>
 <p>A layout manager is typically associated with an FO Object but not always.</p>

 <p>The layout managers are in between the FO Tree and the Area Tree. They get
 information from the FO Tree and create areas and build the pages. They
 hold the state of the layout process as it builds up the areas and pages.
 They also manage the handling of breaks and spacing between areas.</p>


 <p>FO Objects can have two types of properties, ones that relate to the layout and ones that relate to the rendering. THe layout related properties area used by the layout managers to determine how and where to create the areas. The render related properties should be passed through to the renderer in the most efficient way possible.
 </p>

 <section>
  <title>Block Areas</title>

 <p>When a block creating element is complete then it is possible to build the
 block area and add it to the paprent.</p>
 <p>A block area will contain either more block areas or line areas, which are
 special block areas. The line areas are created by the LineLayoutManager
 in which the inline areas flow into.</p>
 <p>So a block area manager handles the lines or blocks as its children and
 determines things like spacing and breaks.</p>
 <p>In the case of tables and lists the blocks are stacked in a specific way
 that needs to be handled by the layout manager.</p>
 </section>

 <section>
  <title>Side Floats</title>

 <p>Side floats alter the length of the inline progression dimension for the
 current line and following lines for the size of the float.</p>
 <p>This means that the float needs to be handled by the block layout manager
 so that it can adjust the available inline progression dimension for the
 relevant line areas.</p>
 </section>

 <section>
  <title>Footnotes and Before Floats</title>

 <p>Footnotes and Before Floats are placed in special areas in the body region
 of the page. The size of these areas is determined by the content. This in
 turn effects the available size of the main reference area that contains
 the flow.</p>
 <p>A layout manager handles the adding and removing of footnotes/floats, this in turn effects the available space in the main reference area.</p>

 </section>
 </section>

    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/pdf_library.xml
+++ b/src/documentation/content/xdocs/design/understanding/pdf_library.xml
@@ -0,0 +1,76 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>PDF Library</title>
    </header>

    <body>
 <section>
  <title>PDF Library</title>

 <p>The PDF Library is an independant package of classes in FOP. These class
 provide a simple way to construct documents and add the contents. The
 classes are found in <code>org.apache.fop.pdf.*</code>.</p>

 <section>
  <title>PDF Document</title>
 <p>This is where most of the document is created and put together.</p>
 <p>It sets up the header, trailer and resources. Each page is made and added to the document.
 There are a number of methods that can be used to create/add certain PDF objects to the document.</p>
 </section>

 <section>
  <title>Building PDF</title>
 <p>The PDF Document is built by creating a page for each page in the Area Tree.</p>
 <p> This page then has all the contents added.
 The page is then added to the document and available objects can be written to the output stream.</p>
 <p>The contents of the page are things such as text, lines, images etc.
 The PDFRenderer inserts the text directly into a pdf stream.
 The text consists of markup to set fonts, set text position and add text.</p>
 <p>Most of the simple pdf markup is inserted directly into a pdf stream.
 Other more complex objects or commonly used objects are added through java classes.
 Some pdf objects such as an image consists of two parts.</p>
 <p>It has a separate object for the image data and another bit of markup to display the image in a certain position on the page.
 </p><p>The java objects that represent a pdf object implement a method that returns the markup for inserting into a stream.
 The method is: byte[] toPDF().</p>

 </section>
 <section>
  <title>Features</title>

 <section>
  <title>Fonts</title>
 <p>Support for embedding fonts and using the default Acrobat fonts.
 </p></section>

 <section>
  <title>Images</title>
 <p>Images can be inserted into a page. The image can either be inserted as a pixel map or directly insert a jpeg image.
 </p></section>

 <section>
  <title>Stream Filters</title>
 <p>A number of filters are available to encode the pdf streams. These filters can compress the data or change it such as converting to hex.
 </p></section>

 <section>
  <title>Links</title>
 <p>A pdf link can be added for an area on the page. This link can then point to an external destination or a position on any page in the document.
 </p></section>

 <section>
  <title>Patterns</title>
 <p>The fill and stroke of graphical objects can be set with a colour, pattern or gradient.
 </p></section>

 <p>The are a number of other features for handling pdf markup relevent to creating PDF files for FOP.</p>
 </section>

  </section>

    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/properties.xml
+++ b/src/documentation/content/xdocs/design/understanding/properties.xml
@@ -0,0 +1,110 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>Properties</title>
    </header>

    <body>
 <section>
  <title>Property Handling</title>
 <p>During XML Parsing, the FO tree is constructed. For each FO object (some
 subclass of FObj), the tree builder then passes the list of all
 attributes specified on the FO element to the handleAttrs method. This
 method converts the attribute specifications into a PropertyList.</p>
 <p>The actual work is done by a PropertyListBuilder (PLB for short). The
 basic idea of the PLB is to handle each attribute in the list in turn,
 find an appropriate "Maker" for it, call the Maker to convert the
 attribute value into a Property object of the correct type, and store
 that Property in the PropertyList.</p>

 <section>
  <title>Finding a Maker</title>
 <p>
 The PLB finds a "Maker" for the property based on the attribute name and
 the element name. Most Makers are generic and handle the attribute on
 any element, but it's possible to set up an element-specific property
 Maker. The attribute name to Maker mappings are automatically created
 during the code generation phase by processing the XML property
 description files.</p> 
 </section>

 <section>
  <title>Processing the attribute list</title>
 <p>The PLB first looks to see if the font-size property is specified, since
 it sets up relative units which can be used in other property 
 specifications. Each attribute is then handled in turn. If the attribute
 specifies part of a compound property such as space-before.optimum, the
 PLB looks to see if the attribute list also contains the "base" property
 (space-before in this case) and processes that first.</p>
 </section>
 <section>
  <title>How the Property Maker works</title>
 <p>There is a family of Maker objects for each of the property datatypes,
 such as Length, Number, Enumerated, Space, etc. But since each Property
 has specific aspects such as whether it's inherited, its default value,
 its corresponding properties, etc. there is usually a specific Maker for
 each Property. All these Maker classes are created during the code
 generation phase by processing (using XSLT) the XML property description
 files to create Java classes.</p>

 <p>The Maker first checks for "keyword" values for a property. These are
 things like "thin, medium, thick" for the border-width property. The
 datatype is really a Length but it can be specified using these keywords
 whose actual value is determined by the "User Agent" rather than being
 specified in the XSL standard. For FOP, these values are currently
 defined in foproperties.xml. The keyword value is just a string, so it
 still needs to be parsed as described next.</p>

 <p>The Maker also checks to see if the property is an Enumerated type and
 then checks whether the value matches one of the specified enumeration 
 values.</p>

 <p>Otherwise the Maker uses the property parser in the fo.expr package to
 evaluate the attribute value and return a Property object. The parser
 interprets the expression language and performs numeric operations and
 function call evaluations.</p>

 <p>If the returned Property value is of the correct type (specificed in
 foproperties.xml, where else?), the Maker returns it. Otherwise, it may
 be able to convert the returned type into the correct type.</p>

 <p>Some kinds of property values can't be fully resolved during FO tree
 building because they depend on layout information. This is the case of
 length values specified as percentages and of the special
 proportional-column-width(x) specification for table-column widths.
 These are stored as special kinds of Length objects which are evaluated
 during layout. Expressions involving "em" units which are relative to
 font-size _are_ resolved during the FO tree building however.</p>
 </section>

 <section>
  <title>Structure of the PropertyList</title>
 <p>The PropertyList extends HashMap and its basic function is to associate
 Property value objects with Property names. The Property objects are all
 subclasses of the base Property class. Each one simply contains a
 reference to one of the property datatype objects. Property provides
 accessors for all known datatypes and various subclasses override the
 accessor(s) which are reasonable for the datatype they store.</p>

 <p>The PropertyList itself provides various ways of looking up Property
 values to handle such issues as inheritance and corresponding
 properties. </p>

 <p>The main logic is:<br/>If the property is a writing-mode relative property (using start, end,
 before or after in its name), the corresponding absolute property value
 is returned if it's explicitly set on this FO. <br/>Otherwise, the
 writing-mode relative value is returned if it's explicitly set. If the
 property is inherited, the process repeats using the PropertyList of the
 FO's parent object. (This is easy because each PropertyList points to
 the PropertyList of the nearest ancestor FO.) If the property isn't
 inherited or no value is found at any level, the initial value is
 returned.</p>
 </section>

 </section>
    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/renderers.xml
+++ b/src/documentation/content/xdocs/design/understanding/renderers.xml
@@ -0,0 +1,131 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>Renderers</title>
    </header>

    <body>
 <section>
  <title>Renderers</title>

 <section>
  <title>Renderers</title>

 <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>
 </section>

 <section>
  <title>Fonts</title>
 <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>
 </section>

 <section>
  <title>Render Context</title>
 <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>
 </section>

 <section>
  <title>XML Handling</title>

 <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>
 </section>

 <section>
  <title>Extensions</title>
 <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>
 </section>

 <section>
 <title>Types</title>

 <section>
  <title>PDF</title>
 <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>
 </section>
 <section>
  <title>SVG</title>
 <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>
 </section>

 <section>
  <title>TXT</title>
 <p>This simply outputs to a text document.</p></section>
 <section>
  <title>AWT</title>
 <p>This draws the pages into an AWT graphic.</p></section>

 <section>
  <title>PS and PCL</title>
 <p>Similar to PDF.</p></section>

 <section>
  <title>XML</title>
 <p>Creates an XML file that represents the AreaTree.</p>
 </section>
 <section>
  <title>Print</title>
 <p>This prints the document using the java printing facitlities. The AWT
 rendering is used to draw the pages onto the printjob.
 </p>
 </section>
 <section>
  <title>RTF and MIF</title>
 <p>These formats do not use this rendering mechanism.</p>
 </section>
 </section>

 <section>
  <title>Adding a Renderer</title>
 <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>
 </section>

 <section>
  <title>Multiple Renderers</title>
 <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>
 </section>

 </section>

    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/svg.xml
+++ b/src/documentation/content/xdocs/design/understanding/svg.xml
@@ -0,0 +1,74 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>SVG</title>
    </header>
    <body>
 <section>
  <title>SVG</title>
    <p>SVG is rendered through Batik.</p><p>The XML from the XSL:FO document
      is converted into an SVG DOM with batik. This DOM is then set as the Document
      on the Foreign Object area in the Area Tree.</p><p>This DOM is then available to
      be rendered by the renderer.</p><p>SVG is rendered in the renderers via an      XMLHandler in the FOUserAgent. This XML handler is used to render the SVG. The
      SVG is rendered by using batik. Batik converts the SVG DOM into an internal
      structure that can be drawn into a Graphics2D. So for PDF we use a
      PDFGraphics2D to draw into.</p><p>This creates the necessary PDF information to
      create the SVG image in the PDF document.</p><p>Most of the work is done in the
      PDFGraphics2D class. There are also a few bridges that are plugged into batik
      to provide different behaviour for some SVG elements.</p>
 <section>
  <title>Text Drawing</title>
 <p>Normally batik converts text into a set of curved
       shapes. </p><p>This is handled as any other shapes when rendering to the output. This
       is not always desirable as the shapes have very fine curves. This can cause the
       output to look a bit bad in PDF and PS (it can be drawn properly but is not by
       default). These curves also require much more data than the original
       text.</p><p>To handle this there is a PDFTextElementBridge that is set when
       using the bridge in batik. If the text is simple enough for the text to be
       drawn in the PDF as with all other text then this sets the TextPainter to use
       the PDFTextPainter. This inserts the text directly into the PDF using the       drawString method on the PDFGraphics2D.</p><p>Text is considered simple if the
       font is available, the font size is useable and there are no tspans or other
       complications. This can make the resulting PDF significantly
       smaller.</p>
 </section>
 <section>
  <title>PDF Links</title>
 <p>To support links in PDF another batik
       element bridge is used. The PDFAElementBridge creates a PDFANode which inserts
       a link into the PDF document via the PDFGraphics2D.</p><p>Since links are       positioned on the page without any transforms then we need to transform the
       coordinates of the link area so that they match the current position of the a
       element area. This transform may also need to account for the svg being
       positioned on the page.</p>
 </section>
 <section>
  <title>Images</title>
 <p>Images are normally drawn
       into the PDFGraphics2D. This then creates a bitmap of the image data that can
       be inserted into the PDF document. </p><p>As PDF can support jpeg images then another
       element bridge is used so that the jpeg can be directly inserted into the       PDF.</p>
 </section>
 <section>
  <title>PDF Transcoder</title>
 <p>Batik provides a mechanism to
       convert SVG into various formats. Through FOP we can convert an SVG document
       into a single paged PDF document. The page contains the SVG drawn as best as
       possible on the page. There is a PDFDocumentGraphics2D that creates a
       standalone PDF document with a single page. This is then drawn into by batik in
       the same way as with the PDFGraphics2D.</p>
 </section>
 <section>
   <title>Other Outputs</title>
 <p>When rendering to AWT the SVG is simply drawn onto the
       awt canvas using batik.</p><p>The PS Renderer uses a similar technique as the
       PDF Renderer.</p><p>The SVG Renderer simply embeds the SVG inside an svg
       element.</p>
 </section>

 </section>

    </body>
 </document>

--- a/src/documentation/content/xdocs/design/understanding/xml_parsing.xml
+++ b/src/documentation/content/xdocs/design/understanding/xml_parsing.xml
@@ -0,0 +1,113 @@
 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

 <document>
    <header>
        <title>XML Parsing</title>
    </header>

    <body>
 <section>
  <title>XML Parsing</title>
 <p>Since everyone knows the basics we can get
                  into the various stages starting with the XML handling.</p>
                <section>
  <title>XML Input</title>
 <p>FOP can take the input XML in a number of ways:
                         </p>
        <ul>
          <li>SAX Events through SAX Handler
            <ul>
              <li>
                <code>FOTreeBuilder</code> is the SAX Handler which is
                obtained through <code>getContentHandler</code> on
                <code>Driver</code>.
              </li>
            </ul>
          </li>
          <li>
            DOM which is converted into SAX Events
            <ul>
              <li>
                The conversion of a DOM tree is done via the
                <code>render(Document)</code> method on
                <code>Driver</code>.
              </li>
            </ul>
          </li>
          <li>
            data source which is parsed and converted into SAX Events
            <ul>
              <li>
                The <code>Driver</code> can take an
                <code>InputSource</code> as input.  This can use a
                <code>Stream</code>, <code>String</code> etc.
              </li>
            </ul>
          </li>
          <li>
            XML+XSLT which is transformed using an XSLT Processor and
            the result is fired as SAX Events
            <ul>
              <li>
                <code>XSLTInputHandler</code> is used as an
                <code>InputSource</code> in the
                render(<code>XMLReader</code>,
                <code>InputSource</code>) method on
                <code>Driver</code>
              </li>
            </ul>
          </li>
        </ul>
                  <p>The SAX Events which are fired on the SAX Handler, class
                         <code>FOTreeBuilder</code>, must represent an XSL:FO document. If not there will be an
                         error. Any problems with the XML being well formed are handled here.</p>
 </section>
   <section>
     <title>Element Mappings</title>
 <p> The element mapping is a hashmap of all
                         the elements in a particular namespace. This makes it easy to create a
                         different object for each element. Element mappings are static to save on
                         memory. </p><p>To add an extension a developer can put in the classpath a jar
                         that contains the file <code>/META-INF/services/org.apache.fop.fo.ElementMapping</code>.
                         This must contain a line with the fully qualified name of a class that
                         implements the <em>org.apache.fop.fo.ElementMapping</em> interface. This will then be
                         loaded automatically at the start. Internal mappings are: FO, SVG and Extension
                         (pdf bookmarks)</p></section>
                <section>
  <title>Tree Building</title>
 <p>The SAX Events will fire all the information
                         for the document with start element, end element, text data etc. This
                         information is used to build up a representation of the FO document. To do this
                         for a namespace there is a set of element mappings. When an element + namepsace
                         mapping is found then it can create an object for that element. If the element
                         is not found then it creates a dummy object or a generic DOM for unknown
                         namespaces.</p>
                  <p>The object is then setup and then given attributes for the element.
                         For the FO Tree the attributes are converted into properties. The FO objects
                         use a property list mapping to convert the attributes into a list of properties
                         for the element. For other XML, for example SVG, a DOM of the XML is
                         constructed. This DOM can then be passed through to the renderer. Other element
                         mappings can be used in different ways, for example to create elements that
                         create areas during the layout process or setup information for the renderer
                         etc.</p>
        <p>
          While the tree building is mainly about creating the FO Tree
          there are some stages that can propagate to the renderer. At
          the end of a page sequence we know that all pages in the
          page sequence can be laid out without being effected by any
          further XML. The significance of this is that the FO Tree
          for the page sequence may be able to be disposed of.  The
          end of the XML document also tells us that we can finalise
          the output document.  (The layout of individual pages is
          accomplished by the layout managers page at a time;
          i.e. they do not need to wait for the end of the page
          sequence.  The page may not yet be complete, however,
          containing forward page number references, for example.)
        </p>
      </section>
 </section>
    </body>
 </document>