The CSL editor project is getting very close to finishing now. As such, the
current features won’t change much now within this specific
Mendeley/Columbia project. You can try it here: http://steveridout.com/csl/about/
I’m pretty happy with how it’s gone, people are using it to create actual
styles and I think it’s a lot more inviting to newcomers than editing XML.
At the same time there are a lot of ideas which couldn’t be done due to
lack of time. Some of these are ‘risky’ ideas where it’s hard to know how
well they’ll work before building some prototypes. e.g. a wizard to build
an initial style template, and a searchable database of all the macros in
the repo to use as building blocks. Before wrapping up I’ll write up a
summary future work suggestions.
Integrating with reference managers
Mendeley have started work on integrating the editor to make the workflow
nicer for their users. I’d like to invite other devs to take a look at the
documentation I’ve started putting on github:
This is still WIP, and before finishing I will add more documentation to
the source code too. Please don’t hesitate to contact me if you want help
understanding, or if you think anything should be changed.
Future Maintenence
Currently the code is split into two repositories on github:
Splitting it like this means everyone can benefit from improvements to the
core cslEditorLib repository.
My situation
I’ve got about 70 hours of contracted work left on this, which I’ll stretch
out over the next three weeks. After that I’ll continue to do a bit in my
free time to help maintain it, and will keep my hosted version of the site
up for as long as it’s useful and not too much of a burden, or until it
gets superseded by another ref-manager agnostic version.
In the realm of “stuff everyone needs to think about and work on” (not a
critique of your work per se), I still think this is an example that needs
to be MUCH simpler. One-click installs please. Hopefully we’ll see some
rigorous forking of your repo!
[image: Inline image 1]
Hello,
The CSL editor project is getting very close to finishing now. As such,
the
current features won’t change much now within this specific
Mendeley/Columbia project. You can try it here: http://steveridout.com/csl/about/
I’m pretty happy with how it’s gone, people are using it to create actual
styles and I think it’s a lot more inviting to newcomers than editing XML.
At the same time there are a lot of ideas which couldn’t be done due to
lack
of time. Some of these are ‘risky’ ideas where it’s hard to know how well
they’ll work before building some prototypes. e.g. a wizard to build an
initial style template, and a searchable database of all the macros in the
repo to use as building blocks. Before wrapping up I’ll write up a summary
future work suggestions.
Integrating with reference managers
Mendeley have started work on integrating the editor to make the workflow
nicer for their users. I’d like to invite other devs to take a look at the
documentation I’ve started putting on github:
This is still WIP, and before finishing I will add more documentation to
the
source code too. Please don’t hesitate to contact me if you want help
understanding, or if you think anything should be changed.
Future Maintenence
Currently the code is split into two repositories on github:
Splitting it like this means everyone can benefit from improvements to the
core cslEditorLib repository.
My situation
I’ve got about 70 hours of contracted work left on this, which I’ll
stretch
out over the next three weeks. After that I’ll continue to do a bit in my
free time to help maintain it, and will keep my hosted version of the site
up for as long as it’s useful and not too much of a burden, or until it
getsOn Wed, Sep 5, 2012 at 11:09 AM, Steve Ridout <@Steve_Ridout1> wrote:
superseded by another ref-manager agnostic version.
In the realm of “stuff everyone needs to think about and work on” (not a critique of your work per se), I still think this is an example that needs to be MUCH simpler.
One-click installs please. Hopefully we’ll see some rigorous forking of your repo!
This is a task for the reference managers. The csl-editor project
offers enough flexibility so $referenceManager can integrate nicely
(see Visual Editor · citation-style-language/csl-editor Wiki · GitHub
, more and better documentation about how to integrate csl-editor with
$referenceManager to be written soon). We have a prototype here with
one click installs (when this will be public I’ll send a note here).
Steve did a demoSite with the instructions that you have seen and as a
example of how to use the cslEditor.
I agree it makes more sense for the clients to do their own integration as they wish. It’s quite a burden to place on the CSL editor developers, particularly if no easy integration is done on the client side, and particularly as the editor itself runs in the browser. So maybe instead Steve can let the clients know what’s the best option for the editor to offer, e.g. a simple URL scheme? In the case of Papers, we have a number of avenues we can take advantage of, like responding to a scheme like papers2://csl/file/path/to/csl/file, or papers2://csl/url/path/to/csl/url.
In the case of Papers, we have a number of avenues we can take advantage of,
like responding to a scheme like papers2://csl/file/path/to/csl/file, or papers2://csl/url/path/to/csl/url.
That is what we’re doing, using a mendeley:// URL. We also have a
facility to import styles into the app by pasting a style link (the
style URI) into a box.
I agree it makes more sense for the clients to do their own integration as
they wish. It’s quite a burden to place on the CSL editor developers,
particularly if no easy integration is done on the client side, and
particularly as the editor itself runs in the browser. So maybe instead
Steve can let the clients know what’s the best option for the editor to
offer, e.g. a simple URL scheme? In the case of Papers, we have a number of
avenues we can take advantage of, like responding to a scheme like
papers2://csl/file/path/to/csl/file, or papers2://csl/url/path/to/csl/url.
charles
Sorry for the delay responding.
I doubt the papers2://csl/file/… scheme will be useful in this case since
saving to the hard drive from a browser is tricky. I used a flash based
plugin called downloadify which requires the user to specify the
destination file path. Saving via pure javascript possible in Chrome but
only to a sandboxed file system ( Read files in JavaScript | Articles | web.dev) - if you could get
the actual file path this would be OK, but I don’t think you can.
To use a papers2://csl/url/… request you’ll want to add some code to store
the style on your server first. I’ve kept the demo
sitehttps://github.com/citation-style-editor/csl-editor-demo-site
server
pretty much stateless to keep things simple so I’m afraid I can’t much help
with this. I’m leaving it to the ref manager devs to override the load and
save functions to get styles in and out of the editor which you should be
able to do by following the documentation here: Home · citation-style-language/csl-editor Wiki · GitHub. If there’s
anything in the core
libraryhttps://github.com/citation-style-editor/csl-editor that
stops you doing what you want, or that you don’t understand, please let me
know.
Another option is passing the whole style in a data URI, e.g.
papers2://csl/url/$CSL_DATA_URI . It would be easy to add links like this
to the demo site for all the ref managers actually. If something like this
would work, let me know and I’ll add it.
(Note: In Firefox I tried installing a style to Zotero using
data:text/x-csl;base64,$ENCODED_CSL but it only worked for trivially small
styles. The confirm dialog goes pure black for real styles,
perhaps because it’s trying to display the whole URL.)
I doubt the papers2://csl/file/… scheme will be useful in this case since saving to the hard drive from a browser is tricky.
I used a flash based plugin called downloadify which requires the user to specify the destination file path.
In Mendeley we only support mendeley:// links that include a URL for
the style, where the URL is usually the style ID.
This is useful since the app can then fetch updates for the style
using only the information in the style itself.
An important caveat with custom URL scheme handlers not implemented by
browser extensions is that
the UX varies across browsers. Google Chrome has a pretty scary
dialog in particular.
What about doing as zotero does: serving the file with a special mime (?) type?
You mean serving the style as an ordinary file download and
registering the app as a handler for the CSL mime type or .csl
extension?
I think that would be a more dependable approach.
I’ve tried this for Zotero using a data URI with the “text/x-csl” mime type
and it works but only for trivially small styles apparently due to a bug in
the confirm dialog.
(I was trying a data URI since I don’t want to write styles to my server,
but any of the ref managers can host their own version of the editor and
make it store styles if they want, like Mendeley is doing. I’m just
considering this to improve the demo site in the meantime)
Then it’s just up to the browser. The reason Zotero can intercept such
files is because it’s a browser extension. Some browsers allow
associating external programs based on content type—optionally without
confirmation—but that will work only once the user sets it up the first
time. Other browsers don’t support that: Safari, as far as I know,
doesn’t have external helper app functionality, just a "‘safe’ files"
list embedded in a plist somewhere. If the ref manager is registered
with the system for the content type or file extension, browsers that do
support external helper app functionality might offer it as the default
choice.
While we’re on the subject, though, we should agree on a different
content type for .csl files. Among other things, Safari (and possibly
other browsers) will display "text/" types rather than downloading
them. “x-” is also considered bad practice these days.
application/vnd.citationstyles.style? Zotero is using
application/vnd.citationstyles.csl+json for CSL JSON data.
Downloading isn’t as nice as auto-import or external helper app
functionality, but it’s better than displaying in the browser. At least
users can then double-click the downloaded file to open it in a properly
registered reference manager.
I see now that indeed, a URL scheme won’t help much. In any case, could I ask you one last favor, then, in the current version? We have changed things so that one can simply save a ‘.csl’ file and then drag it into Papers. Could you thus change the text to:
Use the above button to save your .csl file to the ‘Styles’ subfolder within your Papers2 library folder. More info.
Note that I have also included a better URL for the link.
Thanks again very much for the hard word, the CSL editor has turned into a very useful tool.
While we’re on the subject, though, we should agree on a different
content type for .csl files. Among other things, Safari (and possibly
other browsers) will display "text/" types rather than downloading
them. “x-” is also considered bad practice these days.
application/vnd.citationstyles.style? Zotero is using
application/vnd.citationstyles.csl+json for CSL JSON data.
It could also be application/vnd.citationstyles.style+xml, since RFC3023
recommends the use of “+xml” for XML-based media types. I don’t think
there’s much to be gained from that, but there’s also no particular
reason not to do it.
A.15 Why must I use the ‘+xml’ suffix for my new XML-based media type?
You don't have to, but unless you have a good reason to explicitly
disallow generic XML processing, you should use the suffix so as not
to curtail the options of future users and developers.
Whether the inventors of a media type, today, design it for dispatch
to generic XML processing machinery (and most won't) is not the
critical issue. The core notion is that the knowledge that some
media type happens to use XML syntax opens the door to unanticipated
kinds of processing beyond those envisioned by its inventors, and on
this basis identifying such encoding is a good and useful thing.
Developers of new media types are often tightly focused on a
particular type of processing that meets current needs. But there is
no need to rule out generic processing as well, which could make your
media type more valuable over time. It is believed that registering
with the '+xml' suffix will cause no interoperability problems
whatsoever, while it may enable significant new functionality and
interoperability now and in the future. So, the conservative
approach is to include the '+xml' suffix.
While we’re on the subject, though, we should agree on a different
content type for .csl files. Among other things, Safari (and possibly
other browsers) will display "text/" types rather than downloading
them. “x-” is also considered bad practice these days.
application/vnd.citationstyles.style? Zotero is using
application/vnd.citationstyles.csl+json for CSL JSON data.
It could also be application/vnd.citationstyles.style+xml,
Does that really present any practical problems here though? We use
the csl. extension for the style files, which servers can use to
associate the correct mimetype with.
Ah, yes, that was a bit mysterious, sorry. I meant it would be because it would hopefully prevent Safari from adding a ‘.txt’ extension when saving the file (and maybe would even directly download it instead of displaying it). It makes it a bit easier for adventurous users that find a style on the repository.
I see now that indeed, a URL scheme won’t help much. In any case, could I
ask you one last favor, then, in the current version? We have changed
things so that one can simply save a ‘.csl’ file and then drag it into
Papers. Could you thus change the text to:
Use the above button to save your .csl file to the ‘Styles’ subfolder
within your Papers2 library folder. More
info.
Note that I have also included a better URL for the link.
Thanks, I’ve altered it, it’ll go into the next release.
I’ve just updated some of the CSL editor dependencies to their latest
versions:
locales
styles
citeproc-js
There a few other minor changes too and the updated version is live at http://editor.citationstyles.org. Please keep an eye out for any unintended
breakages and let me know via github issues.
Steve
PS: I’m still hoping that someone else will take over responsibility for
future maintenance and development of the editor. I’m no longer in
academia, and no longer create reference manager software, so it would be
great to see it evolve in the hands of someone more suitable. I’m very
willing to help out if anyone needs help finding their way around the code,
assuming I can still remember how it works!
