Added some notes on getting the same output for PDF/PS and Java2D-based renderers.

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

3 files changed, 73 insertions, 0 deletions

diff --git a/src/documentation/content/xdocs/0.95/output.xml b/src/documentation/content/xdocs/0.95/output.xml
index d6021414f..628df1248 100644
--- a/src/documentation/content/xdocs/0.95/output.xml
+++ b/src/documentation/content/xdocs/0.95/output.xml
@@ -48,6 +48,35 @@
           The net effect is that the layout of a given FO document can be quite different between 
           renderers that do not use the same font information.
         </p>
+        <p>
+          Theoretically, there's some potential to make the output of the PDF/PS renderers match
+          the output of the Java2D-based renderers. If FOP used the font metrics from its own
+          font subsystem but still used Java2D for text painting in the Java2D-based renderers,
+          this could probably be achieved. However, this approach hasn't been implemented, yet.
+        </p>
+        <p>
+          With a work-around, it is possible to match the PDF/PS output in a Java2D-based
+          renderer pretty closely. The clue is to use the
+          <a href="intermediate.html">intermediate format</a>. The trick is to layout the
+          document using FOP's own font subsystem but then render the document using Java2D.
+          Here are the necessary steps (using the command-line):
+        </p>
+        <ol>
+          <li>
+            Produce an IF file: <code>fop -fo myfile.fo -at application/pdf myfile.at.xml</code><br/>
+            Specifying "application/pdf" for the "-at" parameter causes FOP to use FOP's own
+            font subsystem (which is used by the PDF renderer). Note that no PDF file is created
+            in this step.
+          </li>
+          <li>Render to a PDF file: <code>fop -atin myfile.at.xml -pdf myfile.pdf</code></li>
+          <li>Render to a Java2D-based renderer:
+            <ul>
+              <li><code>fop -atin myfile.at.xml -print</code></li>
+              <li><code>fop -atin myfile.at.xml -awt</code></li>
+              <li><code>fop -atin myfile.at.xml -tiff myfile.tiff</code></li>
+            </ul>
+          </li>
+        </ol>
       </section>
       <section id="general-direct-output">
         <title>Output to a Printer or Other Device</title>
diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml
index d488a1f3c..a75cd41e0 100644
--- a/src/documentation/content/xdocs/faq.xml
+++ b/src/documentation/content/xdocs/faq.xml
@@ -645,6 +645,21 @@ Check the following:</p>
         </p>
       </answer>
     </faq>
+    <faq id="pdf-ps-java2d-differences">
+      <question>Why is the output of Java2D/AWT-based renderers different than, for example, PDF or PS?</question>
+      <answer>
+        <p>
+          If you render the same document once to a PNG or TIFF and once into a PDF, the output
+          may not be the same, i.e. line breaks are different or lines may have different heights.
+          The reason for this: The Java2D-based renderers use the font subsystem of Java2D/AWT. The
+          PDF and PS renderers use FOP's own font subsystem which provides much better font metrics
+          than Java2D. These can lead to different layout decisions when the same document is
+          rendered with different renderers. An alternative approach to fix this problem might be
+          available but it hasn't been tested, yet. See also the
+          <link href="0.95/output.html#general-fonts">notes on fonts in the various output formats</link>.
+        </p>
+      </answer>
+    </faq>
   </part>
   <part id="part-embedding">
     <title>Embedding FOP. Using FOP in a servlet.</title>
diff --git a/src/documentation/content/xdocs/trunk/output.xml b/src/documentation/content/xdocs/trunk/output.xml
index d6021414f..628df1248 100644
--- a/src/documentation/content/xdocs/trunk/output.xml
+++ b/src/documentation/content/xdocs/trunk/output.xml
@@ -48,6 +48,35 @@
           The net effect is that the layout of a given FO document can be quite different between 
           renderers that do not use the same font information.
         </p>
+        <p>
+          Theoretically, there's some potential to make the output of the PDF/PS renderers match
+          the output of the Java2D-based renderers. If FOP used the font metrics from its own
+          font subsystem but still used Java2D for text painting in the Java2D-based renderers,
+          this could probably be achieved. However, this approach hasn't been implemented, yet.
+        </p>
+        <p>
+          With a work-around, it is possible to match the PDF/PS output in a Java2D-based
+          renderer pretty closely. The clue is to use the
+          <a href="intermediate.html">intermediate format</a>. The trick is to layout the
+          document using FOP's own font subsystem but then render the document using Java2D.
+          Here are the necessary steps (using the command-line):
+        </p>
+        <ol>
+          <li>
+            Produce an IF file: <code>fop -fo myfile.fo -at application/pdf myfile.at.xml</code><br/>
+            Specifying "application/pdf" for the "-at" parameter causes FOP to use FOP's own
+            font subsystem (which is used by the PDF renderer). Note that no PDF file is created
+            in this step.
+          </li>
+          <li>Render to a PDF file: <code>fop -atin myfile.at.xml -pdf myfile.pdf</code></li>
+          <li>Render to a Java2D-based renderer:
+            <ul>
+              <li><code>fop -atin myfile.at.xml -print</code></li>
+              <li><code>fop -atin myfile.at.xml -awt</code></li>
+              <li><code>fop -atin myfile.at.xml -tiff myfile.tiff</code></li>
+            </ul>
+          </li>
+        </ol>
       </section>
       <section id="general-direct-output">
         <title>Output to a Printer or Other Device</title>