Generating citations and bibliographies with CSL and citeproc-java

I was recently writing a scientific document with AsciiDoc. As usual, my toolchain was AsciiDoc → DocBook → FO → PDF. It really worked quite well until I came to the point where manually adding citations and editing the bibliography by hand became really complex and I suddenly found myself yearning for more automation.

I asked Google what I could do and Google told me about BibTeX and all these things. There even was a tool called asciidoc-bib by Peter Lane that was able to read BibTeX files to generate citations and bibliographies and then put them into an AsciiDoc source file. I tested this tool for a while and contributed one or two commits via GitHub. However, I was not yet convinced by the flexibility and maturity of asciidoc-bib by that time, so I started looking for ways how to extend it.

Enter the Citation Style Language (CSL). CSL is an XML-based description of citation styles and bibliographies that’s maintained by a number of people from the scientific community. They say it’s “by academics, for academics”. I really loved the idea of having a more modern alternative to BibTeX and natbib, which I never found particularly mind-blowing by the way.

I started with extending asciidoc-bib with support for a library called citeproc-ruby by Sylvester Keil. citeproc-ruby is a so-called CSL processor, which means it reads CSL styles and transforms them to citations and bibliographies. However, I still found asciidoc-bib too cumbersome to use, in particular since it was written in Ruby and my toolchain was based on Java.

So I asked Google again, if they could tell me something about CSL and Java, but they said they didn’t know very much about that. That was when I finally decided to write my own CSL processor for Java.

citeproc-java

Today I’m pleased to announce the first release of citeproc-java, a CSL processor for Java! An (almost) complete documentation is available at the following site:

https://michel-kraemer.github.io/citeproc-java/

I have to be honest with you guys. I didn’t implement the whole CSL specification myself. Instead, I tried to incorporate existing code as much as possible. citeproc-java uses the great citeproc-js by Frank G. Bennett, Jr. internally. It is therefore fully CSL 1.0.1-compliant. Apart from that, it offers some cool additional features such as BibTeX import as well as export to AsciiDoc and FO.

For convenience, I uploaded citeproc-java and the CSL styles and locales to Maven central. Please see the installation instructions for more information:

https://michel-kraemer.github.io/citeproc-java/download/

citeproc-java’s BibTeX to CSL mapping is based on the one used in Docear. It has been converted to Java by permission from the Docear authors, in particular Joeran Beel. The BibTeX converter imports author names using the name parser from the citeproc-ruby project. It has been converted to Java by permission from Sylvester Keil. Thank you very much for that!

Although citeproc-java is a very young project and this is the very first release, I consider it rather stable already—not least because it uses citeproc-js under the hood. Nevertheless, development of citeproc-java has just begun and I’m sure there are great features to come. If you want to participate, don’t hesitate to fork my GitHub repository and send me pull requests:

https://github.com/michel-kraemer/citeproc-java

Finally, big thanks go to the CSL community for the great work and support!

License

citeproc-java is licensed under the Apache License, Version 2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

---

Posted by Michel Krämer
on 16 September 2013

---