Clarify documentation on copyForeignObject (fixes #69)

Be explicit about the need to keep the source QPDF object around.

1 files changed, 21 insertions, 11 deletions

diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml
index 18abc013..4fde831a 100644
--- a/manual/qpdf-manual.xml
+++ b/manual/qpdf-manual.xml
@@ -1983,24 +1983,26 @@ outfile.pdf</option>
     Version 3.0 of qpdf introduced the ability to copy objects into a
     <classname>QPDF</classname> object from a different
     <classname>QPDF</classname> object, which we refer to as
-    <firstterm>foreign objects</firstterm>.  This allows arbitrary
-    merging of PDF files.  The <command>qpdf</command> command-line
-    tool provides limited support for basic page selection, including
-    merging in pages from other files, but the library's API makes it
-    possible to implement arbitrarily complex merging operations.  The
-    main method for copying foreign objects is
-    <function>QPDF::copyForeignObject</function>.  This takes an
+    <firstterm>foreign objects</firstterm>. This allows arbitrary
+    merging of PDF files. The &ldqo;from&rdqo;
+    <classname>QPDF</classname> object must remain valid after the
+    copy as discussed in the note below. The <command>qpdf</command>
+    command-line tool provides limited support for basic page
+    selection, including merging in pages from other files, but the
+    library's API makes it possible to implement arbitrarily complex
+    merging operations. The main method for copying foreign objects is
+    <function>QPDF::copyForeignObject</function>. This takes an
     indirect object from another <classname>QPDF</classname> and
     copies it recursively into this object while preserving all object
-    structure, including circular references.  This means you can add
-    a direct object that you create from scratch to a
+    structure, including circular references. This means you can add a
+    direct object that you create from scratch to a
     <classname>QPDF</classname> object with
     <function>QPDF::makeIndirectObject</function>, and you can add an
     indirect object from another file with
-    <function>QPDF::copyForeignObject</function>.  The fact that
+    <function>QPDF::copyForeignObject</function>. The fact that
     <function>QPDF::makeIndirectObject</function> does not
     automatically detect a foreign object and copy it is an explicit
-    design decision.  Copying a foreign object seems like a
+    design decision. Copying a foreign object seems like a
     sufficiently significant thing to do that it should be done
     explicitly.
    </para>
@@ -2012,6 +2014,14 @@ outfile.pdf</option>
     automatically distinguishes between indirect objects in the
     current file, foreign objects, and direct objects.
    </para>
+   <para>
+    Please note: when you copy objects from one
+    <classname>QPDF</classname> to another, the source
+    <classname>QPDF</classname> object must remain valid until you
+    have finished with the destination object. This is because the
+    original object is still used to retrieve any referenced stream
+    data from the copied object.
+   </para>
   </sect1>
   <sect1 id="ref.rewriting">
    <title>Writing PDF Files</title>