Generating citations and bibliographies with CSL and citeproc-java

I was re­cently writ­ing a sci­entific doc­u­ment with As­ciiDoc. As usual my tool­chain was As­ciiDoc → Doc­Book → FO → PDF. It really worked quite well un­til I came to the point where manu­ally adding cita­tions and edit­ing the bib­li­o­graphy by hand be­came really com­plex and I sud­denly found my­self yearn­ing for more auto­ma­tion.

I asked Google what I could do and Google told me about Bib­TeX and all that stuff. There even was a tool called as­ciidoc-bib by Peter Lane that was able to read Bib­TeX files to gen­er­ate cita­tions and bib­li­o­graph­ies and then put them into an As­ciiDoc source file. I tested this tool for a while and con­trib­uted one or two com­mits via Git­Hub. However, I was not yet con­vinced by the flex­ib­il­ity and ma­tur­ity of as­ciidoc-bib by that time, so I star­ted look­ing for ways how to ex­tend it.

Enter the Cita­tion Style Lan­guage (CSL). CSL is an XML-based de­scrip­tion of cita­tion styles and bib­li­o­graph­ies that’s main­tained by a num­ber of people from the sci­entific com­munity. They say it’s “by aca­dem­ics, for aca­dem­ics”. I really loved the idea of hav­ing a more mod­ern al­tern­at­ive to Bib­TeX and nat­bib which I never found par­tic­u­larly mind-blow­ing by the way.

I star­ted with ex­tend­ing as­ciidoc-bib with sup­port for a lib­rary called cite­proc-ruby by Sylvester Keil. cite­proc-ruby is a so-called CSL pro­cessor. That means it reads CSL styles and trans­forms them to cita­tions and bib­li­o­graph­ies. However, I still found as­ciidoc-bib too cum­ber­some to use, in par­tic­u­lar since it was writ­ten in Ruby and my tool­chain was based on Java.

So I asked Google again, if they could tell me something about CSL and Java, but they said they did­n’t know very much about that. That was when I fi­nally de­cided to write my own CSL pro­cessor for Java.


Today I’m pleased to an­nounce the first re­lease of cite­proc-java, a CSL pro­cessor for Java! An (al­most) com­plete doc­u­ment­a­tion is avail­able at the fol­low­ing site:

I have to be hon­est with you guys. I did­n’t im­ple­ment the whole CSL spe­cific­a­tion my­self. In­stead I tried to in­cor­por­ate ex­ist­ing code as much as pos­sible. cite­proc-java uses the great cite­proc-js by Frank G. Ben­nett, Jr. in­tern­ally. It is there­fore fully CSL 1.0.1-com­pli­ant. Apart from that, it of­fers some cool ad­di­tional fea­tures such as Bib­TeX im­port as well as ex­port to As­ciiDoc and FO.

For con­veni­ence I up­loaded cite­proc-java and the CSL styles and loc­ales to Maven cent­ral. Please see the in­stall­a­tion in­struc­tions for more in­form­a­tion:

cite­proc-java’s Bib­TeX to CSL map­ping is based on the one used in the Docear soft­ware. It has been con­ver­ted to Java by per­mis­sion from the Docear au­thors, in par­tic­u­lar Jo­eran Beel. The Bib­TeX con­verter im­ports au­thor names us­ing the name parser from the cite­proc-ruby pro­ject. It has been con­ver­ted to Java by per­mis­sion from Sylvester Keil. Thank you very much for that!

Al­though cite­proc-java is a very young pro­ject and this is the very first re­lease, I con­sider it rather stable already—not least be­cause it uses cite­proc-js un­der the hood. Nev­er­the­less, de­vel­op­ment of cite­proc-java has just be­gun and I’m sure there are great fea­tures to come. If you want to par­ti­cip­ate, don’t hes­it­ate to fork my Git­Hub re­pos­it­ory and send me pull re­quests:

Fi­nally, big thanks go to the CSL com­munity for the great work and sup­port!


cite­proc-java is li­censed un­der the Apache Li­cense, Ver­sion 2.0.

Un­less re­quired by ap­plic­able law or agreed to in writ­ing, soft­ware dis­trib­uted un­der the Li­cense is dis­trib­uted on an “AS IS” BASIS, WITHOUT WAR­RANTIES OR CON­DI­TIONS OF ANY KIND, either ex­press or im­plied. See the Li­cense for the spe­cific lan­guage gov­ern­ing per­mis­sions and lim­it­a­tions un­der the Li­cense.

Posted by Michel Krämer
on September, 16th 2013.