Hi, Simon.
The documentation for citeproc-js needs an update, for sure. We should
move this discussion to the citeproc-js issue tracker
(https://bitbucket.org/fbennett/citeproc-js/issues), but here’s an
immediate answer.
The restoreProcessorState() method is meant only for restoring state
from skeleton data retrieved from a document or cached data, when the
instantiated processor from a previous session (with its internal
state) is no longer available. It provides one way of restoring state,
but you can get by without it (see below).
A few months ago, I put in some time with the integration code in MLZ,
to optimise things for large documents. Here’s how the code there is
set up.On Thu, Sep 20, 2012 at 4:59 PM, Simon Hewitt <@Simon_Hewitt> wrote:
Image a source list consisting of 6 references (doesn’t matter what they
are):
Select References 1, 3, 5 and make a citation giving the output “(1-3)”.
Select References 2, 4, 6 and make a citation giving the output “(4-6)”.
Select Reference 1 to 6 and make a citation. I am getting “(1,4,2,5,3,6)”
rather than the expected “(1-6)”
This is in Docear4Word (I am the part-time developer) and currently I am
using RestoreProcessorState passing in a list of all the citations in the
document exactly as they are found.
My questions are:
-
Is “(1-6)” actually the expected behaviour? I assume it should be
where citation numbers are used
-
Does RestoreProcessorState work differently than processing
clusters?
To force refresh of a document (or to initialise it in the first
place), this should work:
(0) Identify the itemIDs used in the document, by iterating over its
citation objects, if any.
(1) Call:
updateItems(itemIDs, false, true)
with an array of the itemIDs to be initialised. This will reset all
disambiguation data in the processor registry.
(2) Iterate over the document citation objects, extracting a
sequential list of “citation hints”, each consisting of a citationID
and a note position. (If necessary, assign a unique citationID to
citation objects that lack one.)
(3) Iterate over the citation objects again, calling:
processCitationCluster(citation, preHints, postHints, 2)
where citation is a full citation object, preHints are the hints for
citations that fall before the citation, postHints are those that fall
after, and “2” is the value of CSL.ASSUME_ALL_ITEMS_REGISTERED. For
each iteration, cache the return values (string/index pairs) in an
update array.
(4) Iterate over the freshly constructed update array, pushing a
string into the document at each index.
For a single citation edit or insertion, the transaction works like this:
(0) Identify the itemIDs used in the document, by iterating over its
citation objects, if any.
(1) Call:
updateItems(itemIDs)
itemIDs being the array of IDs contained in the document. This will
prime the processor registry with essential disambiguation parameters
needed to produce a bibliography, taking account of the new citation
(if any) and any items deleted since the last time the processor
touched the document.
(2) Call:
processCitationCluster(citation, preHints, postHints, 2)
citation being a citation object, preHints and postHints being
citationID/noteNumber pairings in document order, and “2” being the
value of CSL.ASSUME_ALL_ITEMS_REGISTERED. This will force any
adjustments needed due to cut-and-paste reordering of citations within
the document, et cetera. The result object that comes back will again
contain a string and index for each citation requiring an update
(including the primary citation being added/edited).
(3) Iterate over the return array and perform document insertions.
Code that runs in this way can be found at:
zotero/chrome/content/zotero/xpcom/integration.js at multi · fbennett/zotero · GitHub
It’s not easy code to follow, but if you concentrate on the two
functions above, it may come into focus.
(For followup, let’s meet by mail, or over on the citeproc-js tracker.)
Frank