OpenSystemsDevelopment / qpdf

Commit 4647acbe3c2266e9add3415a06f4c5e84d49f814

Authored by Jay Berkenbilt
1 parent ba2bae4a

Clarify documentation on copyForeignObject (fixes #69) 

Be explicit about the need to keep the source QPDF object around.
Inline Side-by-side
Showing 2 changed files with 34 additions and 19 deletions
include/qpdf/QPDF.hh
  View file @4647acb
@@ -207,14 +207,19 @@ class QPDF @@ -207,14 +207,19 @@ class QPDF
207 replaceReserved(QPDFObjectHandle reserved, 207 replaceReserved(QPDFObjectHandle reserved,
208 QPDFObjectHandle replacement); 208 QPDFObjectHandle replacement);
209 209
210 - // Copy an object from another QPDF to this one. The return value  
211 - // is an indirect reference to the copied object in this file.  
212 - // This method is intended to be used to copy non-page objects and  
213 - // will not copy page objects. To copy page objects, pass the  
214 - // foreign page object directly to addPage (or addPageAt). If you  
215 - // copy objects that contain references to pages, you should copy  
216 - // the pages first using addPage(At). Otherwise references to the  
217 - // pages that have not been copied will be replaced with nulls. 210 + // Copy an object from another QPDF to this one. Please note that
  211 + // the QPDF object containing the object being copied must stick
  212 + // around because it is still used to retrieve any stream data
  213 + // referenced by the copied objects.
  214 + //
  215 + // The return value is an indirect reference to the copied object
  216 + // in this file. This method is intended to be used to copy
  217 + // non-page objects and will not copy page objects. To copy page
  218 + // objects, pass the foreign page object directly to addPage (or
  219 + // addPageAt). If you copy objects that contain references to
  220 + // pages, you should copy the pages first using addPage(At).
  221 + // Otherwise references to the pages that have not been copied
  222 + // will be replaced with nulls.
218 223
219 // When copying objects with this method, object structure will be 224 // When copying objects with this method, object structure will be
220 // preserved, so all indirectly referenced indirect objects will 225 // preserved, so all indirectly referenced indirect objects will
manual/qpdf-manual.xml
  View file @4647acb
@@ -1983,24 +1983,26 @@ outfile.pdf</option> @@ -1983,24 +1983,26 @@ outfile.pdf</option>
1983 Version 3.0 of qpdf introduced the ability to copy objects into a 1983 Version 3.0 of qpdf introduced the ability to copy objects into a
1984 <classname>QPDF</classname> object from a different 1984 <classname>QPDF</classname> object from a different
1985 <classname>QPDF</classname> object, which we refer to as 1985 <classname>QPDF</classname> object, which we refer to as
1986 - <firstterm>foreign objects</firstterm>. This allows arbitrary  
1987 - merging of PDF files. The <command>qpdf</command> command-line  
1988 - tool provides limited support for basic page selection, including  
1989 - merging in pages from other files, but the library's API makes it  
1990 - possible to implement arbitrarily complex merging operations. The  
1991 - main method for copying foreign objects is  
1992 - <function>QPDF::copyForeignObject</function>. This takes an 1986 + <firstterm>foreign objects</firstterm>. This allows arbitrary
  1987 + merging of PDF files. The &ldqo;from&rdqo;
  1988 + <classname>QPDF</classname> object must remain valid after the
  1989 + copy as discussed in the note below. The <command>qpdf</command>
  1990 + command-line tool provides limited support for basic page
  1991 + selection, including merging in pages from other files, but the
  1992 + library's API makes it possible to implement arbitrarily complex
  1993 + merging operations. The main method for copying foreign objects is
  1994 + <function>QPDF::copyForeignObject</function>. This takes an
1993 indirect object from another <classname>QPDF</classname> and 1995 indirect object from another <classname>QPDF</classname> and
1994 copies it recursively into this object while preserving all object 1996 copies it recursively into this object while preserving all object
1995 - structure, including circular references. This means you can add  
1996 - a direct object that you create from scratch to a 1997 + structure, including circular references. This means you can add a
  1998 + direct object that you create from scratch to a
1997 <classname>QPDF</classname> object with 1999 <classname>QPDF</classname> object with
1998 <function>QPDF::makeIndirectObject</function>, and you can add an 2000 <function>QPDF::makeIndirectObject</function>, and you can add an
1999 indirect object from another file with 2001 indirect object from another file with
2000 - <function>QPDF::copyForeignObject</function>. The fact that 2002 + <function>QPDF::copyForeignObject</function>. The fact that
2001 <function>QPDF::makeIndirectObject</function> does not 2003 <function>QPDF::makeIndirectObject</function> does not
2002 automatically detect a foreign object and copy it is an explicit 2004 automatically detect a foreign object and copy it is an explicit
2003 - design decision. Copying a foreign object seems like a 2005 + design decision. Copying a foreign object seems like a
2004 sufficiently significant thing to do that it should be done 2006 sufficiently significant thing to do that it should be done
2005 explicitly. 2007 explicitly.
2006 </para> 2008 </para>
@@ -2012,6 +2014,14 @@ outfile.pdf&lt;/option&gt; @@ -2012,6 +2014,14 @@ outfile.pdf&lt;/option&gt;
2012 automatically distinguishes between indirect objects in the 2014 automatically distinguishes between indirect objects in the
2013 current file, foreign objects, and direct objects. 2015 current file, foreign objects, and direct objects.
2014 </para> 2016 </para>
  2017 + <para>
  2018 + Please note: when you copy objects from one
  2019 + <classname>QPDF</classname> to another, the source
  2020 + <classname>QPDF</classname> object must remain valid until you
  2021 + have finished with the destination object. This is because the
  2022 + original object is still used to retrieve any referenced stream
  2023 + data from the copied object.
  2024 + </para>
2015 </sect1> 2025 </sect1>
2016 <sect1 id="ref.rewriting"> 2026 <sect1 id="ref.rewriting">
2017 <title>Writing PDF Files</title> 2027 <title>Writing PDF Files</title>