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 207 replaceReserved(QPDFObjectHandle reserved,
208 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 224 // When copying objects with this method, object structure will be
220 225 // preserved, so all indirectly referenced indirect objects will
... ...
manual/qpdf-manual.xml
  View file @4647acb
... ... @@ -1983,24 +1983,26 @@ outfile.pdf</option>
1983 1983 Version 3.0 of qpdf introduced the ability to copy objects into a
1984 1984 <classname>QPDF</classname> object from a different
1985 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 1995 indirect object from another <classname>QPDF</classname> and
1994 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 1999 <classname>QPDF</classname> object with
1998 2000 <function>QPDF::makeIndirectObject</function>, and you can add an
1999 2001 indirect object from another file with
2000   - <function>QPDF::copyForeignObject</function>. The fact that
  2002 + <function>QPDF::copyForeignObject</function>. The fact that
2001 2003 <function>QPDF::makeIndirectObject</function> does not
2002 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 2006 sufficiently significant thing to do that it should be done
2005 2007 explicitly.
2006 2008 </para>
... ... @@ -2012,6 +2014,14 @@ outfile.pdf&lt;/option&gt;
2012 2014 automatically distinguishes between indirect objects in the
2013 2015 current file, foreign objects, and direct objects.
2014 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 2025 </sect1>
2016 2026 <sect1 id="ref.rewriting">
2017 2027 <title>Writing PDF Files</title>
... ...