Where to find details

CSL Usage
1

Hey,
I have developed with and around CSL for ~ 9 years, but I find it increasingly difficult to find details about formats, available fields, etc. . I am using citeproc-js inside my own citeproc-plus bundle and have not been able to find concrete answers about:

  • Which version is up-to date? There is a dead link to a version 1.0.1 on the main citeproc-js page (why was that document removed?) [1], most other places there are links to a version 1.0.2, but I also see some discussion on a version 1.2 that is/was under development several years ago [2]. I have a feeling that if I as a developer who has worked with these things need to spend a day understand what is what, then the situation will potentially be worse for new-comers.

  • In the CSL JSON input, how do I specify a short title? I see it says “title-short”/“shortTitle” in some places [3] and then it says it’s deprecated in other places [4]. Is it just deprecated when writing a style but not the JSON with the citation items?

  • I understand the CSL community prefers for titles to be stored in sentence case. I do understand the reasons for this, but unfortunately that is not an option for us given that we also have a LaTeX community. It can also be confusing for end users if they need to type something else into the bibliography manager than what it says on the cover of the book. So we need to store English language titles in title case and put those <span class="nocase"></span> around those capitalized words that should not be converted to sentence case. From the documentation it’s not clear to me how I can specify that a title is in title case. There is something in the documentation that conversion to sentence case is still possible but will be removed in the future [5]. How/where do I access that? Is ti code that I can take to use myself in case it is eventually dropped by CSL?

[1] GitHub - Juris-M/citeproc-js: A JavaScript implementation of the Citation Style Language (CSL) https://citeproc-js.readthedocs.io (contains a dead link to a CSL spec)
[2] CSL 1.2 Planning
[3] documentation/specification.rst at master · citation-style-language/documentation · GitHub
[4] schema/csl-data.json at master · citation-style-language/schema · GitHub schema/csl-data.json at master · citation-style-language/schema · GitHub
[5] CSL 1.0.2 Specification — Citation Style Language 1.0.1-dev documentation

2

Which version is up-to date?

1.0.2
As for most FLOSS projects, you should look to the CSL project’s repositories and documentation for this: 1.0.2 is the latest tagged release of the schema, it’s the automatically updated branch of the styles repository as explained in the style repositories readme, and it’s the documentation/specification branch marked as stable. In addition, the 1.0.2 release was previewed and announced on Twitter, previewed on our blog (though admittedly we never announced it there) and discussed and announced here on the forums.
I’m sure we could do better – we’re a small, thinly stretched team of volunteers – but I’m honestly a bit baffled why you’d take a >3 year old forum post
(that is followed by a discussion making clear the uncertainty about future versioning) and a broken (!) link on a third party repository and conclude that there is any ambiguity about this or spend a day (?!) figuring this out.

why was that document removed?

It wasn’t. I think the link broke (accidentally and I don’t think we can re-direct post-hoc on readthedocs) as we aligned how we’re referring to version number across various CSL repositories. The CSL 1.0.1 specifications remain available here and are available via the version selector in readthedocs.

In the CSL JSON input, how do I specify a short title?

title-short (or shortTitle, but I’d go with the former), as per the tagged release of the CSL JSON data schema. There is discussion and a preliminary decision towards a reworked model for titles in v1.1 (which is what you found), but that’s a good bit out.

From the documentation it’s not clear to me how I can specify that a title is in title case.

You can’t. As you say, CSL styles assume sentence case, and CSL doesn’t allow you (or have any way) to specify otherwise. If you have data in (marked up) title case, I’d recommend (auto-)converting that into sentence case for English before putting the title into the CSL JSON, which shouldn’t be too hard (it’s, e.g., what the BetterBibTeX add-on for Zotero does to translate between bibtex and CSL and back. I think you’ve worked with Emiliano before, so he might be willing to help).

There is something in the documentation that conversion to sentence case is still possible

text-case="sentence", a naive conversion to sentence case, is valid CSL and implemented in citeproc-js (though, as you note, deprecated and we don’t allow it on title elements for styles on the repository), but I don’t really see how that helps you here unless you want to auto-convert every single CSL style that currently doesn’t specify a text-case attribute on a title to add it (which seems much messier than what I suggest above).

3

I started out with receiving a request to add certain fields to our citation translator and therefore I wanted to research which fields there are available in CSL and what kind of data types they accept. This also included whether all fields would allow inline case protection. So I started out on the main website [1] and tried to click through “authors” “publishers” and “developers”, but didn’t find the information I needed anywhere there. I didn’t see anything about CSL versions and which one is current, etc. either.
I then remembered that I earlier found some of the information of styling within styrings on the citeproc-js page, so I continued looking through the README at of the cireproc-js repo [2]. Eventually, after clicking quite a bit, I found some of the information but it seemed contradictory (see last post). Eventually I started googling for the info I wanted and that is how I came across the 3 year old post and a few other ones that seemed to suggest that the versions I was dealing with had been outdated quite a while ago.

It’s entirely possible that I am just getting old and that the information is easily accessible on the citationstyles.org website. But if it’s not, then I would appreciate if it could be put there:

  • Info about which CSL version is current
  • Info about which fields and types exist in that version
  • Info about inline styling and whether it is available in all fields or just some fields

Yes, so I didn’t actually understand that there was a problem until I received an answer from him on a github issue I opened asking him to verify some of the other things because I hadn’t been able to find the right information [3].

OK, thanks. it sounds like I will need to add a converter to sentence case then.

[1] http://citationstyles.org/
[2] GitHub - Juris-M/citeproc-js: A JavaScript implementation of the Citation Style Language (CSL) https://citeproc-js.readthedocs.io
[3] Is καί lower case? · Issue #131 · fiduswriter/biblatex-csl-converter · GitHub

4

All of this is in the specification, which is the first link in the developer tab (and technically on the citationstyles domain, so I guess it counts as “on the site” :stuck_out_tongue_closed_eyes:). We can try to update some of the references to 1.0.1 on the webpages, but for up to date information, the links to schema and specification are always going to be your best bet, because that’s where the actual releases happen. I’m reluctant to put more detailed info on the website, because, as you saw, we’re already having a hard time keeping the existing info current and it is one more thing to do in the already fairly involved process of a new release.

5

All of this is in the specification, which is the first link in the developer tab (and technically on the citationstyles domain, so I guess it counts as “on the site” :stuck_out_tongue_closed_eyes:).

Ok, yes the specification documents was one of the earliest files I found. But clicking around in the index there and trying to scan through it, I didn’t find either the types (article, book, journal-article) nor the fields. Instead I found things that seemed related to writing style files, so after 30-60 minutes or so, I concluded that this was probably just a document about writing styles and gave up finding the information I needed and tried looking other places instead.

I tried now again, but I still cannot find it. All the terms in the index where I think this might be it turned out to be about something else.

6

Ah I now found a very brief list in the appendix. It doesn’t say anything about styling though as far as I can tell, nor about case protection. Searching for “nocase” on that page gives me zero hits.

7

ah, sorry, if by “styling” you mean the (pseudo) HTML syntax for styling within input elements (as opposed to CSL’s own styling like font-style="italic"), I don’t believe that ever made it into any formal specification, so I think the only place within the CSL sites and repositories you’ll find it is in the test suite. I do recall a lengthy discussion around this for 1.1 or even 1.0.2 though, maybe @Denis_Maier or @bwiernik can recall where that happened?

Practically, citeproc-js (which introduced this behavior off-spec many years ago) appears to support the syntax anywhere, though the nocase one in particular probably only makes sense on elements where text-case="title" is actually used, which is principally anything with title in it.