# CSL editor
**URL:** https://discourse.citationstyles.org/t/csl-editor/601
**Category:** CSL Development
**Created:** [April 10, 2009, 10:16pm UTC](https://discourse.citationstyles.org/t/csl-editor/601 "2009-04-10T22:16:10Z")
**Posts on this page:** 6
**Page:** 1
### Author:  [@Frederick\_Gibbs](https://discourse.citationstyles.org/u/Frederick_Gibbs)
#### Post date: [April 10, 2009, 10:16pm UTC](https://discourse.citationstyles.org/t/csl-editor/601/1 "2009-04-10T22:16:10Z")
Folks,
There is now checked into the Zotero SVN a very rough CSL editor
(functioning as a FF extension), about which I hope to garner some feedback.
It is only a first pass, but can hopefully be useful a base to build on. It
is not as independent as it probably should be, as it requires Firefox and
Zotero (for citation rendering, though it could now be abstracted from
Zotero by using Frank’s CSL processor instead).
To mitigate disappointment, let me be upfront about its current but
hopefully short-lived limitations:
1. It cannot load arbitrary CSL files, though it is very good at loading CSL
files that it creates. I am attaching 2 tool-produced .csl files that show
at a glance what a typical CSL file might look like when loaded.
2. The outputted CSL is decent, but differs from convention in one important
(and controversial) respect: All instructions for formatting must be defined
in an item-type block (Bruce, I know you hate this, and I apologize in
advance.) This is not necessarily permanent, but the reason for it ATM is
that the tool is MUCH simpler in terms of both UI and code if it doesn’t
have to think about (potentially) how to restructure a CSL file if a user
wants to change a style for only one item type (which seems like a common
scenario). This does make for more redundant CSL files, but if people are
using a tool to edit them, I’m hoping that the redundancy won’t matter so
much. There is some fallback behavior: the user can define a 'default’
item-type that gets employed when there isn’t an explicit item type defined
for the item being cited. So, the overall trade-off is that the CSL files
aren’t as elegant, and they require more labor up-front to get usable
versions, but the tool makes editing files very easy from then on. Perhaps
as the tool evolves, it will become less strict about item types.
3. There are some CSL specifications like sort order and substitutions that
are not yet fully functional. Because of such incompleteness, the tool
cannot yet produce the most complicated styles like Chicago and Bluebook.
However, it can produce functional imitations of many of the CSL files now
in the Zotero style repository.
4. The tool has not been recently updated to reflect the last month or so of
revisions to the CSL spec, but I think those can be implemented without too
much difficulty.
To experience the editor:
svn co [https://www.zotero.org/svn/styleeditor](https://www.zotero.org/svn/styleeditor)
cd styleeditor
./build\_xpi
open styleeditor.xpi (on OS X, or drag file to Firefox)
Thanks,
Fred Gibbs
---
### Author:  [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)
#### Post date: [April 10, 2009, 10:49pm UTC](https://discourse.citationstyles.org/t/csl-editor/601/2 "2009-04-10T22:49:46Z")
Hi Fred,
> There is now checked into the Zotero SVN a very rough CSL editor
> (functioning as a FF extension), about which I hope to garner some feedback.
> It is only a first pass, but can hopefully be useful a base to build on.
Before I move on to any critique that you know is coming :-), let me
just say kudos on the work. I’ve not yet looked at the extension (I
will over the weekend likely), but nice to see you step up and fill a
void!
> It is not as independent as it probably should be, as it requires Firefox and
> Zotero (for citation rendering, though it could now be abstracted from
> Zotero by using Frank’s CSL processor instead).
>
> To mitigate disappointment, let me be upfront about its current but
> hopefully short-lived limitations:
>
> 1. It cannot load arbitrary CSL files, though it is very good at loading CSL
> files that it creates. I am attaching 2 tool-produced .csl files that show
> at a glance what a typical CSL file might look like when loaded.
To me, this has never been a particular concern.
> 1. The outputted CSL is decent, but differs from convention in one important
> (and controversial) respect: All instructions for formatting must be defined
> in an item-type block (Bruce, I know you hate this, and I apologize in
> advance.)
Well, let me boil down my argument like this:
Good styles (those that are robust, easy-to-debug, etc.) depend on good macros.
A piece of evidence that I believe proves my point is that the vast
majority of styles in the Zotero repo are in fact dependent styles.
This means there’s actually not as much variation as is commonly
assumed.
So if we have a CSL creation UI that incorporates macros, and
incorporates by default some common ones, it becomes really easy for
users to create new styles.
So it’d be great if you could incorporate that over time.
Bruce
PS - I know a lot of people seem to like the notion of a client side
creation and editing interface. I don’t. I really think the
technologies to use are not XUL or Cocoa, but JQuery and whatever
server-side language (PHP, Python, etc.). But … those who code get
the final word!
---
### Author:  [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)
#### Post date: [April 10, 2009, 10:52pm UTC](https://discourse.citationstyles.org/t/csl-editor/601/3 "2009-04-10T22:52:10Z")
Ah, spoke a little too soon. You do have some macros in the output.
More later …
Bruce
---
### Author:  [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)
#### Post date: [April 11, 2009, 1:18am UTC](https://discourse.citationstyles.org/t/csl-editor/601/4 "2009-04-11T01:18:09Z")
OK, some comments …
1. It took me awhile to realize that the extension was folded into
Zotero, and not otherwise accessible. Am not sure that’s a good idea
(?).
2. What you have is quite nice as far as it goes. But I’m sorry, I
just think this is the wrong approach.
I still think MakeBST is a way superior way to author styles
conceptually than is the Endnote et al approach (which is what this is
currently).
There’s no macros panel(s), and as you yourself note, you force a lot
upfront work for the style author.
E.g. it’s now WAY too low-level. It would take me far more time to
create a new style in the editor than it would to hand-create one in
an XML editor.
1. why separate panels for in-text and note citations? Is that really necessary?
2. I do, as you suspect, dislike at least some aspects of the “field
order” panel. I just think this is not a good path to go down. You
have the “default” type at the very end of the list of types, while it
should be the dominant type.
3. Where’s the online integration? Please, please tell me you aren’t
imagining users just creating and maintaining their own local styles.
4. related, why not as a web app???
On one hand, I’m a little bothered by what I see, because it appears
so far along that what I say is unlikely to have much impact on the
outcome. At the same time, it looks to me like people (not sure who)
made the decision to explicitly ignore my advice on how to do this. In
any case, it clearly diverges from all that I’ve said on this issue.
On the other hand, if I’m being more optimistic, perhaps there’s room
for building on this. To do that, I would imagine there’d have to some
tweaks in what’s already there, but also the addition of some kind of
wizard interface upfront, with this stuff accessible when needed.
Bruce
---
### Author:  [@Frederick\_Gibbs](https://discourse.citationstyles.org/u/Frederick_Gibbs)
#### Post date: [April 13, 2009, 3:00pm UTC](https://discourse.citationstyles.org/t/csl-editor/601/5 "2009-04-13T15:00:45Z")
Thanks for your comments, Bruce. A few responses:
> 1. It took me awhile to realize that the extension was folded into
> Zotero, and not otherwise accessible. Am not sure that’s a good idea
> (?).
No, it’s not ideal from a purely CSL perspective. The coupling was
originally done because I wanted to use the Zotero relationships between
item types and fields (and get to their CSL equivalents), the CSL processor,
and be able to produce citations quickly from the user’s Zotero library. I
can see it getting more abstract over time especially now that it’s easier
to get Zotero items via URLs.
> 1. What you have is quite nice as far as it goes. But I’m sorry, I
> just think this is the wrong approach.
> I still think MakeBST is a way superior way to author styles
> conceptually than is the Endnote et al approach (which is what this is
> currently).
Yes, we clearly disagree here.
> There’s no macros panel(s), and as you yourself note, you force a lot
> upfront work for the style author.
>
> E.g. it’s now WAY too low-level. It would take me far more time to
> create a new style in the editor than it would to hand-create one in
> an XML editor.
I fully agree that it would take YOU less time to write a very generic style
by hand than through the tool. But the tool is really designed for people
with no knowledge of CSL, XML, macros, other styles, and the general
problems involved with citation styling.
It’s true that creating full styles from scratch with the tool can take some
time. The way I see the tool being most useful is when people can load a
fairly complete style, like APA or Chicago, then tweak it, save a new style
file, and upload it into a repository. Maybe not all the item types are
defined, or some are wrong, but over time people can easily update the item
types they need to cite. For me, creating complex style files with lots of
grouping and where many item types are formatted differently, the tool has
been MUCH faster than writing or editing CSL. Of course I’ve got quite a bit
of experience using the tool, and you’ve got more experience writing CSL
files. I think macros are much more important for writing files by hand than
by a CSL tool, but I think we disagree about this.
One feature the tool DOES need is the ability to make one style dependent on
another when that is explicitly stated in the dependent style’s rules. So
for the Journal of Ear Cleaners style, which instructs authors to follow the
Chicago style in general, the JEC .csl file can be linked to the Chicago
.csl with some UI functionality to override formatting for some JEC item
types if necessary, which I think makes sense because this is how exceptions
are often explained in style guides. This would be much easier to do if
parent styles are described by item type as well. However, because I haven’t
started to implement this, I might not as clear about this as I should be.
> 1. why separate panels for in-text and note citations? Is that really
> necessary?
Probably not essential, but since there are substantially different options
(though overlap, too, obviously) I thought it would help keep the user clear
about what they are setting options for.
> 1. … You have the “default” type at the very end of the list of types,
> while it
> should be the dominant type.
Many CSL files have a lot of type testing throughout the macros. A simple
example is when the file calls a title macro that decides to use italics or
not. For a UI, and when the tool writes the CSL file, it seemed considerably
easier to do all the item type testing in one place in the file. That being
the case, the default type is not as useful (generally accurate) in tool
produced CSL files as it is in many current CSL files that do type testing
throughout the file. So i wanted to de-emphasize it. This also relates to
the parent-child overrides as mentioned above. If we were to increase macro
support and de-emphasize item types, I would agree that this should be more
prominent.
> 1. Where’s the online integration? Please, please tell me you aren’t
> imagining users just creating and maintaining their own local styles.
I’ve envisioned the tool interfacing with a style repository, but it seemed
like a good idea to get a working tool before tackling the web repository
and interface. I do think users should have the ability to create and work
with local CSL files if they so choose, as long as they are aware of the
disadvantages of that.
> 1. related, why not as a web app???
When I started messing around with the tool, it seemed easier to work up the
basics as a FF extension tied to Zotero, since there were so many unknowns
about what a decent UI would look like, how to deal with Zotero’s data
model, and how to go from UI options to a reasonable CSL file. I agree that
a web based tool is best, and I’m about 20% through converting the tool to
function as a web page. I deliberately tried to code the parsing engine as
flexibly as possible so that it could be configured to work behind a webpage
without too much trouble. So far so good. Maybe I should have just done
jquery (or similar) right out of the gate, but I simply wasn’t prepared to
do that for a number of reasons, many of which are now less relevant. Now
that I have more ideas about how the tool can and should work, it’s a good
time for a makeover. Creating a web version is a top priority now.
> On one hand, I’m a little bothered by what I see, because it appears
> so far along that what I say is unlikely to have much impact on the
> outcome.
Not true. I wouldn’t have posted to the list if I was intending to ignore
feedback. But you’re right in the sense that the tool now follows a certain
philosophy (see below) that is not as macro oriented as you’d prefer. But it
is not set in stone, and there are a great many other aspects to the tool
that can be improved and may prove useful in the appropriate context–and I
think you could be a big help with these.
> At the same time, it looks to me like people (not sure who)
> made the decision to explicitly ignore my advice on how to do this. In
> any case, it clearly diverges from all that I’ve said on this issue.
Well, as we have established, we disagree. I think crafting all styles in
terms of (and linking to) reusable macros is great from a theoretical point
of view, but is not sustainable in the long term. One of my biggest concerns
is that it puts the burden of creating and maintaining macros and style
files and their relationships in the hands of comparatively few people who
understand CSL, macros, and how everything connects together. Perhaps this
is the way it should be, but I think there are too many styles and too many
exceptions to deal with over time. I’d rather try to leverage all the users
of CSL, many of whom will not even know what CSL is, to create and maintain
style files. That 90% of style files could end up with the same explicit
code to format a date or whatever…well, I don’t see that as a problem
because it affords easy editing at the individual style level, which is how
most users interact with styles. When someone needs to change the way some
style formats a date for some item type, they should be able to do that
without thinking about other styles and whether to edit a macro, create a
new one, find an existing one, not use one at all, or be worried if their
change might affect other item types or other styles, etc. It seems that
people are always wanting (and will continue to want) to make small tweaks
to styles but there’s a pretty high technical barrier to doing it. The
philosophy of explicit styles is certainly not as elegant or economical as
the reusable macro approach, but I think it’s much easy to maintain over
time. They do tend to be less useful when immature, but gain utility as
people help refine them. I think highly abstracted CSL files follow the
opposite trajectory. We do share the same goal, I think, of helping to make
CSL become the standard for style descriptions across software, users, and
publishers. Exactly what will work best on a practical level remains to be
seen, so I see the tool as making one of several possible moves toward that.
If a different kind of tool/approach proves more usable and helps
disseminate CSL, that’s great. Maybe we’re just thinking about different
tools for different audiences.
> On the other hand, if I’m being more optimistic, perhaps there’s room
> for building on this. To do that, I would imagine there’d have to some
> tweaks in what’s already there, but also the addition of some kind of
> wizard interface upfront, with this stuff accessible when needed.
Such tweaks are exactly what I’m hoping to get advice about. Of course I
have my own ideas about what to change/improve, but I’ve probably gotten
into some conceptual ruts and would appreciate input from fresh users.
Despite diverging from earlier suggestions for a CSL editor, I have some
hope for the tool, and it might be nice to push it a bit further and see how
it evolves.
Perhaps adding some macros to the UI won’t be as confusing to the user as I
think, and would make the tool less low level but equally usable. The idea
that we should present fewer options to the user up front (i.e. simplify the
UI) and allow them to dig deeper I think is sound advice. Any specific ideas
about what to show/hide or add/remove (and upon what users actions), and how
to present potentially confusing sorting options will be much appreciated.
fred
---
### Author:  [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)
#### Post date: [April 13, 2009, 4:03pm UTC](https://discourse.citationstyles.org/t/csl-editor/601/6 "2009-04-13T16:03:16Z")
Hi Fred,
…
> > I still think MakeBST is a way superior way to author styles
> > conceptually than is the Endnote et al approach (which is what this is
> > currently).
>
> Yes, we clearly disagree here.
Have you ever tried MakeBST?
> > There’s no macros panel(s), and as you yourself note, you force a lot
> > upfront work for the style author.
> >
> > E.g. it’s now WAY too low-level. It would take me far more time to
> > create a new style in the editor than it would to hand-create one in
> > an XML editor.
>
> I fully agree that it would take YOU less time to write a very generic style
> by hand than through the tool. But the tool is really designed for people
> with no knowledge of CSL, XML, macros, other styles, and the general
> problems involved with citation styling.
Absolutely; I guess i"m just thinking these don’t need to be mutually
exclusive concerns.
> It’s true that creating full styles from scratch with the tool can take some
> time. The way I see the tool being most useful is when people can load a
> fairly complete style, like APA or Chicago, then tweak it, save a new style
> file, and upload it into a repository. Maybe not all the item types are
> defined, or some are wrong, but over time people can easily update the item
> types they need to cite. For me, creating complex style files with lots of
> grouping and where many item types are formatted differently, the tool has
> been MUCH faster than writing or editing CSL. Of course I’ve got quite a bit
> of experience using the tool, and you’ve got more experience writing CSL
> files. I think macros are much more important for writing files by hand than
> by a CSL tool, but I think we disagree about this.
The business of macros is not, at all, just about hand-authoring of
styles. It’s about encapsulating formatting logic into bits of
reusable code. This has huge potential wins for GUI interfaces as
well.
For example, why can’t I tell my style editor how I want the publisher
information formatted by choosing among two options:
1. “New York:ABC Books”
2. “ABC Books:New York”
You’re already taking this sort of approaches in some places (like
name configuration); am just suggesting generalizing it.
> > 1. why separate panels for in-text and note citations? Is that really
> > necessary?
>
> Probably not essential, but since there are substantially different options
> (though overlap, too, obviously) I thought it would help keep the user clear
> about what they are setting options for.
Not sure either; was just a question.
> > 1. … You have the “default” type at the very end of the list of types,
> > while it
> > should be the dominant type.
>
> Many CSL files have a lot of type testing throughout the macros. A simple
> example is when the file calls a title macro that decides to use italics or
> not. For a UI, and when the tool writes the CSL file, it seemed considerably
> easier to do all the item type testing in one place in the file.
Easier for whom?
> That being
> the case, the default type is not as useful (generally accurate) in tool
> produced CSL files as it is in many current CSL files that do type testing
> throughout the file. So i wanted to de-emphasize it. This also relates to
> the parent-child overrides as mentioned above. If we were to increase macro
> support and de-emphasize item types, I would agree that this should be more
> prominent.
OK.
> > 1. Where’s the online integration? Please, please tell me you aren’t
> > imagining users just creating and maintaining their own local styles.
>
> I’ve envisioned the tool interfacing with a style repository, but it seemed
> like a good idea to get a working tool before tackling the web repository
> and interface.
OK.
> I do think users should have the ability to create and work
> with local CSL files if they so choose, as long as they are aware of the
> disadvantages of that.
In either case, you still need the same infrastructure (URIs and such).
> > 1. related, why not as a web app???
>
> When I started messing around with the tool, it seemed easier to work up the
> basics as a FF extension tied to Zotero, since there were so many unknowns
> about what a decent UI would look like, how to deal with Zotero’s data
> model, and how to go from UI options to a reasonable CSL file. I agree that
> a web based tool is best, and I’m about 20% through converting the tool to
> function as a web page. I deliberately tried to code the parsing engine as
> flexibly as possible so that it could be configured to work behind a webpage
> without too much trouble. So far so good. Maybe I should have just done
> jquery (or similar) right out of the gate, but I simply wasn’t prepared to
> do that for a number of reasons, many of which are now less relevant. Now
> that I have more ideas about how the tool can and should work, it’s a good
> time for a makeover. Creating a web version is a top priority now.
OK, cool 🙂