Style Updating Survey

bdarcus

Those of us working on CSL development are discussing how the style files are stored and updated. In short, I want to allow different CSL implementations to share the same style files, and to make it easy for users to know their styles are up-to-date.

Assumptions: while now, most CSL styles are hosted at Zotero, where you can look through a repository and click to install, in the future, styles may be hosted anywhere. Ideally, journals start to self-host and self-develop their own styles, so that if you go to a "for authors" page to learn about the style guidelines, you can simply install it.

This brings me to the question: if a style changes in a repository, how should it be updated for you as a user? Options I see (edited to incorporate Sean's feedback):

1. Only by manual input, with no feedback from the application (in this case Zotero). Rather, you go to the place where you first installed the style, and reinstall it.


2. Only manual input, but the application tells you which styles are out-of-date (and maybe provides a dialog box with a list of outdated styles and checkboxes next to each for updating).


3. Automatic update, with no feedback (or at least no explicit input required). This is currently how Zotero works.


4. All of the above (e.g. it's configurable).

Finally, if you think 4, should the options be global (common to all CSL applications on a system), or local (specific to an application)?

mronkko

I would vote for 4 and have that as a global setting which defaults to 2.

Mikko

asplundj

I too would vote for 4 with 2 (local) as default

Rintze

Allow users to choose between 2 and 3, but allow styles to be overwritten via 1, manage styles locally.

sean

Please note that styles are currently automatically updated in Zotero, i.e. bdarcus's option 3.

bdarcus

Thanks, sean. I corrected the options to reflect that.

For those of you arguing for local config, I'm wondering if that would actually work. For example, if you have one application that says to use 3, and another application that says to use 1, then don't you really by default have a global 3?

Rintze

Thinking about this a bit more. Isn't it logical that styles that offer URL-resolvable IDs should always be automatically updated (also from a viewpoint of data-portability)? Users can escape automatic updating by using non-URL (=non-resolvable) IDs.

bdarcus

There might be something to the notion that it gets set in the style, but am not sure relying on the URI pattern will be enough.

noksagt

My ideal app would have 4 & would furthermore be configurable either per-repository or even per-style (e.g. I would trust most changes coming from a publisher's site & would probably want auto-updates, but would probably be more cautious if a style repository was very large and had a very low barrier for changes).

I'd be fine with defaulting to 2 or 3 (and I think 3 is probably the right default at this time, where there has been very few updates that have broken styles).

Such behavior should definitely be app-specific.

For those of you arguing for local config, I'm wondering if that would actually work. For example, if you have one application that says to use 3, and another application that says to use 1, then don't you really by default have a global 3?

I know you're a fan of storing everything in ~/.csl, but I am not. My ideal app would have a configurable csl path. It might have any initial subset of:

• ~/.app/csl
• ~/.csl
• /usr/local/share/app/csl
• /usr/local/share/csl
• /usr/share/app/csl
• /usr/share/csl

(or the equivalent standardized schemes, depending on the operating system).

That is: a subset of styles should probably be global across all users (for example, workstations in a group's lab might contain styles for the most popular hand-full of journals they write for). Some styles would benefit from being shared by multiple apps, if you actually use CSL for multiple apps (you and I do, not everyone will). Some who don't want a cluttered home directory & use only one csl app, as well as some who want to use a csl file from within only a single app (I'd do this for testing an app & for style development) would want csl to continue to be app-specific.

If multiple CSL tools used ~/.csl and update styles within that directory, I don't think users would be too surprised that one applications update updated a style that is used in other applications.

bdarcus

So, noksagt, you're suggesting a global directory, and an app-specific local directory?

And default is global (for the user)?

Would the per-style/repo rules you mention be global (e.g. stored in a global config file), or app-specific?

dstillman

There might be something to the notion that it gets set in the style, but am not sure relying on the URI pattern will be enough.

Yeah, the URI pattern isn't a good way to control this. The place to look for a style URL, if anywhere, would be the <link> element (without a rel attribute, and therefore equivalent to rel="self"). Most styles in the Zotero repo don't use these currently, but they probably should.

It might make sense for CSL clients to support two update mechanisms:

1) Auto-updating based on the <link> URL, using HEAD requests to determine whether a style had been updated. This would be the default method in the absence of a specified repository index and would make sense for individual authors or small publishers who made a few styles available for download, as it would free them from having to maintain an index.

2) Larger repositories would include a different <link> element with an appropriate rel attribute (I don't recall if we ever decided on one to use) and an href pointing to the Atom index. How many styles were displayed on the first page of the feed (and whether that was based on quantity or age) would be up to the publisher, but it wouldn't matter as long as the feed included rel="(first|next|previous|last)" links and the CSL client automatically followed the rel="previous" link until it got to an entry earlier than its last update date.

Clients should be smart enough to check each unique index only once at each update time (even if multiple styles pointed to the same one).

Clients should also have the ability to be subscribed to entire repositories (in which case all styles in that repository would be downloaded and kept up-to-date) or just individual styles. In Zotero's case, users would be subscribed by default to the 'public' index, and dev styles would point to a dev index for updating of installed dev styles. When manually deleting a style that had been downloaded as part of a subscribed repository, the client might want to prompt the user as to whether to stay subscribed to that repo (in which case the style would be reinstalled the next time it was updated).

An empty <content> element without a src attribute would cause an installed style to be deleted (or there could be something more explicit to prevent accidents). We have this ability via the Zotero repo and have needed it on occasion.

bdarcus

Am going to look at your details later, Dan, but on this:

Clients should also have the ability to be subscribed to entire repositories (in which case all styles in that repository would be downloaded and kept up-to-date) or just individual styles.

Right, but I'd add also category-based collections within a repository as well. Generating these feeds would, after all, be pretty easy. So a user, for example, might simply subscribe to some hypothetical http://zotero.org/styles/biology collection, rather than the entire Zotero repository.

noksagt

So, noksagt, you're suggesting a global directory, and an app-specific local directory?

Yes, but I think the most important part of my suggestion is to just make the path configurable, as it gives everyone the ability to get the setup they want. This is how the templates path in OO.o works, for example.

And default is global (for the user)?

I'd actually be fine with any default (especially if, as above, it could be changed). That Mendeley and Zotero both default to being application-specific & that a majority of users will use only a single reference manager, I suspect that a default of being local/app-specific has more traction.

Would the per-style/repo rules you mention be global (e.g. stored in a global config file), or app-specific?

For simplicity of the CSL format (particularly at least the perceived simplicity in implementing it), I'd say that these configurations should also be application-specific.

In this manner, I'd hope that more apps would adopt CSL (even with only update mechanism #1).

I like a model where some apps will then try to improve the end-user experience with CSL. As I said: my ideal app would work a certain way, but I wouldn't expect, need, or even want all CSL-using apps to work that way.

bdarcus

It might make sense for CSL clients to support two update mechanisms:

1) Auto-updating based on the URL, using HEAD requests to determine whether a style had been updated. This would be the default method in the absence of a specified repository index and would make sense for individual authors or small publishers who made a few styles available for download, as it would free them from having to maintain an index.

I think this use case is important. A small journal should just be able to put their CSL style in a directory with an .htaccess file with appropriate setup and be able to publish it, with all the benefits you outline.

So you're saying, effectively, that the lack of a link in the CSL header would mean it would not get updated? E.g. auto-updating requires a link?

2) Larger repositories would include a different element with an appropriate rel attribute (I don't recall if we ever decided on one to use) and an href pointing to the Atom index.

OK.

How many styles were displayed on the first page of the feed (and whether that was based on quantity or age) would be up to the publisher, but it wouldn't matter as long as the feed included rel="(first|next|previous|last)" links and the CSL client automatically followed the rel="previous" link until it got to an entry earlier than its last update date.

So here you're addressing the paging issue; relevant if you have a collection that is large (larger, say, than twenty). Sounds good.

Clients should be smart enough to check each unique index only once at each update time (even if multiple styles pointed to the same one).

Right.

Clients should also have the ability to be subscribed to entire repositories (in which case all styles in that repository would be downloaded and kept up-to-date) or just individual styles. In Zotero's case, users would be subscribed by default to the 'public' index, and dev styles would point to a dev index for updating of installed dev styles.

As I said in my earlier reply, I'm not sure this is the best way to slice it. Certainly the development status of the style is relevant, but the more important way that users slice styles is by category (field, type, etc.). So there are the canonical styles, each associated with certain broad areas, and of a certain type (note, author-date, author, etc.). There are then all of the (typically journal-specific) styles associated with particular fields. I'd like my style management and updating to understand that.

In any case, I like this. So what should we do about this, Dan? Do you want to float this to the xbib-dev list (where one of the Mendeley devs just joined) and see if we can come up with a draft document (or maybe just add it to the schema for now) that formalizes this?