Added documentation about the citproc.processCitationClusters method.

index.rst

@@ -23,6 +23,7 @@ Table of Contents
    acknowledgements.rst
    changes.rst
    deployments.rst
+   processcitations/specification.rst
    dynamic-editing.rst
    editor.rst
    setting-up.rst

processcitations/specification.rst

@@ -0,0 +1,146 @@
+====================
+Processing Citations
+====================
+
+.. include:: ../substitutions.txt
+|CCBYSA| `Frank Bennett <https://twitter.com/fgbjr>`_
+
+
+---------------------------
+
+------------
+Introduction
+------------
+
+In the section showed how to use citeproc-js to create a stand-alone bibliography. Now, we are going to learn how to use citeproc-js to format citations in the text of a document. 
+
+----------------------------
+processCitationCluster()
+----------------------------
+
+``````
+Setup:
+``````
+
+The primary method used to format citations is the *processCitationCluster()*. It can only be called after instantiating the CSL.Engine. The code for creating the *sys* object and loading style and data are in the tutorial for the stand-alone bibliography. We are using the exact same code as the last tutorial, so we will pick up where we left off.
+
+.. code-block:: javascript
+
+   // Instantiate processor
+   citeproc = new CSL.Engine(citeprocSys, style);
+
+
+``````````````````````````````````
+Calling *processCitationCluster()*
+``````````````````````````````````
+
+Now, we have to call the *processCitationCluster()* method with the three following parameters: *currrentCitationCluster*, *previousCitationClusters*, and *followingCitationClusters*. Before examining how to construct these parameters, let's first address two questions. Why does the processor care about previous citations and following citations? And why does the processor work with *citation clusters* instead of individual citations? 
+
+The processor needs to know about where all citations occur in a given text, because citation formatting contextual. The first time a source is cited, it often requires a "long form" of citation; and following citations are written in "short form." Additionally, citations that are frequently repeated in a short span can have an even more abbreviated citation, such as ("Id.", "Ibid.", etc.) citations in legal writing.
+
+A **citation cluster** is one or more citations that occur at the same point in the text document. The *processCitationCluster()* works with citation clusters, instead of with individual citations, primarily for two reasons. *Reason 1*: In some citation systems, citations that occur in the same place in the document are identified in the same numbered footnote or endnote. *Reason 2*: Even in citation systems that use in-text citations, the ordering of citations within a cluster may be alphabetical, so the citeproc-js engine ensures that each citation is completely correct.
+
+A **cluster ID** is the unique identifier generated by the citeproc-js engine that is given to each processed cluster citation.
+
+
+!!!!!!!!!!!!!!!!!!!!!!!!
+processCitationCluster()
+!!!!!!!!!!!!!!!!!!!!!!!!
+
+The *processCitationCluster()* method accepts three parameters, and can return multiple formatted citations.
+
+.. code-block:: javascript
+
+   citeproc.processCitationCluster( currrentCitationCluster , previousCitationClusters , followingCitationClusters );
+
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+currentCitationCluster Parameter
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The *currentCitationCluster* parameter is an object that contains three properties: 'citationItems', 'properties', and 'citationID'.
+
+**'citationItems'** is a required property that contains an array of objects representing the sources referenced within a citation cluster. The objects within the 'citationItems' array must have a property "id" whose value is the item ID that can be used by the *sys* object to retrieve the relevant information about the source. Optional properties include "locator", "prefix", and "suffix". The "locator" property contains the information needed for users to pinpoint the attribution within a source. The "prefix" property contains an explantory prefix or introductory indicator, such as "see" or "confer". The "suffix" property contains the an explanatory suffix.
+**'properties'** is a required property that contains an object, but the object may be empty. In citation styles that use footnotes or endnotes, the "properties" object must have a "noteIndex" property that contains the value of the footnote number or endnote number occupied by the citation cluster.
+**"citationID"** is an optional property that contains a string. "citationID" is only used when editing an already processed citation cluster. Its value is the *cluster ID* of the citation cluster.
+
+.. code-block:: javascript
+
+   {
+        'citationItems': [ { "id" : sourceID, "locator": pincite, "prefix": explanatoryPrefix, "suffix": explanatorySuffix }, ... ];
+	'properties' : { 'noteIndex' : noteNumber },
+	'citationID' : clusterID
+   }
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+previousCitationClusters Parameter
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The *previousCitationClusters* parameter is an array that lists all the processed citation clusters that proceed the citation cluster in the *currentCitationCluster* parameter. Each preceeding citation cluster is represented by an array with two elements: "clusterID" and "Footnote_number". The preceeding citation clusters must be listed in the order in which they appear in the document in order to obtain accurate results from the processor. If there are no proceeding citation clusters, then *previousCitationClusters* should be passed as an empty array ("[ ]").
+**citationClusterID** is a string whose value is the cluster ID of the citation cluster represented by the array.
+**noteIndex** is a number whose value is the footnote number or endnote number occupied by the citation cluster associated with the array. IF the citation style does not use footnotes or endnotes, then the "noteIndex" **must be 0.**
+
+.. code-block:: javascript
+
+   [ [ clusterID , noteIndex ],  ...  ]
+
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+followingCitationClusters Parameter
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The *followingCitationClusters* parameter is an array that lists all the processed citation clusters that are subsequent to the citation cluster in the *currentCitationCluster* parameter. Each subsequent citation cluster is represented by an array with two elements: "clusterID" and "Footnote_number". The subsequent citation clusters must be listed in the order in which they appear in the document in order to obtain accurate results from the processor. If there are no subsequent citation clusters, then *followingCitationClusters* should be passed as an empty array ("[ ]").
+**citationClusterID** is a string whose value is the cluster ID of the citation cluster represented by the array.
+**noteIndex** is a number whose value is the footnote number or endnote number occupied by the citation cluster associated with the array. IF the citation style does not use footnotes or endnotes, then the "noteIndex" **must be 0.**
+
+.. code-block:: javascript
+
+   [ [ clusterID , noteIndex ], ... ]
+
+
+
+````````````````````````````````````````
+*processCitationCluster()* return values
+````````````````````````````````````````
+
+!!!!!!!!
+Overview
+!!!!!!!!
+
+Calling *processCitationCluster()* will return an array with two child elements. The first element is an object that passes messages from the engine to the application about any errors in processing the citation or changes made to the bibliography. The second child element is an array that contains essential information about one or more processed citation clusters. Each citation cluster is represented by an array that contains *(1)* its position in the document, *(2)* the formatted citation, and *(3)* the cluster's ID.
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*processCitationCluster()* return
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+.. code-block:: javascript
+
+   [
+       {
+           'bibchange': false,
+           'citation_errors': [ ]
+       },
+       [
+	    [ clusterPosition , formattedCitationCluster , clusterID ],  ...
+       ]
+   ]
+
+The intricacies of 'bibchange' and 'citation_errors' are not fully understood by the author at this time. Simply note during normal use, it will always return <i>false</i> for "bibchange", and it will return an empty array for "citation_errors".
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*citationClusters* return value
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. code-block:: javascript
+
+   [
+	[clusterPosition, formattedCitationCluster , clusterID ],  ...
+   ]
+
+
+The *citationClusters* return value is an array of processed citation clusters. Multiple citation clusters may be return, even though only one citation cluster was sent to be processed, because every citation cluster that was updated is returned. Each processed citation is represented by an array with three elements: *clusterPosition*, *formattedCitationCluster*, and *clusterID*.
+
+The **clusterPosition** element contains a number representing the position of the citation cluster relative to all other citation clusters within the document. A position of "0" indicates that it is the first citation cluster in the document.
+
+The **formattedCitationCluster** element is a string whose value is the formatted citation.
+
+The **clusterID** element is a string whose value is the unique identifier for the citation cluster.The cluster ID is generated randomly by the citeproc-js processor at the first time the citation cluster is processed. **The citeproc-js engine has its own internal memory of all bibliographic information that it is fed, and of all citation clusters that it has managed**>. The cluster ID is important, not only for the citeproc-js engine's keyed access to cluster information, but it also serves as a method for **providing a map to the processor of where every citation occurs within a document.** (See *previousCitationClusters* and *followingCitationClusters* parameters.) The citeproc-js engine needs to know the sequence in which citations occur in order to support contextual formatting. (It also needs to know whether any citation clusters have been deleted from the document). The cluster ID is how one ensures that the citeproc-js engine state is constistent with the document's state.