Author: psancho
Date: Fri Jun 18 08:38:13 2010
New Revision: 955884
URL: http://svn.apache.org/viewvc?rev=955884&view=rev
Log:
Fop WebSite: update commandline usage help (in Trunk tab > Using FOP > Run)
Modified:
xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/running.xml
Modified:
xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/running.xml
URL:
http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/running.xml?rev=955884&r1=955883&r2=955884&view=diff
==============================================================================
--- xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/running.xml
(original)
+++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/running.xml Fri
Jun 18 08:38:13 2010
@@ -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 fi
-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 fi
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 fi
<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 fi
</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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
