| <?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> |
| |
