clarifications about variables and types

CSL Development
1

Hi,

Some time ago we (in Mendeley) were wondering about the exact meaning
of standard variables and document types. Is there some more
documentation beside in
http://citationstyles.org/downloads/specification.html#standard-variables?

If I remember correctly we found specially confusing
“archive_location” and “archive-place”. Also, when “post” and “entry”
should be used?

Why some variables has underscore and other dash? Or
“editortranslator” doesn’t have underscore either dash.

(maybe the dash / underscore / two words together is for compatibility
with CSL 0.8?)

I hope that these was the questions that we had. I don’t have the
notes from work here.

An example or comment next to some variables and types would help. I
could try to write something but I’m sure that would not be very
correct.

Thanks,–
Carles Pina | Software Engineer

Mendeley Limited | London, UK | www.mendeley.com
Registered in England and Wales | Company Number 6419015

2

Hi Carles,

Some time ago we (in Mendeley) were wondering about the exact meaning
of standard variables and document types. Is there some more
documentation beside in
Redirecting…?

If I remember correctly we found specially confusing
“archive_location” and “archive-place”.

What’s confusing about these: the very concept (“location” vs.
“place”?), or the inconsistent punctuation (underscore vs. hyphen)?

The schema itself has the sorts of descriptions we probably ought to
add to the spec document.

  ## the location within an archival collection (for example, box

and folder)
“archive_location”
>
## the place of the archive
“archive-place”

Also, when “post” and “entry” should be used?

Let me back up and explain something about typing in CSL, and in
bibliographic systems generally.

Traditionally, bibliographic systems have been heavily type-oriented.

I, however, have long believed that this is a big mistake, because the
real world of citation data in the early 21st century encompasses a
diverse range of sources that aren’t well captured by traditional
bibliographic types.

For example, I want to store/annotate/cite an article published on the
New York Times website. In some systems, you’d call this a “newspaper
article”. But often those system won’t let you store the article URL
along with the article metadata. So you then need to use instead a
type called “webpage” or some such. It is, after all, also a web page
(it’s available on the web). So now I can store and cite my URL. But
things become awkward because I have odd fields like “website.” Well,
yes, I access the document on the “New York Times” website at a base
URI of http://nytimes.com.

In CSL, I originally had no macro system. What I did instead is to
introduce a fallback type system. So, all style required templates for
three base types: “book”, “article” and “chapter.” These were concrete
names for what were in effect abstract generic types.

I then added more specific types by hyphenating the names. So
“article-newspaper” is an example of this, where the convention is
simply saying “this has an article fallback” but is a kind of subclass
of it.

You see similar ideas at play in “post” vs. “post-blog” and “entry”
vs. “entry-dictionary.”

So there’s some legacy there, but it’s sensible enough.

What been a problem all along, however, is that we have no clear,
stated, explanation of when and how we define a type. They’ve mostly
been added ad hoc. I’d personally like to change this.

Why some variables has underscore and other dash? Or
“editortranslator” doesn’t have underscore either dash.

I don’t know; I think Frank added that and I missed it at the time :wink:

(maybe the dash / underscore / two words together is for compatibility
with CSL 0.8?)

Not explicitly, but obviously it’s easier.

I hope that these was the questions that we had. I don’t have the
notes from work here.

An example or comment next to some variables and types would help. I
could try to write something but I’m sure that would not be very
correct.

Take a look at the schema and see if you agree moving those comments
into the spec would help.

Bruce

3

Hi Carles,

Some time ago we (in Mendeley) were wondering about the exact meaning
of standard variables and document types. Is there some more
documentation beside in
Redirecting…?

If I remember correctly we found specially confusing
“archive_location” and “archive-place”.

What’s confusing about these: the very concept (“location” vs.
“place”?), or the inconsistent punctuation (underscore vs. hyphen)?

The schema itself has the sorts of descriptions we probably ought to
add to the spec document.

 ## the location within an archival collection (for example, box

and folder)
“archive_location”

 ## the place of the archive
 "archive-place"

Also, when “post” and “entry” should be used?

Let me back up and explain something about typing in CSL, and in
bibliographic systems generally.

Traditionally, bibliographic systems have been heavily type-oriented.

I, however, have long believed that this is a big mistake, because the
real world of citation data in the early 21st century encompasses a
diverse range of sources that aren’t well captured by traditional
bibliographic types.

For example, I want to store/annotate/cite an article published on the
New York Times website. In some systems, you’d call this a “newspaper
article”. But often those system won’t let you store the article URL
along with the article metadata. So you then need to use instead a
type called “webpage” or some such. It is, after all, also a web page
(it’s available on the web). So now I can store and cite my URL. But
things become awkward because I have odd fields like “website.” Well,
yes, I access the document on the “New York Times” website at a base
URI of http://nytimes.com.

In CSL, I originally had no macro system. What I did instead is to
introduce a fallback type system. So, all style required templates for
three base types: “book”, “article” and “chapter.” These were concrete
names for what were in effect abstract generic types.

I then added more specific types by hyphenating the names. So
“article-newspaper” is an example of this, where the convention is
simply saying “this has an article fallback” but is a kind of subclass
of it.

You see similar ideas at play in “post” vs. “post-blog” and “entry”
vs. “entry-dictionary.”

So there’s some legacy there, but it’s sensible enough.

What been a problem all along, however, is that we have no clear,
stated, explanation of when and how we define a type. They’ve mostly
been added ad hoc. I’d personally like to change this.

Why some variables has underscore and other dash? Or
“editortranslator” doesn’t have underscore either dash.

I don’t know; I think Frank added that and I missed it at the time :wink:

Yep, that was the name in my proposal (which I hasten to add was
agreed on the list! :). It’s not very pretty, is it.

This particular locale name will not normally be used directly in a
style. It is composed of the names of two creator variables (“editor”
and “translator”). If those two variables are used together on the
same cs:names element, they will render only a single name string (not
two) if both variables have the same content. In that case, the
creator role of the “collapsed” names string will become
“editortranslator” internally.

Because this term is called through automagic inside the processor,
its name can and probably should be changed to editor-translator at
some point. I’ll file a discussion ticket for CSL 1.1.

(The underscore in the legal_case type has puzzled me as well. It
would be tidier with a hyphen, perhaps this could also be discussed
for the next version upgrade.)

Frank

4

Hi,

Hi Carles,

Some time ago we (in Mendeley) were wondering about the exact meaning
of standard variables and document types. Is there some more
documentation beside in
Redirecting…?

If I remember correctly we found specially confusing
“archive_location” and “archive-place”.

What’s confusing about these: the very concept (“location” vs.
“place”?), or the inconsistent punctuation (underscore vs. hyphen)?

I thought that the word location and place were mainly synonyms. I
remember that I discussed about it with an English workmate and was
not clear for him either.

The schema itself has the sorts of descriptions we probably ought to
add to the spec document.

 ## the location within an archival collection (for example, box

and folder)
“archive_location”

 ## the place of the archive
 "archive-place"

archive_location: the comment is clear and helps.
archive-place: the comment is not helping so much. I assume that it
refers to the city/town (the comment could be a bit more extended and
with some example).

Having said that, my bad that I didn’t see the comments there. It
makes some things more clear.

Also, when “post” and “entry” should be used?

Let me back up and explain something about typing in CSL, and in
bibliographic systems generally.

Traditionally, bibliographic systems have been heavily type-oriented.

I, however, have long believed that this is a big mistake, because the
real world of citation data in the early 21st century encompasses a
diverse range of sources that aren’t well captured by traditional
bibliographic types.

For example, I want to store/annotate/cite an article published on the
New York Times website. In some systems, you’d call this a “newspaper
article”. But often those system won’t let you store the article URL
along with the article metadata. So you then need to use instead a

A system that a document type “newspaper article” doesn’t have an
associated URL needs to be updated ASAP. It’s already 2010.

type called “webpage” or some such. It is, after all, also a web page
(it’s available on the web). So now I can store and cite my URL. But

[loud thinking: I would only use the type “webpage” for
articles/documents that has been originally published in a webpage.
Else mainly everything would be a webpage, since mainly everything is
re-published on webpages (articles, magazines, etc.). ]

Having said that: I understand your point.

things become awkward because I have odd fields like “website.” Well,
yes, I access the document on the “New York Times” website at a base
URI of http://nytimes.com.

In CSL, I originally had no macro system. What I did instead is to
introduce a fallback type system. So, all style required templates for
three base types: “book”, “article” and “chapter.” These were concrete
names for what were in effect abstract generic types.

I then added more specific types by hyphenating the names. So
“article-newspaper” is an example of this, where the convention is
simply saying “this has an article fallback” but is a kind of subclass
of it.

You see similar ideas at play in “post” vs. “post-blog” and “entry”
vs. “entry-dictionary.”

So there’s some legacy there, but it’s sensible enough.

I understand it. Maybe the explanation could added in the
documentation as well. When someone reads the list of types can be a
bit confused if the reader doesn’t know the story behind.

What been a problem all along, however, is that we have no clear,
stated, explanation of when and how we define a type. They’ve mostly
been added ad hoc. I’d personally like to change this.

Agreed. And the dashes/underscores could be normalized.

I hope that these was the questions that we had. I don’t have the
notes from work here.

An example or comment next to some variables and types would help. I
could try to write something but I’m sure that would not be very
correct.

Take a look at the schema and see if you agree moving those comments
into the spec would help.

csl-variables.rnc: yes, it would really help. I would do some minor changes:

  • add examples in some variables (e.g. archive-place)
  • add comments with examples to some variables (e.g. genre, call-number)
  • use always the same format to write the examples (sometimes it’s
    using just parenthesis -medium-, sometimes uses “for example”
    -archive_location-, sometimes “such as” -authority-)

I would also add comments to cs-dates and to some types (csl-types.rnc).

With that, the specification and the documentation would be much more clear.

Thanks,

5

Hi,

Hi Carles,

Some time ago we (in Mendeley) were wondering about the exact meaning
of standard variables and document types. Is there some more
documentation beside in
Redirecting…?

If I remember correctly we found specially confusing
“archive_location” and “archive-place”.

What’s confusing about these: the very concept (“location” vs.
“place”?), or the inconsistent punctuation (underscore vs. hyphen)?

I thought that the word location and place were mainly synonyms. I
remember that I discussed about it with an English workmate and was
not clear for him either.

The schema itself has the sorts of descriptions we probably ought to
add to the spec document.

 ## the location within an archival collection (for example, box

and folder)
“archive_location”

 ## the place of the archive
 "archive-place"

archive_location: the comment is clear and helps.
archive-place: the comment is not helping so much. I assume that it
refers to the city/town (the comment could be a bit more extended and
with some example).

Yes, this should indeed be more clear, and I’ll clean that up.

But yes, your hunch is correct. In the same way that we often include
a city as a conference location or for a publisher, we do the same
thing with an archive (for manuscripts).

Having said that, my bad that I didn’t see the comments there. It
makes some things more clear.

Also, when “post” and “entry” should be used?

Let me back up and explain something about typing in CSL, and in
bibliographic systems generally.

Traditionally, bibliographic systems have been heavily type-oriented.

I, however, have long believed that this is a big mistake, because the
real world of citation data in the early 21st century encompasses a
diverse range of sources that aren’t well captured by traditional
bibliographic types.

For example, I want to store/annotate/cite an article published on the
New York Times website. In some systems, you’d call this a “newspaper
article”. But often those system won’t let you store the article URL
along with the article metadata. So you then need to use instead a

A system that a document type “newspaper article” doesn’t have an
associated URL needs to be updated ASAP. It’s already 2010.

type called “webpage” or some such. It is, after all, also a web page
(it’s available on the web). So now I can store and cite my URL. But

[loud thinking: I would only use the type “webpage” for
articles/documents that has been originally published in a webpage.
Else mainly everything would be a webpage, since mainly everything is
re-published on webpages (articles, magazines, etc.). ]

Having said that: I understand your point.

things become awkward because I have odd fields like “website.” Well,
yes, I access the document on the “New York Times” website at a base
URI of http://nytimes.com.

In CSL, I originally had no macro system. What I did instead is to
introduce a fallback type system. So, all style required templates for
three base types: “book”, “article” and “chapter.” These were concrete
names for what were in effect abstract generic types.

I then added more specific types by hyphenating the names. So
“article-newspaper” is an example of this, where the convention is
simply saying “this has an article fallback” but is a kind of subclass
of it.

You see similar ideas at play in “post” vs. “post-blog” and “entry”
vs. “entry-dictionary.”

So there’s some legacy there, but it’s sensible enough.

I understand it. Maybe the explanation could added in the
documentation as well. When someone reads the list of types can be a
bit confused if the reader doesn’t know the story behind.

OK.

What been a problem all along, however, is that we have no clear,
stated, explanation of when and how we define a type. They’ve mostly
been added ad hoc. I’d personally like to change this.

Agreed. And the dashes/underscores could be normalized.

So we can bring it up for future discussion if need be.

I hope that these was the questions that we had. I don’t have the
notes from work here.

An example or comment next to some variables and types would help. I
could try to write something but I’m sure that would not be very
correct.

Take a look at the schema and see if you agree moving those comments
into the spec would help.

csl-variables.rnc: yes, it would really help. I would do some minor changes:

  • add examples in some variables (e.g. archive-place)
  • add comments with examples to some variables (e.g. genre, call-number)
  • use always the same format to write the examples (sometimes it’s
    using just parenthesis -medium-, sometimes uses “for example”
    -archive_location-, sometimes “such as” -authority-)

OK, good points.

I would also add comments to cs-dates and to some types (csl-types.rnc).

With that, the specification and the documentation would be much more clear.

Right. Thanks!

Bruce

6

Reviving this thread: Zotero 2.1 final will likely include some changes to
Zotero’s metadata model. Possible changes are currently being gathered and
reviewed (see
http://forums.zotero.org/discussion/15636/changes-to-fields-and-item-types-for-zotero-21/).
As these changes might include remappings from Zotero fields to CSL
variables, I thought it useful to polish the CSL variable descriptions:

http://piratepad.net/BdqJrhdJHR (additions are in blue)

Once these new descriptions pass review, I can add them to the spec for the
next release of the CSL specification. The list of CSL types would probably
benefit from the same treatment, but let’s start with the variables.
Feedback is very welcome, especially since I wasn’t (completely) sure about
the intended use in some cases.

RintzeOn Sat, Jul 31, 2010 at 3:34 PM, Carles Pina <@Carles_Pina>wrote:

7

Hello,

Reviving this thread: Zotero 2.1 final will likely include some changes to Zotero’s metadata model.

Do you know what the current status of this is and what the knock-on
effect has been on the CSL spec?

At some point in the new year we’ll want to go over the document types
and variables that we provide in Mendeley and make
sure they are in sync with any upcoming changes in CSL.

The schema itself has the sorts of descriptions we probably ought to
add to the spec document.

We could just copy and paste them into the spec, but I’m concerned
that the descriptions in the spec and schema will inevitably get out
of sync (eg. a contributor adds a clarification on the use of a
variable in one and that doesn’t find its way into the other).

Regards,
Rob.

8

Reviving this thread: Zotero 2.1 final will likely include some changes
to Zotero’s metadata model.

Do you know what the current status of this is and what the knock-on
effect has been on the CSL spec?

At some point in the new year we’ll want to go over the document types
and variables that we provide in Mendeley and make
sure they are in sync with any upcoming changes in CSL.

Requested changes to the Zotero metadata model have been collected in the
zotero-bits issue tracker on GitHub:

Most still have to receive review by the Zotero developers, so things
aren’t settled yet, but from what I understood this review might happen for
Zotero 3.1. I was hoping we could release a backward-compatible CSL 1.0.1
release in the same timeframe as 3.1 with the additional variables that are
needed. The tickets in the tracker are tagged to indicate if CSL changes
are needed.

A draft overview for changes in CSL 1.0.1 (also here things are still in
flux) can be found here: http://goo.gl/mD2Ez

I’ve noted this before, but I think it would be extremely valuable if the
CSL project could also provide guidelines on which CSL variables
should (and shouldn’t) be available each item type. Bruce is a big
proponent of using non-item-type-based logic in coding style conditionals,
which has its advantages, but also makes that styles will only work
reliably between CSL apps like Zotero and Mendeley if all of these offer
the CSL processor a similar metadata model.

The schema itself has the sorts of descriptions we probably ought to

add to the spec document.

We could just copy and paste them into the spec, but I’m concerned
that the descriptions in the spec and schema will inevitably get out
of sync (eg. a contributor adds a clarification on the use of a
variable in one and that doesn’t find its way into the other).

I just took out the descriptions from the schema and moved them into the
spec. You can see this in the schema and spec trunk.

RintzeOn Fri, Dec 9, 2011 at 6:35 AM, Robert Knight <@Robert_Knight>wrote: