Advice on upgrading to latest version

[dazza-codes]

Sylvester,

We have a project (created in 2013) using gem 'citeproc-ruby', '0.0.6' and could really use some helpful advice on how to upgrade either to the latest 0.x version or the latest 1.x version. Our code uses the gem like this:

def cite(citation_data)
  apa_csl_file = Rails.root.join('app', 'data', 'apa.csl')
  CiteProc.process(citation_data, style: apa_csl_file, format: 'html')
end

csl_report = {
 "id"=>"sulpub",
 "type"=>"report",
 "author"=>[{"family"=>"Imberman", "given"=>"S"}, {"family"=>"Kugler", "given"=>"A. D."}, {"family"=>"Sacerdote", "given"=>"B."}],
 "title"=>"Katrina's children: evidence on the structure of peer effects from hurricane evacuees",
 "issued"=>{"date-parts"=>[[2009], [1], [1]]},
 "number"=>"15291",
 "publisher"=>"National Bureau of Economic Research",
 "URL"=>"http://www.nber.org/papers/w15291"
}

cite(csl_report)
#=> "Imberman, S., Kugler, A. D., &#38; Sacerdote, B. (2009). <i>Katrina's children: evidence on the structure of peer effects from hurricane evacuees</i> (No. 15291). National Bureau of Economic Research. Retrieved from http://www.nber.org/papers/w15291"

BTW, I'm wondering what the order of date values should be for:

"issued"=>{"date-parts"=>[[2009], [1], [1]]},

Thanks in advance,
Darren

[inukshuk]

Early adopters! :)

The cite processor and the CSL library was completely re-written from scratch between 0.x and 1.x. so it's probably best for you to update to the latest version. However, as you're aware, the API has changed completely. Many of the more advanced features require state (e.g., rendering ibid citations, suppressing author names in subsequent references, etc.) so the typical workflow is more akin to the one described in the Read Me: create a processor instance with a style and locale, import your library, cite items by id or render references by id.

If you don't require any of the more advanced features, and you're just interested in one-off renditions of references you can bypass the cite processor and use the renderer directly. This would look something like this:

require 'citeproc/ruby'
require 'csl/styles'

style = CSL::Style.load('apa')
style.title
#=> "American Psychological Association 6th edition"

cp = CiteProc:: Ruby::Renderer.new format: 'html'

item = CiteProc::CitationItem.new id: 'sulpub'
item.data = CiteProc::Item.new({
  id: 'sulpub',
  type: 'report',
  author: ['Imberman, S.', 'Kugler, A. D.', 'B. Sacerdote'],
  title: "Katrina's children: evidence on the structure of peer effects from hurricane evacuees",
  issued: '2009-01-01',
  number: 15291,
  publisher: 'National Bureau of Economic Research',
  url: 'http://www.nber.org/papers/w15291'
})

cp.render item, style.bibliography
#=> "Imberman, S., Kugler, A. D., &amp; Sacerdote, B. (2009). <i>Katrina's children: evidence on the structure of peer effects from hurricane evacuees</i> (No. 15291). National Bureau of Economic Research."

Note that if you pass names as strings, citeproc-ruby tries to parse them (see how 'B. Sacerdote' was parsed corretly). As long as you don't have special requirements this should work fine (check out the namae parser for details); similarly, citeproc-ruby allows you to specify dates using EDTF (see edtf-ruby for details) so you can just write '2009-01-01', or just '2009' would be fine, too.

You can install the 'csl-styles' gem I'm using in the example above to get a recent version of all CSL styles, but you can obviously load just any CSL 1.0.1 style.

[dazza-codes]

We've captured a link to this helpful advice on our github issue tracker. I want to suggest that some form of your advice might make their way into the main readme.md because it's helpful to see how that works for an individual CitationItem. (This might help with closing this issue, but I think you can close at will because we have a link to it that should persist after it's closed.) Thanks again!