glfs/pst/ps/fop.xml
Pierre Labastie bf7a1821c2 OpenJDK-1.8.0.131
FOP-2.2

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@18657 af4574ff-66df-0310-9fd7-8a98e5e911e0
2017-04-29 20:22:32 +00:00

431 lines
15 KiB
XML

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % general-entities SYSTEM "../../general.ent">
%general-entities;
<!ENTITY fop-download-http "https://archive.apache.org/dist/xmlgraphics/fop/source/fop-&fop-version;-src.tar.gz">
<!ENTITY fop-download-ftp " ">
<!ENTITY fop-md5sum "6d2388bd8851b4883d3258c0afc96895">
<!ENTITY fop-size "24 MB">
<!ENTITY fop-buildsize "493 MB (add 39 MB for tests)">
<!ENTITY fop-time "0.7 SBU (add 0.7 SBU for tests)">
<!ENTITY jai-version "1_1_3">
<!ENTITY jai-download "http://download.java.net/media/jai/builds/release/&jai-version;/jai-&jai-version;-lib-linux-i586.tar.gz">
<!ENTITY jai-md5sum "a2cbc155ef3899bcde9c74a8035764b3">
<!ENTITY jai-size "3.4 MB">
<!ENTITY jai64-download "http://download.java.net/media/jai/builds/release/&jai-version;/jai-&jai-version;-lib-linux-amd64.tar.gz">
<!ENTITY jai64-md5sum "4a906db35612f668aeef2c0606d7075b">
<!ENTITY jai64-size "3.4 MB">
<!ENTITY offo-download "&sourceforge-repo;/projects/offo/files/offo-hyphenation/2.2/offo-hyphenation.zip">
<!ENTITY offo-md5sum "bf9c09bf05108ef9661b8f08d91c2336">
<!ENTITY offo-size "862 KB">
]>
<sect1 id="fop" xreflabel="fop-&fop-version;">
<?dbhtml filename="fop.html"?>
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<title>fop-&fop-version;</title>
<indexterm zone="fop">
<primary sortas="a-fop">fop</primary>
</indexterm>
<sect2 role="package">
<title>Introduction to fop</title>
<para>
The <application>FOP</application> (Formatting Objects Processor)
package contains a print formatter driven by XSL formatting objects
(XSL-FO). It is a <application>Java</application> application that reads
a formatting object tree and renders the resulting pages to a specified
output. Output formats currently supported include PDF, PCL, PostScript,
SVG, XML (area tree representation), print, AWT, MIF and ASCII text. The
primary output target is PDF.
</para>
&lfs80_checked;
<bridgehead renderas="sect3">Package Information</bridgehead>
<itemizedlist spacing="compact">
<listitem>
<para>Download (HTTP): <ulink url="&fop-download-http;"/></para>
</listitem>
<listitem>
<para>Download (FTP): <ulink url="&fop-download-ftp;"/></para>
</listitem>
<listitem>
<para>Download MD5 sum: &fop-md5sum;</para>
</listitem>
<listitem>
<para>Download size: &fop-size;</para>
</listitem>
<listitem>
<para>Estimated disk space required: &fop-buildsize;</para>
</listitem>
<listitem>
<para>Estimated build time: &fop-time;</para>
</listitem>
</itemizedlist>
<bridgehead renderas="sect3">Additional Downloads</bridgehead>
<itemizedlist spacing="compact">
<title>Recommended packages</title>
<listitem>
<para>Objects for Formatting Objects (OFFO) hyphenation patterns:
<simplelist>
<member><ulink url="&offo-download;"/></member>
<member>&offo-md5sum;</member>
<member>&offo-size;</member>
</simplelist>
</para>
</listitem>
<listitem>
<para>Java Advanced Imaging (JAI) API components (architecture dependent):
<simplelist>
<member><ulink url="&jai-download;"/></member>
<member>&jai-md5sum;</member>
<member>&jai-size;</member>
</simplelist>
<literallayout>or</literallayout> <!-- Force some space -->
<simplelist>
<member><ulink url="&jai64-download;"/></member>
<member>&jai64-md5sum;</member>
<member>&jai64-size;</member>
</simplelist>
</para>
</listitem>
</itemizedlist>
<!-- <itemizedlist spacing="compact">
<title>Required patch</title>
<listitem>
<para>
<ulink url="&patch-root;/fop-&fop-version;-listNPE-1.patch"/>
</para>
</listitem>
</itemizedlist>-->
<bridgehead renderas="sect3">fop Dependencies</bridgehead>
<bridgehead renderas="sect4">Required</bridgehead>
<para role="required">
<xref linkend="apache-ant"/>
</para>
<bridgehead renderas="sect4">Optional</bridgehead>
<para role="optional">
<xref linkend="junit"/> (to run tests),
<xref linkend="x-window-system"/> (to run tests),
<ulink url="https://maven.apache.org/">Maven</ulink>,
<ulink url="https://java.net/projects/jai-imageio">JAI Image I/O Tools</ulink>, and
<ulink url="http://jeuclid.sourceforge.net/">JEuclid</ulink>
<!-- [pierre 2017-04-29] Note to devs: there are a lot of bundled dependencies.
Some were listed here, but not all. I am not sure it is possible to
use system ones. So, I have removed them, an kept only those which
are not bundled. -->
</para>
<para condition="html" role="usernotes">User Notes:
<ulink url="&blfs-wiki;/fop"/></para>
</sect2>
<sect2 role="installation">
<title>Installation of fop</title>
<para>
Ensure <envar>$JAVA_HOME</envar> is set correctly before beginning
the build. To build the <application>JIMI SDK</application> and/or
<application>XMLUnit</application> extension classes, ensure the
corresponding <filename class='extension'>.jar</filename> files can be
found via the <envar>CLASSPATH</envar> environment variable.
</para>
<sect3>
<title>Installing OFFO Hyphenation Patterns</title>
<para>
Copy the XML hyphenation patterns into the fop source tree by running
the following commands:
</para>
<screen><userinput>unzip ../offo-hyphenation.zip &amp;&amp;
cp offo-hyphenation/hyph/* fop/hyph &amp;&amp;
rm -rf offo-hyphenation</userinput></screen>
</sect3>
<sect3>
<title>Installing Java Advanced Imaging (JAI) API components</title>
<para>
Install the JAI API components. As the <systemitem
class="username">root</systemitem> user:
</para>
<screen role="root"><userinput>case `uname -m` in
i?86)
tar -xf ../jai-&jai-version;-lib-linux-i586.tar.gz
cp -v jai-&jai-version;/lib/{jai*,mlibwrapper_jai.jar} $JAVA_HOME/jre/lib/ext/
cp -v jai-&jai-version;/lib/libmlib_jai.so $JAVA_HOME/jre/lib/i386/
;;
x86_64)
tar -xf ../jai-&jai-version;-lib-linux-amd64.tar.gz
cp -v jai-&jai-version;/lib/{jai*,mlibwrapper_jai.jar} $JAVA_HOME/jre/lib/ext/
cp -v jai-&jai-version;/lib/libmlib_jai.so $JAVA_HOME/jre/lib/amd64/
;;
esac</userinput></screen>
</sect3>
<sect3>
<title>Installing fop Components</title>
<para>
The <command>javadoc</command> command coming with OpenJDK 8 has
become much stricter than before regarding the conformance of the
Javadoc comments in source code to HTML. The FOP documentation does
not meet those standard, so the conformance checks have to be
disabled. This can be done with the following command:
</para>
<screen><userinput>sed -i '\@&lt;/javad@i\
&lt;arg value="-Xdoclint:none"/&gt;\
&lt;arg value="--allow-script-in-comments"/&gt;' fop/build.xml</userinput></screen>
<para>
The stack size set in <filename>build.xml</filename> for building the
hyphenation patterns is not enough. Change it by running:
</para>
<screen><userinput>sed -e '/hyph\.stack/s/512k/1M/' \
-i fop/build.xml</userinput></screen>
<para>
Then, compile <application>fop</application> by running the
following commands:
</para>
<screen><userinput>cd fop &amp;&amp;
export LC_ALL=en_US.UTF-8 &amp;&amp;
ant compile &amp;&amp;
ant jar-main &amp;&amp;
ant jar-hyphenation &amp;&amp;
ant javadocs &amp;&amp;
mv build/javadocs .</userinput></screen>
<para>
To test the application, first modify <filename>build.xml</filename>
so that tests do not stop when an error is encountered:
</para>
<screen><userinput>sed -e '/haltonfailure/s/yes/off/' \
-i build.xml</userinput></screen>
<para>
Then, run <command>ant junit</command>. The hyphenation tests will
fail if OFFO hyphenation has not been compiled. To see a list of other
test targets, use <command>ant -p</command>. You must run the tests
from an X-window using a GL-aware <application>Xorg</application>
server or some of the <application>JUnit</application> tests will hang.
</para>
<para>
Now, as the <systemitem class="username">root</systemitem> user:
</para>
<screen role="root"><userinput>install -v -d -m755 -o root -g root /opt/fop-&fop-version; &amp;&amp;
cp -v ../{KEYS,LICENSE,NOTICE,README} /opt/fop-&fop-version; &amp;&amp;
cp -vR build conf examples fop* javadocs lib /opt/fop-&fop-version; &amp;&amp;
chmod a+x /opt/fop-&fop-version;/fop &amp;&amp;
ln -v -sfn fop-&fop-version; /opt/fop</userinput></screen>
</sect3>
</sect2>
<sect2 role="commands">
<title>Command Explanations</title>
<para>
<command>sed -i ... build.xml</command>: This adds two switches to the
<command>javadoc</command> command, preventing some errors to occur when
building the documentation.
</para>
<para>
<command>export LC_ALL=en_US.UTF-8</command>: the compiler fails if using
an ASCII locale.
</para>
<para>
<command>ant <option>target</option></command>: This reads the file
<filename>build.xml</filename> and builds the target: <option>compile
</option> compiles the java sources, <option>jar-main</option> generates
jar archives, <option>jar-hyphenation</option> generates the hyphenation
patterns for FOP, and <option>javadocs</option> builds the documentation.
</para>
<para>
<command>ln -v -sf fop-&fop-version; /opt/fop</command>: This is
optional and creates a convenience symlink so that
<envar>$FOP_HOME</envar> doesn't have to be changed each time there's a
package version change.
</para>
</sect2>
<sect2 role="configuration">
<title>Configuring fop</title>
<sect3 id="fop-config">
<title>Config Files</title>
<para>
<filename>~/.foprc</filename>
</para>
<indexterm zone="fop fop-config">
<primary sortas="e-AA.foprc">~/.foprc</primary>
</indexterm>
</sect3>
<sect3>
<title>Configuration Information</title>
<para>
Using <application>fop</application> to process some large FO's
(including the FO derived from the BLFS XML sources), can lead to
memory errors. Unless you add a parameter to the
<command>java</command> command used in the <command>fop</command>
script you may receive messages similar to the one shown below:
</para>
<para>
<computeroutput>
Exception in thread "main" java.lang.OutOfMemoryError: Java heap
space
</computeroutput>
</para>
<para>
To avoid errors like this, you need to pass an extra parameter to
the <command>java</command> command used in the <command>fop</command>
script. This can be accomplished by creating a
<filename>~/.foprc</filename> (which is sourced by the
<command>fop</command> script) and adding the parameter to the
<envar>FOP_OPTS</envar> environment variable.
</para>
<para>
The <command>fop</command> script looks for a
<envar>FOP_HOME</envar> environment variable to locate the
<application>fop</application> class libraries. You can create this
variable using the <filename>~/.foprc</filename> file as well. Create
a <filename>~/.foprc</filename> file using the following commands:
</para>
<screen><userinput>cat &gt; ~/.foprc &lt;&lt; "EOF"
<literal>FOP_OPTS="-Xmx<replaceable>&lt;RAM_Installed&gt;</replaceable>m"
FOP_HOME="/opt/fop"</literal>
EOF</userinput></screen>
<para>
Replace <replaceable>&lt;RAM_Installed&gt;</replaceable> with a
number representing the amount of RAM installed in your computer (in
megabytes). An example would be
<userinput>FOP_OPTS="-Xmx768m"</userinput>.
<!-- the URL is broken
For more information about
memory issues running <application>fop</application>, see
<ulink url="http://xml.apache.org/fop/running.html#memory"/>.
-->
</para>
<para>
To include the <command>fop</command> script in your path,
update your personal or system-wide profile with the following:
</para>
<screen><literal>PATH=$PATH:/opt/fop</literal></screen>
<note>
<para>
Running <command>fop</command> can be somewhat verbose.
The default logging level can be changed from INFO to any of
FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, ALL, or OFF.
To do this, edit
<filename>$JAVA_HOME/jre/lib/logging.properties</filename> and change
the entries for <option>.level</option> and
<option>java.util.logging.ConsoleHandler.level</option> to
the desired value.
</para>
</note>
</sect3>
</sect2>
<sect2 role="content">
<title>Contents</title>
<segmentedlist>
<segtitle>Installed Programs</segtitle>
<segtitle>Installed Libraries</segtitle>
<segtitle>Installed Directory</segtitle>
<seglistitem>
<seg>fop</seg>
<seg>fop.jar and numerous support library classes located in
<filename class='directory'>/opt/fop/{build,lib}</filename>; JAI
components include libmlib_jai.so, jai_codec.jar, jai_core.jar, and
mlibwrapper_jai.jar</seg>
<seg>/opt/fop-&fop-version;</seg>
</seglistitem>
</segmentedlist>
<variablelist>
<bridgehead renderas="sect3">Short Descriptions</bridgehead>
<?dbfo list-presentation="list"?>
<?dbhtml list-presentation="table"?>
<varlistentry id="fop-prog">
<term><command>fop</command></term>
<listitem>
<para>is a wrapper script to the <command>java</command> command
which sets up the <application>fop</application>
environment and passes the required parameters.</para>
<indexterm zone="fop fop-prog">
<primary sortas="b-fop">fop</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="fop.jar">
<term><filename class='libraryfile'>fop.jar</filename></term>
<listitem>
<para>contains all the <application>fop</application>
<application>Java</application> classes.</para>
<indexterm zone="fop fop.jar">
<primary sortas="c-fop.jar">fop.jar</primary>
</indexterm>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>