CSL Editor - reference manager integration

CSL Development
1

Hello,

I’d like to open a discussion with the developers of Zotero, Papers and any
other reference managers about utilizing the CSL Editor that Columbia
University, Mendeley and myself have been working on (
http://steveridout.com/csl/home/)

It’s not ready for the average user yet but there’s still a large chunk of
dev time left. As of now, I’ve still got more than half the hours I’ve been
contracted for left to finish, and additionally we are now starting to get
input from UX at Mendeley. The code is MIT licenced and we hope it will
continue to be used and maintained after this Sloan funded project ends.

We want to focus now on making the style editor the best it can be for
individual users to edit their styles. It’s not in the project scope to
host user created styles online, or provide an easy method for contributing
to the styles repo (although they are great ideas). With this in mind,
Carles from Mendeley and I have come up with two possibilities for
integrating the editor with reference managers:

— 1. CSL editor runs within the reference manager application. —

This seems ideal from the user’s point of view.

Ref manager application loads the CSL editor page into a web pane, e.g.
using WebKit. It can then interact with the editor to load and save styles
by using a javascript API within the webpage directly.

This is relatively simple for Mendeley to implement given that they use
WebKit panes already. Since Zotero runs within firefox it seems plausible
that this method could be used by Zotero too, but I’d need confirmation
from the developers. I’m not sure about Papers.

— 2. CSL editor runs in a browser, separate from the ref manager. —

The ref manager could initiate the CSL editor by:
a) posting the style to be edited to temporary online storage with a
publicly resolvable URL.
b) opening the CSL editor in a browser with the temporary URL in the query
string so it can fetch the style to be edited.

To get the edited CSL style back into the ref manager, we could use a data
URI with a custom mime type. If the ref manager is registered to handle
this mime type then the user will be presented with an option to either
save or open the file with the ref manager application.—

We think that option 1 is the best, and are only proposing option 2 in case
there are reference managers that would find implementation of 1 difficult.

Look forward to hearing from the other ref manager devs with their opinions
and suggestions.

Thanks,
Steve

2

Hi Steve,

Thanks very much for the update, and the work on the CSL editor. I know I have not responded much on the topic, but that’s unfortunately because we only have limited resources to handle the workload on Papers and the CSL part of it. I have not yet discussed it with Alex, but if we were to integrate the editor in the app, route 1 seems like the best way to do it for us as well. Like you said, that’s a better user experience. At this stage, I don’t know if we will integrate the editor, of course, but we’ll certainly look into it, and we have been keeping an eye on the progress so far. A good CSL editor is definitely an important piece missing for us as well.

Thanks!

Charles

3

We want to focus now on making the style editor the best it can be for

individual users to edit their styles. It’s not in the project scope to
host user created styles online, or provide an easy method for contributing
to the styles repo (although they are great ideas).

I’m not going to comment on the specifics (I’ll leave that to the client
implementers), but just want everyone here to keep in mind the use cases,
in part so that perhaps some kind of smart coordination can happen to fill
in the gaps on the scope question. Since the code is MIT licensed (and on
github?), there’s no impediment for others contributing to this.

So regardless of which of these paths you all want to take for client
integration on the single user case, my question is how we do this in such
a way that the step to social and multi-user is not too large.

Just to repeat and condense my earlier arguments:

  1. People don’t want to create or edit styles. They just want them to
    work.
  2. They want to edit style because either there’s a bug, or because the
    original style author didn’t consider a particular kind of source. But
    these edit needs typically are not needs specific to the user.
  3. They create new styles when they can’t find the style they need.
    Typical case: they need a style for “Journal X” and can’t find it. But
    more-often-than-not, “Journal Y” will fill the need. [this is why your work
    on the search interface is important Steve]. Again, the needs aren’t
    specific to the user.

So when we say “we want … individual users to [be able to] edit their
styles”, what do we really mean?

  1. What is “their styles”? Is it simply the community created styles
    they have access to?
  2. Pull out from the single user and consider the hundreds of thousands
    of CSL users. How do we make the work for the former contribute to making
    life easy for the latter; so they don’t feel the need to “edit their
    styles” to begin with?

Per Rintze’s earlier comments, I think it ought to be possible. Maybe upon
editing a style, for example, there’s a “submit to public repository” link
that has a small description field, and which creates a patch and pull
request on the giithub repository?

There would still need to be an easier way to preview changes though for
the repo style editors. And wed need to grow the number of editors.

Bruce

4

Actually, an idea:

Per Rintze’s earlier comments, I think it ought to be possible. Maybe
upon editing a style, for example, there’s a “submit to public repository”
link that has a small description field, and which creates a patch and pull
request on the giithub repository?

Each project has their own github fork of the main CSL styles repo.

Users get styles from their respective forks, and if they edit and submit,
they do so to that fork, on branches.

Project-specific maintainers merge those branches as they see fit, and
issue a pull request on the main csl repo.

A script could automate this, so that the amount of work in curating the
edits is minor.

Seem reasonable?

If yes, then it ought to be a small step from what Steve has now to that,
and it shouldn’t matter where the editor lives: in client apps, on the web,
or more likely, both.

Right?

Bruce

5

I like the idea of client-specific forks. In fact, I have styles that I could already host on such a fork, which require the PMID variable (and which for now, rely on a Papers2-specific CSL variable).

Forking could have been perceived as a bit aggressive, so I never really considered it (and to be honest, I don’t think I ever realized it could be a nice way to handle the few edge cases like Papers2-specific styles).

Now, there is one potential risk of further confusion for the end user: instead of just 1 repo, there are now a bunch of them. That will require to make it very clear what’s going on. Though, to be honest, if the end user has to go on github to get a style, we already failed :wink: (and in fact, that’s currently something that sometimes confuse the few brave souls that try to get a style from the web).

All in all, I’d say the benefits outweigh the potential problems.

Charles

6

Just to clarify:

I like the idea of client-specific forks. In fact, I have styles that I
could already host on such a fork, which require the PMID variable (and
which for now, rely on a Papers2-specific CSL variable).

Maybe we should add that variable to CSL to avoid that sort of fork?

Forking could have been perceived as a bit aggressive, so I never really
considered it (and to be honest, I don’t think I ever realized it could be
a nice way to handle the few edge cases like Papers2-specific styles).

Now, there is one potential risk of further confusion for the end user:
instead of just 1 repo, there are now a bunch of them.

No. For the user, there would only be one: the main one. This would be
behind-the-scenes.

We’d just need to keep them in sync.

It may not be the best idea; it would really depend on details.

I just floated that as a way to sort of distribute the curation of edits.
There may be other ways to do that, though, with a single repo.

Forking with DVCS has a different social and technical meaning than it does
with CVS/SVN. The main goal we’re shooting for here is for all CSL users to
collectively benefit from the labor of creating and maintaining styles.

BruceOn Wed, Jun 6, 2012 at 12:28 PM, Charles Parnot <@Charles_Parnot>wrote:

7

It it my understanding that it’s coming in CSL 1.0.1?

8

It is (along with “PMCID”).

RintzeOn Wed, Jun 6, 2012 at 12:49 PM, Charles Parnot <@Charles_Parnot>wrote:

9

Now, there is one potential risk of further confusion for the end user: instead of just 1 repo, there are now a bunch of them.

No. For the user, there would only be one: the main one. This would be behind-the-scenes.

We’d just need to keep them in sync.

Sure, but the forked repositories will still be accessible on github, and this is what I meant by potential confusion. We definitely would not give the user any direct way to get there, but they could still end up there. But again, once your user is on github, all bets are off :wink:

10

My feeling is that there should be a modular API for load/save, where an object passed to the editor constructor contains the appropriate methods. The editor could include a default implementation for running within a browser, but it should be possible for custom implementers to provide their own implementation. This would be very easy for us, but I’m not sure how difficult it is for other implementers to expose native functions to content.

Simon

11

@Simon - thanks, that sounds like a good approach, I’ll work on it.

@Charles - good to hear, we’ll focus on option 1 in this case.

Integration with github sounds promising, and there should be nothing to
stop ref managers implementing this in future (if the editor turns out to
be useful!)

12

My feeling is that there should be a modular API for load/save, where an object passed to the editor constructor contains the appropriate methods.

Makes sense, that will work for us. Both QtWebKit and OS X’s WebKit
provide facilities for exposing ‘native’ objects to web content as JS
objects.

Regards,
Rob.