CSL editor instance in http://citationstyles.org?

CSL Development
1

Hi,

Here at Mendeley we are working to integrate the CSL editor with our
desktop application.

But I still think that would make sense to have an instance of the CSL
editor which one is not reference manager specific. In some place like
http://citationstyles.org/editor

Reference managers could send the users to this CSL editor instance
instead of the http://steveridout.com/csl/visualEditor/ . And maybe
Steve Ridout would like to not host it endless :slight_smile:

I feel that it’s important to keep the editor used by a wide
community, to get feedback and ideas to improve it, bugs, etc. and
also to build a community around it to see what next could happen.

I’m happy to assist or install the editor in some server (I’ve done in
a couple of test servers here). It requires an Apache, PHP server.
Mysql not needed. The editor is mainly all done in Javascript. It’s
not complicated to install. If you want some help just write to me in
private (instructions


but some experience may be handy).

Is this possible? Does some of you think that could be useful?

Regards,–
Carles Pina | Software Engineer

Mendeley Limited | London, UK | www.mendeley.com
Registered in England and Wales | Company Number 6419015

2

I definitely think it’d be a good idea. The site is hosted by the Zotero
guys. Am not sure whether we need their help to get it setup (perhaps not
because no db), or whether Rintze could do it (with help)?

3

I currently don’t have access to the server hosting
citationstyles.org. Ammon Shepherd from CHNM installed and maintains
the domain’s WordPress installation, and I presume any requests for
changes to the website (once we agree on what those should be) should
primarily be directed to Dan Stillman. Related, I have asked Dan if he
would consider moving or mirroring the (Zotero) Style Repository to/at
citationstyles.org/styles (which I think would help reduce the
perception of CSL as being a Zotero-specific product), but haven’t
received a response.

Regarding my opinion about hosting the editor on citationstyles.org:
I’m impressed by the progress made by Steve. The “Search by name” and
"Search by example" tools are useful and quite straightforward to use.
But with regard to the Visual editor, I really would like to see some
accompanying documentation before giving my full support for hosting
the editor on citationstyles.org. I think it would be very useful to
provide instructions on how to make some basic style modifications
that demonstrate the various features (and, perhaps, also the
limitations) of the editor. I know that there are already people that
have used the editor with success, but I personally find the editor
hard to use for anything more than small edits that don’t affect the
overall structure of the style (my biggest problem is that I find the
left-hand column much less informative/readable than the raw XML). If
your own experiences are different, it would be valuable to describe
those.

4

Hello,

I currently don’t have access to the server hosting
citationstyles.org. Ammon Shepherd from CHNM installed and maintains
the domain’s WordPress installation, and I presume any requests for
changes to the website (once we agree on what those should be) should
primarily be directed to Dan Stillman. Related, I have asked Dan if he

ok, I’m sure that when we agree what we want we will be able to do it,
somehow (since the CSL Editor doesn’t need anything out of common).

Regarding my opinion about hosting the editor on citationstyles.org:
I’m impressed by the progress made by Steve. The “Search by name” and
“Search by example” tools are useful and quite straightforward to use.
But with regard to the Visual editor, I really would like to see some
accompanying documentation before giving my full support for hosting
the editor on citationstyles.org. I think it would be very useful to

In Mendeley we want to do (video or written) some documentation.

Maybe having the editor available to everyone would speed up the
process or the documentation, since different people could contribute.
See the thread http://xbiblio-devel.2463403.n2.nabble.com/csl-training-ideas-for-methods-good-practice-etc-td7578250.html
(and perhaps Sebastian Karcher’s email
http://xbiblio-devel.2463403.n2.nabble.com/csl-training-ideas-for-methods-good-practice-etc-tp7578250p7578255.html
). The CSL Editor could be useful in some CSL course where we could
get some feedback and maybe some documentation could be generated as
part of the course.

(this doesn’t mean that we should not do some documentation ASAP in
Mendeley or here in xbiblio-devel users).

provide instructions on how to make some basic style modifications
that demonstrate the various features (and, perhaps, also the
limitations) of the editor. I know that there are already people that
have used the editor with success, but I personally find the editor
hard to use for anything more than small edits that don’t affect the
overall structure of the style (my biggest problem is that I find the
left-hand column much less informative/readable than the raw XML). If
your own experiences are different, it would be valuable to describe
those.

During the project we did some user testing to users who didn’t know
about CSL. If I remember correctly we (Steve R or myself) sent to here
the tasks that we asked them to do (I couldn’t find it now… but I
remember discussing it).

Some of the tasks were simple changes in CSL styles (other tasks were
search a CSL style, etc.):
“23. Edit the style for the Journal of Community Health to put the
inline citation between parentheses: ( ) instead of square brackets: [
].”, "
“24. Replace the comma between the inline citation numbers with an
ampersand: &.”
“25. Make the inline citation bold.”
“26. Give the Author names in the bibliography small-caps formatting.”

The user testing was done to 5 users (we wanted to do another round of
usability testing/online one but we ran out of time). I’ve just
re-read the Testing Notes and it went quite well to these tasks (the
point 24. was the weaker because the users had problems to add more
citations).

We chose these tasks after reading and summarising support queries to
Mendeley support (I think that it’s quite aligned with the Zotero’s
forum questions). We found that the majority of the requests says “I
want this style but with this small change” (because some particular
need) or “This style has this problem, how can I fix it?”.

I don’t think that the CSL Editor is useful to create styles from the
scratch (I hope that with the current number of styles no one will
think a completely new approach to cite!), and probably it’s not very
useful to do major changes to the styles.

5

We chose these tasks after reading and summarising
support queries to Mendeley support

These queries are a mix of private emails and public posts on
http://support.mendeley.com/ and http://feedback.mendeley.com

Regards,
Rob.

6

…

We chose these tasks after reading and summarising support queries to
Mendeley support (I think that it’s quite aligned with the Zotero’s
forum questions). We found that the majority of the requests says “I
want this style but with this small change” (because some particular
need) or “This style has this problem, how can I fix it?”.

I don’t think that the CSL Editor is useful to create styles from the
scratch (I hope that with the current number of styles no one will
think a completely new approach to cite!), and probably it’s not very
useful to do major changes to the styles.

Wouldn’t you agree, then, that this research suggests that a
productive next step for developers to explore would be something
higher-level to capture both of these classes of use cases: the simple
minor change in formatting, and the more radical “major changes”
(though I’m skeptical these actually exist when you consider the full
range of extant styles)?

E.g. for the first case, from the user perspective: see example
possibilities, and choose which they want?

Bruce

7

Some of the tasks were simple changes in CSL styles (other tasks were
search a CSL style, etc.):
“23. Edit the style for the Journal of Community Health to put the
inline citation between parentheses: ( ) instead of square brackets: [
].”, "
“24. Replace the comma between the inline citation numbers with an
ampersand: &.”
“25. Make the inline citation bold.”
“26. Give the Author names in the bibliography small-caps formatting.”

Do any of these cases require use of the XML tree? I’m wondering if it
wouldn’t be clearer to hide it by default, since you’re mostly
focusing on facilitating minor edits.

do I make a date localize?"), and then focus on the CSL XML needed to
meet that goal. I like the idea, but it would be a significant
undertaking, probably matching or exceeding the specification in size.

it also would require some extra-effort for users who never wrote XML,
they don’t know what is an element/attribute, need to validate the
styles…

Yes, but there will always be a class of power users that isn’t afraid
of hand-editing XML. Reducing the amount of time these users need to
invest to get familiar with CSL seems worthwhile. I see it more as a
parallel approach to the CSL editor, which is more aimed at casual
users.

Documentation needs to be done, I agree.

Where would we host it? The GitHub wiki?
(Home · citation-style-language/csl-editor Wiki · GitHub)

Rintze

8

Hi,

…

We chose these tasks after reading and summarising support queries to
Mendeley support (I think that it’s quite aligned with the Zotero’s
forum questions). We found that the majority of the requests says “I
want this style but with this small change” (because some particular
need) or “This style has this problem, how can I fix it?”.

I don’t think that the CSL Editor is useful to create styles from the
scratch (I hope that with the current number of styles no one will
think a completely new approach to cite!), and probably it’s not very
useful to do major changes to the styles.

Wouldn’t you agree, then, that this research suggests that a
productive next step for developers to explore would be something
higher-level to capture both of these classes of use cases: the simple
minor change in formatting, and the more radical “major changes”
(though I’m skeptical these actually exist when you consider the full
range of extant styles)?

Some thoughts about creating styles from the scratch and the
non-existing editor that facilities this task:
My personal opinion (I’d be happy if someone proves that I’m
wrong!): CSL is so complex and so rich that an editor to create styles
from the scratch without knowing some advanced CSL concepts (macros,
choose, variables, types) cannot be done… or, at least, I don’t see
at the moment how can be done. Again, I may be wrong.

We could build tools that may help someone to create styles from the
scratch. For example, and we mentioned it here some time ago, based in
re-using existing macros (e.g. list all the available macros in the
repository, allow the user to re-use macros easily). But I don’t see a
way to start with an empty style and easily and friendly without
understanding what happens internally build a style. I don’t think
also that this is a common use case that we should tackle now (perhaps
some years ago yes).

I know different attempts to do a graphical programming language (e.g.
Google Code Archive - Long-term storage for Google Code Project Hosting. , and others). It helps to
explain programming to people, but I don’t see people using it too
much. I know that it’s a different scope, but I hope that it helps to
explain my thoughts.

Somehow it would be like building a Python/any programming language
user interface. It can be done, but if you want to build things from
the scratch you really need to understand what’s underneath… tools
helps, IDEs helps, but doesn’t avoid of studying the programming
language.

(another way of thinking: lot of people doesn’t agree that there is a
good HTML editor. Lot of money and time has been invested in HTML
editors and not everyone is satisfied. Recently it seems that the most
common approach is to create tools like BaseKit
-http://www.basekit.com- that offers different templates and then the
users changes the templates. This is the way to go with getting macros
together, and I still have doubts that this would work well enough).

Regards,

9

Hi,

Some of the tasks were simple changes in CSL styles (other tasks were
search a CSL style, etc.):
“23. Edit the style for the Journal of Community Health to put the
inline citation between parentheses: ( ) instead of square brackets: [
].”, "
“24. Replace the comma between the inline citation numbers with an
ampersand: &.”
“25. Make the inline citation bold.”
“26. Give the Author names in the bibliography small-caps formatting.”

Do any of these cases require use of the XML tree? I’m wondering if it
wouldn’t be clearer to hide it by default, since you’re mostly
focusing on facilitating minor edits.

Some months ago I mentioned exactly it in a CSL Editor meeting. Lot of
tasks could be done without the left tree.

I don’t remember the exact discussion but I think that we didn’t
remove to allow moving nodes (drag and drop on the left tree) and also
to allow adding conditionals, nodes. Users needs to use the left tree
for these operations.

Hiding it by default and having a button to show it would be possible.

I don’t think that this is a blocker to have the editor in
citationstyles.org, but I’m happy that these is being discussed.

do I make a date localize?"), and then focus on the CSL XML needed to
meet that goal. I like the idea, but it would be a significant
undertaking, probably matching or exceeding the specification in size.

it also would require some extra-effort for users who never wrote XML,
they don’t know what is an element/attribute, need to validate the
styles…

Yes, but there will always be a class of power users that isn’t afraid
of hand-editing XML. Reducing the amount of time these users need to
invest to get familiar with CSL seems worthwhile. I see it more as a
parallel approach to the CSL editor, which is more aimed at casual
users.

100% agree, this would be useful to some users.

Documentation needs to be done, I agree.

Where would we host it? The GitHub wiki?
(Home · citation-style-language/csl-editor Wiki · GitHub)

(Any place is better than no place). It could start there (that would
be a good start! and good that we could all edit easily).

Having said that… I don’t think that this Wiki is very user
friendly. It has 400 pixels before the content starts and at the end
it has 500 pixels from the end of the content to the bottom of the
page. To start writing I’d say that it’s a very good place (public,
easy to edit). And perhaps the users will not get scared by all the
buttons before the content starts. Later on could be moved if we
decide it (to blog posts, or something similar to the
Redirecting… format, with or
without docutils).

If someone wants access to the Github repo (I think that to edit the
Wiki it’s needed) just ask me.

Regards,

10

Hi,

…

We chose these tasks after reading and summarising support queries to
Mendeley support (I think that it’s quite aligned with the Zotero’s
forum questions). We found that the majority of the requests says “I
want this style but with this small change” (because some particular
need) or “This style has this problem, how can I fix it?”.

I don’t think that the CSL Editor is useful to create styles from the
scratch (I hope that with the current number of styles no one will
think a completely new approach to cite!), and probably it’s not very
useful to do major changes to the styles.

Wouldn’t you agree, then, that this research suggests that a
productive next step for developers to explore would be something
higher-level to capture both of these classes of use cases: the simple
minor change in formatting, and the more radical “major changes”
(though I’m skeptical these actually exist when you consider the full
range of extant styles)?

Some thoughts about creating styles from the scratch and the
non-existing editor that facilities this task:
My personal opinion (I’d be happy if someone proves that I’m
wrong!): CSL is so complex and so rich that an editor to create styles
from the scratch without knowing some advanced CSL concepts (macros,
choose, variables, types) cannot be done… or, at least, I don’t see
at the moment how can be done. Again, I may be wrong.

I wonder: can we imagine some way to test this hypothesis? Maybe
making use of some previous work (say by Sylvester) that can analyze
style data?

My basic observation is we have 2000+ styles, with some hundreds of
unique styles. But those unique styles are often small variations on
what are no doubt a very small number of core/base styles.

If there was a way to quantify that somehow, it could help us
understand opportunities and constraints for future development?

Bruce

11

Some thoughts about creating styles from the scratch and the
non-existing editor that facilities this task:
My personal opinion (I’d be happy if someone proves that I’m
wrong!): CSL is so complex and so rich that an editor to create styles
from the scratch without knowing some advanced CSL concepts (macros,
choose, variables, types) cannot be done… or, at least, I don’t see
at the moment how can be done. Again, I may be wrong.

I agree.

Some real world feedback. I taught using the editor today for the first
time. It actually went better than I expected. Instead on running through
hypotheticals, I took a real style request from the Zotero forum and had
them essentially do the whole thing with me around to help.

This was a group of librarians - mostly subject and instructional, not IT
people, most of them with absolutely no programming background, some quite
anxious about the prospect of anything “code”. That said, being librarians
they obviously have a very good understanding of citations and using HTML
as a point of reference seemed helpful to most of them - which I don’t
think is true for all user groups.

I spent 15mins talking about the general structure of CSL styles and then
explaining briefly how the map onto the

The first step - using the “search by example” took some guidance for
about half of the group. So documentation will need to be good on that.

The remaining touch-ups - things like lowercasing an editor abbreviation or
turning the volume number for journal articles bold - people were able to
do with no help at all on my part. I really think that’s the type of stuff
we should be aiming for. And I’m quite happy how well the editor does with
that.

I think it’s not that hard to communicate to a pretty large group of users
the basic idea of nested nodes and I feel the bar on the left gives users a
sense of orientation in the style. I’d strongly enourage keeping it as the
default.

Best,
Sebastian--------
Sebastian Karcher
Ph.D. Candidate
Department of Political Science
Northwestern University

14

Hi,

Documentation needs to be done, I agree.

Where would we host it? The GitHub wiki?
(Home · citation-style-language/csl-editor Wiki · GitHub)

In the CSL Editor Wiki: Home · citation-style-language/csl-editor Wiki · GitHub
now there is a link to:
User guide for the CSL Editor · citation-style-language/csl-editor Wiki · GitHub

Feel free to suggest improvements (we will see what we can do :slight_smile: ) or
just improve it :slight_smile: (if someone else wants access to the repository
tell me, Wiki permissions are linked to the repository).

Tomorrow or next week I’ll add a link from the CSL Editor to the Wiki
page, to make it more visible.

Mendeley integration of the CSL Editor is going well, but I still
think that an instance in www.citationstyles.org makes sense to have
more tools all together (and could be referred from Papers / Zotero
forums, other users, etc.), Does someone think that there is something
missing before this happens? Better documentation? (I’m not sure if
this would be a blocker or a nice to have).

BTW, thanks Sebastian Karcher for using the editor in the course and
the feedback that you sent it here last week. We were very happy to
read it!

15

Fine with me.

Rintze