From 13e68b5d711d0840eabf3a297df975e99fc2600a Mon Sep 17 00:00:00 2001
From: Jeremias Maerki <jeremias@apache.org>
Date: Tue, 30 May 2006 12:21:29 +0000
Subject: [PATCH] Updated documentation on the PCL renderer.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@410256 13f79535-47bb-0310-9956-ffa450edef68
---
 .../content/xdocs/trunk/configuration.xml     | 21 +++++++
 .../content/xdocs/trunk/output.xml            | 58 ++++++++++---------
 2 files changed, 51 insertions(+), 28 deletions(-)

diff --git a/src/documentation/content/xdocs/trunk/configuration.xml b/src/documentation/content/xdocs/trunk/configuration.xml
index 188301a0f..a5ad45312 100644
--- a/src/documentation/content/xdocs/trunk/configuration.xml
+++ b/src/documentation/content/xdocs/trunk/configuration.xml
@@ -245,6 +245,27 @@
       </fonts>
     </renderer>]]></source>
     </section>
+    <section id="pcl-renderer">
+      <title>Special Settings for the PCL Renderer</title>
+      <p>
+        Non-standard fonts for the PCL renderer are made available through the Java2D subsystem which means that
+        you don't have to do any custom font configuration in this case but you have to use the font names
+        offered by Java.
+      </p>
+      <p>
+        Additionally, there's one setting that controls how borders are painted.
+      </p>
+<source><![CDATA[<renderer mime="application/vnd.hp-PCL">
+  <rendering>quality</rendering>
+</renderer>]]></source>
+      <p>
+        The default value for the "rendering" setting is "speed" which causes borders 
+        to be painted as plain rectangles. In this mode, no special borders (dotted, 
+        dashed etc.) are available. If you want support for all border modes, set the
+        value to "quality" as indicated above. This will cause the borders to be painted
+        as bitmaps.
+      </p>
+    </section>
   </section>
   </body>
 </document>
diff --git a/src/documentation/content/xdocs/trunk/output.xml b/src/documentation/content/xdocs/trunk/output.xml
index 87e570174..9c701fd76 100644
--- a/src/documentation/content/xdocs/trunk/output.xml
+++ b/src/documentation/content/xdocs/trunk/output.xml
@@ -304,7 +304,6 @@ out = proc.getOutputStream();]]></source>
   </p>
   <section id="pcl">
     <title>PCL</title>
-    <warning>The PCL Renderer is currently in the process of being revived. This is work in progress.</warning>
     <p>
       This format is for the Hewlett-Packard PCL printers and other printers 
       supporting PCL. It should produce output as close to identical as possible 
@@ -317,7 +316,8 @@ out = proc.getOutputStream();]]></source>
       print the output generated by the PCLRenderer. PJL is used to control the
       print job and switch to the PCL language. PCL 5 is used for text, raster 
       graphics and rectangular fill graphics. HP GL/2 is used for more complex
-      painting operations.
+      painting operations. Certain painting operations are done off-screen and
+      rendered to PCL as bitmaps because of limitations in PCL 5.
     </p>
     <section id="pcl-references">
       <title>References</title>
@@ -342,11 +342,11 @@ out = proc.getOutputStream();]]></source>
           metrics and appearance for Helvetica/Arial and Times/Times New are 
           nearly identical, so this has not been a problem so far.
         </li>
+        <li>For the non-symbol fonts, the ISO 8859-1 symbol set is used (PCL set "0N").</li>
         <li>
-          Only the original fonts built into FOP are supported. Support for
-          TrueType fonts will be added later.
+          All fonts available to the Java2D subsystem are usable. The texts are
+          painted as bitmap much like the Windows PCL drivers do.
         </li>
-        <li>For the non-symbol fonts, the ISO 8859-1 symbol set is used (PCL set "0N").</li>
         <li>Multibyte characters are not supported.</li>
         <li>
           At the moment, only monochrome output is supported. PCL5c color extensions
@@ -361,32 +361,34 @@ out = proc.getOutputStream();]]></source>
           to improve the bitmap quality.
         </li>
         <li>
-          Color printing is not supported. Colors are rendered by mapping the color 
-          intensity to one of the PCL fill shades (from white to black in 9 steps).
+          Currently, there's no support for clipping and image transparency, largely 
+          because PCL 5 has certain limitations.
         </li>
       </ul>
     </section>
-
-    <!--section id="pcl-additional">
-      <title>Additional Features</title>
-      <p>There are some special features that are controlled by some public variables on the PCLRenderer class.</p>
-
-      <dl>
-        <dt>orientation</dt>
-        <dd>The logical page orientation is controlled by the public orientation variable. Legal values are:>
-          <ul>
-            <li>0 Portrait</li>
-            <li>1 Landscape</li>
-            <li>2 Reverse Portrait</li>
-            <li>3 Reverse Landscape</li>
-          </ul>
-        </dd>
-        <dt>curdiv, paperheight</dt>
-        <dd>The curdiv and paperheight variables allow multiple virtual pages to be printed on a piece of paper. This allows a standard laser printer to use perforated paper where every perforation will represent an individual page. The paperheight sets the height of a piece of paper in decipoints. This will be divided by the page.getHeight() to determine the number of equal sized divisions (pages) that will fit on the paper. The curdiv variable may be read/written to get/set the current division on the page (to set the starting division and read the ending division for multiple invocations).</dd>
-        <dt>topmargin, leftmargin</dt>
-        <dd>The topmargin and leftmargin may be used to increase the top and left margins for printing.</dd>
-      </dl>
-    </section-->
+    <section id="pcl-configuration">
+      <title>Configuration</title>
+      <p>
+        The PCL renderer configuration currently allows one setting:
+      </p>
+<source><![CDATA[<renderer mime="application/vnd.hp-PCL">
+  <rendering>quality</rendering>
+</renderer>]]></source>
+      <p>
+        The default value for the "rendering" setting is "speed" which causes borders 
+        to be painted as plain rectangles. In this mode, no special borders (dotted, 
+        dashed etc.) are available. If you want support for all border modes, set the
+        value to "quality" as indicated above. This will cause the borders to be painted
+        as bitmaps.
+      </p>
+      <p>
+        You can control the output resolution for the PCL using the "target resolution" 
+        setting on the FOUserAgent. The actual value will be rounded up to the next
+        supported PCL resolution. Currently, only 300 and 600 dpi are supported which
+        should be enough for most use cases. Note that this setting directly affects
+        the size of the output file and the print quality.
+      </p>
+    </section>
   </section>
   <section id="afp">
     <title>AFP</title>
-- 
2.39.5