xmlgraphics-fop-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jerem...@apache.org
Subject svn commit: r369781 - in /xmlgraphics/fop/trunk/src/documentation/content/xdocs: site.xml trunk/intermediate.xml
Date Tue, 17 Jan 2006 14:10:45 GMT
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


Mime
View raw message