Move doc about running SVG in a headless environment from faq.xml to graphics.xml. Add a comment in the "Requirements" section of running.xml to reference this doc.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196404 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 37 insertions, 40 deletions

diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml
index 553281c39..5559dda05 100644
--- a/src/documentation/content/xdocs/faq.xml
+++ b/src/documentation/content/xdocs/faq.xml
@@ -595,31 +595,7 @@ Can I control this?</question>
     <faq id="svg-headless">
       <question>How do I use FOP with SVG on headless servers?</question>
       <answer>
-        <p>
-          Batik uses AWT classes for rendering SVG, which in turn needs an X
-          server on Unixish systems. If you run a server without X, or if you
-          can't connect to the X server due to security restrictions or
-          policies, SVG rendering will fail.
-        </p>
-        <p>
-          There are still several options:
-        </p>
-        <ul>
-          <li>
-            If you are using JDK 1.4, start it with the -Djava.awt.headless=true
-            command line option.
-          </li>
-          <li>
-            Install a X server which provides an im-memory framebuffer without
-            actually using a screen device or any display hardware, like Xvfb.
-          </li>
-          <li>
-            Use a toolkit which emulates AWT without the need of an underlying X
-            server, like <link
-            href="http://www.eteks.com/pja/en">PJA</link>. The PJA toolkit is
-            free and comes with detailed installation instructions.
-          </li>
-        </ul>
+        <p>See <link href="graphics.html#batik">FOP: Graphics (Batik)</link>.</p>
       </answer>
     </faq>
     <faq id="svghangs">
diff --git a/src/documentation/content/xdocs/graphics.xml b/src/documentation/content/xdocs/graphics.xml
index 66b1b563c..655f42594 100644
--- a/src/documentation/content/xdocs/graphics.xml
+++ b/src/documentation/content/xdocs/graphics.xml
@@ -134,7 +134,19 @@ JAI is much faster than JIMI, but is not available for all platforms. See <link
       </section>
       <section id="batik">
         <title>Batik</title>
-        <p>Current FOP distributions include a distribution of the Apache Software Foundation's <jump href="http://xml.apache.org/batik">Batik</jump> version 1.5beta4. No installation is required. Because Batik's API changes frequently, it is highly recommended that you use this version with FOP.</p>
+        <p>Current FOP distributions include a distribution of the Apache Software Foundation's <jump href="http://xml.apache.org/batik">Batik</jump> version 1.5beta4.
+It is automatically installed with FOP.
+Because Batik's API changes frequently, it is highly recommended that you use the version that ships with FOP, at least when running FOP.</p>
+        <warning>Batik must be run in a graphical environment.</warning>
+        <p>Batik must be run in a graphical environment.
+It uses AWT classes for rendering SVG, which in turn require an X server on Unixish systems.
+If you run a server without X, or if you can't connect to the X server due to security restrictions or policies (a so-called "headless" environment), SVG rendering will fail.</p>
+        <p>Here are some workarounds:</p>
+        <ul>
+          <li>If you are using JDK 1.4, start it with the <code>-Djava.awt.headless=true</code> command line option.</li>
+          <li>Install an X server which provides an in-memory framebuffer without actually using a screen device or any display hardware. One example is Xvfb.</li>
+          <li>Install a toolkit which emulates AWT without the need for an underlying X server. One example is the <link href="http://www.eteks.com/pja/en">PJA toolkit</link>, which is free and comes with detailed installation instructions.</li>
+        </ul>
       </section>
     </section>
     <section id="eps">
diff --git a/src/documentation/content/xdocs/running.xml b/src/documentation/content/xdocs/running.xml
index 399ec804d..3105f4271 100644
--- a/src/documentation/content/xdocs/running.xml
+++ b/src/documentation/content/xdocs/running.xml
@@ -8,22 +8,31 @@
   </header>
 
   <body>
-    <section id="install">
-      <title>Installation</title>
-      <section id="install-overview">
-        <title>Overview</title>
-        <p>The following software must be installed:</p>
-        <ul>
-          <li>Java 1.2.x or later.</li>
-          <li>FOP. The <jump href="http://xml.apache.org/fop/download.html">FOP distribution</jump> includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following:</li>
+    <section id="require">
+      <title>System Requirements</title>
+      <p>The following software must be installed:</p>
+      <ul>
+        <li>Java 1.2.x or later Runtime Environment.</li>
+        <li>FOP. The <link href="download.html">FOP distribution</link> includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following:
           <ul>
-            <li>Apache <jump href="http://xml.apache.org/xerces-j/index.html">Xerces-J</jump> for XML parsing. You can use other XML parsers which support SAX and DOM.</li>
-            <li>Apache Xalan, an XSLT processor.</li>
-            <li>Apache <jump href="http://xml.apache.org/batik/">Batik</jump>, an SVG library.</li>
+            <li><jump href="http://xml.apache.org/xerces-j/index.html">Apache Xerces-J</jump> for XML parsing. You can use other XML parsers which support SAX and DOM.</li>
+            <li><jump href="http://xml.apache.org/xalan-j/index.html">Apache Xalan-J</jump>, an XSLT processor.</li>
+            <li><jump href="http://xml.apache.org/batik/">Apache Batik</jump>, an SVG library.</li>
           </ul>
-          <li>Optional Libraries</li>
-        </ul>
-      </section>
+        </li>
+      </ul>
+      <p>The following sofware is optional, depending on your needs:</p>
+      <ul>
+        <li>Graphics libraries. Support for some graphics formats requires additional packages. See <link href="graphics.html">FOP: Graphics Formats</link> for details.</li>
+        <li>PDF encryption. See <link href="pdfencryption.html">FOP: PDF Encryption</link> for details.</li>
+      </ul>
+      <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. See <link href="graphics.html#batik">FOP: Graphics (Batik)</link> for details.</li>
+      </ul>
+    </section>
+    <section id="install">
+      <title>Installation</title>
       <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 site.</p>