source: pst/ps/fop.xml@ de27951

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

    <!-- Inserted as a reminder to do this. The mention of a test suite
         is usually right before the root user installation commands. Please
         delete these 12 (including one blank) lines after you are done.-->

    <!-- Use one of the two mentions below about a test suite,
         delete the line that is not applicable. Of course, if the
         test suite uses syntax other than "make check", revise the
         line to reflect the actual syntax to run the test suite -->

    <!-- <para>This package does not come with a test suite.</para> -->
    <!-- <para>To test the results, issue: <command>make check</command>.</para> -->

  <!ENTITY fop-download-http "http://www.apache.org/dist/xml/fop/fop-&fop-version;-src.tar.gz">
  <!ENTITY fop-download-ftp  "ftp://apache.mirrors.pair.com/xml/fop/source/fop-&fop-version;-src.tar.gz">
  <!ENTITY fop-md5sum        "1a31eb1357e5d4b8d32d4cb3edae2da2">
  <!ENTITY fop-size          "7.8 MB">
  <!ENTITY fop-buildsize     "45.3 MB">
  <!ENTITY fop-time          "0.25 SBU">

  <!ENTITY jai-download      "http://javashoplm.sun.com/ECom/docs/Welcome.jsp?StoreId=22&amp;PartDetailId=jai-1_1_2_01-oth-JPR&amp;SiteId=JSC&amp;TransactionId=noreg">
  <!ENTITY jai-md5sum        "f2be3619a8d002eff3874355e96327eb">
  <!ENTITY jai-size          "2.6 MB">
]>

<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>

    <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>Required package</title>
      <listitem>
        <para><application>Java</application> Advanced Imaging (JAI) API
        components: <ulink url="&jai-download;">
        http://javashoplm.sun.com/ECom/docs/Welcome.jsp?StoreId=22&amp;</ulink>
        <ulink url="&jai-download;">
        PartDetailId=jai-1_1_2_01-oth-JPR&amp;SiteId=JSC&amp;TransactionId=noreg</ulink>
        </para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &jai-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &jai-size;</para>
      </listitem>
    </itemizedlist>

    <para>Choose the <quote><application>Linux</application>
    <application>JDK</application> Install</quote> file after
    accepting the license agreement.</para>

    <itemizedlist spacing='compact'>
      <title>Required patch</title>
      <listitem>
        <para><ulink
        url="&patch-root;/fop-&fop-version;-jdk_1.5.0-1.patch"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">FOP Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="jdk"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="libxslt"/>,
    <ulink url="http://java.sun.com/products/jimi/">JIMI SDK</ulink>,
    <ulink url="http://xml.apache.org/batik/">Batik</ulink> and
    <ulink url="http://forrest.apache.org/">Forrest</ulink> (only used to rebuild
    the documentation)</para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/fop"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of FOP</title>

    <note>
      <para>Ensure <envar>$JAVA_HOME</envar> is set correctly before beginning
      the build.</para>
    </note>

    <para>Some versions of tar will display a message similar to
    <quote><computeroutput>tar: A lone zero block at 33476</computeroutput></quote>
    when unpacking the source tarball. You may safely ignore this message.</para>

    <sect3>
      <title>Installing JAI</title>

      <tip>
        <para>The
        <command>$FOP_BUILD_DIR/../jai-1_1_2_01-lib-linux-i586-jdk.bin</command>
        command below installs the JAI components in the JDK tree. You will be
        required to view, and then accept (by entering a <keycap>y</keycap>
        keypress), a license agreement before the installation will continue.
        If you are scripting (automating) the build, you'll need to account for
        this. There is information about automating build commands in the
        <xref linkend="automating-builds"/> section of Chapter 2. Towards the
        end of this section, specific information for automating this type of
        installation is discussed.</para>
      </tip>

      <para>Install the JAI components by running the following commands as
      the <systemitem class="username">root</systemitem> user while in the
      root of the <application>FOP</application> source tree:</para>

<screen role="root"><userinput>sed -i 's/tail +122/tail -n +122/' \
    ../jai-1_1_2_01-lib-linux-i586-jdk.bin &amp;&amp;
chmod 755 ../jai-1_1_2_01-lib-linux-i586-jdk.bin &amp;&amp;
FOP_BUILD_DIR=$(pwd) &amp;&amp;
cd $JAVA_HOME &amp;&amp;
$FOP_BUILD_DIR/../jai-1_1_2_01-lib-linux-i586-jdk.bin &amp;&amp;
cd $FOP_BUILD_DIR</userinput></screen>

    </sect3>

    <sect3>
      <title>Installing FOP required components</title>

      <para>Install <application>FOP</application> by running the
      following commands:</para>

<screen><userinput>patch -Np1 -i ../fop-&fop-version;-jdk_1.5.0-1.patch &amp;&amp;
./build.sh &amp;&amp;
sed -i "s/build/lib/" fop.sh</userinput></screen>

      <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -d -m755 \
    /opt/fop-&fop-version;/{bin,lib,docs/{general,lib,site}} &amp;&amp;
install -v -m755 fop.sh /opt/fop-&fop-version;/bin &amp;&amp;
install -v -m644 build/fop.jar lib/avalon-framework-cvs-20020806.jar \
    /opt/fop-&fop-version;/lib &amp;&amp;
install -v -m644 docs/* /opt/fop-&fop-version;/docs &amp;&amp;
install -v -m644 CHANGES LICENSE README ReleaseNotes.html STATUS \
    /opt/fop-&fop-version;/docs/general &amp;&amp;
install -v -m644 lib/{avalon.LICENSE.txt,readme} \
    /opt/fop-&fop-version;/docs/lib &amp;&amp;
cp -v -R build/site/* /opt/fop-&fop-version;/docs/site &amp;&amp;
ln -svf fop-&fop-version; /opt/fop</userinput></screen>

    </sect3>

    <sect3>
      <title>Installing the Batik JAR</title>

      <para>You'll need to install one additional <application>Java</application>
      class library to process SVG objects. This library is part of the
      <ulink url="http://xml.apache.org/batik/">Batik</ulink> package, but is
      also included with the <application>FOP</application> package. If you
      have <application>Batik</application> installed, ensure the
      <filename>batik.jar</filename> library is included in your
      <envar>$CLASSPATH</envar> environment variable. Alternatively, create a
      symbolic link from <filename>/opt/fop-&fop-version;/lib/batik.jar</filename>
      pointing to the full path of the installed <filename>batik.jar</filename>
      file so that the <command>fop.sh</command> script will automatically pick it
      up.</para>

      <para>If you don't have the <application>Batik</application> package
      installed, run the following commands as the <systemitem
      class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m644 lib/batik.jar /opt/fop-&fop-version;/lib &amp;&amp;
install -v -m644 lib/batik.LICENSE.txt \
    /opt/fop-&fop-version;/docs/lib</userinput></screen>

    </sect3>

    <sect3>
      <title>Installing the Xalan-Java components</title>

      <para>The components of <application>FOP</application> required to
      process FO files created by an XSL transformation engine (also known
      as an XSLT processor) is now complete. An XSL transformation engine
      (<command>xsltproc</command>) is included with the
      <xref linkend="libxslt"/> package in BLFS. The
      <application>FOP</application> package includes components of
      <ulink url="http://xml.apache.org/xalan-j/">Xalan-Java</ulink> to
      accomplish XSL transformations. If you have the
      <application>Xalan-Java</application> package installed, skip to
      the next section.</para>

      <para>If you wish to install the <application>Xalan-Java</application>
      components provided by the <application>FOP</application>
      package, run the following commands as the <systemitem
      class="username">root</systemitem> user:</para>

<screen role="root"><userinput>sed -i "s/build/lib/" xalan.sh &amp;&amp;
install -v -m755 xalan.sh /opt/fop-&fop-version;/bin &amp;&amp;
install -v -m644 lib/xml-apis.jar \
                 lib/xercesImpl-2.2.1.jar \
                 lib/xalan-2.4.1.jar \
    /opt/fop-&fop-version;/lib &amp;&amp;
install -v -m644 lib/{xml-apis,xerces,xalan}.LICENSE.txt \
                 lib/xml-apis.README.txt \
    /opt/fop-&fop-version;/docs/lib</userinput></screen>

    </sect3>

    <sect3>
      <title>Installing the Jimi SDK JAR</title>

      <para>If you installed the Java Image I/O class library
      (<application>Jimi SDK</application>) into the
      <application>FOP</application> source tree
      <filename class='directory'>lib</filename> directory before building
      <application>FOP</application> (this will enable Jimi
      support), ensure you also install this JAR file into
      <filename class='directory'>/opt/fop-&fop-version;/lib</filename>.</para>

    </sect3>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>sed -i 's/tail +122/tail -n +122/' ...</command>:
    The <application>JAI</application> binary file has a <command>tail</command>
    command imbedded in the file which uses obsolete syntax and causes the
    file to not unpack correctly. This command fixes the obsolete
    syntax.</para>

    <para><command>$FOP_BUILD_DIR/../jai-...-jdk.bin</command>: This
    command installs the <application>JAI</application> components
    into the <application>JDK</application> file structure.
    <envar>$FOP_BUILD_DIR</envar> is used as a reference point to the source
    executable and as a method to return back to the
    <application>FOP</application> source tree.</para>

    <para><command>sed -i "s/build/lib/" ...</command>: These commands modify
    the installed shell scripts so that the location of the installed
    <filename>fop.jar</filename> file is correctly identified.</para>

    <para><command>install -v ...; cp -v ...</command>: There is no installation
    script provided by the <application>FOP</application>
    package. These commands install the package.</para>

    <para><command>ln -svf fop-&fop-version; /opt/fop</command>: This 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.sh</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.sh</command>
      script. This can be accomplished by creating a
      <filename>~/.foprc</filename> (which is sourced by the
      <command>fop.sh</command> script) and adding the parameter to the
      <envar>FOP_OPTS</envar> environment variable.</para>

      <para>The <command>fop.sh</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>. 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.sh</command> script in your path,
      update your personal or system-wide profile with the following:</para>

<screen><literal>PATH=$PATH:/opt/fop/bin</literal></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directory</segtitle>

      <seglistitem>
        <seg>fop.sh and xalan.sh</seg>
        <seg>avalon-framework-cvs-20020806.jar, batik.jar, fop.jar,
        xalan-2.4.1.jar, xercesImpl-2.2.1.jar, and xml-apis.jar. 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.sh">
        <term><command>fop.sh</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.sh">
            <primary sortas="b-fop.sh">fop.sh</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>