You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlgraphics.apache.org by bu...@apache.org on 2012/04/15 07:39:54 UTC
svn commit: r813018 [14/24] - in
/websites/staging/xmlgraphics/trunk/content: ./ fop/ fop/0.95/
fop/0.95/images/ fop/1.0/ fop/1.0/images/ fop/dev/ fop/dev/design/
fop/dev/fo/ fop/dev/svg/ fop/fo/ fop/trunk/ fop/trunk/images/
Added: websites/staging/xmlgraphics/trunk/content/fop/dev/conventions.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/dev/conventions.html (added)
+++ websites/staging/xmlgraphics/trunk/content/fop/dev/conventions.html Sun Apr 15 05:39:50 2012
@@ -0,0 +1,239 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Apache⢠FOP Development: Coding Conventions</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Apache⢠FOP Development: Coding Conventions</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/dev/">Dev</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p><version>$Revision: 1298724 $</version></p>
+<p>Acknowledgement: Some content in this guide was adapted from other Apache⢠projects such as Avalon, Cactus, Turbine and Velocity.</p>
+<h1 id="svn">Subversion Repository</h1>
+<p>Conventions in this section apply to Repository content, regardless of type:</p>
+<ul>
+<li>
+<p>Files checked in must conform to the code conventions for that type of file (java files must conform to java requirements, xml to xml requirements, etc.). If a submitted patch does not conform, it is the responsibility of the committer to bring it into conformance before checking it in. Developers submitting patches are encouraged to follow the code conventions to reduce the work load on the committers.</p>
+</li>
+<li>
+<p>To reduce the amount of spurious deltas, all text (non-binary) files checked into SVN must have Unix-style line endings (LF only). Many IDEs and editors (even on non-Unix platforms) have settings that can facilitate this convention.</p>
+</li>
+<li>
+<p>In order to be able to discern commits from a committer from those where a committer applied a patch from a contributor, the commit message must contain a separate line following this pattern: <strong>"Submitted by: [contributor's name] <[contributor's obfuscated e-mail address]>"</strong> . This also helps doing audits on the repository.</p>
+</li>
+</ul>
+<h1 id="java">Java</h1>
+<h2 id="java-style">Java Style</h2>
+<p>In order to facilitate the human reading of FOP source code, reduce churning in code, and prevent disputes, the FOP developers have agreed on a set of coding conventions. The basis of these coding conventions is documented in the <a href="http://xml.apache.org/source.html">Apache XML Project Guidelines</a> , which requires that <strong>all Java Language source code in the repository must be written in conformance to Sun's</strong> <a href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Code Conventions for the Java Programming Language</a> . In addition, the FOP developers have agreed to other conventions, which are summarized in the following table:</p>
+<table>
+<thead>
+<tr>
+<th>Convention</th>
+<th>Rationale</th>
+<th>Enforced By</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Every Java source file starts with the Apache licence header.</td>
+<td>Required by Apache.</td>
+<td>checkstyle</td>
+</tr>
+<tr>
+<td>No tabs in content.</td>
+<td>Programmers should not have to adjust the tab settings in their editor to be able to read the source code.</td>
+<td>checkstyle</td>
+</tr>
+<tr>
+<td>Indentation of 4 spaces per level.</td>
+<td>Maximize readability.</td>
+<td>Not enforced</td>
+</tr>
+<tr>
+<td>Comments, identifiers, and project documentation must be in English. In general, other languages must not be used, except in translated documentation and language-specific i10n files.</td>
+<td>To avoid the need for everyone to learn all languages, English has become the standard language for many technology projects, and is the only human language that all FOP developers are expected to know.</td>
+<td>Not enforced</td>
+</tr>
+<tr>
+<td>American English spelling should be used. Alternative spelling and idioms are tolerated, but may be changed by anyone to American.</td>
+<td>Some standard is useful, and American English is widely used and accepted for technology standards and projects.</td>
+<td>Not enforced.</td>
+</tr>
+<tr>
+<td>Fully qualify all import statements (no "import java.util.*")</td>
+<td>Clarity</td>
+<td>checkstyle</td>
+</tr>
+<tr>
+<td>No underscores in variable names except for static finals.</td>
+<td>Upper/lower case distinctions can be made in all other variable names, eliminating the need for artificial word boundaries.</td>
+<td>checkstyle</td>
+</tr>
+<tr>
+<td>Opening brace for a block should be on the same line as its control statement (if, while, etc.).</td>
+<td>Standardization, general preference.</td>
+<td>checkstyle</td>
+</tr>
+<tr>
+<td>Write appropriate javadoc entries for all public and protected classes, methods, and variables.</td>
+<td>Basic API documentation is needed.</td>
+<td>checkstyle</td>
+</tr>
+<tr>
+<td>By <a href="http://mail-archives.apache.org/mod_mbox/jakarta-jmeter-dev/200402.mbox/%3C4039F65E.7020406@atg.com%3E">ASF policy</a> , @author tags are officially discouraged. However it is permissible to indicate the original author(s) of an entire file or package in a comment provided it follows the copyright and license header.</td>
+<td>Attribution of subsequent contributions are recorded by the SVN commit history logs, so should not be included.</td>
+<td>checkstyle</td>
+</tr>
+</tbody>
+</table>
+<p>For developers that dislike these conventions, one workaround is to develop using their own style, then use a formatting tool like <a href="http://astyle.sourceforge.net/">astyle</a> (Artistic Style) before committing.</p>
+<h2 id="java-checkstyle">Checkstyle</h2>
+<p>The java syntax checker "<jump href="http://checkstyle.sourceforge.net">Checkstyle</jump>" is used to enforce many of the FOP coding standards. The standards enforced through Checkstyle are documented in its configuration file (xml-fop/checkstyle.cfg). The conventions defined in the configuration file are an integral part of FOP's coding conventions, and should not be changed without common consent. In other words, the configuration file contains additional conventions that are not documented on this page, but are generally accepted as good style within the java community (i.e. they are the default behavior of checkstyle, which the FOP developers have decided to adopt <em>de facto</em> ). Any apparent contradiction between the configuration file and this document should be raised on the fop-dev mailing list so that it can be clarified.</p>
+<p>To use the "checkstyle" target in FOP's build process, download the source from the<jump href="http://checkstyle.sourceforge.net">Checkstyle web site</jump>, place checkstyle-all-*.jar in the lib directory and call "build checkstyle". Output (in the build directory) includes checkstyle_report.txt and checkstyle_report.xml. If you copy the file contrib/checkstyle-noframes.xsl from Checkstyle into FOP's root directory, you will also get an HTML report.</p>
+<p>Checkstyle is probably most useful when integrated into your IDE. See the Checkstyle web site for more information about IDE plugins.</p>
+<h2 id="java-best-practices">Java Best Practices</h2>
+<p>The following general principles are a distillation of best practice expectations on the FOP project.</p>
+<ul>
+<li>
+<p>Apply common sense when coding. When coding keep in mind that others will read your code and have to understand it.</p>
+</li>
+<li>
+<p>Readability comes before performance, at least initially.</p>
+</li>
+<li>
+<p>If you can refactor some code to make it more understandable, please do so.</p>
+</li>
+<li>
+<p>Properly document code, especially where it's important.</p>
+</li>
+<li>
+<p>Use interfaces instead of implementations where possible. This favors a clearer design and makes switching between implementations easier (Examples: List instead of ArrayList/Vector, Map instead of HashMap/Hashtable).</p>
+</li>
+<li>
+<p>Avoid using exceptions for flow control.</p>
+</li>
+<li>
+<p>Try to catch exceptions as much as possible and rethrow higher level exceptions (meaning hiding the low level detailed and putting a message that is more related to the function of your code).</p>
+</li>
+<li>
+<p>It is important not to lose the stack trace which contains important information. Use chained exception for that. Avalon Framework provides<jump href="http://jakarta.apache.org/avalon/api/org/apache/avalon/framework/CascadingException.htm">CascadingException</jump>(and similar) for this. Exception class names and stack traces must be treated like gold. Do whatever is required so that this information is not lost. Printing error messages to System.err or System.out is useless in a server-side environment where this info is usually lost.</p>
+</li>
+<li>
+<p>Always log the exception at the higher level (i.e. where it is handled and not rethrown).</p>
+</li>
+<li>
+<p>Try to avoid catching Throwable or Exception and catch specific exceptions instead.</p>
+</li>
+</ul>
+<h2 id="java-resources">Resources</h2>
+<ul>
+<li>
+<p>[book on code style] Code Complete by Steve McConnell.</p>
+</li>
+<li>
+<p>[code formatting software]<jump href="http://jrefactory.sourceforge.net">JRefactory</jump>.</p>
+</li>
+</ul>
+<h2 id="java-links">Related Links</h2>
+<ul>
+<li>
+<p><jump href="http://xmlgraphics.apache.org/repo.html">Apache XML Graphics Code Repositories</jump></p>
+</li>
+<li>
+<p><jump href="http://jakarta.apache.org/site/faqs.html#Coding%20Conventions%20and%20Standards">Jakarta Code Conventions and Standards</jump>(see Coding Conventions and Standards section)</p>
+</li>
+</ul>
+<h1 id="xml">XML</h1>
+<table>
+<thead>
+<tr>
+<th>Convention</th>
+<th>Rationale</th>
+<th>Enforced By</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>XML files must always be well-formed. Validation is optional.</td>
+<td>Document integrity</td>
+<td>Not enforced</td>
+</tr>
+<tr>
+<td>No tabs in content.</td>
+<td>Users should not have to adjust tab settings in their editor to be able to read the content.</td>
+<td>Not enforced</td>
+</tr>
+<tr>
+<td>Indentation of 2 spaces per level</td>
+<td>Maximize readability</td>
+<td>Not enforced</td>
+</tr>
+</tbody>
+</table></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/fop/dev/design/areas.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/dev/design/areas.html (added)
+++ websites/staging/xmlgraphics/trunk/content/fop/dev/design/areas.html Sun Apr 15 05:39:50 2012
@@ -0,0 +1,145 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Apache⢠FOP Design: Area Tree</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Apache⢠FOP Design: Area Tree</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/dev/">Dev</a> » <a href="/fop/dev/design/">Design</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p><version>$Revision: 1298724 $</version><authors><person email="keiron@aftexsw.com" name="Keiron Liddle"></person></authors></p>
+<h1 id="intro">Introduction</h1>
+<p>The Area Tree is an internal representation of the result document, representing pages and their contents. To make the concepts clearer and easier to understand, the code to implement the area tree matches the areas defined in the XSL-FO specification.</p>
+<p>The area tree is created by the layout managers once the layout is decided for a page. Once a completed page is finished it can then be added to the area tree. From that point forward, the area tree model can then handle the new page. The data in the area tree must be minimal and independant. This means that the data uses less memory and can be serialized to an output stream if needed.</p>
+<p>The Area Tree consists of a set of pages, which the actual implemenation places in a set of page sequences.</p>
+<h1 id="structure">Structure</h1>
+<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 the area tree model handle each page as it is added.</p>
+<h1 id="page">Page</h1>
+<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>
+<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.</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.</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 adding the areas for the body region then the other regions can be done layed out and added.</p>
+<h1 id="block">Block Areas</h1>
+<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>
+<p>Block areas are created and/or returned by all top level elements in the flow. The spacing between block areas is handled by an empty block area. A block area is stacked with other block areas in a particular direction, it has a size and it contains line areas made from a group of inline areas and/or block areas.</p>
+<h1 id="line-area">Line Areas</h1>
+<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 a start position. The line area is rendered by handling each inline area.</p>
+<p>A line area gets a set of inline areas added until complete then it is justified and vertically alignedi when adding the areas. If the line area contains unresolved areas then there will be a line resolver that retains the justification information until all areas in the line are resolved.</p>
+<h1 id="inline">Inline Areas</h1>
+<p>There are a few different types of inline areas. All inline areas have a height and width.</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.</p>
+<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>
+<h1 id="repeated-area">Repeated Areas</h1>
+<p>There are cases where the same subtree could be repeated in the area tree. These areas will be returned by the same layout managers. So it is possible to put a flag on the created areas so that the subtree data can be cached in the output. Examples of this are: static areas, table header/footer, svg.</p>
+<h1 id="traits">Traits</h1>
+<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>
+<h1 id="classes">Classes</h1>
+<p>The following class structure will be used to represent the area tree.</p>
+<h2 id="classes-page">Page Area Classes</h2>
+<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.</p>
+<h2 id="classes-block">Block Area Classes</h2>
+<p>The block areas hold other block areas and/or line areas. The child areas are stacked in a particular direction.</p>
+<p>Areas for tables, lists and block container have their child block areas stacked in different ways. These areas a placed with an absolute positioning. The absolute positioning is where the blocks are placed with an offset from the parent reference area.</p>
+<h2 id="classes-inline">Inline Area Classes</h2>
+<p>The inline areas are used to make up a line area. An inline area typically has a height, width and some content. The inline area is offset from the baseline of the current line area. The content of the inline area can be other inline areas or a simple atomic object.</p>
+<h1 id="forward-references">Forward References</h1>
+<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>
+<h1 id="caching">Caching</h1>
+<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>
+<h1 id="extensions">Extensions</h1>
+<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>
+<h1 id="handlers">Area Tree Handlers</h1>
+<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>
+<h1 id="status">Status</h1>
+<h2 id="status-todo">To Do</h2>
+<h2 id="status-wip">Work in Progress</h2>
+<h2 id="status-complete">Completed</h2>
+<ul>
+<li>
+<p>new area tree model</p>
+</li>
+<li>
+<p>changed area tree xml format to match the area tree hierarchy</p>
+</li>
+</ul></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/fop/dev/design/breakpos.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/dev/design/breakpos.html (added)
+++ websites/staging/xmlgraphics/trunk/content/fop/dev/design/breakpos.html Sun Apr 15 05:39:50 2012
@@ -0,0 +1,114 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Apache⢠FOP Design: Layout Managers</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Apache⢠FOP Design: Layout Managers</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/dev/">Dev</a> » <a href="/fop/dev/design/">Design</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p><subtitle>Break Possibility Proposal</subtitle><version>$Revision: 1298724 $</version><authors><person email="klease@club-internet.fr" name="Karen Lease"></person></authors></p>
+<h1 id="intro">Introduction</h1>
+<p>As explained in <a href="layout.html">Layout</a> , the hierarchy of Layout Managers is responsible for building and placing areas. Each Layout Manager is responsible for creating and filling areas of a particular type, either inline or block. This document explains one potential algorithm for this process. It is based on the the generation of <em>break possibilities</em> (BP for short). The Layout Managers (LM for short), will generate one or more BP and choose the best one. The BP is then used to generate the corresponding areas.</p>
+<h1 id="anatomy-of-a-break-possibility-anatomyofabreakpossibility">Anatomy of a Break Possibility # {#Anatomy+of+a+Break+Possibility}</h1>
+<p>A break possibility is represented by the BreakPoss class. A BreakPoss contains size information in the stacking direction and in the non-stacking direction (at least for inline areas, it must have both). Flags indicating various conditions (ISFIRST, ISLAST, CAN_BREAK_AFTER, FORCE_BREAK_AFTER, ANCHORS etc). A BreakPoss contains a reference to the top-level LayoutManager which generated it.</p>
+<p>A BreakPoss contains an object implementing the BreakPoss.Position interface. This object is specific to the layout manager which created the BreakPoss. It should indicate where the break occurs and allow the LM to create an area corresponding to the BP. A higher level LM Position must somehow reference or wrap the Position returned by its child LM in its BreakPoss object. The layout manager modifies the flags and dimension information in the BP to reflect its own requirements. For example an inline FO layout manager might add space-start, space-end, border and padding values to the stacking or non-stacking dimensions. It might also modify the flags based its on keep properties.</p>
+<h1 id="turning-break-possibilities-into-areas-turningbreakpossibilitiesintoareas">Turning Break Possibilities into Areas # {#Turning+Break+Possibilities+into+Areas}</h1>
+<p>Once break possibilities have been generated, the galley-level layout manager selects the best one and passes it back to the LayoutManager which generated it to create the area. A LayoutManager is responsible for storing enough information in its Position objects to be able to create the corresponding areas.</p>
+<h1 id="a-walk-through-awalk-through">A walk-through # {#A+walk-through}</h1>
+<p>Layout Managers are created from the top down. First the page sequence creates a PageLM and a FlowLM. The PageLM will manage finding the right page model (with help from the PageSequenceMaster) and managing the balancing act between before-floats, footnotes and the normal text flow. The FlowLM will manage the normal content in the main flow. We can think of it as a <em>galley</em> manager.</p>
+<p>In general, each LM asks its child LMs to return sucessive break possibilities. It passes some information to the child in a flags object and it gets back a break possibility which contains the size in the stacking direction as well as information about such things as anchors, break conditions and span conditions which can change the reference area environment. This process continues down to the lowest level of the layout manager hierarchy which corresponds to atomic inline-level FOs such as characters or graphics.</p>
+<p>Each layout manager will repeatedly call getNextBreakPoss on its current child LM until the child returns a BP with the ISLAST flag set. Then the layout manager moves on to its next child LM (ie, it asks the next child FO to generate a layout manager.) Galley level layout managers which are Line and Flow will return to their parent layout managers either when they have finished their content or when they encounter a a BP which will fill one of their areas.</p>
+<p>The break possibilities are generated from the bottom up. All inline content must first be broken into lines which are then stacked into block areas. This is done by the LineLayoutManager, which creates line areas. The LineLM asks its child LM to generate a break possibility, which represents a place where the line can end. This initially means each potential line-end (primarily spaces or forced linefeeds and a few other potential line-end characters such as hard hyphens.) The text LM returns an object which stores the size in the stacking direction as a MinOptMax triplet and a <em>cost</em> , which is based on how well this break would satisfy the constraints. The Text LM keeps track of its position in the text content and returns the total size of the text area it would create if it were to break at a given point. The returned BP object also contains information about whether the break is forced (linefeed) or whether this is the last area which can be generated by the L
M (ISLAST flag). If a textFO ends on a non-break character, the ISLAST flag is set, but the CAN_BREAK_AFTER flag isn't, since we don't know if there is any following text in another inline object for example.</p>
+<p>Variable size content is taken into account from the bottom up. Each LM returns a range of sizes in the stacking direction, based on property values. For text, this comes from variable word-space values or letter-space values. For other inline objects, it may include variable space-start and space-end values (after calculation of the entire sequence of space specifiers at a particular break possibility.)</p>
+<p>The main constraint for laying out lines is the available inline-progression-dimension (IPD) for the line area to be created. This depends on the IPD of the reference area ancestor, on the indents of the containing fo:block, and on any side-floats which may be intruding on this line.
+See below <a href="#getRefIPD">Getting the Reference IPD</a> for discussion of how the reference area IPD is transmitted to the Line LM.
+For now, let's assume that only the LineLM knows about the IPD available to it. Therefore only it can make a decision about which BP is the best one; the lower level inline layout managers can only return potential break points.
+There are certainly optimizations to this model which can be examined later.
+So the Line LM will ask its child LM(s) for break possibilities until it gets back a BP whose stacking dimension <em>could</em> fill the line. This means that the BP.stackdim.max >= LineIPD.min. It can look for further BP, perhaps one whose stackdim.opt is closer to the LineIPD.opt. If it isn't happy with the choice of break possibilities, it can go past the end of the line to the next one, and then try to find a hyphenation point between the last one which fits and the first one which doesn't. If no possibility is found whose min/max values enclose the available IPD, some constraint will be violated (and reported in the log.) The actual strategy is up to the Line LM and should be able to be easily replaced without changing the architecture (Strategy pattern).</p>
+<p>The definition of a good break possibility depends on the properties at the block and inline level which govern things such as wrapping behavior and justification mode. For example, if lines are not to be wrapped, only an explicit linefeed can serve as a BP. If lines are wrapped but not justified then there is no requirement to completely fill the IPD on each line, but a sophisticated layout manager will try to achieve "aesthetic rag".</p>
+<p>Note that no areas have actually been created yet. Once the LineLM has found a potential break point for the inline content, it can calculate the total size of the line area which would be created. The size in the IPD is determined by the Line LM based on the chosen BP. The size of the line area in the the block-progression-dimension depends on the size of the text (or other inline content). These values are set by the inline-level LM in their returned BP (in terms of ascender and descender heights with respect to the baseline). The LineLM adds spacing implied by the current line-stacking strategy and line-height property values. It stores a reference to the chosen inline BP and "wraps" that in its own Position object which it stores in the BP it returns to its parent LM (the block layout manager).</p>
+<p>The block LM now has a potential break position after its first line. It assigns that possibility a cost, based on widow, orphan and keep properties. It can also calculate the total size of the block area it would create, were it to end the area after this line. It does this by adding any padding and border (taking into account conditionality). It also calculates space-before and space-after values, or contributes to building up a sequence of such values. With this information, the block LM creates a new BP (or updates the existing one). It stores a Position object in this BP which wraps the returned BP from its child Line LM. It returns the new BP to its parent and so on, back up to the FlowLM.</p>
+<p>Obviously there is more complicated logic involved when dealing with lists and tables. These cases need to be walked through in detail.</p>
+<p>The FlowLM sees if the returned stacking dimension will still fit in its available block-progression-dimension (BPD). It repeatedly calls getNextBreakPoss on its child LMs until it reaches the maximum BPD for the flow reference area or until there is no more content to lay out. If one child LM is finished, it moves on to the next until the last child LM has returned a BP with the ISLAST flag set. If any child LM returns a BP with a FORCE_BREAK_BEFORE or SPAN flag set, the FlowLM will force layout of any pending break possibilities and return to its parent (the PageLM) in order to handle the break or span condition.</p>
+<p>If the returned BP has any new before-float or footnote anchors in it (ANCHOR flag in the BP), the FlowLM will also return to the PageLM. The PageLM must then try to find space to place the floats, possibly asking the FlowLM for help if the body contains multiple columns.</p>
+<h1 id="some-issues-someissues">Some issues # {#Some+issues}</h1>
+<p>Following are a few remarks on specific issues.</p>
+<h2 id="where-line-layout-managers-are-created-wherelinelayoutmanagersarecreated">Where Line Layout Managers are created ## {#Where+Line+Layout+Managers+are+created}</h2>
+<p>If the first child FO in a block FO is an inline-level FO such as text, the block LM creates an intermediate level LineLM to layout the sequence of inline content into Lines. Note that the whole sequence of inline FOs is managed by a single instance of LineLM. The LineLM becomes the parent to the various inline-level LM created by each individual inline FO. Since an fo:block can have both block and inline content, its LM may create a sequence of intermixed BlockLM and LineLM.</p>
+<h2 id="getRefIPD">Getting the reference IPD</h2>
+<p>When the layout process starts, with the FlowLM asking its first child LM for a break possibility, the IPD isn't known, since we don't know whether the first FO might be spanning, or on which page it might start. (Of course, if all page masters in the sequence have the same region-body IPD and all have only a single column, the IPD will never change and could already be calculated before starting layout.) The FlowLM gets its first child LM and calls its getNextBreakPoss method. That is a child LM for some block-level FO. For now, suppose it's an fo:block. The BlockLM will create its first child LM, which may be another block-level LM in the case of nested blocks or a LineLM as explained above. (Question: do we need a START flag for layout status?)</p>
+<p>We keep calling getNextBreakPoss on lower level layout managers until we get down to the inline level or to a level which cannot have break-before properties, such as a list-item-label. At that point, we assume we are going to have to layout some actual content. But we can't do that yet since we don't know the inline-progression-dimension. So we return a BP object which has 0 size in the stacking dimension, but which has flags set to signal to higher-level layout managers what needs to be done. If it has a break-before property or a span property, it stores these in the BP. If no reference IPD is yet defined, it sets a flag to get that. It then returns to its parent. The parent LM will inspect the BP object returned. In general, it "wraps" it with information about its own needs. If the returned BP is not actually returning any potential areas, the LM can still add information about its own break or span requirements. This return path continues back up to the PageLM. It w
ill then check break and span requirements and create a new page if necessary using the appropriate page-master. At that point, the reference IPD for the main flow is known and is set in the flags object used for the next getNextBreakPoss call to the lower level LM.</p>
+<p>Using this information, the BlockLM parent can now calculate the available IPD for its LineLM child, based on its indents. (If there are any side-floats information about the intrusion must be passed down by the FlowLM to lower level managers.) The LineLM can now generate a series of BreakPoss objects, which it passes back to its parent LM.</p>
+<h2 id="Hyphenation">Hyphenation</h2>
+<p>The LineLM is responsible for initiating hyphenation if it is allowed by the properties and if no satisfactory BP can be found without hyphenating. The hyphenation manager is passed two break possibilities, one whose IPD is less than the desired line area IPD and one whose IPD is greater. These break possibilities might have been generated by different inline-level layout managers (text + a wrapper with a color change for example), though frequently they represent two positions in a single text run. If hyphenation is successful, a new BP is returned. The LineLM may look for several intermediate BP based on the "cost" of the returned possibilities. If no intermediate BP is found, the line will be "short", the white-space stretch will be exceeded, or perhaps the content will be overflowed or clipped, depending on various property settings.</p>
+<h2 id="Optimizing">Optimizing</h2>
+<p>It obviously seems inefficient to go down to the lowest level LM and back up to the FlowLM for every possible line-break decision. It seems like it would be possible to optimize by letting the lower level layout managers run until they had exceeded the current limit in the stacking direction. They would then return control to the "galley" level (LineLM or FlowLM) which would fine-tune the break decision by asking the lower level LM to find a previous BP which would fit. At the inline level, this means hyphenation as described above.</p>
+<p>Another interesting question is at what point pending break possibilities can be turned into areas.The idea is to wait until we are sure we won't have to redo the breaking. This depends on the sophistication of the layout strategy. For example, if a linebreak can be considered final if the line is full and there are no anchors on the line, we could create the LineArea at that point. But if we are willing to change a previous line-end decision to get a better overall composition of a whole group of lines (to prevent multiple hyphens for example), we might wait until the LineLM had finished laying out all its material and then make all the Lines at once.</p></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/fop/dev/design/embedding.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/dev/design/embedding.html (added)
+++ websites/staging/xmlgraphics/trunk/content/fop/dev/design/embedding.html Sun Apr 15 05:39:50 2012
@@ -0,0 +1,176 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Apache⢠FOP Design: Embedding Apache� FOP in Other Applications</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Apache⢠FOP Design: Embedding Apache� FOP in Other Applications</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/dev/">Dev</a> » <a href="/fop/dev/design/">Design</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p><version>$Revision: 1298724 $</version><authors><person email="keiron@aftexsw.com" name="Keiron Liddle"></person></authors></p>
+<h1 id="intro">Introduction</h1>
+<p>This is the design for the external interface when Apache⢠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>
+<h1 id="Settings">Settings</h1>
+<h2 id="user-agent-useragent">User Agent ## {#User+Agent}</h2>
+<p>Possible meanings for a user agent:</p>
+<ul>
+<li>
+<p>something that makes decisions where the specifiction indicates that the user agent should decide</p>
+</li>
+<li>
+<p>FOP as the user agent, represented by a class that handles various setup and decision values</p>
+</li>
+<li>
+<p>an class that handles context for a particular FOP conversion that can be configured/overridden when embedding</p>
+</li>
+</ul>
+<p>The user agent is responsible for supplying user or context specific information. The list of user agent values can be found on the<jump href="useragent.html">User Agent</jump>page.</p>
+<h2 id="Logging">Logging</h2>
+<ul>
+<li>
+<p>logging level</p>
+</li>
+<li>
+<p>logging messages of various levels</p>
+</li>
+<li>
+<p>error handling</p>
+</li>
+<li>
+<p>Logging setup (LogKit, Log4J, JDK14Logging)</p>
+</li>
+</ul>
+<h2 id="xml-input-xmlinput">XML input ## {#XML+input}</h2>
+<ul>
+<li>
+<p>various ways to supply FOP with the xsl:fo file, fo, xml+xsl</p>
+</li>
+<li>
+<p>sax handler</p>
+</li>
+</ul>
+<h2 id="general-options-generaloptions">general options ## {#general+options}</h2>
+<ul>
+<li>
+<p>base url</p>
+</li>
+<li>
+<p>uri resolvers</p>
+</li>
+<li>
+<p>which implementation of a particular LayoutManager to use</p>
+</li>
+</ul>
+<h2 id="rendering-options-renderingoptions">Rendering Options ## {#Rendering+Options}</h2>
+<ul>
+<li>
+<p>embedding fonts</p>
+</li>
+<li>
+<p>compression in pdf</p>
+</li>
+<li>
+<p>image embedding</p>
+</li>
+</ul>
+<p>for the PS renderer (eventually):</p>
+<ul>
+<li>
+<p>PostScript Level</p>
+</li>
+<li>
+<p>PPD to use</p>
+</li>
+<li>
+<p>binary/ascii switch</p>
+</li>
+</ul>
+<h2 id="render-results-renderresults">Render Results ## {#Render+Results}</h2>
+<p>Generate Output statistics from FOP:</p>
+<ul>
+<li>
+<p>Number of pages total</p>
+</li>
+<li>
+<p>Number of pages of each page-sequence</p>
+</li>
+<li>
+<p>page-master used for each page (could be used to control the paper bin to get paper from, important for me in conjunction with PS Renderer)</p>
+</li>
+<li>
+<p>recoverable errors such as overflow</p>
+</li>
+</ul>
+<h2 id="setting-up-settingup">Setting Up ## {#Setting+Up}</h2>
+<p>The Driver handles the XML input. The user agent information is through the FOUserAgent. Handle logging through the user agent. Options could also be handled through the user agent, using mime type selection for renderer options.</p>
+<h2 id="Others">Others</h2>
+<p>Render to more than one renderer at once (maybe not from the command line). For example you could generate a PDF for the archive and the PS for the printer in one run. It would probably be faster than converting the PDF to PostScript afterwards. Make the fo tree reuseable. If the fonts are the same then use the same area tree to output to different renderers.</p>
+<p>Several code pieces for resolving URLs and/or file locations are scattered all over FOP and Batik. These should be replaced with an URIResolver invocation to unify behaviour and remove redundancies.</p></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/fop/dev/design/extending.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/dev/design/extending.html (added)
+++ websites/staging/xmlgraphics/trunk/content/fop/dev/design/extending.html Sun Apr 15 05:39:50 2012
@@ -0,0 +1,131 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Apache⢠FOP Design: Extensions</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Apache⢠FOP Design: Extensions</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/dev/">Dev</a> » <a href="/fop/dev/design/">Design</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p><version>$Revision: 1298724 $</version><authors><person email="keiron@aftexsw.com" name="Keiron Liddle"></person></authors></p>
+<h1 id="intro">Introduction</h1>
+<p>Apache⢠FOP provides an extension mechanism to add extra functionality. There are a number of different types of extensions that apply to different steps when converting FO into the rendered output.</p>
+<h1 id="Extensions">Extensions</h1>
+<p>SVG Graphic - This applies to svg and any other xml document that can be converted into svg in the output. All that is required is the element mapping for the xml and a converter that changes the document into svg. This conversion is done in the FO Tree. The conversion is done by the top level element of the namespace or in the case of an external image a Converter.</p>
+<p>XML Document - Instead of converting the document into svg it can be passed directly to the renderer. The renderer will need to have a handler for the xml document. This handler can add information directly to the output document.</p>
+<p>Output Document - This is used to add document level information to the output result. Such an extension will set information that is passed to the output document. The area tree handles these extensions and passs along the information to the renderer. The extension may contain resolveable objects. The extension can be passed to the renderer once resolve either immediately, after the next page or at the end of the document. This is so that the extension can be handled according to other associated data.</p>
+<p>FO Area - This is where an extension creates an normal or extended area in the Area Tree. This is useful when the normal FO objects cannot create the area in the way that is needed.</p>
+<p>Resolveable - In some cases it may require information to be resolved for information such as page numbers. This can apply to the XML Document, FO Area or output document extensions.</p>
+<ul>
+<li>
+<p>Add a string ['(Continued)'] to a table header if the table spans multiple pages. These tables are part of the content and can start anywhere in the page.</p>
+</li>
+<li>
+<p>Separate page number display for a subsection. ie. - master document is page 4 of 7, but subsection is page 2 of 3.</p>
+</li>
+</ul>
+<h1 id="Examples">Examples</h1>
+<p>Plan - The plan extension is a simple SVG graphic extension. Given a plan document either inside an InstreamForeignObject or as an external graphic, it converts the plan document into an svg graphic. The svg graphic is then passed through the Area Tree to the Renderer. The Renderer then renders the svg graphic as normal.</p>
+<p>PDF Outline - This is output document extension. If rendering to pdf and this extensionis used then the bookmark information is passed to the pdf document. This information is then set on the document.</p>
+<p>PDF Additions - This can be done with an XML Document extension. A simple xml document is defined that provides the appropriate information. When the document is rendered a handler converts the document into PDF markup.</p>
+<p>For example:
+<my:script-link script="app.execMenuItem('AcroSrch:Query');">
+Search
+</my:script-link>
+to result in a text box referencing the following PDF action:
+<<
+/S /JavaScript
+/JS (app.execMenuItem("AcroSrch:Query");)</p>
+<blockquote>
+<blockquote></blockquote>
+</blockquote>
+<h1 id="status">Status</h1>
+<h2 id="status-todo">To Do</h2>
+<h2 id="status-wip">Work In Progress</h2>
+<ul>
+<li>
+<p>mathml extension</p>
+</li>
+<li>
+<p>another xml -> svg extension</p>
+</li>
+<li>
+<p>svg text normal text if that can be handled otherwise stroked this is done automatically</p>
+</li>
+</ul>
+<h2 id="status-complete">Completed</h2>
+<ul>
+<li>
+<p>svg now in an xml handler, FOP can be used without batik</p>
+</li>
+<li>
+<p>bookmark extension improved a bit - changed bookmark extension, now requires a wrapping element bookmark</p>
+</li>
+</ul></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/fop/dev/design/fotree.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/dev/design/fotree.html (added)
+++ websites/staging/xmlgraphics/trunk/content/fop/dev/design/fotree.html Sun Apr 15 05:39:50 2012
@@ -0,0 +1,160 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Apache⢠FOP Design: FO Tree</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Apache⢠FOP Design: FO Tree</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/dev/">Dev</a> » <a href="/fop/dev/design/">Design</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p><version>$Revision: 1298724 $</version><authors><person email="keiron@aftexsw.com" name="Keiron Liddle"></person></authors></p>
+<h1 id="intro">Introduction</h1>
+<p>The FO Tree is an internal hierarchical representation (java objects and properties) of the input XSL-FO document, and is created from the <a href="parsing.html">parsing</a> of that XSL-FO document. The process of building the FO Tree corresponds to the <strong>Objectify</strong> step in the XSL-FO spec. The FO Tree is an intermediate structure which will later be <a href="layout.html">converted into the area tree</a> .</p>
+<h1 id="process">Processing</h1>
+<p>The SAX Events that are fired by the parsing process are caught by the FO Tree system. Events for starting an element, ending an element, and text data are assembled by the FO Tree system into a set of objects that represent the input FO document. A class exists for each element in the XSL-FO set, and an object in the appropriate class is created for each element in the input XSL-FO.</p>
+<p>For attributes attached to an XSL-FO element, a property list mapping is used to convert the attribute into properties of the object related to the element.</p>
+<p>To the extent possible, validation is checked as the FO Tree is built. An appropriate error message is returned to the user, and processing continues if possible.</p>
+<p>Elements from <a href="parsing.html#namespaces">foreign namespaces</a> that are recognized by FOP fall into the following categories:</p>
+<ul>
+<li>
+<p>Pass-thru: These are placed into a DOM object, which is then passed through FOP directly to the renderer. SVG is an example.</p>
+</li>
+<li>
+<p>FOP Internal: These are placed into objects that can then be used by FOP. An example of this would be an element that the layout process will use to create an area. Another example would be an element that contains setup information for the renderer.</p>
+</li>
+</ul>
+<p>For unrecognized namespaces, a dummy object or a generic DOM is created.</p>
+<p>While the tree building is mainly about creating the FO Tree, some FO Tree events trigger processes in other parts of FOP. The end of a page-sequence element triggers the layout process for that page-sequence (see discussion of <a href="#recycle">Recycling</a> ). Also, the end of the XML document tells the renderer that it can finalize the output document.</p>
+<h1 id="recycle">Recycling FO Tree Memory</h1>
+<p>To minimize the amount of memory used by FOP, we wish to recycle FO Tree memory as much as possible. There are at least three possible places that FO Tree fragments could be passed to the Layout process, so that their memory can be reused:</p>
+<ul>
+<li>
+<p><strong>fo:block</strong> It might be tempting to start laying out pages as soon as the first fo:block object is finished. However, there are many downstream things that can affect the placement of that block on a page, such as graphics and footnotes. So, in order to maintain conformance to the XSL-FO specification, and create high-quality output, we must see more of the document.</p>
+</li>
+<li>
+<p><strong>fo:root</strong> The other extreme is to wait until the entire document is read in before processing any of it. This essentially means that there is no memory recycling. Processing the document correctly is more important than saving memory, so this option would be used if there were no better alternative.</p>
+</li>
+<li>
+<p><strong>fo:page-sequence</strong> The page-sequence object provides a nice clean break in the document. Content from one page-sequence will never interfere with nor affect the placement of the content of another. FOP uses this option as the optimum way to maintain compliance with the standard and to minimize memory consumption.</p>
+</li>
+</ul>
+<h1 id="serialize">FO Tree Serialization</h1>
+<p>This issue is implied by the requirement to process documents of arbitrary size. Unless some arbitrary limit is placed on the size of page-sequence objects, FOP must be able to serialize FO tree fragments as necessary.</p>
+<h1 id="specific-elements">Notes About Specific Elements</h1>
+<h2 id="page-master">page-master</h2>
+<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. The root element keeps these objects 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.</p>
+<h2 id="flow">flow</h2>
+<p>The elements within the flow of a page-sequence are those that are needed for the layout process. These element will later be used to create areas in the layout process.</p>
+<h2 id="other-elements">Other Elements</h2>
+<p>The remaining FO Objects are things like page-sequence, title and color-profile. Each is handled by its parent element. The root handles declarations, and declarations maintains a list of colour profiles. The page-sequences are direct descendants of root.</p>
+<h1 id="implement">Implementation Notes</h1>
+<h2 id="fonode">FONode</h2>
+<p>The base class for all objects in the tree is FONode. The base class for all FO Objects is FObj (which is a subclass of FONode). Other FONode subclasses are for foreign and unknown XML.</p>
+<p>Each FO in FOP has a parent (except root) and a Vector of children. Java inheritance (superclasses and subclasses) is used to enforce constraints required by the FO hierarchy.</p>
+<p>FONode, among other things, ensures that each FO has a parent, and provides the mechanism for keeping track of its children.</p>
+<p>Each xml element is represented by a java object. The classes for these objects are grouped into packages for convenience:</p>
+<ul>
+<li>
+<p>pagination: <code>org.apache.fop.fo.pagination.*</code> </p>
+</li>
+<li>
+<p>flow: <code>org.apache.fop.fo.flow.*</code> </p>
+</li>
+<li>
+<p>other: <code>org.apache.fop.fo.*.</code> </p>
+</li>
+</ul>
+<h2 id="create-fo">Creating FO Objects</h2>
+<p>The process of creating an FO Object is as follows (see <code>FOTreeBuilder.startElement()</code> for details):</p>
+<ul>
+<li>
+<p>An FO maker is selected from a hashmap lookup using the namespace and element name.</p>
+</li>
+<li>
+<p>This maker is then used to create the new object that represents the FO element.</p>
+</li>
+<li>
+<p>The new object is given its element name, an FOUserAgent (for resolving properties, etc.), a logger and its attributes.</p>
+</li>
+<li>
+<p>The new object is added to the FO tree as a child of the current parent.</p>
+</li>
+<li>
+<p>Child elements are then processed. This is an iterative process: the child elements go through the same process here documented for their parent.</p>
+</li>
+</ul>
+<h2 id="foreign">Foreign XML</h2>
+<p>For SVG, the DOM needs to be created with Batik, so an element mapping is used to read all elements in the SVG namespace and pass them into the Batik DOM.</p>
+<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 renderer as a DOM, which is expected to know how to handle it. XML from an unknown namespace will be ignored.</p>
+<p>See <a href="parsing.html#namespaces">Input Parsing Namespaces</a> for more discussion and links to information about using foreign XML in FOP.</p>
+<h2 id="unknown">Unknown Elements</h2>
+<p>If an element is in a known namespace but the element is unknown within that namespace, then an Unknown object is created. This generally indicates an input error: perhaps an element from an older version of the XSL-FO standard, or a misspelling. The Unknown object is mainly used to provide information to the user.</p></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/fop/dev/design/images.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/dev/design/images.html (added)
+++ websites/staging/xmlgraphics/trunk/content/fop/dev/design/images.html Sun Apr 15 05:39:50 2012
@@ -0,0 +1,123 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Apache⢠FOP Design: Images</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Apache⢠FOP Design: Images</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/dev/">Dev</a> » <a href="/fop/dev/design/">Design</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p><version>$Revision: 1298724 $</version></p>
+<h1 id="intro">Introduction</h1>
+<p>Images may only be needed to be loaded when the image is rendered to the output or to find the dimensions.<br></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>
+<h1 id="Threading">Threading</h1>
+<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>
+<h1 id="Caches">Caches</h1>
+<h2 id="LRU">LRU</h2>
+<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>
+<h2 id="Context">Context</h2>
+<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>
+<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>
+<h1 id="invalid-images-invalidimages">Invalid Images # {#Invalid+Images}</h1>
+<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></br>This will prevent any extra processing or waiting.</p>
+<h1 id="Reading">Reading</h1>
+<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>
+<h1 id="Data">Data</h1>
+<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>
+<h1 id="Rendering">Rendering</h1>
+<p>Different renderers need to have the information in different forms.</p>
+<h2 id="PDF">PDF</h2>
+<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>
+<h2 id="PS">PS</h2>
+<dl>
+<dt>bitmap</dt>
+<dd>JPG, gif, tiff, bmp, png</dd>
+<dt>other</dt>
+<dd>SVG</dd>
+</dl>
+<h2 id="awt">awt</h2>
+<dl>
+<dt>bitmap</dt>
+<dd>JPG, gif, tiff, bmp, png</dd>
+<dt>other</dt>
+<dd>SVG
+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.</dd>
+</dl></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/xmlgraphics/trunk/content/fop/dev/design/index.html
==============================================================================
--- websites/staging/xmlgraphics/trunk/content/fop/dev/design/index.html (added)
+++ websites/staging/xmlgraphics/trunk/content/fop/dev/design/index.html Sun Apr 15 05:39:50 2012
@@ -0,0 +1,203 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+ <head>
+ <title>Apache⢠FOP Design: Introduction</title>
+
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <meta property="og:image" content="http://www.apache.org/images/asf_logo.gif" />
+<!--
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/style.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+-->
+ <link href="/css/xmlgraphics.css" rel="stylesheet" type="text/css">
+
+ </style>
+
+
+
+
+
+ </head>
+
+ <body>
+ <div id="banner">
+ </div>
+
+ <div id="navigation">
+ <h1 id="xml-graphics">XML Graphics</h1>
+<ul>
+<li><a href="/">Overview</a></li>
+<li><a href="/team.html">Who We Are</a></li>
+<li><a href="/legal.html">Legal Stuff</a></li>
+<li><a href="/charter.html">Project Charter</a></li>
+<li><a href="/mail.html">Mailing Lists</a></li>
+<li><a href="/repo.html">Code Repositories</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a></li>
+</ul>
+<h1 id="subprojects">Subprojects</h1>
+<ul>
+<li><a href="/batik/">Batik</a></li>
+<li><a href="/fop/">FOP</a></li>
+<li><a href="/commons/">Commons</a></li>
+</ul>
+<form name="search" id="search" action="http://www.google.com/search" method="get">
+ <input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"/>
+ <input type="text" name="q" id="query" /><br />
+ <input type="submit" id="submit" value="Search" />
+</form>
+ </div>
+
+ <div id="bannertext">
+ <a href="/"><img src="/images/apache-xml-graphics.gif" alt="The Apache XML Graphics Project" width="220" heigh="51" /></a>
+ <h1>Apache⢠FOP Design: Introduction</h1>
+ </div>
+ <p><a href="/">Home</a> » <a href="/fop/">Fop</a> » <a href="/fop/dev/">Dev</a> » <a href="/fop/dev/design/">Design</a></p>
+ </div>
+ <div id="content" class="grid_16"><div class="section-content"><p><version>$Revision: 1298724 $</version><authors><person email="keiron@aftexsw.com" name="Keiron Liddle"></person></authors>
+The articles in this section pertain mainly to the <em>redesign</em> or <em>trunk</em> line of development. The redesign is mainly focusing on parts of the layout process (converting the FO tree into the Area Tree). Therefore other (non-layout) sections in this document are probably largely accurate for the maintenance branch, but should be used with care in that context.</p>
+<h1 id="black-box">The Black Box View</h1>
+<p>From a user's standpoint, Apache⢠FOP is a black box that an xml file as input, performs some magic, then creates the desired output:</p>
+<table>
+<thead>
+<tr>
+<th><caption>Apache� FOP from a User's Standpoint</caption></th>
+<th>Process</th>
+<th>Result</th>
+<th></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td></td>
+<td>.</td>
+<td>XSL-FO document</td>
+<td></td>
+</tr>
+<tr>
+<td></td>
+<td>FOP</td>
+<td>Output: PDF, Postscript, Print, etc.</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<p>Although this is simple, it is useful in defining the outer limits of FOP's core processing. There may be other things going on under FOP's control that are not really part of FOP. For example, FOP provides a convenience mechanism that takes semantic XML + an XSLT transformation as input, instead of XSL-FO. This is done outside of FOP's core processing (by Xalan), and it is therefore outside the scope of FOP's design, and outside the scope of the FOP design documents.</p>
+<h1 id="primary-goals">Primary Design Goals</h1>
+<p>A discussion of project design properly begins with a list of the goals of the project. Out of these goals will flow the design issues and details, and eventually, the implementation.</p>
+<h2 id="pri-goal-conformance">Conformance to the XSL-FO Specification</h2>
+<p>The current design goal is to reach the "basic" level of conformance, and to have enough flexibility in the design to reach "complete" conformance without major rewriting. After "basic" conformance is achieved, it is probable that higher levels of conformance will be sought.</p>
+<h2 id="pri-goal-unlimited-size">Process Files of Arbitrary Size</h2>
+<p>Except for user storage limitations, the design goal is to be able to process files of any size. In a separate but related issue, the design goal is to be able to process page-sequence elements of any size. (See <a href="fotree.html#recycle">Recycling FO Tree Memory</a> for a discussion of the use of page-sequence as a logical subdivided "chunk" on an FO document).</p>
+<h1 id="secondary-goals">Secondary Design Goals</h1>
+<h2 id="sec-goal-memory">Minimize Memory Use</h2>
+<p>Many FOP design decisions revolve around trying to minimize the use of memory. The primary purpose here is to reduce the amount of data that must be serialized to storage during processing. Since our primary design goals include the ability to process files of arbitrary size, there is no way to avoid the need to serialize. However, many FOP users provide web access to documents that are created in real time. Performance is therefore an important issue in these real-world applications. To the extent that it can be done so without jeopardizing the primary design goals, FOP developers have identified keeping a small memory footprint as being an important secondary goal.</p>
+<h1 id="big-picture">The Big Picture View</h1>
+<p>With our design goals outlined, we'll now open the Black Box and look at the major processes inside. FOP has adopted the basic structure of the XSL-FO standard itself as a convenient model for the major processes in FOP. The Result in each row is the input for the next.</p>
+<table>
+<thead>
+<tr>
+<th><caption>FOP's Big Picture Design</caption></th>
+<th>Process</th>
+<th>Process Result/Input for Next</th>
+<th>Notes</th>
+<th></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td></td>
+<td>.</td>
+<td>XSL-FO document</td>
+<td>.</td>
+<td></td>
+</tr>
+<tr>
+<td></td>
+<td><a href="parsing.html">Parsing</a></td>
+<td><a href="fotree.html">FO Tree</a></td>
+<td>.</td>
+<td></td>
+</tr>
+<tr>
+<td></td>
+<td><a href="properties.html#refine">Refinement</a></td>
+<td><a href="properties.html#refined-fo-tree">Refined FO Tree</a></td>
+<td>.</td>
+<td></td>
+</tr>
+<tr>
+<td></td>
+<td><a href="layout.html">Layout</a></td>
+<td><a href="areas.html">Area Tree</a></td>
+<td>Layout and Area Tree are not needed or used for the structural outputs (MIF and RTF), as they are not paginated.</td>
+<td></td>
+</tr>
+<tr>
+<td></td>
+<td><a href="renderers.html">Renderer</a></td>
+<td>Output: PDF, Postscript, Print, etc.</td>
+<td>.</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<p>In general, each piece of data will be processed in the same way. However, some information may be used more than once, and some may be used out of order. To reduce memory, one process may start before the previous process is completed.</p>
+<p>For a detailed discussion of the design of any component, follow its link in the table above. Each component outlines the design issues which have already been addressed. These resolution of these design issues is in support of the primary and secondary goals, so they are not necessarily written in stone. However, most of them have been discussed at length among the developers, and are reasonably well settled.</p>
+<h1 id="vocabulary">Vocabulary</h1>
+<p>This section will attempt to provide information about any jargon used in the design documentation.</p>
+<p>There is a rough relationship between terms used to describe the various trees in XSL-FO processing, all of which come from the XML and XSL-FO standards. In the table below, the <em>terms</em> (but not the actual items) in each column are roughly equivalent to each other:</p>
+<table>
+<thead>
+<tr>
+<th>Tree Concept</th>
+<th>Thing (Noun)</th>
+<th>Descriptive Item (Adjective)</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>XML</td>
+<td>Element</td>
+<td>Attribute</td>
+</tr>
+<tr>
+<td>FO Tree</td>
+<td>Object</td>
+<td>Property</td>
+</tr>
+<tr>
+<td>Area Tree</td>
+<td>Area</td>
+<td>Trait</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>
+<p><strong>LM</strong> : Layout Manager.</p>
+</li>
+<li>
+<p><strong>PLB</strong> : PropertyListBuilder.</p>
+</li>
+</ul></div></div>
+ <div class="clear"></div>
+
+ <div id="footer">
+ <a alt="Apache Software Foundation" href="http://www.apache.org">
+ <img id="asf-logo" alt="Apache Software Foundation" src="/images/feather-small.gif"/ width="100">
+ </a>
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Apache XML Graphics, the Apache feather logo, and the Apache XML Graphics logos are
+ trademarks of <a href="http://www.apache.org">The Apache Software Foundation</a>. All other
+ marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <br />
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: commits-help@xmlgraphics.apache.org