diff --git a/functions/pdf.xml b/functions/pdf.xml
index 8f4662c403..b17464c5f4 100644
--- a/functions/pdf.xml
+++ b/functions/pdf.xml
@@ -6,59 +6,64 @@
    <sect1 id="pdf.intro">
     <title>Introduction</title>
     <simpara>
-     You can use the PDF functions in PHP to create PDF files if you
-     have the PDF library by Thomas Merz (available at 
-     <ulink url="&url.pdf;">&url.pdf;</ulink>;
-     you will also need <ulink url="&url.jpeg;">the JPEG library</ulink>
-     and <ulink url="&url.tiff;">the TIFF library</ulink> to
-     compile this. These two librariess can often cause problems when
-     configuring PHP, so be sure to pay attention to the output of
-     the configure script and fix any problems it reports.
+    The PDF functions in PHP can create PDF files using the PDFlib
+    library created by <ulink url="&url.pdflib.merz;">Thomas
+    Merz</ulink>.  PDFlib is available at <ulink
+    url="&url.pdf;">&url.pdf;</ulink>.  The <ulink
+    url="&url.jpeg;">JPEG</ulink> and <ulink
+    url="&url.tiff;">TIFF</ulink> libraries are required to compile
+    this extension.  Please see the <link
+    linkend="install.configure.with-pdflib">PDFlib installation</link>
+    section for more information about compiling PDF support into PHP.
     </simpara>
     <simpara>
-     Please consult the documentation for PDFlib shipped with
+     Please consult the documentation for PDFlib included with
      the source distribution of PDFlib.  It provides a very good
      overview of what PDFlib is capable of doing and contains the full
-     and most up-to-date description of all functions.
+     and most up-to-date documentation of all functions.
     </simpara>
     <simpara>
-     All of the functions in PDFlib and the PHP module have the same name.
-     The parameters are also identical.
-     You should also understand some of the concepts of PDF
-     or PostScript to efficiently use this module.
-     All lengths and coordinates are measured in PostScript points.
-     There are generally 72 PostScript points to an inch, but this
-     depends on the output resolution.
+     All of the functions in PDFlib and the PHP module have identical
+     function names and parameters. You will need to understand some
+     of the basic concepts of PDF and PostScript to efficiently use
+     this extension.  All lengths and coordinates are measured in
+     PostScript points. There are generally 72 PostScript points to an
+     inch, but this depends on the output resolution.  Please see the
+     PDFlib documentation included with the source distribution of
+     PDFlib for a more thorough explanation of the coordinate system
+     used.
     </simpara>
-    <simpara>
-     There is another PHP module for PDF document creation based on
-     <ulink url="&url.cpdf;">FastIO's</ulink>.
-     ClibPDF. It has a slightly different API. Check the
-     <link linkend="ref.cpdf">ClibPDF functions</link> section for
-     details.
-    </simpara>
-    <simpara> 
-     The PDF module introduces one new type of variable.
-     It is called a <parameter>pdf object</parameter> and
-     almost all functions need a <parameter>pdf object</parameter> 
-     as its first parameter.
-     </simpara>
+   <simpara> 
+    Please note that most of the PDF functions require a
+    <parameter>pdf object</parameter> as it's first parameter.  Please
+    see the examples below for more information.
+   </simpara>
+   <note>
+    <para>
+     An alternative PHP module for PDF document creation based on
+     <ulink url="&url.cpdf;">FastIO's</ulink> ClibPDF is
+     available.  Please see the <link linkend="ref.cpdf">ClibPDF</link>
+     section for details.  Note that <link
+     linkend="ref.cpdf">ClibPDF</link> has a slightly different API
+     compared to PDFlib.
+    </para>
+   </note>
    </sect1>
    <sect1 id="pdf.oldlibs.confusion">
-    <title>Confusion with old PDFlib versions</title>
-    <simpara>  
-     Starting with PHP 4.0.5, the PHP extension for PDFlib is officially
-     supported by PDFlib GmbH. This means that all the functions
-     described in the PDFlib-manual (V3.00 or greater) are supported by
-     PHP 4 with exactly the same meaning and the same parameters.
-     Only the return values may differ from the PDFlib manual, because
-     the PHP convention of returning <literal>false</literal> was adopted.
-     For compatibility reasons this binding for
-     PDFlib still supports the old functions, but as stated above
-     they should be replaced by their new versions. PDFlib GmbH will not
-     support any problems arising from the use of these deprecated
-     functions. 
-    </simpara>
+    <title>Confusion with old PDFlib versions</title> 
+   <simpara>
+    Starting with PHP 4.0.5, the PHP extension for PDFlib is
+    officially supported by PDFlib GmbH. This means that all the
+    functions described in the PDFlib manual (V3.00 or greater) are
+    supported by PHP 4 with exactly the same meaning and the same
+    parameters. Only the return values may differ from the PDFlib
+    manual, because the PHP convention of returning
+    <literal>false</literal> was adopted. For compatibility reasons
+    this binding for PDFlib still supports the old functions, but they
+    should be replaced by their new versions. PDFlib GmbH will not
+    support any problems arising from the use of these deprecated
+    functions.
+   </simpara>
     <para>
      <table>
       <title>Deprecated functions and its replacements</title>
@@ -219,10 +224,10 @@
     </para>
    </sect1>
    <sect1 id="pdf.install.pdflib">
-    <title>Hints for installation of PDFlib 3.x</title>
+    <title>PDFlib 3.x Installation Hints</title>
     <simpara>
-     Since version 3.0 of PDFlib you should configure PDFlib with the option
-     <literal>--enable-shared-pdflib</literal>.
+     When using version 3.x of PDFlib, you should configure PDFlib
+     with the option <literal>--enable-shared-pdflib</literal>.
     </simpara>
    </sect1>
    <sect1 id="pdf.oldlibs.hints">
@@ -232,7 +237,7 @@
       of PDFlib older than 3.0.
     </simpara>
     <simpara>
-      PDFlib 3.0 or greater is also supported by PHP 3.0.19 and later.
+      PDFlib 3.0 or greater is supported by PHP 3.0.19 and later.
     </simpara>
    </sect1>
    <sect1 id="pdf.examples">