Writing CSL – Features and Best Practices

With the CSL repository growing steadily, and a very large number of different contributors — more than 250 since its beginning — helping by adding or improving styles, I figured this would be a good time to highlight some features of CSL and what they mean for best practices in coding a CSL style.

Groups

CSL allows you to group items that belong together and set a “delimiter” between them. Think of a common example, the colon between place and publisher: New York, NY: Columbia University Press, 1990. You can code this as

 <text variable="publisher-place" suffix=": "/>
 <text variable="publisher"/>
 <text variable="issued" form="year" date-part="year" prefix=", "/>

The problem with this version is that if your item doesn’t have a publisher, you get a mess like New York, NY: , 1990. Using groups makes this a little longer, but much more robust:

 <group delimiter=", ">
   <group delimiter=": ">
     <text variable="publisher-place"/>
     <text variable="publisher"/>
   </group>
   <date variable="issued" form="text" date-part="year"/>
 </group>

This will produce sensible output like New York, NY, 1990 regardless of which input variable may be missing.

Best Practice 1: Prefer groups and group delimiters to affixes for punctuation and spaces between items

Macros

CSL allows you to use macros in citation style. Simply put, macros allow you to write a relatively long sequence only once. Say you need the style to give the year of publication and if there is none “n.d.”. This is the type of thing that you’re going to use multiple times in a style — e.g. in the citation, the bibliography, and maybe for sorting — each time taking eight lines of code. So instead of writing the whole thing multiple times, define

 <macro name="issued-year">
   <choose>
     <if variable="issued">
       <date variable="issued" form="text" date-part="year"/>
     </if>
     <else>
       <text term="no-date" form="short"
     </else>
   </choose>
 </macro>

and simply “call” the macro using <text macro="issued-year"/> where you would otherwise write the whole eight lines.

Code economy isn’t the only, or even principal advantage of using such macros. Their biggest advantage is that if someone else wants to change your code, e.g. for a new similar citation style, any changes in a macro only need to be made once. A huge time-saver! Finally, looking into the future, CSL was always intended to be a “modular” language: you can take one piece out of a citation style and plug it into another style. Relying extensively on macros in citation styles fosters such modularity. (Frank Bennett has written up some informal thoughts on this).

Best Practice 2: Use Macro’s extensively. Keep the cs:citation and cs:bibliography parts shorts and keep cs:choose elements in them to an absolute minimum

Terms

“Available at,” “no date,” “anonymous,” “pages” — citation styles contain many such words or short phrases. CSL defines many of them as “terms” and provides translations into dozens of language. Strictly speaking, many of these wouldn’t be necessary. To provide, e.g. a URL preceded by “Available at”, <text variable="URL" prefix="Available at "/>, works. But it’s, well, ugly. It also means that someone who wants to adapt the structure of your style but use it in Spanish will have to rewrite all such prefixes. Instead use

 <group delimiter=" ">
   <text term="available at" text-case="capitalize-first"/>
   <text variable="URL"/>
 </group>

and your style can be converted to any language by simply changing the default-locale setting in the first line of the style (or, leaving it blank, will automatically appear in the user’s install language).

But what if the term isn’t quite right? You may need “Available from” instead? You can redefine any term for any language/locale in the beginning of the style, in our example:

 <locale xml:lang="en">
   <terms>
     <term name="available at">available from</term>
   </terms>
 </locale>

Best Practice 3: Use terms and labels. Do not add terms or phrases in affixes or using text value=

Miscellanea

  • If you plan to submit the style to the repository, closely read and follow the requirements

  • Assume that users have titles stored in sentence case. Use text-case="title" as needed, but don’t use text-case="sentence"

  • Some styles have left-over clutter from an earlier version. In particular, you will often see periods (which all abbreviated terms have in CSL) first stripped using strip-periods="true" and then added again using suffix=".". Remove this and similar unnecessary code. Future users/coders will thank you.

Best Practice 4: Don’t use sentence case, and keep styles tidy by removing clutter, following CSL repository guidelines

Examples

Best practices are not ironclad commandments. Of all the “rules” above, only failing to conform to repository guidelines and forcing sentence case on a title will prevent a style from being accepted to the CSL repository. You can look at the styles for American Psychological Association or Vancouver. You’ll see a lot of rule-breaking, but also a general adherence to these recommendations to give you a sense of how a well-coded style looks.

Advertisements

3 thoughts on “Writing CSL – Features and Best Practices

  1. Pingback: Literaturverwaltung kompakt 7/2013 – zweiter Teil: Communitynachrichten | Literaturverwaltung

  2. Pingback: Zotero et les styles de citation – épisode 2 : communauté, documentation et outils | Vingt-sept point sept

  3. Pingback: Quality Control for CSL Styles | The Zoteroist

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s