git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/branches/fop-0_94@560886 13f79535-47bb-0310-9956-ffa450edef68tags/fop-0_94
</tr> | </tr> | ||||
</table> | </table> | ||||
<p>Other basic examples on the use of XSL-FO can be found in the FOP distribution in | <p>Other basic examples on the use of XSL-FO can be found in the FOP distribution in | ||||
the subdirectory xml-fop/examples/fo. You can start transformation of all fo files into pdf | |||||
files by starting xml-fop/examples/fo/runtests (only source distribution). The resulting test | |||||
files can be found in xml-fop/examples/fo/tests | |||||
the subdirectory examples/fo. You can start transformation of all fo files into pdf | |||||
files by running ant in this directory (only source distribution). The resulting test | |||||
files can be found in examples/fo/tests | |||||
</p> | </p> | ||||
<p>At the moment the following files are part of the distribution:</p> | <p>At the moment the following files are part of the distribution:</p> | ||||
<ul> | <ul> |
for XSL (FO) documents. | for XSL (FO) documents. | ||||
</p> | </p> | ||||
<p> | <p> | ||||
<link href="http://xml.apache.org/batik">Batik</link> can be used with | |||||
<link href="http://xmlgraphics.apache.org/batik">Batik</link> can be used with | |||||
FOP to <link | FOP to <link | ||||
href="http://xml.apache.org/batik/svgrasterizer.html">transcode an SVG | |||||
href="http://xmlgraphics.apache.org/batik/svgrasterizer.html">transcode an SVG | |||||
image</link> into a PDF document. | image</link> into a PDF document. | ||||
</p> | </p> | ||||
</answer> | </answer> | ||||
<p> | <p> | ||||
XSL is a W3C standard concerned with publishing XML documents. It | XSL is a W3C standard concerned with publishing XML documents. It | ||||
consists of two parts: <link href="#XSLT">XSLT</link> and <link | consists of two parts: <link href="#XSLT">XSLT</link> and <link | ||||
href="#XSLFO">XSLFO</link>. The acronym expands to | |||||
href="#XSLFO">XSL-FO</link>. The acronym expands to | |||||
e<strong>X</strong>tensible <strong>S</strong>tylesheet | e<strong>X</strong>tensible <strong>S</strong>tylesheet | ||||
<strong>L</strong>anguage. | <strong>L</strong>anguage. | ||||
</p> | </p> | ||||
<title>Problems running FOP</title> | <title>Problems running FOP</title> | ||||
<faq id="no-page-master"> | <faq id="no-page-master"> | ||||
<question>I get the error: [ERROR]: 'master-reference' for | <question>I get the error: [ERROR]: 'master-reference' for | ||||
'fo:page-sequence'matches no 'simple-page-master' or | |||||
'fo:page-sequence' matches no 'simple-page-master' or | |||||
'page-sequence-master'</question> | 'page-sequence-master'</question> | ||||
<answer> | <answer> | ||||
<p> | <p> | ||||
FOP was changed to be in accordance with the latest standard (see | FOP was changed to be in accordance with the latest standard (see | ||||
<link href="resources.html#w3-xsl">XSL standard</link>).The page | |||||
master for a fo:page-sequence is now refereced by the | |||||
<link href="resources.html#specs-xslfo">XSL standard</link>).The page | |||||
master for a fo:page-sequence is now referenced by the | |||||
master-reference attribute. Replace the master-name attributes of | master-reference attribute. Replace the master-name attributes of | ||||
your fo:page-sequence elements by master-reference attributes. You | your fo:page-sequence elements by master-reference attributes. You | ||||
have to do this also for fo:single-page-master-reference, | have to do this also for fo:single-page-master-reference, | ||||
whether you got them right. | whether you got them right. | ||||
</p> | </p> | ||||
<p> | <p> | ||||
You may find it helpful to use the <link href="#FO-validate">validation tools</link> to validate your | |||||
You may find it helpful to use the <link href="#fo-validate">validation tools</link> to validate your | |||||
FO document. This will catch most problems, but should not be | FO document. This will catch most problems, but should not be | ||||
relied upon to catch all. | relied upon to catch all. | ||||
</p> | </p> | ||||
</p> | </p> | ||||
<p> | <p> | ||||
If you called the FOP command line application from some other | If you called the FOP command line application from some other | ||||
programm, for example from Java using Runtime.exec(), it may hang | |||||
program, for example from Java using Runtime.exec(), it may hang | |||||
while trying to write log entries to the output pipe. You have to read | while trying to write log entries to the output pipe. You have to read | ||||
the FOP output regularly to empty the pipe buffer. It is best to avoid | the FOP output regularly to empty the pipe buffer. It is best to avoid | ||||
exec'ing FOP, use the library interface instead. | exec'ing FOP, use the library interface instead. | ||||
<question>FOP does not find my fonts.</question> | <question>FOP does not find my fonts.</question> | ||||
<answer> | <answer> | ||||
<p> | <p> | ||||
Did you get: «Failed to read font metrics file C:\foo\arial.xml | |||||
: File "C:\foo\arial.xml" not found»? The value for the | |||||
Did you get: “Failed to read font metrics file C:\foo\arial.xml | |||||
: File "C:\foo\arial.xml" not found”? The value for the | |||||
metrics-file attribute in the user config file is actually an URL, not | metrics-file attribute in the user config file is actually an URL, not | ||||
a file name. Use "file:///C:/foo/arial.xml" instead. | a file name. Use "file:///C:/foo/arial.xml" instead. | ||||
</p> | </p> | ||||
The new implementation uses leader-length.optimum to | The new implementation uses leader-length.optimum to | ||||
determine where to break the line, and expands the leader | determine where to break the line, and expands the leader | ||||
only further if the line should be filled, as indicated by | only further if the line should be filled, as indicated by | ||||
the text-aling and text-align-last properties. | |||||
the text-align and text-align-last properties. | |||||
</p> | </p> | ||||
<p> | <p> | ||||
Actually due to the fuzzyness of the specification both the | Actually due to the fuzzyness of the specification both the | ||||
</p> | </p> | ||||
<p> | <p> | ||||
The <link | The <link | ||||
href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice7.html#force-page-count">force-page-count | |||||
href="http://www.w3.org/TR/xsl11/#force-page-count">force-page-count | |||||
property</link> controls how a FO processor pads page sequences in | property</link> controls how a FO processor pads page sequences in | ||||
order to get certain page counts or last page numbers. The default is | order to get certain page counts or last page numbers. The default is | ||||
"<code>auto</code>". With this setting, if the next page sequence | "<code>auto</code>". With this setting, if the next page sequence | ||||
<answer> | <answer> | ||||
<p> | <p> | ||||
This is usually caused by setting a "height" on a table-row or table-cell and when | This is usually caused by setting a "height" on a table-row or table-cell and when | ||||
the content is higher that the specified height. By setting "height" (a so-called | |||||
the content is higher than the specified height. By setting "height" (a so-called | |||||
corresponding property) you | corresponding property) you | ||||
<link href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice5.html#section-N6057-Height,-and-Width-Properties">implicitely set</link> | |||||
<link href="http://www.w3.org/TR/xsl11/#d0e4413">implicitely set</link> | |||||
block-progression-dimension.minimum, block-progression-dimension.optimum and | block-progression-dimension.minimum, block-progression-dimension.optimum and | ||||
block-progression-dimension.maximum to the same value. You'll get some information | block-progression-dimension.maximum to the same value. You'll get some information | ||||
about that in the warning message. Look for something like: | about that in the warning message. Look for something like: | ||||
</p> | </p> | ||||
<p> | <p> | ||||
Assuming you set the height on the table-row to 14pt and your content is 75pt high, | Assuming you set the height on the table-row to 14pt and your content is 75pt high, | ||||
a constraint (maximum=14pt) is violated. Normally, you just want want to make sure | |||||
a constraint (maximum=14pt) is violated. Normally, you just want to make sure | |||||
with the "height" property that the row has a minimum height. If that is so, the | with the "height" property that the row has a minimum height. If that is so, the | ||||
right solution is to specify block-progression-dimension.minimum="14pt" instead of | right solution is to specify block-progression-dimension.minimum="14pt" instead of | ||||
heigth="14pt". | |||||
height="14pt". | |||||
</p> | </p> | ||||
</answer> | </answer> | ||||
</faq> | </faq> | ||||
<faq id="pdf-bookmark-display"> | <faq id="pdf-bookmark-display"> | ||||
<question>How do I control the Acrobat bookmark display?</question> | <question>How do I control the Acrobat bookmark display?</question> | ||||
<answer> | <answer> | ||||
<p> | |||||
FOP 0.20.5 does not support this feature. Possible workarounds | |||||
include those mentioned in the <link href="0.93/output.html#pdf-postprocess">PDF | |||||
Post-Processing FAQ</link>. | |||||
</p> | |||||
<p> | <p> | ||||
FOP versions 0.93 and later support the starting-state property of the XSL 1.1 | FOP versions 0.93 and later support the starting-state property of the XSL 1.1 | ||||
<link href="http://www.w3.org/TR/xsl11/#fo_bookmark">fo:bookmark</link> | <link href="http://www.w3.org/TR/xsl11/#fo_bookmark">fo:bookmark</link> | ||||
For the second task, you can use some client side script to start | For the second task, you can use some client side script to start | ||||
Acrobat Reader in print mode, or use a Java applet based on the FOP | Acrobat Reader in print mode, or use a Java applet based on the FOP | ||||
print servlet. This depends heavily on the client installation and | print servlet. This depends heavily on the client installation and | ||||
should not relied on except in tightly controlled environments. | |||||
should not be relied on except in tightly controlled environments. | |||||
</p> | </p> | ||||
<p> | <p> | ||||
See also <link href="http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2">http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2</link> | See also <link href="http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2">http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2</link> |
<section id="xml-encoding"> | <section id="xml-encoding"> | ||||
<title>Encoding Issues</title> | <title>Encoding Issues</title> | ||||
<p> | <p> | ||||
If the parser complains about illegal bytes or characters in the input, or there are unexpected characters in the output, this is usually is the result of a character encoding problem. | |||||
If the parser complains about illegal bytes or characters in the input, or there are unexpected characters in the output, this is usually the result of a character encoding problem. | |||||
See the <link href="http://www.dpawson.co.uk/xsl">XSL FAQ</link> for additional information. | See the <link href="http://www.dpawson.co.uk/xsl">XSL FAQ</link> for additional information. | ||||
Many software packages that produce XML, including XSLT processors, use UTF-8 encoding as a default. | Many software packages that produce XML, including XSLT processors, use UTF-8 encoding as a default. | ||||
If you view their output with something not aware of the encoding, like Notepad for Win95/98/ME/NT, funny characters are displayed. A Å is a giveaway. | If you view their output with something not aware of the encoding, like Notepad for Win95/98/ME/NT, funny characters are displayed. A Å is a giveaway. | ||||
<section id="fo-preformat"> | <section id="fo-preformat"> | ||||
<title>Preformatting Content</title> | <title>Preformatting Content</title> | ||||
<p> | <p> | ||||
Sometimes it is desirable to retain linebreaks and hard spaces, and to get preformatted text to pass through without being changed. | |||||
The XSL-FO specification provides some properties for this: <link href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice7.html#white-space-collapse">white-space-collapse</link> and <link href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice7.html#linefeed-treatment">linefeed-treatment</link>. | |||||
In FOP, use white-space-collapse="false" on an enclosing block. | |||||
Sometimes it is desirable to retain linebreaks and hard spaces, and to get | |||||
preformatted text to pass through without being changed. The XSL-FO | |||||
specification provides some properties for this: <link | |||||
href="http://www.w3.org/TR/xsl11/#white-space-collapse">white-space-collapse</link> | |||||
and <link | |||||
href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice7.html#white-space-collapse">linefeed-treatment</link>. | |||||
In FOP, use white-space-collapse="false" on an enclosing block. | |||||
</p> | </p> | ||||
<warning> | |||||
Due to a bug in FOP 0.20.5, setting white-space-collapse="false" will also preserve line breaks in the text. Do not rely on this behavior, as it is non-conformant and has changed in FOP 0.93. | |||||
</warning> | |||||
</section> | </section> | ||||
<section id="fo-total-pages"> | <section id="fo-total-pages"> | ||||
<title>Total Document Pages</title> | <title>Total Document Pages</title> | ||||
</p> | </p> | ||||
<ul> | <ul> | ||||
<li> | <li> | ||||
Horizontal lines can be drawn using <link href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice6.html#fo_leader">fo:leader</link>. | |||||
Horizontal lines can be drawn using <link href="http://www.w3.org/TR/xsl11/#fo_leader">fo:leader</link>. | |||||
</li> | </li> | ||||
<li> | <li> | ||||
Use a solid border on a suitable fo:block. This will work for horizontal and vertical lines only. | Use a solid border on a suitable fo:block. This will work for horizontal and vertical lines only. | ||||
<link href="http://www.renderx.com">RenderX</link> has provided an <link href="http://www.renderx.com/Tests/validator/fo.dtd.html">Unofficial DTD for FO Documents</link>, which may be helpful in validating general FO issues. | <link href="http://www.renderx.com">RenderX</link> has provided an <link href="http://www.renderx.com/Tests/validator/fo.dtd.html">Unofficial DTD for FO Documents</link>, which may be helpful in validating general FO issues. | ||||
</p> | </p> | ||||
<p> | <p> | ||||
FOP also maintains an <link href="http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/foschema/fop.xsd?view=co">Unofficial FOP Schema</link> in the FOP CVS Repository. | |||||
This document can be used either to validate against the FO standard, or against the actual FOP implementation. | |||||
See the notes near the beginning of the document for instructions on how to use it. | |||||
FOP also maintains an <link | |||||
href="http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/foschema/fop.xsd?view=co">Unofficial | |||||
FOP Schema</link> in the FOP Subversion Repository. This document can be used | |||||
either to validate against the FO standard, or against the actual FOP | |||||
implementation. See the notes near the beginning of the document for | |||||
instructions on how to use it. | |||||
</p> | </p> | ||||
</section> | </section> | ||||
<section id="landscape"> | <section id="landscape"> | ||||
</section> | </section> | ||||
<section id="external-resources"> | <section id="external-resources"> | ||||
<title>External Resources</title> | <title>External Resources</title> | ||||
<p>Resources needed by an XSL-FO file that are external to it (graphics, for example), are defined in the XSL-FO standard as being of type "uri-specification". This is defined in the standard at <jump href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice5.html#section-N8794-Property-Datatypes">Section 5.11 Property Datatypes</jump>, which includes a link to the URI standard itself. Refer to the XSL-FO and URI standards themselves for more detailed instructions.</p> | |||||
<p>URIs may be either absolute or relative to a base URI. (See <link href="0.20.5/configuration.html">FOP: Configuration</link> for information on setting the base URI for a FOP session). Here is an example referencing an external-graphic that is relative to the base URI:</p> | |||||
<p>Resources needed by an XSL-FO file that are external to it (graphics, for example), are defined in the XSL-FO standard as being of type "uri-specification". This is defined in the standard at <jump href="http://www.w3.org/TR/xsl11/#datatype">Section 5.11 Property Datatypes</jump>, which includes a link to the URI standard itself. Refer to the XSL-FO and URI standards themselves for more detailed instructions.</p> | |||||
<p>URIs may be either absolute or relative to a base URI. (See <link href="0.94/configuration.html">FOP: Configuration</link> for information on setting the base URI for a FOP session). Here is an example referencing an external-graphic that is relative to the base URI:</p> | |||||
<source><![CDATA[<fo:external-graphic src="url('images/logo.jpg')"/>]]></source> | <source><![CDATA[<fo:external-graphic src="url('images/logo.jpg')"/>]]></source> | ||||
<p>Here is an example referencing an external-graphic that is an absolute URI on a local filesystem:</p> | <p>Here is an example referencing an external-graphic that is an absolute URI on a local filesystem:</p> | ||||
<source><![CDATA[fo:external-graphic src="url('file:d:///images/logo.jpg')"/>]]></source> | <source><![CDATA[fo:external-graphic src="url('file:d:///images/logo.jpg')"/>]]></source> |
<body> | <body> | ||||
<section id="intro"> | <section id="intro"> | ||||
<title>Introduction</title> | <title>Introduction</title> | ||||
<p>Apache FOP (Formatting Objects Processor) is the world's first print formatter driven by XSL formatting | |||||
objects (XSL-FO) and the world's first output independent formatter. It is a | |||||
Java application that reads a formatting object (FO) tree and | |||||
renders the resulting pages to a specified output. <link href="0.20.5/output.html">Output formats</link> | |||||
currently supported include PDF, PCL, PS, SVG, XML (area tree representation), | |||||
Print, AWT, MIF and TXT. | |||||
The primary output target is PDF. | |||||
</p> | |||||
<p>Apache FOP (Formatting Objects Processor) is a print formatter driven by XSL | |||||
formatting objects (XSL-FO) and an output independent formatter. It is a Java | |||||
application that reads a formatting object (FO) tree and renders the resulting | |||||
pages to a specified output. <link href="0.94/output.html">Output formats</link> | |||||
currently supported include PDF, PS, PCL, AFP, XML (area tree representation), | |||||
Print, AWT, PNG and TXT. The primary output target is PDF. | |||||
</p> | |||||
<figure width="480" height="260" src="images/document.jpg" alt="Render Diagram" /> | <figure width="480" height="260" src="images/document.jpg" alt="Render Diagram" /> | ||||
<p> | <p> | ||||
The previous version of FOP (<link href="0.20.5/">0.20.5</link>) is a partial implementation of the | |||||
<link href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Version 1.0 | |||||
W3C Recommendation</link>. | |||||
</p> | |||||
<p> | |||||
The latest stable version of FOP (<link href="0.93/">0.93</link>) is the first stable release | |||||
after a large redesign effort and implements a larger subset than 0.20.5 of the | |||||
<link href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Version 1.0 W3C Recommendation</link> | |||||
as well as some parts of the <link href="http://www.w3.org/TR/xsl11">XSL-FO Version 1.1 Working Draft</link>. | |||||
The latest stable version of FOP (<link href="0.94/">0.94</link>) is the second | |||||
stable release after a large redesign effort and implements a large subset of the | |||||
<link href="http://www.w3.org/TR/xsl11/">XSL-FO Version 1.1 W3C | |||||
Recommendation</link>. | |||||
</p> | </p> | ||||
<p> | <p> | ||||
Support for each of the standard's objects and properties is detailed in <link href="compliance.html">FOP Compliance</link>. | Support for each of the standard's objects and properties is detailed in <link href="compliance.html">FOP Compliance</link>. | ||||
</p> | </p> | ||||
<p> | <p> | ||||
FOP uses the standard XSL-FO file format as input, lays the content out into pages, then renders it to the requested output. | FOP uses the standard XSL-FO file format as input, lays the content out into pages, then renders it to the requested output. | ||||
One great advantage to using XSL-FO as input is that XSL-FO is itself an XML file, which means that it can be conveniently created from a variety of sources. | |||||
One great advantage of using XSL-FO as input is that XSL-FO is itself an XML file, which means that it can be conveniently created from a variety of sources. | |||||
The most common method is to convert semantic XML to XSL-FO, using an XSLT transformation.</p> | The most common method is to convert semantic XML to XSL-FO, using an XSLT transformation.</p> | ||||
</section> | </section> | ||||
<section id="objectives"> | <section id="objectives"> | ||||
<title>FOP Objectives</title> | <title>FOP Objectives</title> | ||||
<p>The goals of the Apache FOP project are to deliver an XSL-FO to PDF formatter that is compliant to at least the Basic | |||||
conformance level described in the W3C Recommendation from 15 October 2001, and that complies with the 11 March 1999 Portable Document | |||||
Format Specification (Version 1.3) from Adobe Systems. | |||||
<p>The goals of the Apache FOP project are to deliver an XSL-FO to PDF formatter that | |||||
is compliant to at least the Basic conformance level described in the W3C | |||||
Recommendation from 05 December 2006, and that complies with the November 2001 | |||||
Portable Document Format Specification (Version 1.4) from Adobe Systems. | |||||
</p> | </p> | ||||
<p>Conformance to the XML 1.0 Recommendation, XSLT 1.0 Recommendation and the XML Namespaces Recommendation is | <p>Conformance to the XML 1.0 Recommendation, XSLT 1.0 Recommendation and the XML Namespaces Recommendation is | ||||
understood. Other relevant documents, such as the XPath and XLink Working Drafts, are referenced as necessary. The FOP | understood. Other relevant documents, such as the XPath and XLink Working Drafts, are referenced as necessary. The FOP | ||||
Project will attempt to use the latest version of evolving specifications. | Project will attempt to use the latest version of evolving specifications. | ||||
</p> | </p> | ||||
<p>The FOP layout system is currently being rewritten to better support the XSL-FO standard.</p> | |||||
</section> | </section> | ||||
<note> | <note> | ||||
The PDF files on this site are created using Apache FOP. | The PDF files on this site are created using Apache FOP. |
<version>$Revision$</version> | <version>$Revision$</version> | ||||
</header> | </header> | ||||
<body> | <body> | ||||
<section> | |||||
<title>XX August 2007 - Apache FOP 0.94 Released</title> | |||||
<p>The Apache FOP team is pleased to present you the second production | |||||
grade release of the new FOP codebase. This release contains many bug | |||||
fixes and features.</p> | |||||
</section> | |||||
<section> | <section> | ||||
<title>26 January 2007 - New Committer</title> | <title>26 January 2007 - New Committer</title> | ||||
<p>Welcome Jay Bryant!</p> | <p>Welcome Jay Bryant!</p> |