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