|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145 |
- <?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[
- FopFactory fopFactory = FopFactory.newInstance();
-
- // 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 = fopFactory.newFOUserAgent();
-
- //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>
- <p>
- The intermediate format can also be used from the <a href="running.html#standalone-start">command-line</a>
- by using the "-atin" parameter for specifying the area tree XML as input file. You can also
- specify a "mimic renderer" by inserting a MIME type between "-at" and the output file.
- </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>
|