Flipping "citation" to "bibliography" in get.js might be unclear

[austinjp]

Hi @larsgw This may be more of a feature request than an issue. Plus, a question that I'm not sure where else to ask.

I notice that you detect styles preceded with "citation-" and map this to "bibliography" in the citation-js code:

https://github.com/larsgw/citation.js/blob/master/src/Cite/get.js#L52

This is confusing, since CSL styles use both <citation> and <bibliography> sections. For example: https://github.com/citation-style-language/styles/blob/master/harvard-imperial-college-london.csl

I was hunting through the code trying to work out how to use citation.js to produce inline citations, and this threw me off track. I'm happy using it to produce a whole bibliography, but how can it produce a citation like this in the text of an article:

... as recommended by Wallace, Grommit, Tottington et al (2005).

CSL stylesheets provide the formatting instructions, but I'm unclear how to achieve this with citation-js. If this isn't implement, is there a way I can query a Cite object and pull the relevant stylesheet information from it?

Many thanks.

[larsgw]

Using citation-* for bibliographies was a mistake I made in the early days of Citation.js. Since v0.4.0-1, there's a new, hopefully better output system, that can be used with Cite#format():

let cite = new Cite(...)

cite.format(format, {options})

The format param accepts bibliography instead of citation-*, and you can provide templates in the options. To register new templates, a different API is used.

cite.format('bibliography', {
  template: 'apa',
  lang: 'en-US',
  format: 'html'
})

A separate citation options will be provided in the future as well, but I still have to figure out the citeproc API on how to do that for these use cases.

https://github.com/larsgw/citation.js/blob/02db8a96ca2325721b720ef8804bf853af1ec777/src/get/modules/csl/index.js#L26-L29

I don't know of any workarounds right now, apart from getting the parsed data and running them through a citeproc engine yourself, although you might be able to get that engine from Citation.js:

let cite = new Cite(...)
let data = cite.data // [{id: 'a', ...}, ...]
let template = Cite.CSL.style('apa')
let retrieveItem = searchId => data.find(entry => entry.id === searchId)
let retrieveLocale = Cite.CSL.locale // not sure if you'd need a wrapper function for this, i.e.
let retrieveLocale = lang => Cite.CSL.locale(lang)

let engine = Cite.CSL.fetchEngine('apa', 'en-US', template, retrieveItem, retrieveLocale)

/// ...

Note that this API is deprecated, and doesn't have a definite replacement yet. I won't remove it until I do, however. The new API will have a better signature, too.

As for why Cite#get() still accepts citation-*, it's because of backwards compatibility.

[austinjp]

Excellent, many thanks @larsgw -- I'll have a look at this in a few days' time. Really appreciate the pointers and explanation.

[larsgw]

I added support on master, but a new release will take a while, as I have to change some secondary namespaces and APIs first, and have some other things on my mind right now. If you want, you could install it from master temporarily (until a new non-backported release), by setting the version as github:larsgw/citation.js#3063dfc. Alternatively, github:larsgw/citation.js#master would work too, but could include breaking changes in the future.

API:

Cite(...).format('citation', {
  entry: [...] // ids that should be included
               // - can also be a single id
  // other options: template, lang, format (the usual stuff)
})

Feedback on the API is welcome! Citeproc has some other options regarding citations, including locators, prefixes, suffixes, labels and some things regarding ordering, so I can look into support for that, too.

---

Just to be perfectly clear, this part of Citation.js – creating formatted bibliographies and citations from CSL-JSON – is basically just a layer of abstraction on top of Frank Bennett's (and others) great citeproc-js, which should be credited for all the actual formatting. So when I said I can look into support for some features that citeproc-js has, I meant changing my thin layer of abstraction to allow users of Citation.js to use those features of citeproc-js.

[larsgw]

citation support is available in v0.4.0-7 and later.

[will-hart]

Any idea when you might get a chance to update the archive branch so we can try this out via gitcdn?

[larsgw]

@will-hart: I updated the branch. Note that you can, since v0.4.0-7 (and properly since v0.4.0-8), get the builds via npm CDNs, like I now outlined in the archive README.

[will-hart]

Awesome, thank you very much :)