diff options
Diffstat (limited to 'src/documentation/content/xdocs/0.95/configuration.xml')
-rw-r--r-- | src/documentation/content/xdocs/0.95/configuration.xml | 394 |
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> + |