Skip to content

Commit 5105b75

Browse files
dstillmandstillman
committed
Update README
1 parent f141a07 commit 5105b75

File tree

1 file changed

+52
-57
lines changed

1 file changed

+52
-57
lines changed

‎README.md‎

Lines changed: 52 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
# citeproc-node
1+
# citeproc-js-server
22

3-
Citeproc-node is tested with io.js. It should also work with nodejs 0.12 with harmony features, but
4-
jsdom, on which citeproc-node relies, has moved to io.js.
3+
citeproc-js-server is a Node-based server that generates citations and bibliographies using [citeproc.js](https://github.com/Juris-M/citeproc-js).
54

6-
For optimal performance, you should maintain separate directories with json styles/locales.
5+
For optimal performance, you should maintain separate directories with JSON styles/locales.
76
This can be done by running the included xmltojson.py:
87

98
```
@@ -18,29 +17,30 @@ xmltojson.py --changed 300 ./csl ./csljson
1817
xmltojson.py --changed 300 ./csl-locales ./csljson-locales
1918
```
2019

21-
And point cslPath and localesPath in citeServerConf.json to point to the json directories.
20+
And point `cslPath` and `localesPath` in config/local.json to point to the json directories.
2221

2322
Also note that the citation server automatically watches the style and locale directories
2423
to automatically use the new versions when they're pulled. This is subject to [platform
25-
caveats](https://iojs.org/api/fs.html#fs_caveats)
24+
caveats](https://nodejs.org/api/fs.html#fs_caveats)
2625

27-
## Setting up a standalone citeproc-node server
26+
## Setting up citeproc-js-server
2827

2928
### Step 1
3029

31-
Get citeproc-node
30+
Get citeproc-js-server
3231

3332
```
34-
git clone --recursive https://github.com/zotero/citeproc-node.git
35-
cd citeproc-node
33+
git clone --recurse-submodules https://github.com/zotero/citeproc-js-server.git
34+
cd citeproc-js-server
35+
npm install
3636
```
3737

3838
### Step 2
3939

4040
Start the server:
4141

4242
```
43-
node lib/citeServer.js
43+
npm start
4444
```
4545

4646
If all is well, you will see:
@@ -52,7 +52,7 @@ info Server running at http://127.0.0.1:8085
5252
### Step 3
5353

5454
Now to test the server using the sampledata.json file provided in the
55-
citeproc-node sources. Try posting it to your server, from a separate
55+
citeproc-js-server sources. Try posting it to your server, from a separate
5656
console:
5757

5858
```
@@ -76,24 +76,22 @@ You should see a response similar to this:
7676

7777
## Configuration
7878

79-
Configuration parameters are specified in the *citeServerConf.json* file.
79+
citeproc-js-server uses [node-config](https://github.com/lorenwest/node-config) for configuration. Configuration parameters can be specified in config/local.json or other files and formats supported by node-config.
8080

81-
Citeproc-node now supports csl styles that has been converted to JSON.
81+
citeproc-js-server now supports CSL styles that has been converted to JSON.
8282
This improves performance significantly on style initialization, and somewhat on style execution
83-
over the jsdom xml parsing mode. Local styles can be converted ahead of time which improves performance
84-
even futher, otherwise both local and remote styles will be converted at run time.
83+
over the JSDOM XML parsing mode. Local styles can be converted ahead of time, which improves performance even futher. Otherwise both local and remote styles will be converted at run time.
8584

86-
There is now a python script (xmltojson.py) included to convert a single file or a directory, including
87-
the option to only convert files that have been modified within a specified time limit, to better handle
88-
periodic pulling of style/locale changes.
89-
To use pre-converted json styles, just point the cslPath preference at the directory of converted styles.
85+
There is a Python script, xmltojson.py, to convert a single file or a directory, including
86+
the option to only convert files that have been modified within a specified time limit, to better handle periodic pulling of style/locale changes.
87+
To use pre-converted json styles, just point the `cslPath` preference at the directory of converted styles.
9088

9189
## Running the tests
9290

9391
Start citation server
9492

9593
```
96-
node ./lib/citeServer.js
94+
npm start
9795
```
9896

9997
Run a test with all independent styles in the csl directory:
@@ -102,22 +100,50 @@ Run a test with all independent styles in the csl directory:
102100
node ./test/testallstyles.js
103101
```
104102

103+
## Using the web service
104+
105+
The service responds to HTTP `OPTIONS` or `POST` requests only.
106+
107+
When sending a request, various options should be set in the query string of the URL, and
108+
the CSL-JSON data should be sent in the content body.
109+
110+
The following query string parameters are recognized:
111+
112+
* responseformat - One of `html`, `json`, or `rtf`
113+
(value is passed through to citeproc.js). Default is `json`.
114+
* bibliography - Default is `1`.
115+
* style - This is a URL or a name of a CSL style. Default is `chicago-author-date`.
116+
* locale - Default is `en-US`
117+
* citations - Default is `0`.
118+
* outputformat - Default is `html`.
119+
* memoryUsage - If this is `1`, and the server has debug enabled, the server will respond
120+
with a report of memory usage (and nothing else). Default is `0`.
121+
* linkwrap - Default is `0`
122+
* clearCache - If this `1`, then the server will clear any cached style engines, and
123+
reread the CSL styles. This can only be sent from the localhost. Default is `0`.
124+
125+
The POST data JSON object can have these members:
126+
127+
* items - either an array or a hash of items
128+
* itemIDs - an array of identifiers of those items to convert. If this is not
129+
given, the default is to convert all of the items.
130+
* citationClusters
131+
* styleXML - a CSL style to use
132+
105133

106134
## Included libraries
107135

108136
### csl
109137

110-
Included as a Git submodule.
138+
CSL citation styles, included as a Git submodule
111139

112140
### csl-locales
113141

114-
Included as a Git submodule.
142+
CSL locales, included as a Git submodule
115143

116144
### citeproc-js
117145

118-
Built from [citeproc-js](https://bitbucket.org/fbennett/citeproc-js)
119-
Currently needs minor modifications to work with citeproc-node, so you should not
120-
just drop in new versions at the moment.
146+
The [citeproc-js citation processor](https://github.com/Juris-M/citeproc-js)
121147

122148
## Logging
123149

@@ -139,34 +165,3 @@ In the code, to create a log message at a particular level, for example,
139165
```javascript
140166
log.warn("Uh-oh!");
141167
```
142-
143-
## Using the web service
144-
145-
The service responds to HTTP `OPTIONS` or `POST` requests only.
146-
147-
When sending a request, various options should be set in the query string of the URL, and
148-
the CSL-JSON data should be sent in the content body.
149-
150-
The following query string parameters are recognized:
151-
152-
* responseformat - One of `html`, `json`, or `rtf`
153-
(value is passed through to citeproc.js). Default is `json`.
154-
* bibliography - Default is `1`.
155-
* style - This is a URL or a name of a CSL style. Default is `chicago-author-date`.
156-
* locale - Default is `en-US`
157-
* citations - Default is `0`.
158-
* outputformat - Default is `html`.
159-
* memoryUsage - If this is `1`, and the server has debug enabled, the server will respond
160-
with a report of memory usage (and nothing else). Default is `0`.
161-
* linkwrap - Default is `0`
162-
* clearCache - If this `1`, then the server will clear any cached style engines, and
163-
reread the CSL styles. This can only be sent from the localhost. Default is `0`.
164-
165-
The POST data JSON object can have these members:
166-
167-
* items - either an array or a hash of items
168-
* itemIDs - an array of identifiers of those items to convert. If this is not
169-
given, the default is to convert all of the items.
170-
* citationClusters
171-
* styleXml - a CSL style to use
172-

0 commit comments

Comments
 (0)