From 7f0a9b9f4448f7f2e87313e9e147b631b687e81b Mon Sep 17 00:00:00 2001
From: Robin Watts <Robin.Watts@artifex.com>
Date: Sat, 3 Jun 2017 21:27:33 -0700
Subject: Tweak pdf_graft_map API.

Passing a pdf_document to pdf_graft_object to specify the source
document is redundant, as if we need to know the document, it will
be pickled into the object we are copying.

Similarly, repeatedly having to pass the destination document
seems silly when we can just pickle it into the map too (and this
removes the possibility of people using a different destination
document part way through).

This leaves to simplifying the pdf_graft_object call, at the expense
of splitting it into 2 calls - one with a map, and one without.

Also, we can delay the creation of the mapping table until we are
first asked to copy an object that requires deep copying. This
avoids us ever having to manually pass in the source document.

This has knock-on effects in the java and javascript classes, but
with the advantage of being clearer in the end (IMHO).

Conflicts:
	include/mupdf/pdf/document.h
---
 docs/manual-mutool-run.html | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/manual-mutool-run.html b/docs/manual-mutool-run.html
index 596d11a2..59bb8cc1 100644
--- a/docs/manual-mutool-run.html
+++ b/docs/manual-mutool-run.html
@@ -678,11 +678,15 @@ The buffer must contain already compressed data that matches the Filter and Deco
 The following functions can be used to copy objects from one document to another:
 
 <dl>
-<dt>PDFDocument#graftObject(sourceDocument, object, sourceGraftMap)
-<dd>Deep copy an object into the destination document. The graft map may be null, but should be used if you
-are copying several objects from the same source document using multiple calls to graftObject.
+<dt>PDFDocument#graftObject(object)
+<dd>Deep copy an object into the destination document. This function will not remember previously
+copied objects.
+If you are copying several objects from the same source document using multiple calls, you should
+use a graft map instead.
 <dt>PDFDocument#newGraftMap()
 <dd>Create a graft map for the source document, so that objects that have already been copied can be found again.
+<dt>PDFGraftMap#graftObject(object)
+<dd>Use the graft map to copy objects, with the ability to remember previously copied objects.
 </dl>
 
 <p>
-- 
cgit v1.2.3