a 1.0 repo for styles [IMPORTANT]

[Bruce_D_Arcus1]

Please see this thread on the pandoc list:

http://groups.google.com/group/pandoc-discuss/browse_frm/thread/4e49b9f74686ebd

Upshot is we really need to do something about the CSL 1.0 styles repo
sooner, rather than later.

One idea:

We’ve previously talked about possibly basing a next-gen shared repo
on git and github. The nice thing about this approach is that it’s
easy to build up incrementally, so that we could simply fork the 0.8
styles in the zotero svn, convert them to 1.0, and load them into a
repo at github.

There’d still be details to work out of course, but is there interest
in pursuing this path?

Bruce

[Andrea_Rossato1]

I’m not familiar with the zotero community and I do not familiar with
the zotero styles development process. If the move you are proposing
is not going to have any bad impact on that community I think the need
is indeed present.

I’m not really at home with git, but this is irrelevant.

Andrea

[Bruce_D_Arcus1]

Please see this thread on the pandoc list:

http://groups.google.com/group/pandoc-discuss/browse_frm/thread/4e49b9f74686ebd

Upshot is we really need to do something about the CSL 1.0 styles repo
sooner, rather than later.

One idea:

We’ve previously talked about possibly basing a next-gen shared repo
on git and github. The nice thing about this approach is that it’s
easy to build up incrementally, so that we could simply fork the 0.8
styles in the zotero svn, convert them to 1.0, and load them into a
repo at github.

There’d still be details to work out of course, but is there interest
in pursuing this path?

I’m not familiar with the zotero community and I do not familiar with
the zotero styles development process. If the move you are proposing
is not going to have any bad impact on that community I think the need
is indeed present.

Right now, there’s a small number of Zotero (power) users that create
and maintain the styles, most of whom are on this list. So I doubt it
would be disruptive.

I’m not really at home with git, but this is irrelevant.

We could just as well use mercurial w/bitbucket as far as I’m
concerned, but the general idea was to use a well-supported DVCS with
good mindshare, and which has a good, free, hosting site with an API.

This is as opposed to rolling our own repository model and code.

Bruce

[Carles_Pina]

Hi,On 24 November 2010 17:43, Bruce D’Arcus <@Bruce_D_Arcus1> wrote:

One idea:

We’ve previously talked about possibly basing a next-gen shared repo
on git and github. The nice thing about this approach is that it’s
easy to build up incrementally, so that we could simply fork the 0.8
styles in the zotero svn, convert them to 1.0, and load them into a
repo at github.

There’d still be details to work out of course, but is there interest
in pursuing this path?

I think that there is interest. At least, I don’t see any reason to
not do it (some way or another)., but the DCVS idea is nice to avoid
re-implementing the wheel again.

[Bruce_D_Arcus1]

Any other thoughts out there? Simon? Dan?

[Simon_Kornblith]

This sounds good to me.

Simon

[Bruce_D_Arcus1]

So if this is a good, how should we go about proceeding? The detail
questions I have center on the ids/uris:

1. Should 0.8 styles have different URIs from 1.0 styles?

2. how do we deal with the base URI? Do we want
   "http://citationstyles.org" and somehow redirect to the github repo?
   If the latter, how?

3. how do we want to setup the repo and associated policies?

   • what account? do we want a new “citationstyles” account with a
     few different admins?
   • how do we encourage style changes? Sign up at github, fork the
     repo, and issue a pull request?

Anything else?

Bruce

[Bruce_D_Arcus1]

Oh, and could we hook up citeproc-js to some kind of enhanced
sortable/searchable index view of the styles?

[Simon_Kornblith]

This sounds good to me.

So if this is a good, how should we go about proceeding? The detail
questions I have center on the ids/uris:

1. Should 0.8 styles have different URIs from 1.0 styles?

Provided we are sure we want to host 0.8 styles at all, and deal with the associated headache of keeping 0.8 and 1.0 styles in sync, they’d have to have different URIs for dependent styles to work as implemented in Zotero 2.0.9.

In an ideal world, I think we’d use the same URI and use either a client header or a query string appended to the URI to choose which version to return, or give a 300 Multiple Choices response if neither are present. We can implement this in Zotero, but we have no plans for a future Zotero 2.0.* release at present, so maybe this is something that we should implement in preparation for CSL 1.1 instead.

2. how do we deal with the base URI? Do we want
   “http://citationstyles.org” and somehow redirect to the github repo?
   If the latter, how?

At least for the Zotero use case, this depends on whether we can serve the styles as text/x-csl off of github. The Zotero repository allows serving as both text/x-csl and text/xml, but I’m not sure that’s necessary.

We will want an HTML frontend on citationstyles.org that’s generated off of a checkout anyway, so we could also serve off the checkout and avoid redirecting, provided we can update it when the github repo changes.

3. how do we want to setup the repo and associated policies?
   • what account? do we want a new “citationstyles” account with a
     few different admins?
   • how do we encourage style changes? Sign up at github, fork the
     repo, and issue a pull request?

I’ll defer to others with greater DVCS experience on this issue, although what you suggest sounds fine to me.

Simon

[Bruce_D_Arcus1]

OK, John MacFarlane is asking for some resolution for this, so that he
can add a link to a repository of 1.0 styles in his README. So I’d
like to deal with this in the next 24-48 hours, but have some
remaining questions to resolve …

This sounds good to me.

So if this is a good, how should we go about proceeding? The detail
questions I have center on the ids/uris:

1. Should 0.8 styles have different URIs from 1.0 styles?

Provided we are sure we want to host 0.8 styles at all, and deal with the
associated headache of keeping 0.8 and 1.0 styles in sync, they’d have to
have different URIs for dependent styles to work as implemented in Zotero
2.0.9.

I don’t want to host 0.8 styles at all.

So what to do? I guess I’d lean towards having different URIs, and so
inserting a “1.0” as part of the fragment.

This is a pretty big decision so speak now or forever hold your peace.

In an ideal world, I think we’d use the same URI and use either a client
header or a query string appended to the URI to choose which version to
return, or give a 300 Multiple Choices response if neither are present. We
can implement this in Zotero, but we have no plans for a future Zotero 2.0.*
release at present, so maybe this is something that we should implement in
preparation for CSL 1.1 instead.

2. how do we deal with the base URI? Do we want
   “http://citationstyles.org” and somehow redirect to the github repo?
   If the latter, how?

At least for the Zotero use case, this depends on whether we can serve the
styles as text/x-csl off of github. The Zotero repository allows serving as
both text/x-csl and text/xml, but I’m not sure that’s necessary.
We will want an HTML frontend on citationstyles.org that’s generated off of
a checkout anyway, so we could also serve off the checkout and avoid
redirecting, provided we can update it when the github repo changes.

OK, so maybe for the initial repo that John’s asking for, we can just
use the citationstyles.org base domain, but not worry about the
details?

3. how do we want to setup the repo and associated policies?
   • what account? do we want a new “citationstyles” account with a
     few different admins?
   • how do we encourage style changes? Sign up at github, fork the
     repo, and issue a pull request?

I’ll defer to others with greater DVCS experience on this issue, although
what you suggest sounds fine to me.

Here’s a discussion of github’s “organizations” model:

https://github.com/blog/674-introducing-organizations

Is that appropriate for us, such that we want a “Citation Styles” organization?

Some other suggestion(s)?

Bruce

[Bruce_D_Arcus1]

Also …

I think if we settle the details I was asking about in the last
message, maybe we could setup a placeholder page like, I dunno,
“http://citationstyles.org/repository” where we initially could just
put a link to a repo on github?

So to sum up:

1. copy all 1.0 styles in the zotero repo and dependent styles to
   having a “citationstyles.org” base and to include a “1.0” fragment
   (this would commit to versioning styles going forward)

2. establish a “Citation Style” org at github, and relevant repo

3. create a placeholder for the repo gui at citationstyles.org that points to 2.

Bruce

[Rintze_Zelle]

Could we perhaps have the base URI point to the newest CSL version of a
style, with an optional version indicator?:

http://citationstyles.org/styles/apa (points to the newest CSL version, i.e.
“1.0” for now)
http://citationstyles.org/styles/apa/0.8 (points to the CSL 0.8 version)
http://citationstyles.org/styles/apa/1.0 (points to the CSL 1.0 version)

(I don’t know a lot about building URIs, so I might not make a lot of sense)

Rintze

[Bruce_D_Arcus1]

Well, I think it might make sense to take that approach using
mod-rewriting (mapping one URI to another). But you still need to
define the URIs to map. For that, I was thinking more like:

http://citationstyles.org/styles/1.0/apa

That would presume a repo directory organization like:

/
1.0/
apa.csl
1.1/
apa.csl

Bruce

[Ron_Jerome]

http://citationstyles.org/styles/apa (points to the newest CSL version, i.e.
“1.0” for now)
http://citationstyles.org/styles/apa/0.8 (points to the CSL 0.8 version)
http://citationstyles.org/styles/apa/1.0 (points to the CSL 1.0 version)

(I don’t know a lot about building URIs, so I might not make a lot of sense)

Well, I think it might make sense to take that approach using
mod-rewriting (mapping one URI to another). But you still need to
define the URIs to map. For that, I was thinking more like:

I hate to keep going on about the Drupal CMS, but it’s really tailor
made for this because you can map URI’s to callback functions. For
instance, you could map “Redirecting…” to a
callback function “get_style()”, now anything following /styles in the
URI is passed to the function as arguments, so
http://citationstyles.org/styles/apa/0.8 would call get_style(‘apa’,
0.8), then within the callback function you could pull the appropriate
file from github (using their php-api) and return it the user based on
the arguments provided (or list of available files if no arguments
are given). Similarly, arguments could be added to the URI
(http://citationstyles.org/styles/apa/install) which would trigger the
callback function to add the appropriate mime type (text/x-csl) in the
response header for Zotero.

Pulling the styles from GitHub for every request might be the greatest
idea though, so you could cache the styles locally in the DB on
citationsyles.org and update the cache daily (or some other
predetermined frequency) from GitHub.

Ron.

[Bruce_D_Arcus1]

I vaguely remember you mentioned Drupal in this context previously. So
are you suggesting moving citationstyles.org to Drupal, and using that
as a front-end for the repository? Is there something in particular
that Drupal does that some simply PHP functions couldn’t?

Just asking; am a pretty big fan of what I’m seeing in Drupal 7.

Bruce

[Frank_Bennett]

Provided we are sure we want to host 0.8 styles at all, and deal with
the
associated headache of keeping 0.8 and 1.0 styles in sync, they’d have
to
have different URIs for dependent styles to work as implemented in
Zotero
2.0.9.

I don’t want to host 0.8 styles at all.

So what to do? I guess I’d lean towards having different URIs, and so
inserting a “1.0” as part of the fragment.

Could we perhaps have the base URI point to the newest CSL version of a
style, with an optional version indicator?:

http://citationstyles.org/styles/apa (points to the newest CSL version, i.e.
“1.0” for now)
http://citationstyles.org/styles/apa/0.8 (points to the CSL 0.8 version)
http://citationstyles.org/styles/apa/1.0 (points to the CSL 1.0 version)

(I don’t know a lot about building URIs, so I might not make a lot of sense)

Well, I think it might make sense to take that approach using
mod-rewriting (mapping one URI to another). But you still need to
define the URIs to map. For that, I was thinking more like:

http://citationstyles.org/styles/1.0/apa

That would presume a repo directory organization like:

/
1.0/
apa.csl
1.1/
apa.csl

Whatever the layout of the repository, shouldn’t the style name come
before the version in the URI? The user will typically want a
particular style, but they (or their processor) may or may less fussy
about the CSL version in which it is expressed.

[Bruce_D_Arcus1]

So you’re suggesting:

apa/
1.0.csl

…?

In any case, worth considering how we imagine using these over time,
as the spec and repositories evolve.

Bruce

[Ron_Jerome]

I hate to keep going on about the Drupal CMS, but it’s really tailor
made for this because you can map URI’s to callback functions. For
instance, you could map “Redirecting…” to a
callback function “get_style()”, now anything following /styles in the
URI is passed to the function as arguments, so
http://citationstyles.org/styles/apa/0.8 would call get_style(‘apa’,
0.8), then within the callback function you could pull the appropriate
file from github (using their php-api) and return it the user based on
the arguments provided (or list of available files if no arguments
are given). Similarly, arguments could be added to the URI
(http://citationstyles.org/styles/apa/install) which would trigger the
callback function to add the appropriate mime type (text/x-csl) in the
response header for Zotero.

Pulling the styles from GitHub for every request might be the greatest
idea though, so you could cache the styles locally in the DB on
citationsyles.org and update the cache daily (or some other
predetermined frequency) from GitHub.

I vaguely remember you mentioned Drupal in this context previously. So
are you suggesting moving citationstyles.org to Drupal, and using that
as a front-end for the repository?

Yes, that’s exactly what I’m proposing and writing a bridge module
between GitHub and Drupal. I just tested the PHP API to access
GitHub, and it’s fairly straightforward, but as I suspected, it’s not
very fast. So I don’t think serving csl styles directly from GitHub
would be scalable to large numbers of clients.

What is citestyles.org currently running on in terms of it’s framework?

Is there something in particular that Drupal does that some simply PHP functions couldn’t?

Yes, the path mapping to callback functions that I described earlier,
for one, but there are a multitude of others RDF would be another that
you would be interested in, not to mention the modular architecture,
which allows you to extend the core functionality very easily. I
would be willing to bet that I could craft a GitHub<->Drupal bridge
module within a day or two.

Just asking; am a pretty big fan of what I’m seeing in Drupal 7.

Ron.

[Bruce_D_Arcus1]

I hate to keep going on about the Drupal CMS, but it’s really tailor
made for this because you can map URI’s to callback functions. For
instance, you could map “Redirecting…” to a
callback function “get_style()”, now anything following /styles in the
URI is passed to the function as arguments, so
http://citationstyles.org/styles/apa/0.8 would call get_style(‘apa’,
0.8), then within the callback function you could pull the appropriate
file from github (using their php-api) and return it the user based on
the arguments provided (or list of available files if no arguments
are given). Similarly, arguments could be added to the URI
(http://citationstyles.org/styles/apa/install) which would trigger the
callback function to add the appropriate mime type (text/x-csl) in the
response header for Zotero.

Pulling the styles from GitHub for every request might be the greatest
idea though, so you could cache the styles locally in the DB on
citationsyles.org and update the cache daily (or some other
predetermined frequency) from GitHub.

I vaguely remember you mentioned Drupal in this context previously. So
are you suggesting moving citationstyles.org to Drupal, and using that
as a front-end for the repository?

Yes, that’s exactly what I’m proposing and writing a bridge module
between GitHub and Drupal. I just tested the PHP API to access
GitHub, and it’s fairly straightforward, but as I suspected, it’s not
very fast. So I don’t think serving csl styles directly from GitHub
would be scalable to large numbers of clients.

What is citestyles.org currently running on in terms of it’s framework?

WordPress.

Is there something in particular that Drupal does that some simply PHP functions couldn’t?

Yes, the path mapping to callback functions that I described earlier,
for one, but there are a multitude of others RDF would be another that
you would be interested in, not to mention the modular architecture,
which allows you to extend the core functionality very easily. I
would be willing to bet that I could craft a GitHub<->Drupal bridge
module within a day or two.

Well then I’ll just have to dare you to

Seriously, if you have time, that’d be cool.

So from that perspective, Drupal would give us authentication, the
callback structure, and it should be pretty easy to set up per-style
preview pages with comments.

How about indexing and searching of styles?

Bruce

[Frank_Bennett]

Provided we are sure we want to host 0.8 styles at all, and deal with
the
associated headache of keeping 0.8 and 1.0 styles in sync, they’d have
to
have different URIs for dependent styles to work as implemented in
Zotero
2.0.9.

I don’t want to host 0.8 styles at all.

So what to do? I guess I’d lean towards having different URIs, and so
inserting a “1.0” as part of the fragment.

Could we perhaps have the base URI point to the newest CSL version of a
style, with an optional version indicator?:

http://citationstyles.org/styles/apa (points to the newest CSL version, i.e.
“1.0” for now)
http://citationstyles.org/styles/apa/0.8 (points to the CSL 0.8 version)
http://citationstyles.org/styles/apa/1.0 (points to the CSL 1.0 version)

(I don’t know a lot about building URIs, so I might not make a lot of sense)

Well, I think it might make sense to take that approach using
mod-rewriting (mapping one URI to another). But you still need to
define the URIs to map. For that, I was thinking more like:

http://citationstyles.org/styles/1.0/apa

That would presume a repo directory organization like:

/
1.0/
apa.csl
1.1/
apa.csl

Whatever the layout of the repository, shouldn’t the style name come
before the version in the URI? The user will typically want a
particular style, but they (or their processor) may or may less fussy
about the CSL version in which it is expressed.

So you’re suggesting:

apa/
1.0.csl

…?

I don’t have an opinion about the directory hierarchy. My point was
only about the URI.