MakeCSL: A Proposal

CSL is at the stage where the language is virtually stable, and has gone through enough refinement that it has achieved its objective of being a powerful, open and accessible language for encoding citation styling information. It has been implemented fully in Javascript, and there are other implementations in progress for PHP, Python, and Ruby. In addition, styles are being written and deployed in publicly accessible style repository that allows styles to be accessed directly over HTTP.

However, it remains difficult for the average user to create new styles. There remains a large gap between the number of styles there are and the number of styles there needs to be to be declared a success.

To rectify this situation, one obvious approach is to build a full-blown editing GUI, which allows a user to load existing styles modify them, etc. However, such a task is not straightforward. Citation styling can be quite complex, and CSL is designed to accommodate that complexity. While it is certainly possible to do such a GUI, it will take time to realize.

Rather than to take the next step for a fully implemented editor than can both read and write CSL styles, then, I propose instead a much simpler and more incremental enhancement that borrows from lessons of the past. Like the MakeBST utility that allowed BibTeX users to more easily create new citation styles by answering a series of questions, MakeCSL will make it much quicker for users to create new styles by focusing on writing new styles.

Model

At its core, MakeCSL is a simple web application that take a series of parameters, and outputs a compliant CSL style. The parameters should probably be encoded in JSON, and consist of the following:

The layout parameters would consist of a list of style macros, of the form:

["[style id]#[macro name]"]

To generate the style, then, a script would simply assemble the macros from the relevant styles.

Such an application could be easily extended to a full database backend, of course, with classes/tables for styles, macros, citations, bibliographies, and layouts.

UI

MakeCSL will start from the premise that 95% or more of citation styling options can be captured through selecting from a series of pre-defined options, and then from there generating the finished style programmatically. A further design premise is that rather than build the formatting configuration from the smallest components and options to the full rendering of the data fields, it would be more efficient to start from the fully rendered citations and bibliographic entries. The user should not, then, have to step through a myriad of often abstract questions and options, but rather first start by selecting from one or two lists of options, complete with rich previews that allow them to instantly see which style options most closely match their intended output.

The interface should use standard:

At every step of the way, the interface should make it easy for the user to see the implications of their choices. Further, answers to questions can be used to alter the form options in later questions. For example, the field(s) a user chooses will be useful information, since styles tend to vary significantly depending on field. Numeric styles are most common in the sciences, for example, while author-date predominates in the social sciences, and the humanities tend to be dominated by note-based styles. MakeCSL can and should know this and exploit it.

Form

As a start, MakeCSL shall include the following form fields:

  1. basic description (title, description, author name and email, and fields)
  2. the style wizard, which gathers information about:

  3. class of style (author-date, footnote, etc.)

  4. parent style (APA, Chicago, etc.)

Once this information is gathered, the UI presents a preview using predefined sample data from a variety of types of resources. If the formatting is correct as is, the user may submit the style at this point.

If not, the UI should visually show the component macros used to assemble the formatting, and the user should then be able to choose one-or-more of these macros for modifying. For each selected macro, the UI again presents the user a list of options with previews.

By iterating through this process, they can refine and customize the base styles.

Processing

Upon completing the form and pressing "submit style" the process should send a list of configuration parameters to the server so that it can be stored on its own, and used to generate the CSL file. This allows the style to be regenerated should, for example, the component macros be enhanced over time.

Once the style is submitted, it is given a URI and a time-stamp, and made publicly available. For convenience, it would be good to allow the user to immediately install the style.

Prerequisites

For MakeCSL to be most effective, it will depend on a rich collection of styles and well-defined macros.

Implementation Notes

JQuery has a fantastic infrastructure to do these kinds of wizards.

See the following JQuery UI plug-ins:

The above make it easy to create a tabbed interface and to control movement of the user through the wizard. For example, the following simply command sets up the tabbed interface, but disables all but the first tab.

$("#wizard ul").tabs({ disabled: [2, 3] });

One can then setup up callback functions that allow a user to click a "next" button, which then validates the form, and enables the next tab. Using a bit of Ajax would enable, then, a really simple and clean UI that adjusts as the user goes.