Re: xbiblio-devel Digest, Vol 118, Issue 1

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

Re: xbiblio-devel Digest, Vol 118, Issue 1



Thank you for referring me to Nabble. I definitely feel like I don't know what I am doing on the mailing list, and Nabble looks like the ticket. I sent a request for access just now. 😊

In the mean time, I want to send a link to a blog post that I created. . The gist of the post is that CSL styles are amazing, and they fill an unmet need for bibliographic applications. One of the coolest things that CSL styles can do is create User Interfaces based on the citation system a person is targeting. I also lay out some ideas about how CSL styles could be even more useful for applications.

I know the point of a mailing list is to keep a public record. You should visit my blog ( to the interact with the demonstration. However, I will post the main text of the blog below for sake of the record.

- Tom O'reilly


If you are a developer of a bibliography application, you probably want to allow the user to enter their own data. How can you turn user inputs into a format that is usable by citeproc-js? This question is the starting point, but we are going to end up exploring the philosophic under-pinnings of CSL and of bibliography technology stacks. I will show how CSL can already be used to fill existing needs in the bibliography ecosystem. Then, I will offer suggestions as to how CSL can improve its position as the de facto standard for citation styles.

There is something consequential for applications developers to understand about the Citation Style Language. CSL only defines how to create citation styles. CSL does not define how bibliographic information should be formatted.

CSL is interested only in standardizing how to create style sheets - and it avoids the thorny problem of standarding bibliographic records. There are, in fact, probably hundreds of competing standards for encoding records, and a CSL Processor is free to choose the format that works best for it. For the citeproc-js processor, it relies upon a standard called CSL-JSON. JSON is great for a web application, because it is quite efficient over networks. However, desktop publishing applications would probably prefer to use an XML format for bibliographic records for the sake of consistency.

I am not going to duplicate the tutorial concerning CSL-JSON. You can learn more about it here. I think that there may be some value to having the CSL community adopting one or more standards for bibliographic records. This would be helpful for word processors that want to integrate CSL. It would mean styles and records would be cross-platform - and users would not lose any of their hard work by switching applications. Any standard for bibliographic records should also consider possible applications with semantic web technologies. However, these are just my musings. Let's dive into how powerfully amazing CSL is currently for productivity.

Even though CSL does not fully standardize how to create bibliographic records, it does provide some guidance to ensure that bibliographic records are compatible across styles. Appendices 1 and 2 apply directly to CSL styles, and Appenice 3 and 4 apply to both bibliographic records and CSL styles.

Appendix 3 defines a set of source "type"s that may characterize a record. The source's "type" is the fundamental piece of information required of any bibliographic record. This is universal to all citation systems: the formatting of a bibliographic record depends on the source type.

Appendix 4 defines a set of variable fields and their corresponding data-type. It gives a list of approved "string" variables, "number" variables, "name" variables, and "date" variables.

When style creators conform to the conventions laid out in the Appendices, they ensure that bibliographic records will be compatible between styles. This is a powerful feature: to allow users to switch citation styles on the fly without losing any information.

Where does CSL fit in the bigger picture?

Let's draw back and look at a larger perspective of the bibliography field. One of the paradoxes of bibliographic record standards is that there is opposition between "flexibility" and "compatability." When a standard is very strictly defined, applications that rely on that standard will be compatible, but it is hard to adapt that standard to every citation system. By relaxing the standard to be flexible enough to accomodate unforseen cases, it makes it harder for applications to interpret and use that data. Let's pretend that we want a strict standard that is comprehensive of every deviation in citation systems, including (naming, numbering, dating conventions, required fields), then we end up with a standard that becomes too "cumbersome" to use. I think that this characterizes the MARC 21 standard. Some standards take a middle ground between "cumbersome" and "comprehensive," but they have to exercise editorial judgments about what to include, and how to organize what they have included. This approach characterizes standards like Zotero, OOXML, ODF.

I think the Citation Style Language is in a sweet spot to help answer that paradox. There are two layers of a bibliography technology stack: the application on top and bibliographic records on the bottom. Citation style languages insert another layer of abstraction into the middle of the bibliography stack - which helps bridge the application's need for data compatability and the user's need for flexibility. If a record represents a source, the CSL style is a representation of the real world citation system. The CSL language defines the CSL styles, which in turn, define the parameters of bibliographic records. The citaiton language layer is also the best layer to make editorial judgments, because citation styles have the best knowledge of the citation systems they model. Editorial judgments could be pushed from the application layer to CSL style layer, which frees application developers from having to become bibliography experts and making editorial judgments about how to organize bibliographic systems.

By embracing CSL as this middle layer of abstraction, we can see how to extend CSL's current functionality. Not only can CSL styles be used for format bibliography records; it can be used to generate interfaces for user input in applications.

The CSL style determines which variable fields can be displayed - and under which conditions they will be displayed. This makes bibliography UI much more manageable, because we can hide fields that are irrelevant to the user. This also informs the user when they are missing information that is important. Finally, it removes editorial control from the application developer, and places that control with style creators.

How to user-interface generation works

CSL styles are a branching logic flow chart. I created a module called "SetLogic" that can iterate through every logic path, and evaluate what conditions have been cumulatively applied to the statement at the end of those nodes. Thus, the processor knows under what conditions each node will be rendered in output. The processor then pairs which fields will be displayed with which source type. Click here to read more about how SetLogic works, and other potential applications for SetLogic. 

I created a second module called Form Utility. Form Utility depends on the SetLogic module for the relationships between fields and source types, and repackages them into a template for easy form generation. It will return all the source types referenced by the CSL style. It will also return an array of month and season names, based upon the locale file. Calling FormUtility.retrieve() will return an object with the following properties:

  • "fields": a dictionary of fields, their types, and associated subfields.
  • "menu": an array of types. Each type is an object with a "label" and "value" property.
  • "dateSelect": contains an array of seasons and an array of months. Each is represented by an object with a "value" property corresponding to the CSL Appendix II (Months and Seasons). Each object also has a long-form name and short-form name for the month or season (as long as both are supported by the locale). Try the "Russian GOST R 7.0.5-2008 (numeric, sorted alphabetically, Russian)" style to see how date-fields are automatically localized for styles.

Future Development of CSL

Compatability v. Flexibility

One of the limitations of CSL is a return to the perrenial dillema - how do we acheive compatability and flexibility? CSL styles are compatible with each other, because they adhere to the CSL Appendices I-IV. They share the same "types", the same variable names, the same field categories, and the same terms. Unfortunately, this compatibility undermines flexibility of style creators, and a significant amount of editorial judgments made by the CSL crafters is locked at the application level. We should look for a mechanism to push editorial judgment and autonomy into the style level.

Source Type

One example that I run into is in creating styles for legal users. While CSL has one classification for "legal_case", the BlueBook citation system distinguishes between Article III Courts, administrative courts, and arbitrations. Where CSL has the "legislation" type, the BlueBook distinguishes constitutions, passed statutes, resolutions, and executive orders. I imagine that this problem is true for every specialized discipline. Style creators are using their editorial judgment to match the types recognized by the citation system to the types defined by CSL. However, if style creators could map the citation system's type to CSL types, and test against those arbitrary types in a style sheet, then they could create very accurate styles. Moreover, the styles would generate even more tailored UI.

Complexity v. Usability

I think that our technology will have arrived when novices can create high quality citations without ever referring to a citation guide. We have a start on the promise already. By having a UI that only displays fields that are relevant to the source's type, the application informs the user about the requirements of the citation system. However, we can do much more to make the interface informative to the user. One way of doing this is through tooltips that popup when the cursor or finger hovers over the field name.

The easy way to implement this feature is to use the CSL definition for variables (taken directly from CSL Appendix IV). However, what if these tooltips could offer specific guidance for how to use those variable fields within the citation system. I will demonstrate with another example from BlueBook concerning the "issued" field.

CSL specifies that, generally, the "issued" date variable contains the "date the item was issued/published." It's the primary field used for dating items in CSL. However, the BlueBook citation system rules for dating sources is much more complicated. For example:

  • Cases are dated with the date they are decided.
  • Statutes are dated with the date of the code edition cited.
  • In-force Constitutional provisions are not dated, except provisions that have been repealed are dated by the date of the repeal. And superseded constitutions are dated by the year of adopton.

Dating rules are complicated, and style creators are usually experts of a citation system. Style creators could add a ton of value to styles if they could communicate their knowledge of the intricacies of style rules to their users. Such style creators would want tips that are specific to that variable field and item type.

From: [hidden email] <[hidden email]>
Sent: Saturday, May 27, 2017 8:29 AM
To: [hidden email]
Subject: xbiblio-devel Digest, Vol 119, Issue 1
Send xbiblio-devel mailing list submissions to
        [hidden email]

To subscribe or unsubscribe via the World Wide Web, visit

or, via email, send a message with subject or body 'help' to
        [hidden email]

You can reach the person managing the list at
        [hidden email]

When replying, please edit your Subject line so it is more specific
than "Re: Contents of xbiblio-devel digest..."

Today's Topics:

   1. Re: xbiblio-devel Digest, Vol 118, Issue 1 (bwiernik)


Message: 1
Date: Tue, 7 Feb 2017 01:30:04 -0700 (MST)
From: bwiernik <[hidden email]>
To: [hidden email]
Subject: Re: [xbiblio-devel] xbiblio-devel Digest, Vol 118, Issue 1
Message-ID: <[hidden email]>
Content-Type: text/plain; charset=us-ascii

(The mailing list doesn't seem function well when your email notifications
are set to digest. I'd recommend just responding on the Nabble archive to
respond--it's what I do. Another good reason to move to a new platform?)

Thomas, given your responses to the formatting particulars of parallel
citations, I wonder whether such a major change as you propose is really
necessary? Given that (1) the reporting requirements across styles are
either all reporters or just the first and (2) the ordering of reporters
should always be consistent, it seems to me like it should work for legal
items to just be expected to have multiples of the individual reporter
fields (e.g., multiple 'publication' fields). Each field should be
interpreted as an ordered list so that corresponding elements are in the
same order. in clients, the UI could be arranged to "Add reporter" or
similar, which would add new sets of the relevant fields as a unit. Styles
that require just the primary reporter would then just take the first
element from the list, while other styles would use the full lists.

View this message in context:

Sent from the xbiblio-devel mailing list archive at


Check out the vibrant tech community on one of the world's most
engaging tech sites,!


Subject: Digest Footer

xbiblio-devel mailing list
[hidden email]


End of xbiblio-devel Digest, Vol 119, Issue 1

Check out the vibrant tech community on one of the world's most
engaging tech sites,!
xbiblio-devel mailing list
[hidden email]