Citation Style Editor prototype

Hi, Steve,

Had another thought on the editor UI this morning.

In the sample, to get at the comma between the name and the title, you
need to open the citation object, and expand down to find the
enclosing group object in the tree view.

An intuitive way to reach it from the right-hand view would be to
select one element (the title block, say), and then use ctrl-click to
select a partner. The selection would then “expand” to the
lowest-level object that contains both selected items and bingo,
there’s the delimiter between the two.

Frank

Hi Frank,

Thanks for the suggestion. This sounds like a workaround which may be
useful for a power-user, but a bit complicated for a novice user,
especially when you consider how complicated the editor is currently for a
newcomer. Ideally, that comma would only fall within the span tag for the
group which creates the delimiter, and not withing a child of the group. If
possible, it would be nice to fix the root cause of the problem and get the
span tags working at a character level, although I know you’ve said this is
very difficult.

Regards,
Steve

PS: I haven’t updated the site in a while but progress is going well, I’ve
got an updated tree view working now allows you to expand nodes to allow viewing and editing the macro definition within
it. Hopefully this will allow novices to navigate the style structure and
make some edits without understanding macros, and if they do attempt to
edit one then we can prompt to check whether they want the edit to affect
all instances. I’ll probably push an update to the site by the end of next
week.

Hi Frank,

Thanks for the suggestion. This sounds like a workaround which may be useful
for a power-user, but a bit complicated for a novice user, especially when
you consider how complicated the editor is currently for a newcomer.
Ideally, that comma would only fall within the span tag for the group which
creates the delimiter, and not withing a child of the group.

We may be talking past one another; I don’t think this is a
workaround, it would just be a little smoothing of the interface.
Assuming that the comma is on the group as a delimiter, there is
currently no way to select the group from the right-side view. You
have to know that you are looking for a group, and select things in
the left-side tree display until you find the one you’re looking for.
All I’m suggesting is that the normal ctrl-click behavior (the same as
for selections in a normal GUI-based file manager) can be adopted in
the right-side view, as a way of selecting the group containing two or
more chunks of output.

If possible, it
would be nice to fix the root cause of the problem and get the span tags
working at a character level, although I know you’ve said this is very
difficult.

It would indeed be hard. The only approach I can think of would be to
subclass the string type, so that strings can carry metadata about
where they originated from. That would be possible in Python, but I’m
not sure Javascript can be pushed that far.

Hi Frank,

Thanks for the suggestion. This sounds like a workaround which may be
useful
for a power-user, but a bit complicated for a novice user, especially
when
you consider how complicated the editor is currently for a newcomer.
Ideally, that comma would only fall within the span tag for the group
which
creates the delimiter, and not withing a child of the group.

We may be talking past one another; I don’t think this is a
workaround, it would just be a little smoothing of the interface.
Assuming that the comma is on the group as a delimiter, there is
currently no way to select the group from the right-side view.

Sorry, this was a bad example, clicking on delimiters seems to work OK.
e.g. try clicking on the period between the title and journal name in APA
style, it selects the correct group.

Prefixes and suffixes don’t work though, they aren’t contained within the
span tag for the group. e.g. try clicking on the “(” or the “).” before and
after the year in the APA bibliography entries. In this case these are
defined in a group but the group span tags only enclose the year.

You
have to know that you are looking for a group, and select things in
the left-side tree display until you find the one you’re looking for.
All I’m suggesting is that the normal ctrl-click behavior (the same as
for selections in a normal GUI-based file manager) can be adopted in
the right-side view, as a way of selecting the group containing two or
more chunks of output.

If it seems simple to implement could try it out, but I imagine most users
won’t think of trying to Ctrl click on the example output and may be
confused when the selected node doesn’t match the ones they clicked on
unless we put some work into the UI to make it clear that the selected node
is the nearest common ancestor.

But it does give me the easy idea of putting the entire path of the
selected node in the title bar of the property panel, and allowing the user
click on each node in the path. A bit like Windows explorer does.

If possible, it
would be nice to fix the root cause of the problem and get the span tags
working at a character level, although I know you’ve said this is very
difficult.

It would indeed be hard. The only approach I can think of would be to
subclass the string type, so that strings can carry metadata about
where they originated from. That would be possible in Python, but I’m
not sure Javascript can be pushed that far.

Hmm, it sounds like some refactoring would be needed. Once the editor is in
a better state we can try to see how big a problem the lack of
character-level accuracy is for users. I think it will confuse people for
sure when they click on something and the wrong node is selected.

Hi Frank,

Thanks for the suggestion. This sounds like a workaround which may be
useful
for a power-user, but a bit complicated for a novice user, especially
when
you consider how complicated the editor is currently for a newcomer.
Ideally, that comma would only fall within the span tag for the group
which
creates the delimiter, and not withing a child of the group.

We may be talking past one another; I don’t think this is a
workaround, it would just be a little smoothing of the interface.
Assuming that the comma is on the group as a delimiter, there is
currently no way to select the group from the right-side view.

Sorry, this was a bad example, clicking on delimiters seems to work OK. e.g.
try clicking on the period between the title and journal name in APA style,
it selects the correct group.

Prefixes and suffixes don’t work though, they aren’t contained within the
span tag for the group. e.g. try clicking on the “(” or the “).” before and
after the year in the APA bibliography entries. In this case these are
defined in a group but the group span tags only enclose the year.

I hadn’t noticed that. I may be able to do something there; those
affixes are on the right node, I think (I’m pretty sure parens don’t
migrate). It would just be a matter of making sure the tag encloses
them.

You
have to know that you are looking for a group, and select things in
the left-side tree display until you find the one you’re looking for.
All I’m suggesting is that the normal ctrl-click behavior (the same as
for selections in a normal GUI-based file manager) can be adopted in
the right-side view, as a way of selecting the group containing two or
more chunks of output.

If it seems simple to implement could try it out, but I imagine most users
won’t think of trying to Ctrl click on the example output and may be
confused when the selected node doesn’t match the ones they clicked on
unless we put some work into the UI to make it clear that the selected node
is the nearest common ancestor.

But it does give me the easy idea of putting the entire path of the selected
node in the title bar of the property panel, and allowing the user click on
each node in the path. A bit like Windows explorer does.

That’s a better idea.

Hi Frank,

Thanks for the suggestion. This sounds like a workaround which may be
useful
for a power-user, but a bit complicated for a novice user, especially
when
you consider how complicated the editor is currently for a newcomer.
Ideally, that comma would only fall within the span tag for the group
which
creates the delimiter, and not withing a child of the group.

We may be talking past one another; I don’t think this is a
workaround, it would just be a little smoothing of the interface.
Assuming that the comma is on the group as a delimiter, there is
currently no way to select the group from the right-side view.

Sorry, this was a bad example, clicking on delimiters seems to work OK. e.g.
try clicking on the period between the title and journal name in APA style,
it selects the correct group.

Prefixes and suffixes don’t work though, they aren’t contained within the
span tag for the group. e.g. try clicking on the “(” or the “).” before and
after the year in the APA bibliography entries. In this case these are
defined in a group but the group span tags only enclose the year.

I hadn’t noticed that. I may be able to do something there; those
affixes are on the right node, I think (I’m pretty sure parens don’t
migrate). It would just be a matter of making sure the tag encloses
them.

Steve: I’ve just put up a fresh processor release (version 1.0.331)
that properly captures the affixes. It also fixes a bug in date
objects, which were setting a bad trace node ID.

Frank

Thanks, I’ve updated the site with the latest citeproc version and this is
working properly.

I’ve also made a quite a few other changes to the site:
http://steveridout.com/csl/visualEditor/

It’s at a stage where I’d encourage brave technically minded users to do
real work with it, with the caveat that it’s still an early alpha version,
no guarantees, back up your style regularly, etc…

The biggest change from last time is the tree view on the left. You can now
expand nodes to see the macro definition inside. This
hopefully makes the macro functionality more obvious. Currently there’s no
warning that editing a macro will affect all instances - we plan to add
this soon.

Please let me know if you have any suggestions or bug reports.

Thanks,
Steve

I’m not really remembering, or don’t know, how the current design
relates to the ultimate goal; what real, average, users will see in
the end. But I’ll just say it:

I don’t think the current UI is any easier to use than using a good
XML editor (though the live previewing is definitely awesome).

It’s very well done work, but it still represents quite directly a
complex and abstract model that will be hard for people (even me) to
grok.

Of course, if this is just to the first stage towards something
simpler, then nothing to worry about.

For example, the “search by example” tab is evolving nicely.

First, a little thing: I think we want a link like “create new style
based on” link.

Second, I’ll just remind of the most overwhelmingly common use case:

User searches by example, and finds something very, very close to what
they need, but not quite there. Let’s say everything is correct,
except that issue numbers need the parentheses removed.

So I’m trying to do this right now: edit a style (APA) that has issue
numbers with parenthesis affixes. It should take me two seconds to do.
But I can’t find where the parentheses are.

If I could edit punctuation directly in the output example, that would
solve that problem.

But then consider changes that don’t involve punctuation.

Bruce

It’s at a stage where I’d encourage brave technically minded users to do real work with it, with the caveat that it’s still an early alpha version, no guarantees, back up your style regularly, etc…
Please let me know if you have any suggestions or bug reports.

I’m not really remembering, or don’t know, how the current design
relates to the ultimate goal; what real, average, users will see in
the end. But I’ll just say it:

I don’t think the current UI is any easier to use than using a good
XML editor (though the live previewing is definitely awesome).

The cross-reference between visual form and style code is invaluable.
This will save anyone charged with maintaining production styles of
any degree of complexity a huge amount of time.

It’s very well done work, but it still represents quite directly a
complex and abstract model that will be hard for people (even me) to
grok.

Of course, if this is just to the first stage towards something
simpler, then nothing to worry about.

For example, the “search by example” tab is evolving nicely.

First, a little thing: I think we want a link like “create new style
based on” link.

Second, I’ll just remind of the most overwhelmingly common use case:

User searches by example, and finds something very, very close to what
they need, but not quite there. Let’s say everything is correct,
except that issue numbers need the parentheses removed.

So I’m trying to do this right now: edit a style (APA) that has issue
numbers with parenthesis affixes. It should take me two seconds to do.
But I can’t find where the parentheses are.

Really?

Citation 1 → select article-journal.
Click on issue number in cite sample.
Delete parenthesis.

Done.

If I could edit punctuation directly in the output example, that would
solve that problem.

But then consider changes that don’t involve punctuation.

The UI provides access to every attribute of the node, and illustrates
the effect as changes are made.

Or is your point that style examples should be editable directly,
without revealing the nodes at all? If so, I think that would be bad
design; surely users need to be encouraged to understand and work
through the abstract model. It’s the most concise language we have
available for describing citation requirements with any degree of
precision.

It’s at a stage where I’d encourage brave technically minded users to do real work with it, with the caveat that it’s still an early alpha version, no guarantees, back up your style regularly, etc…
Please let me know if you have any suggestions or bug reports.

I’m not really remembering, or don’t know, how the current design
relates to the ultimate goal; what real, average, users will see in
the end. But I’ll just say it:

I don’t think the current UI is any easier to use than using a good
XML editor (though the live previewing is definitely awesome).

The cross-reference between visual form and style code is invaluable.
This will save anyone charged with maintaining production styles of
any degree of complexity a huge amount of time.

Fair enough. But it won’t work if the editor itself is too complex.

It’s very well done work, but it still represents quite directly a
complex and abstract model that will be hard for people (even me) to
grok.

Of course, if this is just to the first stage towards something
simpler, then nothing to worry about.

For example, the “search by example” tab is evolving nicely.

First, a little thing: I think we want a link like “create new style
based on” link.

Second, I’ll just remind of the most overwhelmingly common use case:

User searches by example, and finds something very, very close to what
they need, but not quite there. Let’s say everything is correct,
except that issue numbers need the parentheses removed.

So I’m trying to do this right now: edit a style (APA) that has issue
numbers with parenthesis affixes. It should take me two seconds to do.
But I can’t find where the parentheses are.

Really?

Citation 1 → select article-journal.
Click on issue number in cite sample.
Delete parenthesis.

Done.

Yes, really. That didn’t even occur to me. Why should it? If I click
a journal article on the output example, why do I have to find some
hidden other place to select, well, a journal article?

When the time is right, ideally we’d do usability testing to assess.
Is there any possibility that Mendeley and/or CNMH could hire or
corral some students to do this? Sit them in front of a monitor and
ask them to do one task: the edit an existing one I laid out here.
Record their interactions with the UI, and time how long it takes
them.

If I could edit punctuation directly in the output example, that would
solve that problem.

But then consider changes that don’t involve punctuation.

The UI provides access to every attribute of the node, and illustrates
the effect as changes are made.

Or is your point that style examples should be editable directly,
without revealing the nodes at all? If so, I think that would be bad
design; surely users need to be encouraged to understand and work
through the abstract model. It’s the most concise language we have
available for describing citation requirements with any degree of
precision.

I guess I go back to the argument I’ve been making for the past few years:

Users won’t be bothered with these details. They just want the stuff
to work, which in this case means to match the output they expect.

Consider the use case again: a not-terribly-technically savvy, and
very busy, junior faculty member who has to submit her article
manuscript to Journal X. There’s no such style, and she’s really
stressed. She just needs the damned thing to work, ASAP. She won’t
spent three hours (if she’s lucky) learning the CSL model, and how to
use it in a very complicated UI.

I don’t think a direct representation of the model is consistent with
making this user happy, which should be our goal.

I think allowing users to select different macros–or even better to
have the software do it for them as la Simon’s proof-of-concept–is.

To be clear, these aren’t mutually-exclusive. The current UI could
simply be an “advanced” editor to create new macros, and edit existing
ones.

Bruce

Hi,

When the time is right, ideally we’d do usability testing to assess.
Is there any possibility that Mendeley and/or CNMH could hire or
corral some students to do this? Sit them in front of a monitor and
ask them to do one task: the edit an existing one I laid out here.
Record their interactions with the UI, and time how long it takes
them.

This is on the way (students being recruited, documentation about the
tasks is prepared, etc.).
Tasks similar to the one that you described… but not creating a
style from the scratch.

Consider the use case again: a not-terribly-technically savvy, and
very busy, junior faculty member who has to submit her article
manuscript to Journal X. There’s no such style, and she’s really

is there a similar style?
Or she needs to do it from the scratch?
Because if there is a similar one the current approach should be useful, no?
If needs to be done from the scratch… it looks harder.

Hi,

When the time is right, ideally we’d do usability testing to assess.
Is there any possibility that Mendeley and/or CNMH could hire or
corral some students to do this? Sit them in front of a monitor and
ask them to do one task: the edit an existing one I laid out here.
Record their interactions with the UI, and time how long it takes
them.

This is on the way (students being recruited, documentation about the
tasks is prepared, etc.).

Excellent!

Tasks similar to the one that you described… but not creating a
style from the scratch.

That’s fine.

Consider the use case again: a not-terribly-technically savvy, and
very busy, junior faculty member who has to submit her article
manuscript to Journal X. There’s no such style, and she’s really

is there a similar style?
Or she needs to do it from the scratch?
Because if there is a similar one the current approach should be useful, no?

Not if it takes her hours to figure out how to make a simple change :wink:

If needs to be done from the scratch… it looks harder.

I believe existing evidence (2000+ styles, and many years of
collective of experience) demonstrates that creating from scratch can
be defined as a corner case at this point.

Bruce

Some preliminary suggestions/questions:

  • are there plans to hook the editor up to GitHub? I’m wondering if it
    would be a good idea to make it possible for users to click a button, write
    a description of the changes they’ve made, and have the editor handle the
    creation of a pull request. (my concern is that obviously somebody would
    have to moderate all those pull requests)
  • elements such as cs:text have a long list of possible attributes. I think
    it would be clearer to group these in the bottom-right frame in a group of
    active attributes at the top, and inactive attributes at the bottom.
  • it would be nice to have tooltips for all the attributes. It might be
    possible to pull these from the CSL schema, since it contains annotations
    for most of them.
  • many attributes are mutually exclusive (e.g. “macro”, “term”, “value”,
    and “variable” on cs:text). Maybe these attributes should be presented in a
    dropdown menu?
  • it might be helpful to provide a bit more information on the nodes in the
    tree, and list the most important node information. E.g. “Text (variable:
    “page”)” instead of just “Text”

Rintze

And another little note about the “search by example” panel:

At some point, there needs to be a way to account for different
classes of style (note, numeric, in-text, label).

I’m not sure how best to do that, but it might be that upon opening
the panel, all the user initially sees is a pop-up select list (or
maybe buttons?). When they select “note”,’ then, they’d get the
properly configured “edit” area (where in this case one could deselect
the “bibliography”).

Bruce

Regarding Bruce’s comments: I totally understand your point of view, and I
agree that even a highly polished version of the current site will still be
difficult for non-technical users. However I think it will be far easier
than a generic XML editor and will enable more users to edit CSL.

The idea of editing the formatted citations directly and inferring a
style algorithmically is very interesting, but I think it’s difficult do
well. The ‘black box’ nature of this approach could get very annoying for
users when they don’t get the results they want. Saying that, I’d like to
go some way down this road later in the project, extracting all the macros
from the existing repository for use as building blocks. In this case, I
think a version of the ‘Search By Example’ search but applied to macros
could be very powerful.

Some preliminary suggestions/questions:

  • are there plans to hook the editor up to GitHub? I’m wondering if it
    would be a good idea to make it possible for users to click a button, write
    a description of the changes they’ve made, and have the editor handle the
    creation of a pull request. (my concern is that obviously somebody would
    have to moderate all those pull requests)

This would be cool, we’ve thought about it but decided to focus on the core
editing features first, and then on an API to integrate it with reference
managers. So no immediate plans, but it’s something we’re considering, and
the code is open source, so anyone who wants is welcome to try implementing
this.

  • elements such as cs:text have a long list of possible attributes. I
    think it would be clearer to group these in the bottom-right frame in a
    group of active attributes at the top, and inactive attributes at the
    bottom.

Funnily enough it used to be like this, but we changed it since the
controls ‘jumping around’ was thought to be confusing.

  • it would be nice to have tooltips for all the attributes. It might be
    possible to pull these from the CSL schema, since it contains annotations
    for most of them.

That’s a very good idea, I’ll look into implementing it.

  • many attributes are mutually exclusive (e.g. “macro”, “term”, “value”,
    and “variable” on cs:text). Maybe these attributes should be presented in a
    dropdown menu?

True, the property panel is very crudely designed at the moment and needs a
lot of work. I could see if this is easy to pull from the schema too,

  • it might be helpful to provide a bit more information on the nodes in
    the tree, and list the most important node information. E.g. “Text
    (variable: “page”)” instead of just “Text”

I’ve been meaning to do this, just need to find the right balance and not
make it too cluttered.

And another little note about the “search by example” panel:

At some point, there needs to be a way to account for different
classes of style (note, numeric, in-text, label).

I’m not sure how best to do that, but it might be that upon opening
the panel, all the user initially sees is a pop-up select list (or
maybe buttons?). When they select “note”,’ then, they’d get the
properly configured “edit” area (where in this case one could deselect
the “bibliography”).

True, we could add a combo box to filter by different classes. For the
moment, searches for a given in-line citation will return matches
regardless of whether the style is note, numeric, in-text or label.

(Also, the search results need some indication of how close the match is,
will work on this)

Bruce

  • it would be nice to have tooltips for all the attributes. It might be
    possible to pull these from the CSL schema, since it contains annotations
    for most of them.

That’s a very good idea, I’ll look into implementing it.

If you do, you might want to take a look at the latest version of the CSL
schema in the master branch. I’ve reorganized a lot of annotations since we
released CSL 1.0, and I hope to release CSL 1.0.1 in the next few months.

Rintze

The idea of editing the formatted citations directly and inferring a
style algorithmically is very interesting, but I think it’s difficult do
well. The ‘black box’ nature of this approach could get very annoying for
users when they don’t get the results they want.

Yes, no doubt doing really simple really well is really hard!

Saying that, I’d like to go
some way down this road later in the project, extracting all the macros from
the existing repository for use as building blocks. In this case, I think a
version of the ‘Search By Example’ search but applied to macros could be
very powerful.

Sounds good.

Bruce

I’m obviously biased, and I don’t want to be overly pessimistic, but with
the current iteration I would still much prefer a plain text editor.
Changing values of attributes is relatively straightforward, but the
current tree view still doesn’t work very well in showing the style
structure, especially for cs:group and cs:choose elements since you have to
expand and select every node to see what’s going on, and I’m having a
really hard time creating a mental map of a style by looking at the tree.
E.g., maybe I want to move the date to follow the title. I can’t drag the
element in the formatted example, and it’s not very intuitive which element
in the tree should be dragged, and what its destination should be.

Rintze

P.S. dragging elements around in the tree only works sporadically for me. I
often drop an element but nothing happens.On Wed, May 23, 2012 at 11:41 AM, Steve Ridout <@Steve_Ridout1>wrote:

Regarding Bruce’s comments: I totally understand your point of view, and
I agree that even a highly polished version of the current site will still
be difficult for non-technical users. However I think it will be far easier
than a generic XML editor and will enable more users to edit CSL.

I’m obviously biased, and I don’t want to be overly pessimistic, but with
the current iteration I would still much prefer a plain text editor.
Changing values of attributes is relatively straightforward, but the
current tree view still doesn’t work very well in showing the style
structure, especially for cs:group and cs:choose elements since you have to
expand and select every node to see what’s going on, and I’m having a
really hard time creating a mental map of a style by looking at the tree.
E.g., maybe I want to move the date to follow the title. I can’t drag the
element in the formatted example, and it’s not very intuitive which element
in the tree should be dragged, and what its destination should be.

I’ll think about how to improve this, but I’m not sure about dragging the
formatted output, that would be very tricky to implement. If you can think
of a clearer way to represent the style structure I’m open to ideas.

Rintze

P.S. dragging elements around in the tree only works sporadically for me.
I often drop an element but nothing happens.

Ah, I’m aware of one bug here with jstree. It happens if you leave the
mouse exactly between two nodes so instead of slightly overlapping one when
dropping. I’ll work on it. Thanks.On May 23, 2012 7:30 PM, “Rintze Zelle” <@Rintze_Zelle> wrote:

On Wed, May 23, 2012 at 11:41 AM, Steve Ridout <@Steve_Ridout1> wrote: