Citation Style Language

[Feedback CSL 1.0.2]: Publication type "event"

One little wrinkle: this is related to the as yet unresolved “related” modeling discussion for 1.1.

In theory, it could be events get modeled also as relations; e.g.:

type: paper
title: Some Title
presentedAt:
  type: event
  subtype: conference
  title: Conference Title

I don’t think overlapping terms are as big a deal when we are talking about an a type of relation and an item type. If the event variable is renamed to event-title, then the meaning here is clear:

type: speech
title: A conference presentation:
related:
  event:
    type: event
    genre: Conference
    title: Conference title

If we did want a separate label for the type of relation, perhaps related-event or containing-event. presented-at might work too. I don’t know what other types of event relations there might be, so that would probably be fine.

A somewhat related question. Currently, we are inconsistent in whether number variables include -number or not. For example, chapter-number and collection-number but volume and issue. We currently are slated to add some more variables without -number in them for 1.0.2 (e.g., part, supplement, printing).

Since we are going to rename event, should we also rename these? I think it would be clearer to have volume-title and volume-number rather than volume-title and volume (the latter being a number).

I’ve been confused by this too, and tend to think we should fix it.

But I guess we’d want to make sure we can easily fix it in existing styles we upgrade for 1.1.

Edit: turns out this is easy:

  <xsl:template match="//*/@variable[.='event']">
    <xsl:attribute name="variable">event-title</xsl:attribute>
  </xsl:template>

I’ve added a xslt-update branch to the schema repo to add these to csl-update.xsl.

Actually, could you possible update here on what variable names we need to update in the styles, @bwiernik, so I can just add them at once, and then merge?

These are the number variables:

  variables.numbers =
    "chapter-number"
    | "citation-number"
    | "collection-number"
    | "edition"
    | "first-reference-note-number"
    | "issue"
    | "locator"
    | "number"
    | "number-of-pages"
    | "number-of-volumes"
    | "page"
    | "page-first"
    | "part-number"
    | "printing-number"
    | "section"
    | "supplement-number"
    | "version"
    | "volume"

(part-number, printing-number, supplement-number are new in 1.0.2; I pushed a commit to my PR making them -number in 1.0.2)

These are the title variables:

  variables.titles =
    "collection-title"
    | "container-title"
    | "original-title"
    | "part-title"
    | "reviewed-title"
    | "title"
    | "translated-title"
    | "volume-title"

So:

  1. :heavy_check_mark: volume to volume-number I think should change.
  2. :heavy_check_mark: issue to issue-number probably
  3. :x: locator is an object, so clearer to leave without
  4. :x: edition, version, section are reasonably likely to be non-numeric, so we should leave these
  5. :question: page we’ve discussed making possible to contain other types of locators (e.g., column numbers), like locator, so I suggest we leave this (or discuss some other change).
  6. :question: number would perhaps better be labeled document-number. It is currently used both for document numbers (e.g., reports, patents, legislation, legal cases) and in Zotero for episode numbers on broadcasts. That creates some problems that could be addressed by understanding number to be a document number and an episode number to be page and/or chapter-number.

I don’t think that this XSLT rule is enough. For example have a look at testing more than one variable like, e.g.

<if variable="event version" type="speech dataset motion_picture" match="none">

I neglected to check that. Did you?

It should work, because the logic of the stylesheet is copy everything as is, except those with specific template matches.

If not, and you figure out how to fix it, let me know.

The problem is that with multiple variables your expression (='event') is not matching. The matching part needs to be less restrictive with some contains(). However, the real challenge is the replace then, because you cannot replace the attribute value completely but only parts of of. A quick search lead me to this https://stackoverflow.com/questions/15976297/in-xslt-replace-one-class-value-when-there-are-multiple-values which looks very similar and should be possible to adapt. Alternatively some small Python script might be in a lot of cases easier to do than XSLT.

However, the main problem is maybe, that the CSL styles are only one part. The other part CSL JSON data comes from a variety of sources which will not immediately (maybe also not within a year) switch to the new variables we want to introduce. Thus, I expect that we need to support the deprecated variables longer.

This could mean two direction: (1) either in the CSL styles handle the new variable besides the old (deprecated) variable, or (2) only in the implementations like citeproc-js have some mechanism to map any value from a deprecated variable into the new one before. I guess we have to start with (1) and look that (2) happens and then be very careful before stoping with (1).

1 Like

As there is currently no alias mechanism, maybe we should now consider adding one? So we could update styles to use the new terms, but preserve legacy compatibility.

1 Like

The data schema is versioned; 1.0 has a different id than 1.1 will.

I’m not sure if we also need to add a top level version property for this as well, but if the data format is versioned, there’s no problem; is there?

A CSL JSON file currently has no indication of its version, it just gives item data. I expect there will be a very long delay all sources serve data with a new version, and there are existing data files (e.g., in archived manuscripts or with embedded data in Word documents) that won’t ever be updated. It’s not clear to me how we would expect a processor to handle these if we drop support for old structures or variables. At a minimum, processors will need instructions as to what they should do when they encounter deprecated or removed structures or variables.

1 Like

As I said, though, we an add one.

{ 
  "version": "1.1",
  "references": [ ]
}

Yeah, you’re probably right. I was actually initially thinking of that; a python script that does some pre-processing, and then runs the XSLT.

Want to submit a PR ;-)?

But for all of the existing un-versioned data—it’s assumed that it is 1.0.2 or earlier?

Yes, exactly.

That would also give us a place to put other metadata.

One wrinkle to consider is Dan Stillman’s comment comparing RIS and RDF—a strength of RIS is that each item is self-contained and it’s easy to copy and transfer a single item from a file.

I don’t think a single meta field at the top of a file is necessarily a problem, but it’s something to consider and weigh against, e.g., putting the meta in each individual item.

We wouldn’t want to allow a file to mix different versions though; that’d be a nightmare.

Copying-and-pasting already won’t work across versions, given the change in the date model.

But sure; those are the details we should consider.

Sorry, maybe I am missing something, but I think there are some potential problems when deleting deprecated variables:

We can control the official CSL styles and make sure that they will update (e.g. like you indicated with a XSLT script) shortly after the schema is updated. But how can we then make sure that old CSL JSON data 1.0 can be displayed with a new CSL style 1.1?

The old data file may for example still have an event-variable but the new style file does then only handle event-title-variable. Then, it is up to the processor (not in our control) whether there is any mapping, or whether any alias mechanism is respected.

Or do I have some error in the argumentation here?

I would expect a CSL processor that supports both 1.0 and 1.1 to be able to read the 1.0 data and apply it to a 1.1 style (so it sees original-title but converts that internally to ['original']['title']). Why would that be a prolem?

A 1.1 processor (say something new developed next year) might say it won’t accept 1.0 data or styles.