Hello everyone,
Lately I’ve been working on the CSL editor
projecthttps://csleditor.wordpress.com/about/,
which is being managed by Jeffery Lancaster and Ian Mulvany.
We’ve now got a working prototype which gives an idea of the direction
we’re going with this, you can try it out here:
steveridout.com/csl/visualEditor
And the code is all on github:
Thanks to recent work on citeproc-js by Frank Bennett, it allows the user
to identify the relevant part of the CSL style by hovering over the
formatted output.
I’m posting here to get some feedback, but please bear in mind it’s in the
early stages and we are more interested in discussing the overall approach
rather than little bugs. To avoid too many obvious comments here are some
known problems:
- Only tested with latest Chrome and Firefox
- UI looks and feels clunky
- Tree view (jstree) drag and drop behavior is sometimes strange
- Don’t have mapping from every output character to CSL node, and vice
vera, not from every CSL node to output. There’s room for improvement here,
but Frank says it’s difficult to achieve 100% coverage.
- Not enough example citations
- Code editor sometimes wrongly highlights nodes in red
- Comments are stripped from imported CSL files
- Should have interactive highlight when hovering over the CSL tree too
We have definite plans for the following:
-
Allow user to modify the example documents, and provide a larger set of
built in examples.
-
Only allow CSL schema validating styles. e.g. instead of text boxes for
attribute names, use combo boxes populated with data from the csl.rng file.
If anyone has advice on parsing the .rng with javascript please let me know.
Here are possible ideas for future work:
-
Simplify/clean up tree view heirachy. At the moment it exactly maps the
CSL XML. I think there’s scope for simplifying this view whilst internally
keeping the CSL structure. If we did this, we should allow switching back
and fore between the actual CSL structure.
e.g. (just thinking)
- put macros inside a ‘macros’ node to avoid cluttering the interface.
- try removing the leaf nodes from ‘info’ and ‘author’ and use more
friendly GUI controls in the property panel instead.
- place ‘symlinks’ within nodes to the relevant macro
-
Allow construction of styles using a database of all macros extracted
from the repository as building blocks.
-
Allow user to specify desired textual output of the example documents, to
be used as unit tests for that style. This could be pre populated for users
arriving from ‘search by example’. The editor would show an error and the
relevant diff if the style fails to match.
-
Import and export of styles. We want an easy way to import and export
styles to and from ref managers. I think providing online storage and
resolvable URLs for all edited styles would be ideal, but is probably
beyond the scope of this project.
Look forward to hearing your comments!
Steve
I’ll look at this later in depth later, but I’ll ask a basic question:
where, ideally (irrespective of time/resource constraints), would you
like to see this end up?
E.g. let’s say you have some Mendeley user who needs a style for
"Journal X", and it’s not returned by a name search.
Let’s also assume they’re not the most technically savvy user.
What’s their path to a finished, activated, style they can use?
I’ll look at this later in depth later, but I’ll ask a basic question:
where, ideally (irrespective of time/resource constraints), would you
like to see this end up?
E.g. let’s say you have some Mendeley user who needs a style for
“Journal X”, and it’s not returned by a name search.
Let’s also assume they’re not the most technically savvy user.
What’s their path to a finished, activated, style they can use?
Basically this:
- Name search
- Advanced search. e.g. the ‘search by example’, ideally made more user
friendly with autocompletion of fields.
If a style was found which is close to the desired one:
- Open the Visual Editor so that the style can be tweaked.
If search couldn’t find anything useful:
- Either:
– a: Open a blank style in the Visual Editor. Hopefully starting a style
from scratch won’t be so intimidating if the user can draw upon a library
of macros to use as building blocks.
– b: Open a wizard tool, to set up the basic structure of the style, and
open this in the Visual Editor.
Whether or not a wizard is preferable may be easier to decide once we get
some testing with a more mature version of the editor.
- Export/store the edited style for use in your ref manager of choice
(ideally hosted online with a permanently resolvable URL so that documents
can be shared easily). In the short term, I’m open to opinions from Zotero,
Papers and Mendeley for the best way to import/export edited styles.
I like a lot of this. The example view is great and we could probably
use that to direct users to similar style in the very near future. I
know you want to add more example, but as a quick enhancement, I’d
suggest to add locators - i.e. make the example (Einstein, 1905, pp.
23-47) - the way locators are separated from the citation and whether
or not they have a label is a common variation especially in
author-date styles.
I haven’t had a lot of time yet to play with the tree view. My first
impression is that I imagine it to be a bit intimidating for the
uninitiated. I know what all the “macro” “substitute” “choose” etc.
means - but I would guess that it would freak out someone who has
never seen a CSL style. But maybe I’m missing the way you envision how
this is going to be used.
Anyway - exciting to see this moving along, congratulations.
Sebastian
This is my hunch as well. It’s a direct representation of what is
effectively a fairly abstract language.
Bruce
I’ll look at this later in depth later, but I’ll ask a basic question:
where, ideally (irrespective of time/resource constraints), would you
like to see this end up?
E.g. let’s say you have some Mendeley user who needs a style for
“Journal X”, and it’s not returned by a name search.
Let’s also assume they’re not the most technically savvy user.
What’s their path to a finished, activated, style they can use?
Basically this:
- Name search
- Advanced search. e.g. the ‘search by example’, ideally made more user
friendly with autocompletion of fields.
If a style was found which is close to the desired one:
- Open the Visual Editor so that the style can be tweaked.
OK. Makes sense.
Given the number of styles we have, I expect this to be the vastly
more common case, and so suggest optimizing for it.
If search couldn’t find anything useful:
- Either:
– a: Open a blank style in the Visual Editor. Hopefully starting a style
from scratch won’t be so intimidating if the user can draw upon a library of
macros to use as building blocks.
– b: Open a wizard tool, to set up the basic structure of the style, and
open this in the Visual Editor.
So these might be a layer on top of the Visual Editor, so feasible
newbies wouldn’t need to see the latter?
Whether or not a wizard is preferable may be easier to decide once we get
some testing with a more mature version of the editor.
- Export/store the edited style for use in your ref manager of choice
(ideally hosted online with a permanently resolvable URL so that documents
can be shared easily). In the short term, I’m open to opinions from Zotero,
Papers and Mendeley for the best way to import/export edited styles.
I’ll just repeat my previous suggestion that the way Zotero does this
is ideal: one click and it’s ready. So no downloading, moving files
around, etc.
Bruce
I’ll look at this later in depth later, but I’ll ask a basic question:
where, ideally (irrespective of time/resource constraints), would you
like to see this end up?
E.g. let’s say you have some Mendeley user who needs a style for
“Journal X”, and it’s not returned by a name search.
Let’s also assume they’re not the most technically savvy user.
What’s their path to a finished, activated, style they can use?
Basically this:
- Name search
- Advanced search. e.g. the ‘search by example’, ideally made more user
friendly with autocompletion of fields.
If a style was found which is close to the desired one:
- Open the Visual Editor so that the style can be tweaked.
OK. Makes sense.
Given the number of styles we have, I expect this to be the vastly
more common case, and so suggest optimizing for it.
I agree
If search couldn’t find anything useful:
- Either:
– a: Open a blank style in the Visual Editor. Hopefully starting a style
from scratch won’t be so intimidating if the user can draw upon a
library of
macros to use as building blocks.
– b: Open a wizard tool, to set up the basic structure of the style, and
open this in the Visual Editor.
So these might be a layer on top of the Visual Editor, so feasible
newbies wouldn’t need to see the latter?
Could be, but right now I’m not convinced we could make something flexible
enough to create a complete style without exposing the user to the fully
featured editor.
Whether or not a wizard is preferable may be easier to decide once we get
some testing with a more mature version of the editor.
- Export/store the edited style for use in your ref manager of choice
(ideally hosted online with a permanently resolvable URL so that
documents
can be shared easily). In the short term, I’m open to opinions from
Zotero,
Papers and Mendeley for the best way to import/export edited styles.
I’ll just repeat my previous suggestion that the way Zotero does this
is ideal: one click and it’s ready. So no downloading, moving files
around, etc.
Does Zotero allow people to share a Word/OO document which uses a custom
style between different machines and users easily? I know that Mendeley
doesn’t at the moment.
If we postpone the sharing issue for the time being, at the least we need
to implement:
- A way to get the styles from the editor into a ref manager. The ref
manager should check the style id and style name doesn’t conflict with an
existing style act accordingly.
- A way to get the edited styles back from a ref manager into the editor.
Bruce
I like a lot of this. The example view is great and we could probably
use that to direct users to similar style in the very near future. I
know you want to add more example, but as a quick enhancement, I’d
suggest to add locators - i.e. make the example (Einstein, 1905, pp.
23-47) - the way locators are separated from the citation and whether
or not they have a label is a common variation especially in
author-date styles.
I’ll work on a way to switch between examples soon and will incorporate the
suggestion, thanks.
I haven’t had a lot of time yet to play with the tree view. My first
impression is that I imagine it to be a bit intimidating for the
uninitiated. I know what all the “macro” “substitute” “choose” etc.
means - but I would guess that it would freak out someone who has
never seen a CSL style. But maybe I’m missing the way you envision how
this is going to be used.
I agree, currently it’s way too intimidating. Some ways I plan to improve
it:
-
Get the current view, which mirrors the CSL, working smoothly and to
constrain it to the CSL schema. This will help a lot since the user won’t
be allowed to create any new attribute, but will have all the attributes
there ready to play with and see what happens in the output.
-
Think about provide an alternative tree view which is restructured to be
more intuitive. This is no more than a vauge idea at present, but I have a
feeling there be a way to re-structure the heirachy, re-name some the
attributes, and design some nice GUI tools for the properties of some nodes
to be more user friendly.
-
Build help documentation into the tool via tooltips or links to the
appropriate part of
Redirecting…http://citationstyles.org/downloads/specification.html#id77
.
-
Try to utilize the macros from the existing styles to use as building
blocks.
-
Get feedback from real first time users. The prospect of this is quite
scary at the moment 
Anyway - exciting to see this moving along, congratulations.On 30 March 2012 16:59, Sebastian Karcher <@Sebastian_Karcher>wrote:
neither does Zotero.On Fri, Mar 30, 2012 at 11:11 AM, Steve Ridout <@Steve_Ridout1> wrote:
Does Zotero allow people to share a Word/OO document which uses a custom
style between different machines and users easily? I know that Mendeley
doesn’t at the moment.
Sebastian Karcher
Ph.D. Candidate
Department of Political Science
Northwestern University
Does Zotero allow people to share a Word/OO document which uses a custom
style between different machines and users easily?
Giving all created styles an ID which doubles as a URL from which the
style can be fetched, so they could
work in the same way as existing styles and be automatically
downloaded by clients if necessary, seems like
the obvious option. The 1-click install can just be a link to this
URL - possibly converted to a tool-appropriate
link (Mendeley registers itself as a handler for mendeley:// links and
I believe Zotero and Papers both have a similar facility).
So for the style ID/URL, something like:
http://citationstyles.org/styles//
Where is some prefix assigned to all styles created with the
tool and is
some name assigned by the user (from an alphabetic limited to letters,
numbers and hyphens).
The main question then is whether/how to handle updates and
authentication. Zotero and Mendeley both
have online accounts that could be used as identities for this purpose
and I presumably Papers must have one for Livfe as well.
Regards,
Rob.
Very interesting, thanks for the shout-out on this early prototype. I’ll be following the development as well, but at the moment, don’t have comments.
Regarding Papers, on the Mac, we are planning to add proper support for loading ‘csl’ files into Papers 2.2 by simple drag-and-drop. Nothing extraordinary, we just need to handle the file type appropriately. But that makes it easy to load a CSL file into Papers, as one can simply use e.g. the command-line open command, or from a Cocoa app, use the LaunchServices APIs. The command open is for instance:
open -a Papers /path/to/some-style.csl
Thanks,
Charles
Is there any reason it shouldn’t just be possible to click on a link
on a web repository, and have it correctly installed?
That’s always been my vision, and I don’t want to let it go if I can help it 
Bruce
Ah, ha, yes, that too… sort of 
you can use the Papers bookmarklet on a URL for a CSl file. Since we ship all the styles from the CSL repository, though, the main workflow is to add a new CSL file to the user’s styles.
Ah, ha, yes, that too… sort of 
you can use the Papers bookmarklet on a URL for a CSl file. Since we ship all the styles from the CSL repository, though, the main workflow is to add a new CSL file to the user’s styles.
Right, but I’m still hoping to see CSL evolve to where
journals/publishers start to host their own styles.
Also, how do you deal with updating styles?
Bruce
Does Zotero allow people to share a Word/OO document which uses a custom
style between different machines and users easily?
Giving all created styles an ID which doubles as a URL from which the
style can be fetched, so they could
work in the same way as existing styles and be automatically
downloaded by clients if necessary, seems like
the obvious option. The 1-click install can just be a link to this
URL - possibly converted to a tool-appropriate
link (Mendeley registers itself as a handler for mendeley:// links and
I believe Zotero and Papers both have a similar facility).
So for the style ID/URL, something like:
http://citationstyles.org/styles//
Where is some prefix assigned to all styles created with the
tool and is
some name assigned by the user (from an alphabetic limited to letters,
numbers and hyphens).
The main question then is whether/how to handle updates and
authentication.
For updates the following could work:
http://citationstyles.org/styles// - returns the newest
style with this base URL
http://citationstyles.org/styles//?version= -
returns a specific version of the style, where starts at 1 and
increments each time a user exports an update of this style from the style
editor tool.
The simplest way to implement this would be with no authentication, which
could work since if someone changes your style, your version is still there
in the history.
The simplest way to implement this would be with no authentication, which could work since if someone
changes your style, your version is still there in the history.
I think that would be OK to start with.
In a subsequent iteration, associating a Mendeley / Zotero / other
identity with a particular style would be useful for authentication
but it also means that you could incorporate profile info - such as
name, description and photo into the ‘About style X’ page, which might
be useful
for people wanting to know whether a style is the one they are looking for.
Regards,
Rob.
Ah, ha, yes, that too… sort of you can use the Papers bookmarklet on a URL for a CSl file. Since we ship all the styles from the CSL repository, though, the main workflow is to add a new CSL file to the user’s styles.
Right, but I’m still hoping to see CSL evolve to where
journals/publishers start to host their own styles.
Indeed, that will be covered as well.
Also, how do you deal with updating styles?
Updates come with the app updates, which are somewhat frequent, but it is still always a bit behind. We are still looking into more frequent updates indepedent of app updates, but in general, it has not been an issue very much. When we find some style problems, it’s very rarely already fixed in the repo. Instead, I tweak the style, send it to the user, so they can try it. This gives me an extra way to check the style modifications too.
Charles
Hi, Steve,
Tuned in to take a took this morning. The cosmetics and tie-ins
between search and edit are looking good (apart from the little typo
on “properties”).
http://steveridout.com/csl/visualEditor
One small thought on usability that might entail a bunch of work: the
frames are pretty cramped on a small display. It would be handy to be
able to detach the sample output to a separate window, so that it can
be moved to a separate desktop on a netbook, or to a separate monitor
on a multi-head display.
Frank
Hi, Steve,
Tuned in to take a took this morning. The cosmetics and tie-ins
between search and edit are looking good (apart from the little typo
on “properties”).
Typo fixed (but not yet live)
http://steveridout.com/csl/visualEditor
One small thought on usability that might entail a bunch of work: the
frames are pretty cramped on a small display. It would be handy to be
able to detach the sample output to a separate window, so that it can
be moved to a separate desktop on a netbook, or to a separate monitor
on a multi-head display.
I agree this could be useful, and we’ll think about implementing it after
doing the following:
- A simpler representation of the CSL structure. I’ve done some
refactoring to allow experimentation with this, at the moment I’m working
on implementing this mockup:
https://docs.google.com/presentation/d/1n0TxxDuWUwqDvgzKjL6wlZrL1u85MVC9SsbrCoRIlio/editOn 26 April 2012 00:03, Frank Bennett <@Frank_Bennett> wrote:
feedback and suggestions are welcome.
-
There should be more example documents, plus the ability to add custom
ones.
-
The property panel needs a makeover.
Thanks for the feedback.
Steve