diff options
Diffstat (limited to 'manual')
-rw-r--r-- | manual/qpdf-manual.xml | 32 |
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> |