UI for editing CSL files

CSL Development
1

In thinking about how to allow users to make specific changes to a
citation style format within Zotero (which seems like good
functionality to have), is this really possible with the current
version of CSL? Or is local customization of CSL files the wrong
approach?

It’s the wrong approach in my view.

…

One option might be to duplicate a base CSL (Chicago, say), bring up
the options in a generic CSL editor, then ask the user to configure
the punctuation (or whatever) to according to the user’s wishes, then
output a new CSL file, essentially written from scratch by the UI.

That’d be my preference, where those base styles are composed of a set
of macro components. Max’s interface can be nicely extended along
these lines.

Providing that any UI can make a nice CSL (still undecided, i think),
this would be considerably easier than editing an existing file. But
the problem here seems to be in parsing a CSL file and translating it
into a decent UI that is structured the way a user is likely to think
about styles (who i presume is rather uninterested in the language
that creates the styles). I say this is a challenge because it seems
that good UI will be in line with how users think of styles (i.e.
itemTypes, as in “i want to format pre-modern manuscripts like THIS,
and encyclopedias like THIS”, etc. and which is also how journals,
presses, etc. provide citation examples to readers),

I’m really not convinced about this assumption. I think it just as
likely that users and style writers think in terms of generic rules,
with type-related exceptions/modifications. With Max’s UI, for
example, adding previewing would go a long way to making it easier to
visualize output.

but a good CSL
creation UI, i think, will need to be in line with how properly-done
CSL files are organized, which is in terms of macros, groups, etc.

I believe that’s right.

I’m finding in quite difficult to translate between the two.

Rather than note this in the abstract, it might be more useful to
identify particular issues in existing interface efforts like Max’s?

Another option might be to duplicate the Chicago CSL file and add to
it the block to handle the new itemType. This obviously
degrades the quality of CSL per the original intent of the language.
But it often seems to me that the original goal of CSL was to design a
syntax and structure that prioritized economic markup over easy
editing and augmenting by a wide user base.

Not exactly “economic markup” for its own sake, but rather to allow
the styles to be made in such a way that they are robust. E.g. they
should work at least well in cases where there are no explicit
instructions for a given type.

Type-based formatting languages, by contrast, tend to be pretty
fragile, forcing users to regularly edit styles.

Another option in the same vein is to move away from the intricate
macro oriented approach of CSL files and favor organizing CSL files by
itemType. While not as elegant and certainly more repetitious than CSL
as now implemented by Zotero, a more explicit definition of styles may
have the advantage of being easily edited by the average user with an
intuitive UI, who could augment and modify citation styles at the item
level.

I think before you go through all of this, you really need to spend
some time with Max’s prototype and consider how it can be improved.
Once we all agree that approach has been exhausted, we might consider
other options. But I think copying Endnote’s approach to styling is a
really bad idea.

Even if we have a good makeCSL-like tool for creating new CSL files,
it seems that local and specific customization would always be nice to
provide to the Zotero user. So, to echo my initial questions, is user
customization really possible with the current version of CSL? Or is
local editing of CSL files the wrong approach? Or am i making improper
assumptions about editing a complex CSL file?

Hopefully the above comments give my answer to this.

Keep in mind that my goal with CSL is to have something like BibTeX
for the 21st century. My goal is that in five years, say, one never
has to think about citation styling; that there are thousands of
styles easily available on the web, and that one can use those styles
in dozens of applications.

Zotero is just the first (absent my early prototypes), but we now have
people working on CSL processors for Python, Ruby and Haskell, in
addition to Zotero’s Javascript. I hope at some point my original XSLT
version will get updated as well.

So I think carefully building this infrastructure out has some value,
even if many users are currently frustrated by not having infinite
flexibility (which, as I hint above, has its own costs).

Bruce

2

If people are going to edit their own style files, it might be nice to
be able to watch what they do and say, hey, you’ve re-created the xyz
public style (or very close), perhaps you’d like to use that?

Of course, implementing that might be a bit tricky :slight_smile:

–J

3

In thinking about how to allow users to make specific changes to a
citation style format within Zotero (which seems like good
functionality to have), is this really possible with the current
version of CSL? Or is local customization of CSL files the wrong
approach?

It’s the wrong approach in my view.

…

One option might be to duplicate a base CSL (Chicago, say), bring up
the options in a generic CSL editor, then ask the user to configure
the punctuation (or whatever) to according to the user’s wishes, then
output a new CSL file, essentially written from scratch by the UI.

That’d be my preference, where those base styles are composed of a set
of macro components. Max’s interface can be nicely extended along
these lines.

If people are going to edit their own style files, it might be nice to
be able to watch what they do and say, hey, you’ve re-created the xyz
public style (or very close), perhaps you’d like to use that?

Definitely!

Of course, implementing that might be a bit tricky :slight_smile:

It requires being able to have some CSL formatting process (client JS,
or maybe server-side) that can take a fragment of a CSL style – like
a macro – and return a preview. For the user perspective, the
previewing should be real-time and seamless. I don’t think that should
that hard, assuming good generic libraries (either completed python
or ruby or php implementations, or having zotero’s CSL code
abstracted).

Bruce

4

Hi Fred,

In the interest of efficiency, I’m going to zero in on a few of your
points and seek some clarification …

I asked:

  1. where is the magic that allows Zotero (or any other application) to
    know what to do with your new type?
  2. what happens if you’re collaborating on a document with another user?
  3. what happens if you want to use the style with another application?
  1. well, i’m NOT talking about a new type (though i admit it sounds
    very similar; yet it’s meant to be distinctly different). I’m thinking
    that a zotero item will be assigned by the user to use a certain
    “citationFormat”, a block of valid CSL (using existing, not custom,
    types and fields) that will describe the citation.

But that’s essentially what a type does :wink:

So for sake of argument, you’re saying every single record in a Zotero
database may have one additional field, the content of which is
totally up to the user.

Le’s call this field “format-type.”

You’re then saying CSL should also have a matching variable type that
would allow users to tie formatting to those records. Again, the value
of that variable type would be uncontrolled.

Right?

This block will associated with (or copied into) in a local CSL file or files (the
user will have an interface to create the CSL snippet; and an
interface to append that snippet to whatever CSL files they want
(probably copy of existing CSL files in the repository, and hence a
different URI). When Zotero goes to cite that item, it checks to see
if the item has a citationFormat assigned to it, and if so, then uses
the block of CSL for that citationFormat instead of the rest of the
CSL file.

OK, let’s step back b/c I’m finding this confusing. What is the
content that is returned at the end? Is it just some formatted string?
If yes, then why does this problem require the particular solution
you’re proposing?

  1. For this to work now, each party will need the same CSL file,
    presumably from the CSL repository (or wherever the URI points?),
    right?

Is that all? What about their databases?

I imagine that Zotero could be configured to share or sync the
CSL file (or snippet) as well. If someone is trying to cite an item
without the proper CSL, it fails, and they’re in the same boat they’re
in now, since they can’t edit it at all. I presume it would not be too
difficult to share and sync CSL files for the times when people wanted
to share them–which i think, and hope, will be rarely.

  1. This is why i’m so interested in your input. I could modify Zotero
    to handle custom citation formatting totally independent of CSL, but
    we already have a nice CSL parser and there’s no reason to duplicate
    functionality. Then, too, there would be a zero chance that that
    custom formatting is useful beyond zotero–a limitation i’m hoping to
    avoid. So if there was a CSL standard way of dealing with exceptions,
    i know that anyone wanting to use another application that implements
    CSL properly can therefore utilize the citationFormat blocks (or
    whatever you might propose in its place) in the same way (if they take
    their CSL file with them). But perhaps the real answer is that i think
    it’s more important to give the user that local functionality soon,
    even if its in the spirit of partially planned obsolescence. As you
    say, sharing custom stuff, especially styles, is quite messy–but
    perhaps not a reason to discourage or to forbid local customization.

I guess what i’m really interested in is whether you see any value in
handing ad-hoc formatting in CSL–not just for getting around
limitations in zotero, but the limitations (be it the same or
different) in any application that uses CSL. Or do you think it should
be left up to the application? If there is value in handling
exceptions at all, then if a user sees a citation isn’t getting
formatted properly (for whatever reason), should they be able to
customize that item (not type) to display in a certain way for their
convenience (which would have one kind of UI geared around the item
type, fields, and punctuation), or should they have to create a new
CSL file (with a UI geared around macros, groups, prefixes, etc.)?

I think flexibility is good, unless that flexibility leads to
interoperability problems.

…

My first impulse was to indeed suggest the above tied to the
“manuscript” type, but that won’t work, b/c many manuscripts you do
want the author printed. In effect, this is about some detail of the
person in question it seems, and so isn’t really about type.

I see what you’re saying here, but ‘classical works’ (as i’ve seen
them called, however they are defined, where you have an established
short title and no author in the citation, with perhaps the first
citation revealing the modern edition used) are often considered a
genre in their own right. For me, i see that characteristic as being
more fundamental than detail of the author. Six or half dozen,
perhaps.

So no instances of a classical work would include the author in the
citation? That’s my point, since I’m assuming you’re suggesting that
rule is flexible.

The type list is fixed. I’d be open to making it extensible, but only
if my above questions are resolved. I really don’t see anyway to
resolve them though.

This is a somewhat broader question than is relevant to the immediate
task, but i’ll ask anyway: Do you envision a time when people could
share, perhaps only amongst a collaborative group, an RDF file that
described their custom item types and fields (a customized version of
the new bibo, maybe?)…or is this just silly? If so, would CSL be
able to use that RDF? (assuming that an ref manager app could handle
it as well.)

My general thought is that if there are holes in CSL or bibo, they
should be plugged. That only happens when experts in particular areas
work with the specs (or the applications that use them) and identify
their problems.

The advantage of this general approach is that it’s all transparent,
and CSL (and bibo) implementers can implement it in their tools
without having to think about it.

But it takes conscious work, and (unfortunately) time. I don’t see a
way to magically make this happen ATM. Will think about it though.

…

Well, this is exactly why we have every CSL file have a URI. It’s easy
to embed that URI in the document file. But it seems to me it becomes
rather a mess if you have any user maintaining their own unique styles
locally, particularly if each of those style have custom types.

It sounds like are arguing against having custom CSL files in general.
If so, are you against allowing users to custom format their citations
without creating a new and public CSL file?

No.

Let me ask you bluntly, if I may, (and being aware that it’s not your
problem) if you have any ideas for how to handle formatting
exceptions? Or is it just something that you’d rather not have be part
of CSL?

I’m just trying to get a better handle on exactly what you need before
I can figure out if there’s a different way to do this.

Bruce

5

Oops; forgot to cc. I’m still not really following this, but I think
in effect he’s wanting the ability to extend the type list without
restriction.---------- Forwarded message ----------
From: Bruce D’Arcus
Date: Mon, Jun 30, 2008 at 1:23 PM
Subject: Re: UI for editing CSL files
To: zotero-dev@googlegroups.com

On Mon, Jun 30, 2008 at 12:52 PM, Fred Gibbs wrote:

So for sake of argument, you’re saying every single record in a Zotero
database may have one additional field, the content of which is
totally up to the user.

Le’s call this field “format-type.”

You’re then saying CSL should also have a matching variable type that
would allow users to tie formatting to those records.

I think that’s right.

Again, the value of that variable type would be uncontrolled.

Right?

Not totally uncontrolled. I’m thinking it would be some CSL that
displays the fields and the punctuation in the order the user
specified.

But I’m meaning the value of those types are uncontrolled. It could be
“pre-modern manuscript” or it could be “1234”.

The CSL would be generated by a UI, and thus relatively
standard, so it’s not wholly uncontrolled in that we have users
entering some sort of format strings, about which we can predict
little. If by value you mean name or ID of the format-type field, then
yes, it’s a user generated string. I don’t know how else to couple an
item with a block of CSL without both using a unique ID.

Yes, that’s what I mean.

This block will associated with (or copied into) in a local CSL file or files (the
user will have an interface to create the CSL snippet; and an
interface to append that snippet to whatever CSL files they want
(probably copy of existing CSL files in the repository, and hence a
different URI). When Zotero goes to cite that item, it checks to see
if the item has a citationFormat assigned to it, and if so, then uses
the block of CSL for that citationFormat instead of the rest of the
CSL file.

OK, let’s step back b/c I’m finding this confusing. What is the
content that is returned at the end? Is it just some formatted string?
If yes, then why does this problem require the particular solution
you’re proposing?

Now I’m confused. End of what?

The “end of” your explanation there.

  1. For this to work now, each party will need the same CSL file,
    presumably from the CSL repository (or wherever the URI points?),
    right?

Is that all? What about their databases?

I didn’t mean to imply that was all, but that CSL needed to be shared
anyway, so maybe it wouldn’t be too hard to share these custom CSL
bits as well, either as part of a larger file or as separate entities.

My point in asking is this: to me, it seems that your wanting this
sort of customization involves a burden on both the formatting end
(CSL, etc.) and the data source end (database, etc.), since a
formatting process has to be able to associate data with output
template. If you introduce a custom type, then you need some way for
the application to know how to match data to it. I’m still not
understanding how that would work (generally; beyond Zotero).

As you say, any customization decreases the ease of sharing and
generally complicates things. So i’m trying to figure out how to allow
ad-hoc citation formatting with minimal impact on Zotero and the way
it uses CSL. Even though i want it to be a temporary solution (with
the goal that improved CSL files and editors will obviate exception
handling for the most part), i want to be interoperable as much as
possible in the meantime.

Has any of this clarified anything?

Not really :slight_smile:

You’re still repeating the same jargon (“ad-hoc formatting”, “block of
CSL”, etc.) that I’m having a hard time seeing into.

I also think this is related to another issue we’ve previously
discussed, which is how to achieve things like grouping of references.
This is a bit fuzzy ATM (John McCaskey might remember this discussion
better than I), but I recall some discussion of optionally assigning
items to user-defined groups. I could imagine such a feature MIGHT
address what you’re wanting here.

The issue of customization has come up before on this list, and I know
Dan had some very concrete thoughts about how to achieve it. It might
be valuable to open up this discussion a bit and see if we can get Dan
to offer some thoughts, and compare them to how you’ve framed the
problem?

Bruce