== {{citeproc-js-logo.png}} Coding and deployment ==

Code contributions are welcome.

=== Coding Guidelines ===

New code should follow the [[http://www.zotero.org/support/dev/coding_guidelines|Zotero Coding Guidelines]], and must be
accompanied by tests proving that it works as intended and doesn't
break anything.  Apart from that, it's mostly about common sense and
what works.

=== Development Environment ===

The {{{citeproc-js}}} processor is hosted on [[http://bitbucket.org/fbennett/citeproc-js/|BitBucket]].  
You will need to have [[http://www.selenic.com/mercurial/wiki/|Mercurial (hg)]]
installed to obtain the versioned archive of the sources.
Questions, problems and suggestions for further development should be directed to 
[[http://bitbucket.org/fbennett/citeproc-js/issues/|the issue tracker on the BitBucket project page]].  As the tests and examples shipped
with the source code are an indispensable reference in coming to grips with the operation
of the program, evaluation should begin with the setup of a fully working test-bed environment.

=== Dependencies ===

The processor itself requires a Javascript (ECMAscript) interpreter to run.  Because Javascript
proper does not have a standard means of I/O, particular combinations of software are required
to run the test suites that ship with the source code.

The main test suite runs on the Rhino interpreter, which in turn runs on top of Java.
A copy of Rhino 1.7 is included in the distribution archive, so if you have Java installed
you your system, you should be all set to run the primary tests.  They have been confirmed
to run on Linux, Mac OSX, and Windows platforms.

The distribution also includes a primitive example of an RPC server/client setup
that drives the processor through an API, which may be a suitable model for some
server environments.  The demo runs on the Spidermonkey Javascript engine, with
I/O provided by Python communicating with the Javascript engine using the
{{{python-spidermonkey}}} bridge module and an appropriate JSON module to
encode and decode data transferred across the bridge.  The server/client demo
has been tested only in a Linux environment, using an SVN checkout of {{{python-spidermonkey}}}
compiled from source.  

The following tables provide a guide to the required packages.  Those marked
{{{(pkg)}}} in the **FROM?** column are likely to be available via the package
installer of a typical Linux distribution.

  **For the main test suite**

  |= Language  |= Package |= Ver. |= From? |= URL |
  | Java            |  (JRE)           | 1.5, 1.6    | {{{(pkg)}}}  | http://www.java.com/ |
  | Javascript      | Rhino            |  1.7        | {{{citeproc-js}}} |   http://www.mozilla.org/rhino/ |

  **For the RPC server/client demo**

  //All of the following ...//

  |= Package |= Ver. |= From? |= URL  |
  | Python          |  2.5, 2.6  | {{{(pkg)}}}     |    http://www.python.org/ |
  | libjs.so          | 1.x        | {{{(pkg)}}} |   http://www.mozilla.org/js/spidermonkey/ |
  | python-spidermonkey | SVN | {{{SVN}}}    |   http://code.google.com/p/python-spidermonkey/ |
  | wget            | 1.11   | {{{(pkg)}}} | http://www.gnu.org/software/wget/ |

  //... plus// **one** //of the following://

  |= Language  |= Package |= for Python ver. |= From? |= URL  |
  | Python          | simplejson | 2.5 | {{{(pkg)}}} | http://pypi.python.org/pypi/simplejson/ |
  | Python          | cjson      | 2.5  | {{{(pkg)}}} | http://pypi.python.org/pypi/python-cjson |
  | Python          | json       | 2.6 | n/a | (bundled with Python 2.6) |

Please report any difficulties to the [[http://bitbucket.org/fbennett/citeproc-js/issues/|project tracker on BitBucket]].


=== Data input format ===

The processor does not provide native support for storage and retrieval
of bibliographic records.  Data items must be delivered to the
processor as appropriately formatted JSON objects.  The [[http://bitbucket.org/fbennett/citeproc-js/src/tip/rpc-stuff/data/|{{{./rpc-stuff/data}}}]]
subdirectory of the distribution archive contains files that
illustrate the format required by the processor API methods.
There is not at present a full guide to the field names defined
in the CSL language; for the present, see the 
[[http://xbiblio.svn.sourceforge.net/viewvc/xbiblio/csl/schema/trunk/csl.rnc?revision=940&view=markup|source of the CSL specification]] (in REST-NG) for guidance.

=== Integration ===

The initial development has been done under Rhino, using E4X for the
initial parsing of XML style information, but the engine is not anchored
to E4X.  The small number of DOM instantiation and navigation functions
required by the engine are encased in a wrapper (see {{{CSL.System.Xml}}} in the source archive).
For those who which to use the engine in environments where E4X is
not available, the {{{JunkyardJavascript}}} parser, written in
pure Javascript, demonstrates what is needed to implement of an alternative
XML parser -- {{{JunkyardJavascript}}} itself is not meant for
production use, although it does seem to work).