+++ /dev/null
-These documents are written for docbook
-http://sourceforge.net/projects/docbook
-
-To convert to pdf:
-- place the docbook files in a directory named "docbook"
-download and unzip the docbook distribution into the
-directory <cvs>/docs/design/dockbook/
-
-- place docbookx package in a directory name "docbookx"
-the files are avaialable here:
-http://www.oasis-open.org/docbook/xml/4.1.2/index.shtml
-
-
-- run the build script
-
--- /dev/null
+<?xml version="1.0" standalone="no"?>
+
+<!-- by Arved Sandstrom -->
+<document>
+ <header>
+ <title>Architecture</title>
+ <subtitle>Architecture information for FOP</subtitle>
+ <authors>
+ </authors>
+ </header>
+
+ <body>
+
+<s1 title="FOP Mechanics">
+
+<s2 title="Introduction">
+
+<p>
+The overall process is controlled by <em>org.apache.fop.apps.Driver</em>. In
+this class, a typical sequence is:</p>
+
+<source>Driver driver = new Driver();<br/>
+driver.setRenderer("org.apache.fop.render.pdf.PDFRenderer", version);<br/>
+driver.setOutputStream(new FileOutputStream(args[1]));<br/>
+driver.render(parser, inputHandler.getInputSource());</source>
+</s2>
+
+<s2 title="Formatting Object Tree">
+<p>The class <em>org.apache.fop.fo.FOTreeBuilder</em> is responsible for actually
+constructing the FO tree. The key SAX events used are </p>
+<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>
+
+<p><code>            FONode</code></p>
+<p><code>               |</code></p>
+<p><code>     __________|________</code></p>
+<p><code>    |                   |</code></p>
+<p><code>   FObj               FOText</code></p>
+<p><code>    |</code></p>
+<p><code>    |___________________</code></p>
+<p><code>    |                   |</code></p>
+<p><code>  FObjMixed      SequenceSpecifier
+</code></p>
+
+<p><code>Block</code></p>
+<p><code>Inline</code></p>
+<p><code>BasicLink</code></p>
+
+</s2>
+
+<s2 title="FONode">
+<p>
+The class inheritance described above only describes the nature of the
+content. Every FO in FOP also has a parent, and a Vector of children. The
+parent attribute (in the Java sense), in particular, is used to enforce
+constraints required by the FO hierarchy.
+</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.
+</p>
+</s2>
+
+<s2 title="Making FO's">
+
+<p>
+Every FO class has code that looks something like this:
+</p>
+
+<p><code>public static class Maker extends FObj.Maker {</code></p>
+<p><code>   public FObj make(FObj parent, PropertyList propertyList)</code></p>
+<p><code>     throws FOPException</code></p>
+<p><code>   {</code></p>
+<p><code>     return new SimplePageMaster(parent, propertyList);</code></p>
+<p><code>   }</code></p>
+<p><code>}</code></p>
+
+
+<p>
+The class also has a static method that resembles
+</p>
+
+<p><code>public static FObj.Maker maker()</code></p>
+<p><code>   {</code></p>
+<p><code>     return new PageSequence.Maker();</code></p>
+<p><code>   }</code></p>
+
+<p>
+A hash 'fobjTable' exists in <em>FOTreeBuilder</em>, and maps the FO names (such as
+'fo:table') to object references to the appropriate factories
+(such as <em>Table.Maker</em>).
+</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
+accomplishes this by using a <em>PropertyListBuilder</em>. There is a
+separate <em>PropertyListBuilder</em> for each namespace encountered
+while building the FO tree. Each Builder object contains a hash of
+property names and <ref>their</ref> respective makers. It may also
+contain element-specific property maker hashes; these are based on the
+<em>local name</em> of the flow object, ie. <em>table-row</em>, not
+<em>fo:table-row</em>. If an element-specific property mapping exists,
+it is preferred to the generic mapping.</p>
+<p>The base class for all
+properties is <em>Property</em>, and all the property makers extend
+<em>Property.Maker</em>. A more complete discussion of the property
+architecture may be found in <jump href="properties.html">Properties</jump>.
+</p>
+</s2>
+<s2 title="FO Formatting">
+
+<p>
+<em>FOTreeBuilder</em> calls <code>format()</code> on the root FO, passing
+it the <em>AreaTree</em>
+reference. In turn, <em>Root</em> calls <code>format()</code> on each
+<em>PageSequence</em>, passing <ref>it</ref>
+the <em>AreaTree</em> reference.
+</p>
+
+<p>
+The <em>PageSequence</em> <code>format()</code> method does the following things:
+</p>
+
+<ol>
+<li>Makes a <em>Page</em>, using <em>PageMasterFactory</em> to produce a
+<em>PageMaster</em>, and
+using <code>makePage()</code> in the latter class. In the simplest picture,
+a <em>Page</em> has
+5 areas represented by <em>AreaContainers</em>;</li>
+
+<li>Handles layout for <em>StaticContent</em> objects in the 'before' and 'after'
+regions, if set. This uses the <code>layout()</code> method in
+<em>StaticContent</em>;</li>
+
+<li>If a page break is not forced, it will continue to layout the flow into
+the body area (<em>AreaContainer</em>) of the current page;</li>
+
+<li>It continues with (1) when layout into the current page is done, but
+the flow is not empty.</li>
+</ol>
+</s2>
+
+<s2 title="Area Layout">
+
+<p>
+FO's that represent actual areas, starting with <em>Flow</em> and
+<em>StaticContent</em>, have
+a <code>layout()</code> method, with the following signature:
+</p>
+
+<p>
+<code>
+ public Status layout(Area area)
+</code>
+</p>
+
+<p>
+The fundamental role of the <code>layout()</code> method is to manage the layout of
+children and/or to generate new areas.
+</p>
+
+<p>
+<em>Example</em>: the <code>layout()</code> method for <em>Flow</em> generates no new areas - it manages the
+layout of the flow children.
+</p>
+
+<p>
+<em>Example</em>: the <code>layout()</code> method for <em>Block</em>
+generates a new <em>BlockArea</em> in and of
+itself, and also manages the layout of the block children, which are added
+to the <em>BlockArea</em> before that is itself added to its parent
+<em>Area</em>.
+</p>
+
+<p>
+<code>Layout()</code> methods are subject to the general constraint that possibly not
+all of their children can be accommodated, and they report back accordingly
+with an appropriate <em>Status</em>.
+</p>
+</s2>
+
+<s2 title="Rendering">
+
+<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>.
+</p>
+
+<p>
+At the highest level <em>PDFRenderer</em>, for example, begins by rendering each
+<em>Page</em>. The <code>render()</code> method in <em>Page</em> (as is the case for other areas),
+invokes a particular method in the renderer of choice, e.g.
+<code>renderPage()</code>.
+<em>NOTE</em>: this system is bypassed for <em>Page</em>, incidentally.
+</p>
+
+</s2>
+
+
+<!-- by Art Welch -->
+<s2 title="Renderers">
+ <s3 title="PrintRenderer">
+ <p>The PrintRenderer is an abstract base class for print type renderers. Currently the PCL, PDF, and TXT renderers extend from this. This allows as much common functionality to be contained in one place as possible (at least as much as I could consolidate fairly quickly). Unfortunately I have not yet been able to make the renderPage and renderWordArea methods common. This is unfortunate because these methods seem to experience the most activity. Maybe soneone else will have a clever solution to this (without breaking them into a bunch of little bits).</p>
+ <p>It is my hope that this base class will be useful for other renderers as well.</p>
+ </s3>
+
+ <s3 title="PCLRenderer">
+ <p>The PCLRenderer is a FOP renderer that should produce output as close to identical as possible to the printed output of the PDFRenderer within the limitations of the renderer, and output device.</p>
+
+ <p>The output created by the PCLRenderer is generic PCL 5 as documented in the "HP PCL 5 Printer Language Technical Reference Manual" (copyright 1990). This should allow any device fully supporting PCL 5 to be able to print the output generated by the PCLRenderer.</p>
+
+ <s4 title="Limitations">
+ <ul>
+ <li>Text or graphics outside the left or top of the printable area are not rendered properly. In general things that should print to the left of the printable area are shifted to the right so that they start at the left edge of the printable area and an error message is generated.</li>
+ <li>The Helvetica and Times fonts are not well supported among PCL printers so Helvetica is mapped to Arial and Times is mapped to Times New. This is done in the PCLRenderer, no changes are required in the FO's. The metrics and appearance for Helvetica/Arial and Times/Times New are nearly identical, so this has not been a problem so far.</li>
+ <li>Only the original fonts built into FOP are supported.</li>
+ <li>For the non-symbol fonts, the ISO 8859/1 symbol set is used (PCL set "0N").</li>
+ <li>Multibyte characters are not supported.</li>
+ <li>SVG support is limited. Currently only lines, rectangles (may be rounded), circles, ellipses, text, simple paths, and images are supported. Colors are supported (dithered black and white) but not gradients.</li>
+ <li>Images print black and white only (not dithered). When the renderer prints a color image it uses a threshold value, colors above the threshold are printed as white and below are black. If you need to print a non-monochrome image you should dither it first.</li>
+ <li>Image scaling is accomplished by modifying the effective resolution of the image data. The available resolutions are 75, 100, 150, 300, and 600 DPI.</li>
+ <li>Color printing is not supported. Colors are rendered by mapping the color intensity to one of the PCL fill shades (from white to black in 9 steps).</li>
+ <li>SVG clipping is not supported.</li>
+ </ul>
+ </s4>
+
+ <s4 title="Additional Features">
+ <p>There are some special features that are controlled by some public variables on the PCLRenderer class.</p>
+
+ <dl>
+ <dt>orientation</dt>
+ <dd><p>The logical page orientation is controlled by the public orientation variable. Legal values are:</p>
+ <ul>
+ <li>0 Portrait</li>
+ <li>1 Landscape</li>
+ <li>2 Reverse Portrait</li>
+ <li>3 Reverse Landscape</li>
+ </ul>
+ </dd>
+ <dt>curdiv, paperheight</dt>
+ <dd>The curdiv and paperheight variables allow multiple virtual pages to be printed on a piece of paper. This allows a standard laser printer to use perforated paper where every perforation will represent an individual page. The paperheight sets the height of a piece of paper in decipoints. This will be divided by the page.getHeight() to determine the number of equal sized divisions (pages) that will fit on the paper. The curdiv variable may be read/written to get/set the current division on the page (to set the starting division and read the ending division for multiple invocations).</dd>
+ <dt>topmargin, leftmargin</dt>
+ <dd>The topmargin and leftmargin may be used to increase the top and left margins for printing.</dd>
+ </dl>
+ </s4>
+ </s3>
+
+ <s3 title="TXTRenderer">
+ <p>The TXTRenderer is a FOP renderer that produces plain ASCII text output that attempts to match the output of the PDFRenderer as closely as possible. This was originally developed to accommodate an archive system that could only accept plain text files. Of course when limited to plain fixed pitch text the output does not always look very good.</p>
+ <p>The TXTRenderer works with a fixed size page buffer. The size of this buffer is controlled with the textCPI and textLPI public variables. The textCPI is the effective horizontal characters per inch to use. The textLPI is the vertical lines per inch to use. From these values and the page width and height the size of the buffer is calculated. The formatting objects to be rendered are then mapped to this grid. Graphic elements (lines, borders, etc) are assigned a lower priority than text, so text will overwrite any graphic element representations.</p>
+ </s3>
+</s2>
+
+
+<s2 title="UML Diagrams">
+<p>
+You can find UML diagramms for all Fop packages (latest release version)
+<jump href="http://xml.apache.org/dist/fop/fop-uml.zip">here</jump>.</p>
+</s2>
+
+<s2 title="SVG">
+
+<p>
+FOP supports svg rendering. SVG is supported as an instream-foreign-object
+embedded in an FO document or as an external SVG image.
+</p>
+
+<p>
+If the svg is embedded in an instream-foreign-object then all the elements and
+attributes are read directly and converted into an SVG DOM representation
+using the Batik library. This is then stored as a DOM until required for rendering.
+The rendering process depends on the what type of renderer is being used.
+</p>
+
+<p>
+The SVG DOM is rendered in the PDF renderer by using the abitlity of Batik to render
+DOM to a Graphics2D. First the DOM is converted into an intermediate representation
+then this is rendered to a PDFGraphics2D graphic object which writes the drawing
+instructions directly as PDF markup.
+</p>
+
+<p>
+The AWTRenderer and the PrintRenderer use Batik directly to draw the SVG image
+into the current java Graphics2D context.
+</p>
+
+<p>
+For more information see the SVG documentation.
+</p>
+</s2>
+</s1>
+ </body>
+</document>
+
-<?xml version = "1.0" encoding = "UTF-8"?>
-<section id="areatree">
- <title>Area Tree</title>
- <para>
+<?xml version="1.0" standalone="no"?>
+
+<!-- Overview -->
+
+<document>
+ <header>
+ <title>Area Tree</title>
+ <subtitle>Area Tree Design for FOP</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="Area Tree">
+<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.
- </para>
- <para>
+for similar areas and groups of areas.
+ </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.
- </para>
-
-<section>
- <title>The Area Tree</title>
- <para>
+discarded once the layout is finalised.
+ </p>
+<s2 title="Structure">
+<p>
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>
+ </p>
+ </s2>
+<s2 title="Page">
+<p>
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>
+ </p>
+ <p>
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>
+ </p>
+ <p>
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>
+ </p>
+ </s2>
+<s2 title="Block Areas">
+<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.
- </para>
- <para>
+ </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.
- </para>
-</section>
-
-<section>
- <title>Line Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Line Areas">
+<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.
- </para>
- <para>
+ </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.
- </para>
-</section>
-
-<section>
- <title>Inline Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Inline Areas">
+<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.
- </para>
- <para>
+ </p>
+ <p>
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>
+ </p>
+ </s2>
+<s2 title="Cloning">
+<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.
- </para>
- <para>
+ </p>
+ <p>
Resolveable areas may be converted into an unresolved form.
- </para>
-</section>
-
-<section>
- <title>Classes</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Classes">
+<p>
The following class structure will be used to represent the area
tree.
- </para>
- <para>
-
- </para>
-<section>
- <title>Page Area Classes</title>
- <para>
+ </p>
+<s3 title="Page Area Classes">
+<p>
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>
+ </p>
+ </s3>
+<s3 title="Block Area Classes">
+<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.
- </para>
- <para>
+ </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.
- </para>
-</section>
-<section>
- <title>Inline Area Classes</title>
- <para>
+ </p>
+ </s3>
+<s3 title="Inline Area Classes">
+<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.
- </para>
-</section>
+ </p>
+ </s3>
+ </s2>
-</section>
-
-<section>
- <title>Rendering Area Tree</title>
- <para>
+<s2 title="Rendering Area Tree">
+<p>
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>
+ </p>
+ <p>
The relevent structures that will need to be rendered are:
Page
Viewport
Block
Line
Inline
- </para>
- <para>
+ </p>
+ <p>
The renderer will need to be able to:
<itemizedlist>
<listitem><para>
draw various lines and rectangles
</para></listitem>
</itemizedlist>
- </para>
- <para>
+ </p>
+ <p>
An abstract renderer will be able to handle the generic positioning
of child areas, iterating through areas that have child areas.
- </para>
-</section>
+ </p>
+ </s2>
+
+ </s1>
+
+ </body>
+</document>
-</section>
--- /dev/null
+<?xml version="1.0"?>
+
+<book title="FOP Design" copyright="1999-2002 The Apache Software Foundation">
+ <external href="http://xml.apache.org/fop/" label="About FOP"/>
+ <separator/>
+ <page id="index" label="Design" source="intro.xml"/>
+ <page id="architecture" label="Architecture" source="architecture.xml" />
+ <page id="properties" label="Properties" source="properties.xml" />
+ <page id="fotree" label="FO Tree" source="fotree.xml" />
+ <page id="areatree" label="Area Tree" source="areas.xml" />
+ <separator/>
+ <page id="layout" label="Layout" source="layout.xml" />
+ <page id="renderers" label="Renderers" source="renderers.xml" />
+ <page id="useragent" label="User Agent" source="useragent.xml" />
+ <page id="optimise" label="Optimisations" source="optimise.xml" />
+ <separator/>
+ <page id="embedding" label="Embedding" source="embedding.xml" />
+ <separator/>
+ <page id="status" label="Status" source="status.xml" />
+</book>
+++ /dev/null
-
-echo NOTE: Do NOT use jdk1.4 - It doesn't work properly
-@echo off
-
-echo Design Doc Build System
-echo ----------------
-
-if "%JAVA_HOME%" == "" goto error
-
-set LIBDIR=..\..\lib
-set TARGET_CLASSPATH=%LIBDIR%\xerces-1.2.3.jar;%LIBDIR%\batik.jar;%LIBDIR%\ant.jar;%LIBDIR%\buildtools.jar;%LIBDIR%\xalan-2.0.0.jar;%LIBDIR%\bsf.jar;..\..\build\fop.jar;%LIBDIR%\logkit-1.0b4.jar;%LIBDIR%\avalon-framework-4.0.jar;%LIBDIR%\jimi-1.0.jar
-set TARGET_CLASSPATH=%TARGET_CLASSPATH%;%JAVA_HOME%\lib\tools.jar;%JAVA_HOME%\lib\classes.zip
-
-set ANT_HOME=%LIBDIR%
-
-%JAVA_HOME%\bin\java.exe -classpath "%TARGET_CLASSPATH%" org.apache.tools.ant.Main %1 %2 %3 %4
-
-goto end
-
-:error
-
-echo ERROR: JAVA_HOME not found in your environment.
-echo Please, set the JAVA_HOME variable in your environment to match the
-echo location of the Java Virtual Machine you want to use.
-
-:end
-
-rem set TARGET_CLASSPATH=
-
+++ /dev/null
-#! /bin/sh
-# $Id$
-
-LIBDIR=../../lib
-TARGET_CLASSPATH=$LIBDIR/ant.jar:\
-$LIBDIR/buildtools.jar:\
-$LIBDIR/xalan-2.0.0.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
-
-if [ "$JAVA_HOME" != "" ] ; then
- TARGET_CLASSPATH=$TARGET_CLASSPATH:$JAVA_HOME/lib/tools.jar
-else
- echo "Error: The JAVA_HOME environment variable is not set."
-fi
-
-java -classpath $TARGET_CLASSPATH org.apache.tools.ant.Main $*
+++ /dev/null
-<?xml version="1.0"?>
-<!-- ======================================================================= -->
-<!-- JBoss documentation build file -->
-<!-- ======================================================================= -->
-<project name="FOPDocs" default="docs" basedir="./">
- <target name="init">
- <property name="Name" value="FOPDocs"/>
- <property name="name" value="fopdocs"/>
- <property name="version" value="0.1"/>
- <property name="lib.dir" value="${basedir}/lib"/>
- <taskdef name="xslt" classname="org.apache.fop.tools.anttasks.Xslt"/>
- <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop"/>
- </target>
- <!-- =================================================================== -->
- <!-- Generate a help screen -->
- <!-- =================================================================== -->
- <target name="help" depends="init">
- <echo message="${name}-${version} build file, available targets:"/>
- <echo message="------------------------------------------------------------"/>
- <echo message="main : Compile and prepare deployment directory. "/>
- <echo message="pdf : Compile and prepare pdf user docs. "/>
- <echo message="clean : Clean deployment and distribution. "/>
- <echo message="------------------------------------------------------------"/>
- <echo message=" USAGE: build <target> "/>
- </target>
- <!-- =================================================================== -->
- <!-- Prepares the build directory -->
- <!-- =================================================================== -->
- <target name="prepare" depends="init"/>
- <!-- =================================================================== -->
- <!-- Generates the pdf documentation -->
- <!-- =================================================================== -->
- <target name="pdf" depends="prepare">
- <echo message="Building pdf documentation. Please wait ..."/>
- <delete file="fop.fo"/>
- <xslt infile="fop.xml" xsltfile="docbook/fo/docbook.xsl" dependent="fop.xml" outfile="fop.fo" smart="yes"/>
- <!--
- <style basedir="./"
- destdir="./"
- style="docbook/fo/docbook.xsl"
- extension=".fo"
- includes="fop.xml"/>
--->
- <fop fofile="fop.fo" outfile="fop.pdf"/>
- <!-- <delete file="fop.fo"/>-->
- </target>
- <!-- =================================================================== -->
- <!-- Generates pdf and html documentation -->
- <!-- =================================================================== -->
- <target name="docs" depends="pdf"/>
- <!-- =================================================================== -->
- <!-- Cleans up generated stuff -->
- <!-- =================================================================== -->
- <target name="clean" depends="init">
- <delete file="fop.fo"/>
- <delete file="fop.pdf"/>
- </target>
-</project>
--- /dev/null
+<?xml version="1.0" standalone="no"?>
+
+<!-- Overview -->
+
+<document>
+ <header>
+ <title>FOP Design</title>
+ <subtitle>Design Approach to FOP</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="Introduction">
+<p>
+This is the design for the external interface when FOP is to be embedded
+inside another java application.
+ </p>
+ <p>
+Common places where FOP is embedded is in a report production application
+of a server side application such as <jump href="http://xml.apache.org/cocoon/index.html">Cocoon</jump>.
+ </p>
+ </s1>
+
+ </body>
+</document>
+
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx/docbookx.dtd" [
- <!ENTITY intro.xml SYSTEM "intro.xml">
- <!ENTITY layout.xml SYSTEM "layout.xml">
- <!ENTITY areas.xml SYSTEM "areas.xml">
- <!ENTITY optimise.xml SYSTEM "optimise.xml">
- <!ENTITY useragent.xml SYSTEM "useragent.xml">
-]>
-<book>
- <bookinfo>
- <title>FOP documentation</title>
- <copyright>
- <year>2001</year>
- <holder>The Apache Software Foundation. All rights reserved.</holder>
- </copyright>
- </bookinfo>
-&intro.xml;
-<chapter id="fop">
- <title>FOP</title>
-&layout.xml;
-</chapter>
-<chapter id="areas">
- <title>Areas</title>
-&areas.xml;
-</chapter>
-<chapter id="optimise">
- <title>Optimising</title>
-&optimise.xml;
-</chapter>
-<chapter id="useragent">
- <title>User Agent</title>
-&useragent.xml;
-</chapter>
-</book>
--- /dev/null
+<?xml version="1.0" standalone="no"?>
+
+<!-- Overview -->
+
+<document>
+ <header>
+ <title>FO Tree</title>
+ <subtitle>Design of FO Tree Structure</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="Introduction">
+<p>
+The FO Tree is an internal representation of the input FO document.
+The tree is created by building the elements and attributes from
+the SAX events.
+ </p>
+ <p>
+The FO Tree is used as an intermediatory structure which is converted
+into the area tree. The complete FO tree should not be held in memory
+since FOP should be able to handle FO documents of any size.
+ </p>
+ </s1>
+
+ </body>
+</document>
+
-<?xml version = "1.0" encoding = "UTF-8"?>
-<preface>
- <title>About this Document</title>
- <para>
-This document is written in docbook with the hope that it will
-provide a good test case of a common usage of FO created by
-docbook. The information is then processed by fop to produce
-a PDF document.
- </para>
- <para>
-It is hoped that this document can be used as a basis for designing
-a new layout system for FOP so that it can handle all necessary
-situations when deciding line breaks, page breaks and spacing.
-It should also allow for the easy implementation of different
-writing modes and character sets.
- </para>
+<?xml version="1.0" standalone="no"?>
+
+<!-- Overview -->
+
+<document>
+ <header>
+ <title>FOP Design</title>
+ <subtitle>Design Approach to FOP</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="Introduction">
+<p>
+The information here describes the design and architecture details for FOP.
+Currently this is part of a redesign process for some of the core parts of
+FOP.
+ </p>
+ <p>
+The redesign is mainly focusing on some particular process involved
+with the layout process when converting the FO tree into the Area Tree.
+ </p>
+ <p>
+
+ </p>
+ </s1>
+
+ </body>
+</document>
-</preface>
-<?xml version = "1.0" encoding = "UTF-8"?>
-<section id="layout">
- <title>FO Layout</title>
- <para>
+<?xml version="1.0" standalone="no"?>
+
+<!-- Overview -->
+
+<document>
+ <header>
+ <title>Layout</title>
+ <subtitle>Layout Process in FOP</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="FO Layout">
+<p>
The aim of the layout system is to be self contained and allow for
easy changes or extensions for future development. For example the
line breaking should be decided at a particular point in the process
that makes it easier to handle other languages.
- </para>
- <para>
+ </p>
+ <p>
The layout begins once the hierarchy of FO objects has been constructed.
Note: it may be possible to start immediately after a block formatting
object has been added to the flow but this is not currently in the scope
of the layout. It is also possible to layout all pages in a page sequence
after each page sequence has been added from the xml.
- </para>
- <para>
+ </p>
+ <p>
The layout process is handled by a set of layout managers. The block
level layout managers are used to create the block areas which are
added to the region area of a page.
- </para>
- <section>
- <title>Layout Managers</title>
- <para>
+ </p>
+<s2 title="Layout Managers">
+ <p>
The layout managers are set up from the hierarchy of the formatting
object tree. A manager represents a hierachy of area producing objects.
A manager is able to handle the block area(s) that it creates and
organise or split areas for page breaks.
- </para>
- <para>
+ </p>
+ <p>
Normally any object that creates a block area will have an associated
layout manager. Other cases are tables and lists, these objects will
also have layout managers that will manager the group of layout managers
that make up the object.
- </para>
- <para>
+ </p>
+ <p>
A layout manager is also able to determine height (min/max/optimum)
and keep status. This will be used when organising the layout on
a page. The manager will be able to determine the next place a break
can be made and then be able to organise the height.
- </para>
- <para>
+ </p>
+ <p>
A layout manager is essentially a bridge between the formatting objects
and the area tree. It will keep a list of line areas inside block areas.
Each line area will contain a list of inline areas that is able to be
adjusted if the need arises.
- </para>
- <para>
+ </p>
+ <p>
The objects in the area tree that are organised by the manager will mostly
contain the information about there layout such as spacing and keeps, this
information will be thrown away once the layout for a page is finalised.
- </para>
-</section>
-
- <section>
- <title>Creating Managers</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Creating Managers">
+ <p>
The managers are created by the page sequence. The top level manager
is the Page manager. This asks the flow to add all managers in this
page sequence.
- </para>
- <para>
+ </p>
+ <p>
For block level objects they have a layout manager. Neutral objects
don't represent any areas but are used to contain a block level
area and as such these objects will ask the appropriate child to
create a layout manager.
- </para>
- <para>
+ </p>
+ <p>
Any nested block areas or inline areas may be handled by the layout
manager at a later stage.
- </para>
-</section>
-
- <section>
- <title>Using Managers</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Using Managers">
+ <p>
Block area layout managers are used to create a block area, other block
level managers may ask their child layout managers to create block areas
which are then added to the area tree (subset).
- </para>
- <para>
+ </p>
+ <p>
A manager is used to add areas to a page until the page is full,
then the manages contain all the information necessary to make
the decision about page break and spacing. A manager can split an
area that it has created will keep a status about what has been
added to the current area tree.
- </para>
-</section>
-
- <section>
- <title>Page Layout</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Page Layout">
+ <p>
Once the Page layout manager, belonging to the page sequence, is ready
then we can start laying out each page. The page sequence will create
the current page to put the page data, the next page and if it exists
a last page.
- </para>
- <para>
+ </p>
+ <p>
The current page will have the areas added to it from the block layout
managers. The next page will be used when splitting a block that goes
over the page break. Note: any page break overrides the layout decided
here. The last page will be necessary if the last block area is added
to this page. The size of the last page will be considered and the
areas will be added to the last page instead.
- </para>
- <para>
+ </p>
+ <p>
The first step is to add areas to the current page until the area is full
and the lines of the last block area contain at least n(orphans) and at least
n(orphans) + n(widows) in total. This will only be relevant for areas at
the start or end of a particular reference area.
- </para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref = "page.svg"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>
+ </p>
+ <p>
+ <image src="page.svg"/>
+ </p>
+ <p>
The spacing between the areas (including spacing in block areas inside
an inline-container) will be set to the minimum values. This will allow
the page to have at least all the information it needs to organise the
page properly.
- </para>
- <para>
+ </p>
+ <p>
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
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>
+ </p>
+ <p>
The spacing and keep information is stored so that the area positions
and sizes can be adjusted.
- </para>
- <section>
- <title>Balancing Page</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Balancing Page">
+ <p>
The page is vertically justified so that it distributes the areas
on the page for the best result when considering keeps and spacing.
- </para>
- <section>
- <title>Finding Break</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Finding Break">
+ <p>
First the keeps are checked. The available space on the page may have
changed due to the presence of before floats or footnotes. The page break
will need to be at a height <= the available space on the page.
- </para>
- <para>
+ </p>
+ <p>
A page break should be made at the first available position that
has the lowest keep value when searching from the bottom. Once the first
possible break is found then the next possible break, with equally low
keep value, is considered. If the height of the page is closer to the
optimal spacing then this break will be used instead.
- </para>
- <para>
+ </p>
+ <p>
Keep values include implicit and explicit values when trying to
split a block area into more than one area. Implicit keeps may
be such things as widows/orphans.
- </para>
- <para>
+ </p>
+ <p>
If the page contains before floats or footnotes then as each area or line
-area is removed the float/footnote should also be removed. This will
+area is removed the float/footnote should also be removed. This will
change the available space and is a one way operation. The footnote
-should be removed first as a footnote may be placed on the next page.
+should be removed first as a footnote may be placed on the next page.
The lowest keep value may need to be reassessed as each conditional
area is removed.
- </para>
- <para>
+ </p>
+ <p>
The before float and footnote regions are managed so that the separator
regions will be present if it contains at least one area.
- </para>
-</section>
- <section>
- <title>Optimising</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Optimising">
+ <p>
Once the areas for the page are finalised then the spacing will
need to be adjusted. The available height on the page is compared
with the min and max spacing. All of the spacing in all the areas
on the page is then adjusted by the appropriate percentage value.
- </para>
-</section>
-
- <section>
- <title>Multi-Column Pages</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Multi-Column Pages">
+ <p>
In the case of multi-column pages the column breaks and eventually
the page break must be found in a slightly different way.
- </para>
- <para>
+ </p>
+ <p>
The columns need to be layed out completely from first to last but
this can only be done after a rough estimate of all the elements
on the page in case of before floats or footnotes.
- </para>
- <para>
+ </p>
+ <p>
So first the complete page is layed out with all columns filled
with areas and the spacing at a minimum. Then if there are any
before floats or footnotes then the availabe space is adjusted.
the first column. If any before floats or footnotes are removed
as a result of the new breaks and optimised spacing then all the
columns should still be layed out for the same column height.
- </para>
-</section>
-
-</section>
-</section>
-
- <section>
- <title>Completing Page</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Completing Page">
+ <p>
After the region body has been finished the static areas can be
layed out. The width of the static area is set and the height is
inifinite, that is all block areas should be placed in the area
and their visibility is controlled be other factors.
- </para>
- <para>
+ </p>
+ <p>
The area tree for the region body will contain the information
about markers that may be necessary for the retrieve marker.
- </para>
- <para>
+ </p>
+ <p>
The ordering of the area tree must be adjusted so that the areas are
before, start, body, end and after in that order. The body region
should be in the order before float, main then footnote.
- </para>
-</section>
-
- <section>
- <title>Line Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Line Areas">
+ <p>
Creating a line areas uses a similair concept. Each inline area
is placed across the available space until there is no room left.
The line is then split by considering all keeps and spacing.
- </para>
- <para>
+ </p>
+ <p>
Each word (group of adjacent character inline areas) will have keeps
based on hyphenation. The line break is at the lowest keep value
starting from the end of the line.
- </para>
- <para>
+ </p>
+ <p>
Once a line has been layed out for a particular width
then that line is fixed for the page (except for unresolved
page references).
- </para>
-</section>
-
- <section>
- <title>Before Floats and Footnotes</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Before Floats and Footnotes">
+ <p>
The before float region and footnote region are handled by the page
layoutmanger. These regions will handle the addition and removal
of the separator regions when before floats/footnotes area added
and removed.
- </para>
-</section>
-
- <section>
- <title>Side Floats</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Side Floats">
+ <p>
If a float anchor is present in a particular line area then the available
space for that line (and other in the block) will be reduced. The side float
adds to the height of the block area and this height also depends
on the clear value of subsequent blocks. The keep status of the block is
also effected as there must be enough space on the page to fit the
side float.
- </para>
- <para>
- <mediaobject>
- <imageobject>
- <imagedata fileref = "float.svg"/>
- </imageobject>
- </mediaobject>
- </para>
-</section>
-
- <section>
- <title>Unresolved Areas</title>
- <para>
+ </p>
+ <p>
+<image src="float.svg"/>
+ </p>
+ </s2>
+<s2 title="Unresolved Areas">
+ <p>
Once the layout of the page is complete there may be unresolved areas.
- </para>
- <para>
+ </p>
+ <p>
Page number citations and links may require following pages to be
layed out before they can be resolved. These will remain in the
area tree as unresolved areas.
- </para>
- <para>
+ </p>
+ <p>
As each page is completed the list of unresolved id's will be checked
and if the id can be resolved it will be. Once all id's are resolved
then the page can be rendered.
- </para>
- <para>
+ </p>
+ <p>
Each page contains a map of all unresolved id's and the corresponding
areas.
- </para>
- <para>
+ </p>
+ <p>
In the case of page number citations. The areas reserves the equivalent
of 3 number nines in the current font. When the area is resolved
then the area is adjusted to its proper size and the line area is
re-aligned to accomodate the change.
- </para>
-</section>
-
- <section>
- <title>ID and Link Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="ID and Link Areas">
+ <p>
Any formatting object that has an ID or any inline link defines an area
that will be required when rendering and resolving id references.
- </para>
- <para>
+ </p>
+ <p>
This area is stored in the parent area and may be a shape that exists
in more than one page, for example over a page break. This shape consists
of the boundary of all inline (or block) areas that the shape is defined
for.
- </para>
-</section>
-
- <section>
- <title>Inline Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Inline Areas">
+ <p>
This is the definition of all inline areas that will exist in the
area.
- </para>
- <section>
- <title>Fixed Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Fixed Areas">
+ <p>
instream-foreign-object, external-graphic, inline-container
- </para>
- <para>
+ </p>
+ <p>
These areas have a fixed width and height. They also have a viewport.
- </para>
-</section>
- <section>
- <title>Stretch Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Stretch Areas">
+ <p>
leader, inline space
- </para>
- <para>
+ </p>
+ <p>
These areas have a fixed height but the width may vary.
- </para>
-</section>
- <section>
- <title>Character Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Character Areas">
+ <p>
character
- </para>
- <para>
+ </p>
+ <p>
This is an simple character that has fixed properties according to
the current font. There are implicit keeps with adjacent characters.
- </para>
-</section>
- <section>
- <title>Anchor Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Anchor Areas">
+ <p>
float anchor, footnote anchor
- </para>
- <para>
+ </p>
+ <p>
This area has no size. It keeps the position for footnotes and floats
and has a keep with the associated inline area.
- </para>
-</section>
- <section>
- <title>Unresolved Page Numbers</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Unresolved Page Numbers">
+ <p>
page-number-citation
- </para>
- <para>
+ </p>
+ <p>
A page number area that needs resolving, behaves as a character and
has the space of 3 normal characters reserved. The size will adjust
when the value is resolved.
- </para>
-</section>
-
-</section>
-
- <section>
- <title>Block Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Block Areas">
+ <p>
The block area has info about the following:
<itemizedlist>
<listitem><para>
widows and orphans
</para></listitem>
</itemizedlist>
- </para>
- <para>
+ </p>
+ <p>
Once the layout has been finalised then this information can be
discarded.
- </para>
-</section>
-
- <section>
- <title>Page Areas</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Page Areas">
+ <p>
Contains inforamtion about all the block areas in the body,
before area and footer area.
- </para>
- <para>
+ </p>
+ <p>
Has a list of the unresolved page references and a list of id refences
that can be used to obtain the area associated with that id.
- </para>
-</section>
-
- <section>
- <title>Test Cases</title>
- <para>
+ </p>
+ </s2>
+<s2 title="Test Cases">
+ <p>
Here a few layout possibilities areas explored to determine how the
layout process will handle these situations.
- </para>
- <section>
- <title>Simple Pages</title>
- <para>
+ </p>
+<s3 title="Simple Pages">
+ <p>
All blocks (including nested) are placed on the page with minimum spacing
and the last block has the minimum number of lines past the page end.
The lowest keep value is then found within the body area limits. Then the next
equally low keep is found to determine if the spacing will be closer to
the optimum values.
- </para>
- </section>
- <section>
- <title>Before Floats/Footnotes</title>
- <para>
+ </p>
+ </s3>
+<s3 title="Before Floats/Footnotes">
+ <p>
After filling the page with the block areas then the new body height
is used to find the best position to break. Before each line area or block
area is remove any associated before floats and footnotes are removed.
breaking point until the areas fit on the page. When finding the
optimum spacing the removal of before floats and footnotes must also
be considered.
- </para>
- </section>
- <section>
- <title>Multicolumn</title>
- <para>
+ </p>
+ </s3>
+<s3 title="Multicolumn">
+ <p>
First the page is filled with all columns for the intial page area.
Then each column is adjusted for the new height starting from the
first column. The best break for the column is found then the next
column. Once all the columns are finished then all the columns are
adjusted to fit in the same height columns. This handles the situation
where before floats or footnotes may have been removed.
- </para>
- </section>
- <section>
- <title>Last Page</title>
- <para>
+ </p>
+ </s3>
+<s3 title="Last Page">
+ <p>
If in the process of adding areas to a page it is found that there
are no more areas in the flow then this page will need to be changed to
the last page (if applicable). The areas are then placed on a last
page.
- </para>
- </section>
+ </p>
+ </s3>
+ </s2>
+
+ </s1>
-</section>
+ </body>
+</document>
-</section>
-<?xml version = "1.0" encoding = "UTF-8"?>
-<section id="optimisations">
- <title>Process Optimisations</title>
- <para>
+<?xml version="1.0" standalone="no"?>
+
+<!-- Overview -->
+
+<document>
+ <header>
+ <title>FOP Optimisations</title>
+ <subtitle>Notes for Optimising FOP</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="Process Optimisations">
+<p>
FOP should be able to handle very large documents. A document can be
supplied using SAX and the information should be passed entirely through
the system, from fo elements to rendered output as soon as possible.
- </para>
- <para>
+ </p>
+ <p>
A top level block area, immediately below the flow, can be added to the
page layout as soon as the element is complete.
- </para>
- <para>
+ </p>
+ <p>
The fo elements used to construct a page can be discarded as soon as the
layout for the page is complete. Some information may be stored in the
area tree of the page in order to handle unresolved page references
and links.
- </para>
- <para>
+ </p>
+ <p>
Once the layout of a page has been completed, all elements are fully
resolved, then the page can be rendered. Some renderers may support
out of order rendering of pages.
- </para>
- <para>
+ </p>
+ <p>
The main problem that will remain is that any page with forward
references will need to be stored until the refence is resolved.
-This means that the information contained in the page should be
+This means that the information contained in the page should be
as minimal as possible.
- </para>
- <para>
+ </p>
+ <p>
Line areas can be optimised once the layout for the line has
been finalised. Consecutive characters with the same properties
can be combined into a "word" to hold the information with
limited overhead.
- </para>
- <para>
+ </p>
+ <p>
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>
+ </p>
+ </s1>
+
+ </body>
+</document>
-</section>
--- /dev/null
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!-- $Id$ -->
+
+<document>
+ <header>
+ <title>Properties</title>
+ <subtitle>Properties overview</subtitle>
+ <authors>
+ <person name="Karen Lease"/>
+ </authors>
+ </header>
+
+ <body>
+
+<s1 title="Properties">
+ <s2 title="Property datatypes">
+<p>The property datatypes are defined in the
+org.apache.fop.datatypes package, except Number and String which are java
+primitives. The FOP datatypes are:</p>
+<ul>
+<li>Number</li>
+<li>String</li>
+<li>ColorType</li>
+<li>Length (has several subclasses)</li>
+<li>CondLength (compound)</li>
+<li>LengthRange (compound)</li>
+<li>Space (compound)</li>
+<li>Keep (compound)</li>
+</ul>
+<p>The <em>org.apache.fop.fo.Property</em> class is the superclass for all
+Property subclasses. There is a subclass for each kind of property
+datatype. These are named using the datatype name plus the word
+Property, resulting in NumberProperty, StringProperty, and so
+on. There is also a class EnumProperty which uses an <code>int</code>
+primitive to hold enumerated values. There is no corresponding Enum
+datatype class.</p>
+<p>The Property class provides a "wrapper" around any possible
+property value. Code manipulating property values (in layout for
+example) usually knows what kind (or kinds) of datatypes are
+acceptable for a given property and will use the appropriate accessor.</p>
+<p>The base Property class defines accessor methods for all FO property
+datatypes, such as getNumber(), getColorType(), getSpace(), getEnum(),
+etc. It doesn't define
+accessors for SVG types, since these are handled separately (at least
+for now.) In the base Property class, all of these methods return
+null, except getEnum which returns 0. Individual subclasses return a value of the appropriate type,
+such as Length or ColorType. A subclass may also choose to return a
+reasonable value for other accessor types. For example, a
+SpaceProperty will return the optimum value if asked for a Length.</p>
+ </s2>
+
+ <s2 title="Property Makers">
+<p>The Property class contains a nested class called
+<em>Maker</em>. This is the base class for all other property Makers. It
+provides basic framework functionality which is overridden by the
+code generated by properties.xsl from the *properties.xml files. In
+particular it provides basic expression evaluation, using
+PropertyParser class in the org.apache.fop.fo.expr package.</p>
+<p>Other Property subclasses such as LengthProperty define their own
+nested Maker classes (subclasses of Property.Maker). These handle
+conversion from the Property subclass returned from expression
+evaluation into the appropriate subclass for the property.</p>
+<p>For each generic or specific property definition in the
+properties.xml files, a new subclass of one of the Maker classes is
+created. Note that no new Property subclasses are created, only new
+PropertyMaker subclasses. Once the property value has been parsed and
+stored, it has no specific functionality. Only the Maker code is
+specific. Maker subclasses define such aspects as keyword
+substitutions, whether the property can be inherited or not, which
+enumerated values are legal, default values, corresponding properties
+and specific datatype conversions.</p>
+</s2>
+ <s2 title="XML property specification format">
+ <s3 title="Generic properties">
+<p>In the properties xml files, one can define generic property
+definitions which can serve as a basis for individual property
+definitions. There are currently several generic properties defined in
+foproperties.xml. An example is GenericColor, which defines basic properties
+for all ColorType properties. Since the generic specification doesn't include
+the inherited or default elements, these should be set in each property
+which is based on GenericColor. Here is an example:</p>
+<p>
+<code>
+ <property type='generic'>
+ <name>background-color</name>
+ <use-generic>GenericColor</use-generic>
+ <inherited>false</inherited>
+ <default>transparent</default>
+ </property>
+</code></p>
+<p>A generic property specification can include all of the elements
+defined for the property element in the DTD, including the description
+of components for compound properties, and the specification of
+keyword shorthands.</p>
+
+<p>Generic property specifications can be based on other generic
+specifications.
+An example is GenericCondPadding template which is based on the
+GenericCondLength definition but which extends it by adding an inherited
+element and a default value for the length component.</p>
+<p>
+Generic properties can specify enumerated values, as in the
+GenericBorderStyle template. This means that the list of values, which
+is used by 8 properties (the "absolute" and "writing-mode-relative"
+variants for each BorderStyle property) is only specified one time.</p>
+<p>
+When a property includes a "use-generic" element and includes no other
+elements (except the "name" element), then no class is generated for the
+property. Instead the generated mapping will associate this
+property directly with an instance of the generic Maker.</p>
+<p>
+A generic class may also be hand-coded, rather than generated from the
+properties file.
+Properties based on such a generic class are indicated by the
+attribute <code>ispropclass='true'</code> on the
+<em>use-generic</em> element.</p>
+<p> This is illustrated by the SVG properties, most of
+which use one of the Property subclasses defined in the
+<em>org.apache.fop.svg</em>
+package. Although all of these properties are now declared in
+svgproperties.xml, no specific classes are generated. Classes are only
+generated for those SVG properties which are not based on generic
+classes defined in svg.</p>
+ </s3>
+ <s3 title="Element-specific properties">
+<p>Properties may be defined for all flow objects or only for
+particular flow objects. A PropertyListBuilder object will always look
+first for a Property.Maker for the flow object before looking in the
+general list. These are specified in the
+<code>element-property-list</code> section of the properties.xml
+files. The <code>localname</code> element children of this element specify for
+which flow-object elements the property should be registered.</p>
+<p><em>NOTE</em>: All the properties for an object or set of objects
+must be specified in a single element-property-list element. If the
+same localname appears in several element lists, the later set of
+properties will hide the earlier ones! Use the <em>ref</em>
+functionality if the same property is to be used in different sets of
+element-specific mappings.
+</p>
+ </s3>
+ <s3 title="Reference properties">
+ <p>A property element may have a type attribute with the value
+ <code>ref</code>. The
+ content of the <em>name</em> child element is the name of the referenced
+ property (not its class-name!). This indicates that the property
+ specification has
+ already been given, either in this same specification file or in a
+ different one (indicated by the <code>family</code> attribute). The
+ value of the family attribute is <em>XX</em> where the file
+ <em>XXproperties.xml</em> defines the referenced property. For
+ example, some SVG objects may have properties defined for FO. Rather
+ than defining them again with a new name, the SVG properties simply
+ reference the defined FO properties. The generating mapping for the
+ SVG properties will use the FO Maker classes.</p>
+ </s3>
+ <s3 title="Corresponding properties">
+<p>Some properties have both <em>absolute</em> and
+<em>writing-mode-relative</em> forms. In general, the absolute forms
+are equivalent to CSS properties, and the writing-mode-relative forms
+are based on DSSSL. FO files may use either or both forms. In
+FOP code, a request for an absolute form will retrieve that value if it
+was specified on the FO; otherwise the corresponding relative property
+will be used if it was specified. However, a request for a relative
+form will only use the specified relative value if the corresponding
+absolute value was <em>not</em> specified for that FO.
+</p>
+<p>Corresponding properties are specified in the properties.xml files
+using the element <code>corresponding</code>, which has at least one
+<code>propval</code> child and may have a <code>propexpr</code> child,
+if the corresponding
+value is calculated based on several other properties, as for
+<code>start-indent</code>.
+</p>
+<p><em>NOTE</em>: most current FOP code accesses the absolute variants
+of these properties, notably for padding, border, height and width
+attributes. However it does use start-indent and end-indent, rather
+than the "absolute" margin properties.
+</p>
+</s3>
+ </s2>
+
+ <s2 title="Mapping">
+<p>The XSL script <code>propmap.xsl</code> is used to generate
+property mappings based on
+both foproperties.xml and svgproperties.xml. The mapping classes
+in the main fop packages simply load these automatically generated
+mappings. The mapping code still uses the static
+"maker" function of the generated object to obtain a Maker
+object. However, for all generated classes, this method returns an
+instance of the class itself (which is a subclass of Property.Maker)
+and not an instance of a separate nested Maker class.</p>
+<p>For most SVG properties which use the SVG Property classes directly,
+the generated mapper code calls the "maker" method of the SVG Property
+class, which returns an instance of its nested Maker class.</p>
+<p>The property generation also handles element-specific property
+mappings as specified in the properties XML files.</p>
+ </s2>
+
+ <s2 title="Enumerated values">
+<p>For any property whose datatype is <code>Enum</code> or which
+contains possible enumerated values, FOP code may need to access
+enumeration constants. These are defined in the interfaces whose name
+is the same as the generated class name for the property,
+for example <code>BorderBeforeStyle.NONE</code>. These interface classes
+are generated by the XSL script <code>enumgen.xsl</code>. A separate
+interface defining the enumeration constants is always generated for
+every property which uses the constants, even if the constants
+themselves are defined in a generic class, as in BorderStyle.</p>
+<p>If a subproperty or component of a compound property has enumerated
+values, the constants are defined in a nested interface whose name is
+the name of the subproperty (using appropriate capitalization
+rules). For example,
+the keep properties may have values of AUTO or FORCE or an integer
+value. These are defined for each kind of keep property. For example,
+the keep-together property is a compound property with the components
+within-line, within-column and within-page. Since each component may
+have the values AUTO or FORCE, the KeepTogether interface defines
+three nested interfaces, one for each component, and each defines
+these two constants. An example of a reference in code to the constant
+is <code>KeepTogether.WithinPage.AUTO</code>.</p>
+
+ </s2>
+
+ <s2 title="Compound property types">
+<p>Some XSL FO properties are specified by compound datatypes. In the FO file,
+these are defined by a group of attributes, each having a name of the
+form <code>property.component</code>, for example
+<code>space-before.minimum</code>. These are several compound
+datatypes:</p>
+<ul>
+<li>LengthConditional, with components length and conditionality</li>
+<li>LengthRange, with components minimum, optimum, and maximum</li>
+<li>Space, with components minimum, optimum, maximum, precedence and
+conditionality </li>
+<li>Keep, with components within-line, within-column and within-page</li>
+</ul>
+<p>These are described in the properties.xml files using the element
+<code>compound</code> which has <code>subproperty</code> children. A subproperty element is much
+like a property element, although it may not have an <code>inherited</code> child
+element, as only a complete property object may be inherited.
+</p>
+<p>Specific datatype classes exist for each compound property. Each
+component of a compound datatype is itself stored as a Property
+object. Individual components may be accessed either by directly
+performing a get operation on the name, using the "dot" notation,
+eg. <code>get("space-before.optimum")</code>; or by using an accessor on the compound
+property, eg. <code>get("space-before").getOptimum()</code>.
+In either case,
+the result is a Property object, and the actual value may be accessed
+(in this example) by using the "getLength()" accessor.
+</p>
+ </s2>
+</s1>
+ </body>
+</document>
+
--- /dev/null
+<?xml version="1.0" standalone="no"?>
+
+<!-- Overview -->
+
+<document>
+ <header>
+ <title>Renderers</title>
+ <subtitle>Design of Renderers</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="Introduction">
+<p>
+A render is primarily design to convert a given area tree into the output
+document format. It should be able to produce pages and fill the pages
+with the text and graphical content. Usually the output is sent to
+an output stream.
+ </p>
+ <p>
+Some output formats may support extra information that is not available
+from the area tree or depends on the destination of the document.
+ </p>
+ </s1>
+
+ </body>
+</document>
+
--- /dev/null
+<?xml version="1.0" standalone="no"?>
+
+<!-- Overview -->
+
+<document>
+ <header>
+ <title>Design Status</title>
+ <subtitle>Current Status of FOP and Design</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="Status">
+<p>
+Currently some of FOP is being re-written so that the layout can be handled
+properly without the problems that have been encountered and to make
+it possible to handle keeps/breaks and spacing better.
+ </p>
+<p>
+
+ </p>
+ </s1>
+
+ </body>
+</document>
+
-<?xml version = "1.0" encoding = "UTF-8"?>
-<section id="useragent-use">
- <title>Usage</title>
- <para>
+<?xml version="1.0" standalone="no"?>
+
+<document>
+ <header>
+ <title>FO User Agent</title>
+ <subtitle>Design of FO User Agent</subtitle>
+ <authors>
+ <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+ </authors>
+ </header>
+
+ <body>
+<s1 title="Purpose">
+<p>
+Technically the user agent is FOP in the role of determining the
+output format and when resolving various attributes. The user
+agent is represented by a class that is available to others to
+specify how FOP should behave.
+ </p>
+ <p>
The user agent is used by the formatting process to determine
certain user definable values.
- </para>
- <para>
+ </p>
+ <p>
It will enable the customisation of values for generating and
rendering the document.
- </para>
- <para>
+ </p>
+ <p>
The user agent must be available to the layout processor and
the renderer. Users can supply their own user agent or use
the default one for a particular renderer.
- </para>
- <para>
+ </p>
+ <p>
The user agent needs to be made available to the property
resolution layout process and the renderer.
- </para>
+ </p>
- <para>
+ <p>
Standard Features:
<itemizedlist>
<listitem><para>
rendering processor of content-type (mime type)
</para></listitem>
</itemizedlist>
- </para>
+ </p>
- <para>
+ <p>
Interactive Features:
<itemizedlist>
<listitem><para>
media usage of auto
</para></listitem>
</itemizedlist>
- </para>
+ </p>
+
+ </s1>
+
+ </body>
+</document>
-</section>
projects / xmlgraphics-fop.git / commitdiff