You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-commits@xmlgraphics.apache.org by je...@apache.org on 2006/01/17 15:10:45 UTC
svn commit: r369781 - in
/xmlgraphics/fop/trunk/src/documentation/content/xdocs: site.xml
trunk/intermediate.xml
Author: jeremias
Date: Tue Jan 17 06:10:39 2006
New Revision: 369781
URL: http://svn.apache.org/viewcvs?rev=369781&view=rev
Log:
Initial documentation for the intermediate format.
Added:
xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/intermediate.xml (with props)
Modified:
xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml
Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml?rev=369781&r1=369780&r2=369781&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml (original)
+++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/site.xml Tue Jan 17 06:10:39 2006
@@ -132,6 +132,7 @@
<features label="Features">
<output label="Output Targets" href="output.html"/>
+ <if label="Intermediate Format" href="intermediate.html"/>
<pdfencryption label="PDF Encryption" href="pdfencryption.html"/>
<graphics label="Graphics" href="graphics.html"/>
<fonts label="Fonts" href="fonts.html"/>
Added: xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/intermediate.xml
URL: http://svn.apache.org/viewcvs/xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/intermediate.xml?rev=369781&view=auto
==============================================================================
--- xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/intermediate.xml (added)
+++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/intermediate.xml Tue Jan 17 06:10:39 2006
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2006 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<!-- $Id$ -->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Intermediate Format</title>
+ <version>$Revision$</version>
+ </header>
+ <body>
+ <note>
+ Please note that the intermediate format is an <strong>advanced feature</strong> and can be ignored by most
+ users of Apache FOP.
+ </note>
+ <section id="introduction">
+ <title>Introduction</title>
+ <p>
+ The intermediate format (IF) is a proprietary XML format that represents the area tree
+ generated by the layout engine. The area tree is conceptually defined in the
+ <a href="http://www.w3.org/TR/xsl/slice1.html#section-N742-Formatting">XSL-FO specification in chapter 1.1.2</a>.
+ The IF can be generated through the area tree XML Renderer (the XMLRenderer).
+ </p>
+ <p>
+ The intermediate format can be used to generate intermediate documents that are modified
+ before they are finally rendered to their ultimate output format. Modifications include
+ adjusting and changing trait values, adding or modifying area objects, inserting prefabricated
+ pages, overlays, imposition (n-up, rotation, scaling etc.). Multiple IF files can be combined
+ to a single output file.
+ </p>
+ </section>
+ <section id="usage">
+ <title>Usage of the Intermediate Format</title>
+ <p>
+ As already mentioned, the IF is generated by using the <strong>XMLRenderer</strong> (MIME type:
+ <strong>application/X-fop-areatree</strong>). So, you basically set the right MIME type for
+ the output format and process your FO files as if you would create a PDF file. However, there
+ is an important detail to consider: The various Renderers don't all use the same font sources.
+ To be able to create the right area tree for the ultimate output file, you need to create
+ the IF file using the right font setup. This is achieved by telling the XMLRenderer to mimic
+ another renderer. This is done by calling the XMLRenderer's mimicRenderer() method with an
+ instance of the ultimate target renderer as the single parameter. This has a consequence: An
+ IF file rendered with the Java2DRenderer may not look as expected when it was actually generated
+ for the PDF renderer. For renderers that use the same font setup, this restriction does not
+ apply (PDF and PS, for example). Generating the intermediate format file is the first step.
+ </p>
+ <p>
+ The second step is to reparse the IF file using the <strong>AreaTreeParser</strong> which is
+ found in the org.apache.fop.area package. The pages retrieved from the IF file are added to an
+ AreaTreeModel instance from where they are normally rendered using one of the available Renderer
+ implementations. You can find examples for the IF processing in the
+ <a href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/examples/embedding/java/embedding/intermediate/"><code>examples/embedding</code></a>
+ directory in the FOP distribution
+ </p>
+ <p>
+ The basic pattern to parse the IF format looks like this:
+ </p>
+ <source><![CDATA[
+// Setup output
+OutputStream out = new java.io.FileOutputStream(pdffile);
+out = new java.io.BufferedOutputStream(out);
+try {
+ //Setup fonts and user agent
+ FontInfo fontInfo = new FontInfo();
+ FOUserAgent userAgent = new FOUserAgent();
+
+ //Construct the AreaTreeModel that will received the individual pages
+ AreaTreeModel treeModel = new RenderPagesModel(userAgent,
+ MimeConstants.MIME_PDF, fontInfo, out);
+
+ //Parse the IF file into the area tree
+ AreaTreeParser parser = new AreaTreeParser();
+ Source src = new StreamSource(myIFFile);
+ parser.parse(src, treeModel, userAgent);
+
+ //Signal the end of the processing. The renderer can finalize the target document.
+ treeModel.endDocument();
+} finally {
+ out.close();
+}]]></source>
+ <p>
+ This example simply reads an IF file and renders it to a PDF file. Please note, that in normal
+ FOP operation you're shielded from having to instantiate the FontInfo object yourself. This
+ is normally a task of the AreaTreeHandler which is not present in this scenario. The same
+ applies to the AreaTreeModel instance, in this case an instance of a subclass called
+ RenderPagesModel. RenderPagesModel is ideal in this case as it has very little overhead
+ processing the individual pages. An important line in the example is the call to
+ <code>endDocument()</code> on the AreaTreeModel. This lets the Renderer know that the processing
+ is now finished.
+ </p>
+ <section id="concat">
+ <title>Concatenating Documents</title>
+ <p>
+ This initial example is obviously not very useful. It would be faster to create the PDF file
+ directly. As the <a href="http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/examples/embedding/java/embedding/intermediate/ExampleConcat.java">ExampleConcat.java</a>
+ example shows you can easily parse multiple IF files in a row and add the parsed pages to the
+ same AreaTreeModel instance which essentially concatenates all the input document to one single
+ output document.
+ </p>
+ </section>
+ <section id="modifying">
+ <title>Modifying Documents</title>
+ <p>
+ One of the most important use cases for the intermediate format is obviously modifying the area
+ tree XML before finally rendering it to the target format. You can easily use XSLT to process
+ the IF file according to your needs. Please note, that we will currently not formally describe
+ the intermediate format. You need to have a good understanding its structure so you don't
+ create any non-parseable files. We may add an XML Schema and more detailed documentation at a
+ later time. You're invited to help us with that.
+ </p>
+ </section>
+ <section id="advanced">
+ <title>Advanced Use</title>
+ <p>
+ The generation of the intermediate format as well as it parsing process has been designed to allow
+ for maximum flexibility and optimization. Please note that you can call <code>setTransformerHandler()</code> on
+ XMLRenderer to give the XMLRenderer your own TransformerHandler instance in case you would like to
+ do custom serialization (to a W3C DOM, for example) and/or to directly modify the area tree using
+ XSLT. The AreaTreeParser on the other side allows you to retrieve a ContentHandler instance where
+ you can manually send SAX events to to start the parsing process (see <code>getContentHandler()</code>).
+ </p>
+ </section>
+ </section>
+ </body>
+</document>
Propchange: xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/intermediate.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/intermediate.xml
------------------------------------------------------------------------------
svn:keywords = Id
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org