|
|
@@ -38,8 +38,8 @@ |
|
|
|
</ul> |
|
|
|
</li> |
|
|
|
<li> |
|
|
|
Apache FOP. The <a href="../download.html">FOP distribution</a> includes all libraries that you will |
|
|
|
need to run a basic FOP installation. These can be found in the [fop-root]/lib directory. These |
|
|
|
Apache FOP. The <a href="../download.html">FOP distribution</a> includes all libraries that you will |
|
|
|
need to run a basic FOP installation. These can be found in the [fop-root]/lib directory. These |
|
|
|
libraries include the following: |
|
|
|
<ul> |
|
|
|
<li><a class="fork" href="ext:xmlgraphics.apache.org/commons">Apache XML Graphics Commons</a>, an shared library for Batik and FOP.</li> |
|
|
@@ -54,7 +54,7 @@ |
|
|
|
<ul> |
|
|
|
<li> |
|
|
|
Graphics libraries. Generally, FOP contains direct support for the most important |
|
|
|
bitmap image formats (including PNG, JPEG and GIF). See |
|
|
|
bitmap image formats (including PNG, JPEG and GIF). See |
|
|
|
<a href="graphics.html">FOP: Graphics Formats</a> for details. |
|
|
|
</li> |
|
|
|
<li> |
|
|
@@ -64,7 +64,7 @@ |
|
|
|
<p>In addition, the following system requirements apply:</p> |
|
|
|
<ul> |
|
|
|
<li> |
|
|
|
If you will be using FOP to process SVG, you must do so in a graphical environment. |
|
|
|
If you will be using FOP to process SVG, you must do so in a graphical environment. |
|
|
|
See <a href="graphics.html#batik">FOP: Graphics (Batik)</a> for details. |
|
|
|
</li> |
|
|
|
</ul> |
|
|
@@ -74,19 +74,19 @@ |
|
|
|
<section id="install-instruct"> |
|
|
|
<title>Instructions</title> |
|
|
|
<p> |
|
|
|
Basic FOP installation consists of first unzipping the <code>.gz</code> file that is the |
|
|
|
distribution medium, then unarchiving the resulting <code>.tar</code> file in a |
|
|
|
directory/folder that is convenient on your system. Please consult your operating system |
|
|
|
documentation or Zip application software documentation for instructions specific to your |
|
|
|
Basic FOP installation consists of first unzipping the <code>.gz</code> file that is the |
|
|
|
distribution medium, then unarchiving the resulting <code>.tar</code> file in a |
|
|
|
directory/folder that is convenient on your system. Please consult your operating system |
|
|
|
documentation or Zip application software documentation for instructions specific to your |
|
|
|
site. |
|
|
|
</p> |
|
|
|
</section> |
|
|
|
<section id="install-problems"> |
|
|
|
<title>Problems</title> |
|
|
|
<p> |
|
|
|
Some Mac OSX users have experienced filename truncation problems using Stuffit to unzip |
|
|
|
and unarchive their distribution media. This is a legacy of older Mac operating systems, |
|
|
|
which had a 31-character pathname limit. Several Mac OSX users have recommended that |
|
|
|
Some Mac OSX users have experienced filename truncation problems using Stuffit to unzip |
|
|
|
and unarchive their distribution media. This is a legacy of older Mac operating systems, |
|
|
|
which had a 31-character pathname limit. Several Mac OSX users have recommended that |
|
|
|
Mac OSX users use the shell command <code>tar -xzf</code> instead. |
|
|
|
</p> |
|
|
|
</section> |
|
|
@@ -96,30 +96,31 @@ |
|
|
|
<section id="fop-script"> |
|
|
|
<title>Using the fop script or batch file</title> |
|
|
|
<p> |
|
|
|
The usual and recommended practice for starting FOP from the command line is to run the |
|
|
|
The usual and recommended practice for starting FOP from the command line is to run the |
|
|
|
batch file fop.bat (Windows) or the shell script fop (Unix/Linux). |
|
|
|
These scripts require that the environment variable JAVA_HOME be |
|
|
|
set to a path pointing to the appropriate Java installation on your system. Macintosh OSX |
|
|
|
includes a Java environment as part of its distribution. We are told by Mac OSX users that |
|
|
|
These scripts require that the environment variable JAVA_HOME be |
|
|
|
set to a path pointing to the appropriate Java installation on your system. Macintosh OSX |
|
|
|
includes a Java environment as part of its distribution. We are told by Mac OSX users that |
|
|
|
the path to use in this case is <code>/Library/Java/Home</code>. <strong>Caveat:</strong> |
|
|
|
We suspect that, as Apple releases new Java environments and as FOP upgrades the minimum |
|
|
|
Java requirements, the two will inevitably not match on some systems. Please see |
|
|
|
<a href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</a> for information as |
|
|
|
We suspect that, as Apple releases new Java environments and as FOP upgrades the minimum |
|
|
|
Java requirements, the two will inevitably not match on some systems. Please see |
|
|
|
<a href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</a> for information as |
|
|
|
it becomes available. |
|
|
|
</p> |
|
|
|
<source><![CDATA[ |
|
|
|
USAGE |
|
|
|
Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at [mime]|-print] <outfile> |
|
|
|
[OPTIONS] |
|
|
|
-d debug mode |
|
|
|
-x dump configuration settings |
|
|
|
-q quiet mode |
|
|
|
[OPTIONS] |
|
|
|
-version print FOP version and exit |
|
|
|
-d debug mode |
|
|
|
-x dump configuration settings |
|
|
|
-q quiet mode |
|
|
|
-c cfg.xml use additional configuration file cfg.xml |
|
|
|
-l lang the language to use for user information |
|
|
|
-l lang the language to use for user information |
|
|
|
-r relaxed/less strict validation (where available) |
|
|
|
-dpi xxx target resolution in dots per inch (dpi) where xxx is a number |
|
|
|
-s for area tree XML, down to block areas only |
|
|
|
-v to show FOP version being used |
|
|
|
-v run in verbose mode (currently simply print FOP version and continue) |
|
|
|
|
|
|
|
-o [password] PDF file will be encrypted with option owner password |
|
|
|
-u [password] PDF file will be encrypted with option user password |
|
|
@@ -127,62 +128,73 @@ Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl |
|
|
|
-nocopy PDF file will be encrypted without copy content permission |
|
|
|
-noedit PDF file will be encrypted without edit content permission |
|
|
|
-noannotations PDF file will be encrypted without edit annotation permission |
|
|
|
-a enables accessibility features (Tagged PDF etc., default off) |
|
|
|
-pdfprofile prof PDF file will be generated with the specified profile |
|
|
|
(Examples for prof: PDF/A-1b or PDF/X-3:2003) |
|
|
|
|
|
|
|
[INPUT] |
|
|
|
infile xsl:fo input file (the same as the next) |
|
|
|
-fo infile xsl:fo input file |
|
|
|
-xml infile xml input file, must be used together with -xsl |
|
|
|
-atin infile area tree input file |
|
|
|
-xsl stylesheet xslt stylesheet |
|
|
|
|
|
|
|
-conserve Enable memory-conservation policy (trades memory-consumption for disk I/O) |
|
|
|
(Note: currently only influences whether the area tree is serialized.) |
|
|
|
|
|
|
|
[INPUT] |
|
|
|
infile xsl:fo input file (the same as the next) |
|
|
|
(use '-' for infile to pipe input from stdin) |
|
|
|
-fo infile xsl:fo input file |
|
|
|
-xml infile xml input file, must be used together with -xsl |
|
|
|
-atin infile area tree input file |
|
|
|
-ifin infile intermediate format input file |
|
|
|
-imagein infile image input file (piping through stdin not supported) |
|
|
|
-xsl stylesheet xslt stylesheet |
|
|
|
|
|
|
|
-param name value <value> to use for parameter <name> in xslt stylesheet |
|
|
|
(repeat '-param name value' for each parameter) |
|
|
|
|
|
|
|
[OUTPUT] |
|
|
|
|
|
|
|
-catalog use catalog resolver for input XML and XSLT files |
|
|
|
[OUTPUT] |
|
|
|
outfile input will be rendered as PDF into outfile |
|
|
|
(use '-' for outfile to pipe output to stdout) |
|
|
|
-pdf outfile input will be rendered as PDF (outfile req'd) |
|
|
|
-pdfa1b outfile input will be rendered as PDF/A-1b compliant PDF |
|
|
|
(outfile req'd, same as "-pdf outfile -pdfprofile PDF/A-1b") |
|
|
|
-awt input will be displayed on screen |
|
|
|
-awt input will be displayed on screen |
|
|
|
-rtf outfile input will be rendered as RTF (outfile req'd) |
|
|
|
-pcl outfile input will be rendered as PCL (outfile req'd) |
|
|
|
-ps outfile input will be rendered as PostScript (outfile req'd) |
|
|
|
-pcl outfile input will be rendered as PCL (outfile req'd) |
|
|
|
-ps outfile input will be rendered as PostScript (outfile req'd) |
|
|
|
-afp outfile input will be rendered as AFP (outfile req'd) |
|
|
|
-tiff outfile input will be rendered as TIFF (outfile req'd) |
|
|
|
-png outfile input will be rendered as PNG (outfile req'd) |
|
|
|
-txt outfile input will be rendered as plain text (outfile req'd) |
|
|
|
-at [mime] out representation of area tree as XML (outfile req'd) |
|
|
|
specify optional mime output to allow AT to be converted |
|
|
|
-txt outfile input will be rendered as plain text (outfile req'd) |
|
|
|
-at [mime] out representation of area tree as XML (outfile req'd) |
|
|
|
specify optional mime output to allow the AT to be converted |
|
|
|
to final format later |
|
|
|
-print input file will be rendered and sent to the printer |
|
|
|
see options with "-print help" |
|
|
|
-if [mime] out representation of document in intermediate format XML (outfile req'd) |
|
|
|
specify optional mime output to allow the IF to be converted |
|
|
|
to final format later |
|
|
|
-print input file will be rendered and sent to the printer |
|
|
|
see options with "-print help" |
|
|
|
-out mime outfile input will be rendered using the given MIME type |
|
|
|
(outfile req'd) Example: "-out application/pdf D:\out.pdf" |
|
|
|
(Tip: "-out list" prints the list of supported MIME types) |
|
|
|
-mif outfile input will be rendered as MIF (FrameMaker) (outfile req'd) |
|
|
|
Experimental feature - requires additional fop-sandbox.jar. |
|
|
|
-svg outfile input will be rendered as an SVG slides file (outfile req'd) |
|
|
|
-svg outfile input will be rendered as an SVG slides file (outfile req'd) |
|
|
|
Experimental feature - requires additional fop-sandbox.jar. |
|
|
|
|
|
|
|
-foout outfile input will only be XSL transformed. The intermediate |
|
|
|
XSL-FO file is saved and no rendering is performed. |
|
|
|
-foout outfile input will only be XSL transformed. The intermediate |
|
|
|
XSL-FO file is saved and no rendering is performed. |
|
|
|
(Only available if you use -xml and -xsl parameters) |
|
|
|
|
|
|
|
|
|
|
|
[Examples] |
|
|
|
Fop foo.fo foo.pdf |
|
|
|
Fop -fo foo.fo -pdf foo.pdf (does the same as the previous line) |
|
|
|
Fop -xml foo.xml -xsl foo.xsl -pdf foo.pdf |
|
|
|
Fop -xml foo.xml -xsl foo.xsl -foout foo.fo |
|
|
|
Fop foo.fo -mif foo.mif |
|
|
|
Fop foo.fo -rtf foo.rtf |
|
|
|
Fop foo.fo -print or Fop -print foo.fo |
|
|
|
Fop foo.fo -awt]]></source> |
|
|
|
fop foo.fo foo.pdf |
|
|
|
fop -fo foo.fo -pdf foo.pdf (does the same as the previous line) |
|
|
|
fop -xml foo.xml -xsl foo.xsl -pdf foo.pdf |
|
|
|
fop -xml foo.xml -xsl foo.xsl -foout foo.fo |
|
|
|
fop -xml - -xsl foo.xsl -pdf - |
|
|
|
fop foo.fo -mif foo.mif |
|
|
|
fop foo.fo -rtf foo.rtf |
|
|
|
fop foo.fo -print |
|
|
|
fop foo.fo -awt]]></source> |
|
|
|
<p> |
|
|
|
PDF encryption is only available if FOP was compiled with encryption support |
|
|
|
<strong>and</strong> if compatible encryption support is available at run time. |
|
|
|
PDF encryption is only available if FOP was compiled with encryption support |
|
|
|
<strong>and</strong> if compatible encryption support is available at run time. |
|
|
|
Currently, only the JCE is supported. Check the <a href="pdfencryption.html">Details</a>. |
|
|
|
</p> |
|
|
|
</section> |
|
|
@@ -194,8 +206,8 @@ Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl |
|
|
|
org.apache.fop.cli.Main <arguments></code>. The arguments |
|
|
|
consist of the options and infile and outfile specifications |
|
|
|
as shown above for the standard scripts. You may wish to review |
|
|
|
the standard scripts to make sure that |
|
|
|
you get your environment properly configured. |
|
|
|
the standard scripts to make sure that |
|
|
|
you get your environment properly configured. |
|
|
|
</p> |
|
|
|
</section> |
|
|
|
<section id="jar-option"> |
|
|
@@ -251,38 +263,38 @@ Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl |
|
|
|
<section id="check-input"> |
|
|
|
<title>Using Xalan to Check XSL-FO Input</title> |
|
|
|
<p> |
|
|
|
FOP sessions that use -xml and -xsl input instead of -fo input are actually |
|
|
|
controlling two distinct conversions: Tranforming XML to XSL-FO, then formatting |
|
|
|
FOP sessions that use -xml and -xsl input instead of -fo input are actually |
|
|
|
controlling two distinct conversions: Tranforming XML to XSL-FO, then formatting |
|
|
|
the XSL-FO to PDF (or another FOP output format). |
|
|
|
Although FOP controls both of these processes, the first is included merely as |
|
|
|
Although FOP controls both of these processes, the first is included merely as |
|
|
|
a convenience and for performance reasons. |
|
|
|
Only the second is part of FOP's core processing. |
|
|
|
If a user has a problem running FOP, it is important to determine which of these |
|
|
|
If a user has a problem running FOP, it is important to determine which of these |
|
|
|
two processes is causing the problem. |
|
|
|
If the problem is in the first process, the user's stylesheet is likely the cause. |
|
|
|
The FOP development team does not have resources to help with stylesheet issues, |
|
|
|
although we have included links to some useful |
|
|
|
<a href="../resources.html#specs">Specifications</a> and |
|
|
|
The FOP development team does not have resources to help with stylesheet issues, |
|
|
|
although we have included links to some useful |
|
|
|
<a href="../resources.html#specs">Specifications</a> and |
|
|
|
<a href="../resources.html#articles">Books/Articles</a>. |
|
|
|
If the problem is in the second process, FOP may have a bug or an unimplemented |
|
|
|
If the problem is in the second process, FOP may have a bug or an unimplemented |
|
|
|
feature that does require attention from the FOP development team. |
|
|
|
</p> |
|
|
|
<note>The user is always responsible to provide correct XSL-FO code to FOP.</note> |
|
|
|
<p> |
|
|
|
In the case of using -xml and -xsl input, although the user is responsible for |
|
|
|
the XSL-FO code that is FOP's input, it is not visible to the user. To make the |
|
|
|
intermediate FO file visible, the FOP distribution includes the "-foout" option |
|
|
|
which causes FOP to run only the first (transformation) step, and write the |
|
|
|
In the case of using -xml and -xsl input, although the user is responsible for |
|
|
|
the XSL-FO code that is FOP's input, it is not visible to the user. To make the |
|
|
|
intermediate FO file visible, the FOP distribution includes the "-foout" option |
|
|
|
which causes FOP to run only the first (transformation) step, and write the |
|
|
|
results to a file. (See also the Xalan command-line below) |
|
|
|
</p> |
|
|
|
<note> |
|
|
|
When asking for help on the FOP mailing lists, <em>never</em> attach XML and |
|
|
|
XSL to illustrate the issue. Always run the XSLT step (-foout) and send the |
|
|
|
resulting XSL-FO file instead. Of course, be sure that the XSL-FO file is |
|
|
|
When asking for help on the FOP mailing lists, <em>never</em> attach XML and |
|
|
|
XSL to illustrate the issue. Always run the XSLT step (-foout) and send the |
|
|
|
resulting XSL-FO file instead. Of course, be sure that the XSL-FO file is |
|
|
|
correct before sending it. |
|
|
|
</note> |
|
|
|
<p> |
|
|
|
The -foout option works the same way as if you would call the |
|
|
|
The -foout option works the same way as if you would call the |
|
|
|
<a href="http://xml.apache.org/xalan-j/commandline.html">Xalan command-line</a>: |
|
|
|
</p> |
|
|
|
<p> |
|
|
@@ -304,39 +316,39 @@ Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl |
|
|
|
</p> |
|
|
|
<ul> |
|
|
|
<li> |
|
|
|
Increase memory available to the JVM. See |
|
|
|
<a href="http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/java.html">the -Xmx option</a> |
|
|
|
Increase memory available to the JVM. See |
|
|
|
<a href="http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/java.html">the -Xmx option</a> |
|
|
|
for more information. |
|
|
|
<warning> |
|
|
|
It is usually unwise to increase the memory allocated to the JVM beyond the amount of |
|
|
|
It is usually unwise to increase the memory allocated to the JVM beyond the amount of |
|
|
|
physical RAM, as this will generally cause significantly slower performance. |
|
|
|
</warning> |
|
|
|
</li> |
|
|
|
<li> |
|
|
|
Avoid forward references. |
|
|
|
Forward references are references to some later part of a document. |
|
|
|
Examples include page number citations which refer to pages which follow the citation, |
|
|
|
tables of contents at the beginning of a document, and page numbering schemes that |
|
|
|
include the total number of pages in the document |
|
|
|
Examples include page number citations which refer to pages which follow the citation, |
|
|
|
tables of contents at the beginning of a document, and page numbering schemes that |
|
|
|
include the total number of pages in the document |
|
|
|
(<a href="../faq.html#pagenum">"page N of TOTAL"</a>). |
|
|
|
Forward references cause all subsequent pages to be held in memory until the reference |
|
|
|
Forward references cause all subsequent pages to be held in memory until the reference |
|
|
|
can be resolved, i.e. until the page with the referenced element is encountered. |
|
|
|
Forward references may be required by the task, but if you are getting a memory |
|
|
|
Forward references may be required by the task, but if you are getting a memory |
|
|
|
overflow, at least consider the possibility of eliminating them. |
|
|
|
A table of contents could be replaced by PDF bookmarks instead or moved to the end of |
|
|
|
A table of contents could be replaced by PDF bookmarks instead or moved to the end of |
|
|
|
the document (reshuffle the paper could after printing). |
|
|
|
</li> |
|
|
|
<li> |
|
|
|
Avoid large images, especially if they are scaled down. |
|
|
|
If they need to be scaled, scale them in another application upstream from FOP. |
|
|
|
For many image formats, memory consumption is driven mainly by the size of the image |
|
|
|
file itself, not its dimensions (width*height), so increasing the compression rate |
|
|
|
For many image formats, memory consumption is driven mainly by the size of the image |
|
|
|
file itself, not its dimensions (width*height), so increasing the compression rate |
|
|
|
may help. |
|
|
|
</li> |
|
|
|
<li> |
|
|
|
Use multiple page sequences. |
|
|
|
FOP starts rendering after the end of a page sequence is encountered. |
|
|
|
While the actual rendering is done page-by-page, some additional memory is |
|
|
|
While the actual rendering is done page-by-page, some additional memory is |
|
|
|
freed after the page sequence has been rendered. |
|
|
|
This can be substantial if the page sequence contains lots of FO elements. |
|
|
|
</li> |