aboutsummaryrefslogtreecommitdiffstats
path: root/src/documentation/content/xdocs/0.95/configuration.xml
diff options
context:
space:
mode:
Diffstat (limited to 'src/documentation/content/xdocs/0.95/configuration.xml')
-rw-r--r--src/documentation/content/xdocs/0.95/configuration.xml394
1 files changed, 394 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/0.95/configuration.xml b/src/documentation/content/xdocs/0.95/configuration.xml
new file mode 100644
index 000000000..e82a6e862
--- /dev/null
+++ b/src/documentation/content/xdocs/0.95/configuration.xml
@@ -0,0 +1,394 @@
+<?xml version="1.0" standalone="no"?>
+<!--
+ 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>Apache FOP: Configuration</title>
+ <version>$Revision$</version>
+ </header>
+
+ <body>
+ <section id="general">
+ <title>Configuration File Basics</title>
+ <p>
+ The FOP configuration file is an XML file containing a variety of settings that are useful
+ for controlling FOP's behavior, and for helping it find resources that you wish it to use.
+ </p>
+ <p>
+ The easiest way to get started using a FOP configuration file is to copy the sample found
+ at <code>{fop-dir}/conf/fop.xconf</code> to a location of your choice, and then to
+ edit it according to your needs.
+ It contains templates for the various configuration options, most of which are commented
+ out. Remove the comments and change the settings for entries that you wish to use.
+ Be sure to follow any instructions, including comments which specify the value range.
+ Also, since the configuration file is XML, be sure to keep it well-formed.
+ </p>
+ <section id="general-available">
+ <title>Making Configuration Available to FOP</title>
+ <p>After creating your configuration file, you must tell FOP how to find it:</p>
+ <ul>
+ <li>
+ If running FOP from the command-line, see the "-c" command-line option in
+ <a href="running.html">Running FOP</a>.
+ </li>
+ <li>
+ If running FOP as an embedded application, see
+ <a href="embedding.html#config-external">Embedding, Using a Configuration File</a>.
+ </li>
+ </ul>
+ <p>
+ See <a href="embedding.html#config-internal">Setting the Configuration Programmatically</a>
+ for instructions on how to do so in an embedded environment.
+ </p>
+ </section>
+ </section>
+ <section id="general-elements">
+ <title>Summary of the General Configuration Options</title>
+ <table>
+ <tr>
+ <th>Element</th>
+ <th>Data Type (for the value)</th>
+ <th>Description</th>
+ <th>Default Value</th>
+ </tr>
+ <tr>
+ <td>base</td>
+ <td>URL or directory</td>
+ <td>Specifies the base URL based on which relative URL will be resolved.</td>
+ <td>current directory</td>
+ </tr>
+ <tr>
+ <td>font-base</td>
+ <td>URL or directory</td>
+ <td>Specifies the base URL based on which relative font URLs will be resolved.
+ </td>
+ <td>base URL/directory (above)</td>
+ </tr>
+ <tr>
+ <td>hyphenation-base</td>
+ <td>URL or directory</td>
+ <td>Specifies the base URL based on which relative URLs to hyphenation pattern
+ files will be resolved. If not specified, support for user-supplied hyphenation
+ patterns remains disabled.
+ </td>
+ <td>disabled</td>
+ </tr>
+ <tr>
+ <td>source-resolution</td>
+ <td>Integer, dpi</td>
+ <td>
+ Resolution in dpi (dots per inch) which is used internally to determine the pixel
+ size for SVG images and bitmap images without resolution information.
+ </td>
+ <td>72 dpi</td>
+ </tr>
+ <tr>
+ <td>target-resolution</td>
+ <td>Integer, dpi</td>
+ <td>
+ Resolution in dpi (dots per inch) used to specify the output resolution for bitmap
+ images generated by bitmap renderers (such as the TIFF renderer) and by bitmaps
+ generated by Apache Batik for filter effects and such.
+ </td>
+ <td>72 dpi</td>
+ </tr>
+ <tr>
+ <td>strict-configuration</td>
+ <td>Boolean (true, false)</td>
+ <td>
+ Setting this option to 'true' will cause FOP to strictly verify the contents of the
+ FOP configuration file to ensure that defined resources (such as fonts and base
+ URLs/directories) are valid and available to FOP. Any errors found will cause FOP to
+ immediately raise an exception.</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>strict-validation</td>
+ <td>Boolean (true, false)</td>
+ <td>
+ Setting this option to 'false' causes FOP to be more forgiving about XSL-FO validity,
+ for example, you're allowed to specify a border on a region-body which is supported
+ by some FO implementations but is non-standard. Note that such a border would
+ currently have no effect in Apache FOP.</td>
+ <td>true</td>
+ </tr>
+ <tr>
+ <td>break-indent-inheritance</td>
+ <td>Boolean (true, false)</td>
+ <td>
+ Setting this option to 'true' causes FOP to use an alternative rule set to determine
+ text indents specified through margins, start-indent and end-indent. Many commercial
+ FO implementations have chosen to break the XSL specification in this aspect. This
+ option tries to mimic their behaviour. Please note that Apache FOP may still not
+ behave exactly like those implementations either because FOP has not fully matched
+ the desired behaviour and because the behaviour among the commercial implementations
+ varies. The default for this option (i.e. false) is to behave exactly like the
+ specification describes.</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>default-page-settings</td>
+ <td>n/a</td>
+ <td>
+ Specifies the default width and height of a page if "auto" is specified
+ for either or both values. Use "height" and "width" attributes on the
+ default-page-settings element to specify the two values.</td>
+ <td>"height" 11 inches, "width" 8.26 inches</td>
+ </tr>
+ <tr>
+ <td>use-cache</td>
+ <td>boolean (true, false)</td>
+ <td>All fonts information that has been gathered as a result of "directory"
+ or "auto-detect" font configurations will be cached for future rendering runs.
+ This setting should improve performance on systems where
+ fonts have been configured using the "directory" or "auto-detect" tag mechanisms.
+ By default this option is switched on.</td>
+ <td>true</td>
+ </tr>
+ <tr>
+ <td>cache-file</td>
+ <td>String</td>
+ <td>This options specifies the file/directory path of the fop cache file.
+ This option can also be specified on the command-line using the -cache option.
+ This file is currently only used to cache font triplet information for future reference.</td>
+ <td>${base}/conf/fop.cache</td>
+ </tr>
+ <tr>
+ <td>renderers</td>
+ <td>(see text below)</td>
+ <td>Contains the configuration for each renderer. See below.</td>
+ <td>N/A</td>
+ </tr>
+ </table>
+ <p>
+ This is an excerpt from the example configuration file coming with FOP:
+ </p>
+ <source><![CDATA[
+<fop version="1.0">
+
+ <!-- Strict user configuration -->
+ <strict-configuration>true</strict-configuration>
+
+ <!-- Strict FO validation -->
+ <strict-validation>true</strict-validation>
+
+ <!-- Base URL for resolving relative URLs -->
+ <base>./</base>
+
+ <!-- Font Base URL for resolving relative font URLs -->
+ <font-base>./</font-base>
+
+ <!-- Source resolution in dpi (dots/pixels per inch) for determining the size of pixels in SVG and bitmap images, default: 72dpi -->
+ <source-resolution>72</source-resolution>
+ <!-- Target resolution in dpi (dots/pixels per inch) for specifying the target resolution for generated bitmaps, default: 72dpi -->
+ <target-resolution>72</target-resolution>
+
+ <!-- default page-height and page-width, in case
+ value is specified as auto -->
+ <default-page-settings height="11in" width="8.26in"/>
+
+ <!-- etc. etc..... -->
+</fop>]]></source>
+ </section>
+ <section id="renderers">
+ <title>Renderer configuration</title>
+ <p>
+ Each Renderer has its own configuration section which is identified by the
+ MIME type the Renderer is written for, ex. "application/pdf" for the PDF Renderer.
+ </p>
+ <p>
+ The configuration for the PDF Renderer could look like this:
+ </p>
+ <source><![CDATA[
+ <renderers>
+ <renderer mime="application/pdf">
+ <filterList>
+ <!-- provides compression using zlib flate (default is on) -->
+ <value>flate</value>
+ </filterList>
+ <fonts>
+ <font metrics-url="arial.xml" kerning="yes" embed-url="arial.ttf">
+ <font-triplet name="Arial" style="normal" weight="normal"/>
+ <font-triplet name="ArialMT" style="normal" weight="normal"/>
+ </font>
+ <font metrics-url="arialb.xml" kerning="yes" embed-url="arialb.ttf">
+ <font-triplet name="Arial" style="normal" weight="bold"/>
+ <font-triplet name="ArialMT" style="normal" weight="bold"/>
+ </font>
+ </fonts>
+ </renderer>
+
+ <renderer mime="application/postscript">
+ <!-- etc. etc..... -->]]></source>
+ <p>
+ The details on the font configuration can be found on the separate <a href="fonts.html">Fonts</a> page.
+ Note especially the section entitled <a href="fonts.html#register">Register Fonts with FOP</a>.
+ </p>
+ <section id="pdf-renderer">
+ <title>Special Settings for the PDF Renderer</title>
+ <p>
+ The configuration element for the PDF renderer contains two elements. One is for the font configuration
+ (please follow the link above) and one is for the "filter list". The filter list controls how the
+ individual objects in a PDF file are encoded. By default, all objects get "flate" encoded (i.e. simply
+ compressed with the same algorithm that is also used in ZIP files). Most users don't need to change that
+ setting. For debugging purposes, it may be desired not to compress the internal objects at all so the
+ generated PDF commands can be read. In that case, you can simply use the following filter list. The
+ second filter list (type="image") ensures that all images still get compressed but also ASCII-85 encoded
+ so the produced PDF file is still easily readable in a text editor.
+ </p>
+ <source><![CDATA[
+ <renderer mime="application/pdf">
+ <filterList>
+ <value>null</value>
+ </filterList>
+ <filterList type="image">
+ <value>flate</value>
+ <value>ascii-85</value>
+ </filterList>
+
+ <fonts....
+ </renderer>]]></source>
+ <p>
+ Another (optional) setting specific to the PDF Renderer is an output color profile, an ICC
+ color profile which indicates the target color space the PDF file is generated for. This
+ setting is mainly used in conjunction with the <a href="pdfx.html">PDF/X</a> feature.
+ An example:
+ </p>
+ <source><![CDATA[
+ <renderer mime="application/pdf">
+ <filterList...
+
+ <output-profile>C:\FOP\Color\EuropeISOCoatedFOGRA27.icc</output-profile>
+
+ <fonts....
+ </renderer>]]></source>
+ <p>
+ Some people don't have high requirements on color fidelity but instead want the smallest
+ PDF file sizes possible. In this case it's possible to disable the default sRGB color space
+ which XSL-FO requires. This will cause RGB colors to be generated as device-specific RGB.
+ Please note that this option is unavailable (and will cause an error) if you enable
+ PDF/A or PDF/X functionality or if you specify an output profile. This setting will make the
+ PDF about 4KB smaller. To disable the sRGB color space add the following setting:
+ </p>
+ <source><![CDATA[
+ <renderer mime="application/pdf">
+ <filterList...
+
+ <disable-srgb-colorspace>true</disable-srgb-colorspace>
+
+ <fonts....
+ </renderer>]]></source>
+ </section>
+ <section id="ps-renderer">
+ <title>Special Settings for the PostScript Renderer</title>
+ <p>
+ Besides the normal font configuration (the same "fonts" element as for the PDF renderer) the PostScript
+ renderer has an additional setting to force landscape pages to be rotated to fit on a page inserted into
+ the printer in portrait mode. Set the value to "true" to activate this feature. The default is "false".
+ Example:
+ </p>
+ <source><![CDATA[
+ <renderer mime="application/postscript">
+ <auto-rotate-landscape>true</auto-rotate-landscape>
+
+ <fonts>
+ <font metrics-url="arial.xml" kerning="yes" embed-url="arial.ttf">
+ <font-triplet name="Arial" style="normal" weight="normal"/>
+ <font-triplet name="ArialMT" style="normal" weight="normal"/>
+ </font>
+ <font metrics-url="arialb.xml" kerning="yes" embed-url="arialb.ttf">
+ <font-triplet name="Arial" style="normal" weight="bold"/>
+ <font-triplet name="ArialMT" style="normal" weight="bold"/>
+ </font>
+ </fonts>
+ </renderer>]]></source>
+ </section>
+ <section id="pcl-renderer">
+ <title>Special Settings for the PCL Renderer</title>
+ <p>
+ Non-standard fonts for the PCL renderer are made available through the Java2D subsystem which means that
+ you don't have to do any custom font configuration in this case but you have to use the font names
+ offered by Java.
+ </p>
+ <p>
+ Additionally, there are certain settings that control how the renderer handles various elements.
+ </p>
+<source><![CDATA[<renderer mime="application/vnd.hp-PCL">
+ <rendering>quality</rendering>
+ <text-rendering>bitmap</text-rendering>
+</renderer>]]></source>
+ <p>
+ The default value for the "rendering" setting is "speed" which causes borders
+ to be painted as plain rectangles. In this mode, no special borders (dotted,
+ dashed etc.) are available. If you want support for all border modes, set the
+ value to "quality" as indicated above. This will cause the borders to be painted
+ as bitmaps.
+ </p>
+ <p>
+ The default value for the "text-rendering" setting is "auto" which paints the
+ base fonts using PCL fonts. Non-base fonts are painted as bitmaps through Java2D.
+ If the mix of painting methods results in unwelcome output, you can set this
+ to "bitmap" which causes all text to be rendered as bitmaps.
+ </p>
+ </section>
+ </section>
+
+ <section>
+ <title>When it does not work</title>
+
+ <p>FOP searches the configuration file for the information it
+expects, at the position it expects. When that information is not
+present, FOP will not complain, it will just continue. When there is
+other information in the file, FOP will not complain, it will just
+ignore it. That means that when your configuration information is in
+the file but in a different XML element, or in a different XML path,
+than FOP expects, it will be silently ignored.</p>
+
+ <p>Check the following possibilities:</p>
+
+ <ul>
+ <li>The format of the configuration file has changed
+considerably between FOP 0.20.5 and FOP 1.0 and its beta versions. Did
+you convert your file to the new format?</li>
+
+ <li>The FOP distribution contains a schema for configuration
+files, at src/foschema/fop-configuration.xsd. Did you validate your
+configuration file against it? Add the following schema location to
+the <code>schema</code> element:
+
+<source><![CDATA[<fop
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:noNamespaceSchemaLocation=
+"http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/foschema/fop-configuration.xsd?view=co">]]>
+</source>
+
+and run the configuration file through a validating schema
+parser. Note that the schema cannot detect all errors, and that it is
+stricter about the order of some elements than FOP itself is.</li>
+
+ <li>Run FOP in debug mode (command line option
+<code>-d</code>). This makes FOP report which configuration
+information it finds. Check if FOP finds what you expect.</li>
+
+ </ul>
+
+ </section>
+ </body>
+</document>
+