style access, caching

CSL Development
1

So as Frank works on this tests and such, I’d like to raise an issue
for discussion, and that I would hope make it into the unit tests and
documentation.

How should a style be accessed?

Sub-issues:

  1. files names vs. ids

Right now, implementations are typically just using some variant of
accessing a file; in pseudo-code:

STYLE_FILE = 'apa.csl’
style = CSL.new(STYLE_FILE)

But we have an Atom-based metadata system that this fails to exploit.
So what I want to suggest, instead, is that the (or at least a)
constructor is the style id; e.g.:

STYLE_ID = 'http://zotero.org/styles/apa’
style = CSL.new(id = STYLE_ID)

  1. caching

Styles include update date-time stamps. The purpose here is enable
smart caching and updating. Can we say that implementations should
implement this? If yes, then should we suggests details on how (which
might borrowing some Atom documentation and adapting it for our use)?

  1. storage

Shouldn’t CSL styles be cached in a fixed (but perhaps configurable)
local directory? E.g., at least in Unix/Linux/Mac OS:

.csl/
styles/

I have styles as a subdirectory to leave room for other stuff (maybe
config file to list CSL repos? some default behavior?).

So if all of these are implemented, it means that I can be assured
that if I have two different applications using CSL on my system, that
if I say to use the style “http://zotero.org/styles/apa” then I am
assured both that a) they are using the same style, and b) that the
style is up-to-date.

Thoughts?

Bruce

2

Like imagine a config file that looked something like:

“repos” : [
“z” : “http://zotero.org/styles/”
]

… where maybe by convention you could invoke the style by doing:

   style = CSL.new('z:apa')

E.g. the 'z" prefix expands to the uri a la xml namespace binding. Not
important in a GUI app, but can be convenient with examples like
pandoc + citeproc.

Bruce

3

I have styles as a subdirectory to leave room for other stuff (maybe
config file to list CSL repos? some default behavior?).

Like imagine a config file that looked something like:

“repos” : [
“z” : “Zotero Style Repository”
]

… where maybe by convention you could invoke the style by doing:

  style = CSL.new('z:apa')

I think this would be something for Andrea and Simon to speak to. As
far as I know, the development environment I’m using for citeproc-js
(rhino) is not able to access content over
the wire. The program has an area for system localization, though,
where features like this
could be implemented.

Frank

4

So as Frank works on this tests and such, I’d like to raise an issue
for discussion, and that I would hope make it into the unit tests and
documentation.

How should a style be accessed?

Sub-issues:

  1. files names vs. ids

Right now, implementations are typically just using some variant of
accessing a file; in pseudo-code:

STYLE_FILE = ‘apa.csl’
style = CSL.new(STYLE_FILE)

But we have an Atom-based metadata system that this fails to exploit.
So what I want to suggest, instead, is that the (or at least a)
constructor is the style id; e.g.:

STYLE_ID = ‘http://zotero.org/styles/apa’
style = CSL.new(id = STYLE_ID)

  1. caching

Styles include update date-time stamps. The purpose here is enable
smart caching and updating. Can we say that implementations should
implement this? If yes, then should we suggests details on how (which
might borrowing some Atom documentation and adapting it for our use)?

Re: the above two options, maybe it makes more sense to copy styles
locally than to cache them? It makes sense to check for updates to a
style, but I’m not sure it’s a good idea to change a style without any
user interaction.

  1. storage

Shouldn’t CSL styles be cached in a fixed (but perhaps configurable)
local directory? E.g., at least in Unix/Linux/Mac OS:

.csl/
styles/

I have styles as a subdirectory to leave room for other stuff (maybe
config file to list CSL repos? some default behavior?).

I would suggest:
~/Library/Application Support/CSL/Styles (Mac OS X)
%AppData%/CSL/Styles (Windows)
~/.csl/styles (Unix/Linux)

Simon

5

As I said in my previous email, we might want to reconsider whether we
should really try to remotely load CSL files, as opposed to
downloading them for local use. In any case, though, this isn’t a
feasible constructor in browser-based JS, because the HTTP request has
to be done asynchronously with a callback to avoid freezing the UI
thread. We’d have to have something more like

CSL.new(‘z:apa’, function(style) {
// do something with the style object here
})

which is not really a very friendly construction.

Simon

6

Re: the above two options, maybe it makes more sense to copy styles locally
than to cache them?

Sure, that’s fine. Just wanted to get the conversation going.

It makes sense to check for updates to a style, but I’m
not sure it’s a good idea to change a style without any user interaction.

OTOH, this might be a config option. For example, I’d probably want it
to be set to update automatically, though grant that not everyone
would.

  1. storage

Shouldn’t CSL styles be cached in a fixed (but perhaps configurable)
local directory? E.g., at least in Unix/Linux/Mac OS:

.csl/
styles/

I have styles as a subdirectory to leave room for other stuff (maybe
config file to list CSL repos? some default behavior?).

I would suggest:
~/Library/Application Support/CSL/Styles (Mac OS X)
%AppData%/CSL/Styles (Windows)
~/.csl/styles (Unix/Linux)

Seems reasonable.

Bruce2009/3/23 Simon Kornblith <@Simon_Kornblith>:

7

Just an FYI that I solicited some feedback on this from the Zotero forums.

http://forums.zotero.org/discussion/6348

Some good points, and Dan has what look at first glance like some good
ideas on details (which I’ll look at in more detail later).

Bruce

8

So just a head’s up that I’ve been playing a bit with some code, and
what I’m doing ATM is having a directory organized like this:

~/.csl
/styles
index.json
apa.csl
…

The index file then looks like this:

{
“http://zotero.org/styles/apa” : {
“link”: “http://zotero.org/styles/apa.csl”,
“file”: “apa.csl”,
“updated”: “2008-10-29T21:01:24+00:00”
},
“http://zotero.org/styles/aag”: {
“link”: “http://zotero.org/styles/aag.csl”,
“file”: “aag.csl”,
“updated”: “2008-10-29T21:01:24+00:00”
}
}

This might be all too simple ATM, but it does make it easy to load the
right styles, to know when they need updating, etc., and does so using
a lightweight standard format. Right now, for example, I have
functions like:

def update_styles():
""“
Updates the users’ style repository.
”""
for styles in styles_index[‘styles’]:
style.update(style[‘id’])

The update method would then look at the existing updated value and
compare it against the server header for the link value.

Bruce

9

…

The update method would then look at the existing updated value and
compare it against the server header for the link value.

Or, come to think of it, etags might be better.

Bruce