src/documentation/content/xdocs/0.95/intermediate.xml - xmlgraphics-fop - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You 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/2001/REC-xsl-20011015/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>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You 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/2001/REC-xsl-20011015/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>