on citestyles.org, wizard

CSL Development
1

So just some notes to think about in terms of rough plans for citestyles.org.

Here’s what I think we need on the coding front:

  1. The styles tab will host the styles in the zotero repo updated to
    CSL 1.0. For this, we need something like what Rintze is working to
    find styles.

  2. We probably need the HTML pages-per-style that Robert mentioned.
    Ideally those HTML pages also have a comments facility (though this is
    less critical, and adds complexity).

  3. Finally, the style wizard to create new styles easily (I’d say a
    reasonable goal is five minutes).

To remind people, I started to spec it out here:

http://sourceforge.net/apps/trac/xbiblio/wiki/CslWizardDesign

I also started a mockup using JQuery here:

http://www.users.muohio.edu/darcusb/citations/MakeCSL/

Finally, I started to play with a Python script that can ingest a
simple JSON definition of a style, and spit out a CSL:

http://xbiblio.svn.sourceforge.net/viewvc/xbiblio/csl/scripts/makecsl/

So on this front, assuming my basic idea is right, I think we need to finish:

  1. the (or a) script, which includes ensuring we have a sufficient
    collections of macros for that

  2. the JS/JQuery-based UI (generating the JSON for 1? and hooking up
    citeproc-js-based previewing?)

We also need a good designer to write some CSS and such for
citestyles.org in general.

Are there any particular opinions about:

a) whether this is right, and …

b) how we should proceed such that people/companies can contribute to
this? Put differently, who’s willing to dedicate what specific
resources to what specific work? Where should the code live? Under
what license? With what sorts of contribution mechanisms?

Bruce

2

Um, citationstyles.org.

Bruce

3

Assuming we want to use a server-side search, maybe this helps:

http://sourceforge.net/apps/trac/xbiblio/wiki/StyleSearchApi

Rintze

4

Why both title-start and title-exact? Do we really need that kind of detail?

Just asking …

Bruce

5

Both have their uses. title-start allows you to easily skip all the “journal
of …” results if you’re looking for a title that starts with something
different. Likewise, title-exact helps with finding short generic journal
titles (Cell, Nature, Science).

Rintze

6

So just some notes to think about in terms of rough plans for
citestyles.org.

Here’s what I think we need on the coding front:

  1. The styles tab will host the styles in the zotero repo updated to
    CSL 1.0. For this, we need something like what Rintze is working to
    find styles.

Assuming we want to use a server-side search, maybe this helps:

XBib download | SourceForge.net

Probably just title-contains is enough for titles?
Would it be useful to also be able to select all of the dependent
styles of a master?

The results would need to include the navigation values (number of
items to list, page position) so that they can be thrown back at the
server.

7

Probably just title-contains is enough for titles?

My thought as well. Seems the default should be that the search input
is a space-separated list of tokens? So if I’m searching “Journal of
Particle Physics” I should just be able to type “particle physics” and
it will return the above style (if present) at the top of the list.

Would it be useful to also be able to select all of the dependent
styles of a master?

Yes, though not necessarily from the search field per se.

The results would need to include the navigation values (number of
items to list, page position) so that they can be thrown back at the
server.

“Page position”?

I’d really like to avoid old-school search results interfaces that
force users to page through a bunch of pages. I want this to work fast
and simply.

All of this sort of reminds me: might be nice to define the use cases
before settling on the solution?

Bruce

8

I think the main ones are:

  1. a user is looking for one specific style, e.g. the one dictated by some
    journal. You can expect the user to search by title or issn/issn-l.
  2. a user is looking for a style with the desired formatting. Here you might
    expect users to skim over a couple dozen of styles. The ability to select
    for style features (currently only citation-format) is very helpful here.
  3. a user is looking for a way to install all the styles he/she is likely to
    need. Here subscriptions to a group of styles might be very useful.
    Currently the field/subject categories can be used for this, but maybe
    something more flexible would be handy as well (e.g. the ability for users
    to create sharable style collections that contain arbitrary sets of styles).
    E.g. in my research group we probably publish > 95% of all our papers in
    just 10 journals.

Rintze

9

I think the main ones are:

  1. a user is looking for one specific style, e.g. the one dictated by some
    journal. You can expect the user to search by title or issn/issn-l.

Yup.

Question: should the database be able to index styles hosted elsewhere?

  1. a user is looking for a style with the desired formatting. Here you might
    expect users to skim over a couple dozen of styles. The ability to select
    for style features (currently only citation-format) is very helpful here.

Yes.

Related to this and the wizard feature, it should be possible for a
user to also easily see that the style they want doesn’t exist, and to
be able to someone create a new one based on an existing one that is
close?

  1. a user is looking for a way to install all the styles he/she is likely to
    need. Here subscriptions to a group of styles might be very useful.
    Currently the field/subject categories can be used for this, but maybe
    something more flexible would be handy as well (e.g. the ability for users
    to create sharable style collections that contain arbitrary sets of styles).
    E.g. in my research group we probably publish > 95% of all our papers in
    just 10 journals.

Don’t you first want to sat that a user might want to search by field?
Do we want to say there should be index pages based on field?

Bruce

10

Just as a reminder, there’s a screenshot here of the Django repo app
that I started awhile back.

http://community.muohio.edu/blogs/darcusb/archives/2008/02/25/from-proposal-to-example-csl-gallery

It includes three main mechanisms to access styles:

  1. by category
  2. by title
  3. search

The first two are just index pages.

Bruce

11

b) how we should proceed such that people/companies can contribute
to this? Put differently, who’s willing to dedicate what specific
resources to what specific work? Where should the code live? Under
what license? With what sorts of contribution mechanisms?

Hello,

We’d be willing to contribute to the CSL wizard part of this in the
near term - both drafting a proposal for the user interface (and
integrating it on the wiki page you mentioned) and technical
development of the style wizard. We might also be able to help out
with aspects of the design in future - although to begin with as long
as the page is simple to use and functional the CSS fine tuning can
wait.

For the license, something I would suggest something simple, liberal
and well known. I’m thinking of BSD for example.
I would suggest that the code should live somewhere where all
interested parties have easy access to it (both to read and to
contribute) - eg. a hosting service such as Google Code, Launchpad,
Gitorious or similar - preferably one which allows people to easily
fork and experiment.

Regards,
Robert.2009/9/27 Bruce D’Arcus <@Bruce_D_Arcus1>:

12

b) how we should proceed such that people/companies can contribute
to this? Put differently, who’s willing to dedicate what specific
resources to what specific work? Where should the code live? Under
what license? With what sorts of contribution mechanisms?

Hello,

We’d be willing to contribute to the CSL wizard part of this in the
near term - both drafting a proposal for the user interface (and
integrating it on the wiki page you mentioned) and technical
development of the style wizard. We might also be able to help out
with aspects of the design in future - although to begin with as long
as the page is simple to use and functional the CSS fine tuning can
wait.

Right.

For the license, something I would suggest something simple, liberal
and well known. I’m thinking of BSD for example.
I would suggest that the code should live somewhere where all
interested parties have easy access to it (both to read and to
contribute) - eg. a hosting service such as Google Code, Launchpad,
Gitorious or similar - preferably one which allows people to easily
fork and experiment.

So we’ve got four questions, with Robert suggesting the following:

  1. Who’s willing to dedicate what specific resources to what specific work?

Mendeley is offering to contribute to the design and development of
the wizard ui; let’s call it makecsl-ui.

I know Zotero is also interested in working on some of this.

  1. Where should the code live?

I’m partial to bitbucket and github, but people here are tending to
gravitate towards the former. So I’d suggest that. It gives us a nice
ui with built-in wiki and issue tracker, and it’s designed for easy
forking (mercurial).

  1. Under what license?

Robert suggests BSD. I don’t really care; whatever emerges as
consensus is fine by me.

  1. With what sorts of contribution mechanisms?

The choice is between centralized (CVS/SVN-like) or decentralized.

I strongly favor the second because it lowers the bar to contribute.
People can easily fork a project and work on it independently, and
then issue a pull request if they want to merge.

So I’m going to float a proposal:

How about I setup two projects at bitbucket: makecsl-core and
makecsl-ui. We can do the spec work over there on the wikis. We can
deal with contribution and management stuff later as things evolve
(e.g. I can assign one or more other people to take over ownership to
manage issues, commit access, etc.).

Alternately, there could be just a single makecsl repo, but I’m
thinking there may be value in splitting them.

Anyone from Zotero care to comment on any of this, in particular #3?

Any other thoughts?

Bruce

13

The choice is between centralized (CVS/SVN-like) or decentralized.
I strongly favor the second because it lowers the bar to contribute.
People can easily fork a project and work on it independently, and
then issue a pull request if they want to merge.

I concur.

I’m partial to bitbucket and github, but people here are tending to
gravitate towards the former. So I’d suggest that. It gives us a nice
ui with built-in wiki and issue tracker, and it’s designed for easy
forking (mercurial).

Seems sensible. We’re more used to git but I’m sure we can pick up
mercurial without problems.

Alternately, there could be just a single makecsl repo, but I’m
thinking there may be value in splitting them.

I would suggest keeping the structure simple with just one repo
initially - we can always split things out later on.

Regards,
Robert.2009/9/28 Bruce D’Arcus <@Bruce_D_Arcus1>:

14

I’ll wait for our core development team to chime in regarding code
repositories, but on the licensing front we would prefer GPL 3.0.
Based on our experiences with the wider Zotero development community,
we believe it will attract and reward the greatest amount of
contribution. We’ve already heard from CSL developers who are cagey
enough about the packaging and redistribution of CSLs by Mendeley, and
I don’t know that I want to antagonize that community further.

Sean

15

Robert, what do you guys think about GPL 3.0? I presume the basic
difference is that we’d be saying people can’t modify and deploy the
code on the web without also releasing the code. Is there any
particular reason that restriction would be a problem?

Are there possibly unanticipated problems with using GPL 3 here (I
don’t really understand the intricacies of potentially conflicting
licenses in this area)?

Bruce

16

Robert, what do you guys think about GPL 3.0? I presume the
basic difference is that we’d be saying people can’t modify and
deploy the code on the web without also releasing the code

GPL 3.0 is fine for us. To clarify what the requirements are though -
the ‘release the code’ part
there applies to code that the user is running on the client (eg.
JavaScript in the web browser).
I would hope though that the code running on the server would just
reflect a branch in the CSL repository that you proposed but
it is worth being aware of the conditions.

Are there possibly unanticipated problems with using GPL 3 here (I
don’t really understand the intricacies of potentially conflicting
licenses in this area)?

The only potential I can see for problems is if someone wants to use a
Javascript library which is not GPL-3 compatible when
implementing the client UI. The well known ones that I know of are
suitably licensed for use with GPL code.

Regards,
Robert.2009/9/28 Bruce D’Arcus <@Bruce_D_Arcus1>:

17

OK, I put up the placeholder at …

http://bitbucket.org/bdarcus/makecsl/

… complete with this license. I’d suggest using the wiki here for
specing it out (we need to move over the stuff from the xbib trac).

Bruce