1 files changed, 37 insertions, 1 deletions
diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml
index c14d0bdf..241431b9 100644
--- a/manual/qpdf-manual.xml
+++ b/manual/qpdf-manual.xml
@@ -5070,13 +5070,40 @@ print "\n";
        <itemizedlist>
         <listitem>
          <para>
+          Note: the changes in this section cause differences in
+          output in some cases. These differences change the syntax of
+          the PDF but do not change the semantics (meaning). I make a
+          strong effort to avoid gratuitous changes in qpdf's output
+          so that qpdf changes don't break people's tests. In this
+          case, the changes significantly improve the readability of
+          the generated PDF and don't affect any output that's
+          generated by simple transformation. If you are annoyed by
+          having to update test files, please rest assured that
+          changes like this have been and will continue to be rare
+          events.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
           <function>QPDFObjectHandle::newUnicodeString</function> now
           uses whichever of ASCII, PDFDocEncoding, of UTF-16 is
           sufficient to encode all the characters in the string. This
           reduces needless encoding in UTF-16 of strings that can be
           encoded in ASCII. This change may cause qpdf to generate
           different output than before when form field values are set
-          using <classname>QPDFFormFieldObjectHelper</classname>.
+          using <classname>QPDFFormFieldObjectHelper</classname> but
+          does not change the meaning of the output.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          The code that places form XObjects and also the code that
+          flattens rotations trim trailing zeroes from real numbers
+          that they calculate. This causes slight (but semantically
+          equivalent) differences in generated appearance streams and
+          form XObject invocations in overlay/underlay code or in user
+          code that calls the methods that place form XObjects on a
+          page.
          </para>
         </listitem>
        </itemizedlist>
@@ -5184,6 +5211,15 @@ print "\n";
           contents of a file through a pipeline as binary data.
          </para>
         </listitem>
+        <listitem>
+         <para>
+          Add option to <function>QUtil::double_to_string</function>
+          to trim trailing zeroes, which is on by default. Within the
+          qpdf library, this causes changes to output the from code
+          that places form XObjects and the code that flattens
+          rotations.
+         </para>
+        </listitem>
        </itemizedlist>
       </listitem>
       <listitem>