From 4647acbe3c2266e9add3415a06f4c5e84d49f814 Mon Sep 17 00:00:00 2001
From: Jay Berkenbilt <ejb@ql.org>
Date: Sat, 29 Jul 2017 09:25:25 -0400
Subject: Clarify documentation on copyForeignObject (fixes #69)

Be explicit about the need to keep the source QPDF object around.
---
 include/qpdf/QPDF.hh   | 21 +++++++++++++--------
 manual/qpdf-manual.xml | 32 +++++++++++++++++++++-----------
 2 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/include/qpdf/QPDF.hh b/include/qpdf/QPDF.hh
index ad8503dc..58f6af6e 100644
--- a/include/qpdf/QPDF.hh
+++ b/include/qpdf/QPDF.hh
@@ -207,14 +207,19 @@ class QPDF
     replaceReserved(QPDFObjectHandle reserved,
                     QPDFObjectHandle replacement);
 
-    // Copy an object from another QPDF to this one.  The return value
-    // is an indirect reference to the copied object in this file.
-    // This method is intended to be used to copy non-page objects and
-    // will not copy page objects.  To copy page objects, pass the
-    // foreign page object directly to addPage (or addPageAt).  If you
-    // copy objects that contain references to pages, you should copy
-    // the pages first using addPage(At).  Otherwise references to the
-    // pages that have not been copied will be replaced with nulls.
+    // Copy an object from another QPDF to this one. Please note that
+    // the QPDF object containing the object being copied must stick
+    // around because it is still used to retrieve any stream data
+    // referenced by the copied objects.
+    //
+    // The return value is an indirect reference to the copied object
+    // in this file. This method is intended to be used to copy
+    // non-page objects and will not copy page objects. To copy page
+    // objects, pass the foreign page object directly to addPage (or
+    // addPageAt). If you copy objects that contain references to
+    // pages, you should copy the pages first using addPage(At).
+    // Otherwise references to the pages that have not been copied
+    // will be replaced with nulls.
 
     // When copying objects with this method, object structure will be
     // preserved, so all indirectly referenced indirect objects will
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>
-- 
cgit v1.2.3-54-g00ecf