macros vs. types

Let’s pull this into a new thread. So to answer my own questions to Fred:

  1. 'Macros, as the term itself implies, are best at generic
    behavior": what kind of “generic behavior” might they be “best” at?

CSL macros are really good are describing how to format:

  • dates
  • titles
  • publisher info
  • names

Forget about the word “macro”: to describe this from the user
perspective, the user should be able to choose from lists of
pre-defined options how to format these components of a citation or
reference. I should be able to say “names should look like this” or
"dates like that". At some points, at least, it should be possible to
allow such selectors to create a new definition (macro) or edit an
existing one (?).

  1. “to enable users to easily make small and incremental changes
    means that editing a style will tend toward explicit type definitions
    and away from macros”: “small and incremental changes” in what
    specific things? Variable order? Inter-variable punctuation?

Am not really sure, but would like some specific examples. I think the
details here matter a lot.

I also think, on the point that the approaches need not be mutually
exclusive, that my primary points are we

  1. make macros available to (and perhaps even required in) layouts

  2. privilege what is in effect the “generic” type, but perhaps still
    allow type-specific exceptions (though exactly how best to do this
    depends a lot on the “details” above). Maybe my “order” UI example,
    for example, could have a little “+” tab that would add a new
    template?

Bruce

So this conversation never did get resolved. Any thoughts on how to
move this forward?

Hi all,

my tacit interpretation of the discussion was that my UI proposal would
generally be compatible with either a macros or a types approach - does
anybody disagree with that?

So in order to move this forward, if we could broadly agree on my UI
proposal (as a starting point), Mendeley could start scheduling resources to
implement the UI web frontend (or, those bits that are independent of
whether we go with macros vs. types). Until the implementation actually
begins, everybody could add their modifications/thoughts to the UI specs in
the wiki.

Does that sound reasonable?

Best,
Victor

I’d been waiting to see if anyone else would respond this, but realize
nobody did. So …

my tacit interpretation of the discussion was that my UI proposal would
generally be compatible with either a macros or a types approach - does
anybody disagree with that?

Yes, mainly in that we probably need to clarify our terms.

I’m thinking it might be more helpful to distinguish between a primary
UI focus on generic formatting (using macros) vs. one focused on
reference types. While these aren’t mutually exclusive approaches,
your UI suggestion currently fits the latter model, while my strong
preference is the former (e.g. to start with the generic).

So in order to move this forward, if we could broadly agree on my UI
proposal (as a starting point), Mendeley could start scheduling resources to
implement the UI web frontend (or, those bits that are independent of
whether we go with macros vs. types). Until the implementation actually
begins, everybody could add their modifications/thoughts to the UI specs in
the wiki.

How do propose to move forward from the specs to the code? Is there a
way to iteratively work through this? Does someone need access to the
BitBucket project?

Bruce

Hi Bruce, hi all,

apologies for the silence from our end. Following up on last November’s
discussions on the web-based WYSIWYG CSL Editor, we have some progress to
report. We have recently started work on an implementation of the specs we
shared earlier. We’ve set-up a Mercurial code repository at Bitbucket:
http://bitbucket.org/csledit/csl-wysiwyg-editor/

Feel free to clone the repository to set up your own test server. Our editor
requires the Kohana PHP framework and jQuery. You can also see our developer
Tom’s work-in-progress here: http://csleditor.quist.de/

A few more words on the macro-based vs. doctype-based approach discussion:
We are still convinced that both perspectives, i.e. the task-oriented,
end-user-centric perspective and the more structure-orientented advocated by
Bruce and others, are compatible. With Frank’s recent efforts on macro
extraction, normalization and canonization, we feel the first steps have
been taken towards “bridging the gap” between the two approaches.

As Bruce wrote in http://n2.nabble.com/forum/PostLink.jtp?post=2618727:

“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.”

That’s what we’re trying to realize in our editor. To speed up development
process, we will initially focus on implementing the front-end as described
in the spec. This gives us some more time to discuss the back-end
implementation of csl-lib and the workflow model propsed by Frank:

Frank Bennett on Nov 02, 2009:

If you went this route, the first step (before deployment of CSL 1.0?)
would be to set up for automated repository housecleaning, identifying
macros that have exactly the same CSL definition, giving them uniform
names, and extracting them to a WYSIWYG library archive that can be
updated automatically from the raw contents of the repository. Some
means of automatically assigning descriptive names to macros would
need to accompany that, to provide consistent and meaningful names
without human intervention.

Anyway, just wanted to give you an update of what we’re working on.

All the best,
Victor

Also, it seems this is access controlled? I get a “You do not have
access to this repository.”

Bruce

Hi Bruce, hi all,

apologies for the silence from our end. Following up on last November’s
discussions on the web-based WYSIWYG CSL Editor, we have some progress to
report. We have recently started work on an implementation of the specs we
shared earlier. We’ve set-up a Mercurial code repository at Bitbucket:
http://bitbucket.org/csledit/csl-wysiwyg-editor/

Feel free to clone the repository to set up your own test server. Our editor
requires the Kohana PHP framework and jQuery. You can also see our developer
Tom’s work-in-progress here: http://csleditor.quist.de/

Awesome; nice to see this!

A few more words on the macro-based vs. doctype-based approach discussion:
We are still convinced that both perspectives, i.e. the task-oriented,
end-user-centric perspective and the more structure-orientented advocated by
Bruce and others, are compatible. With Frank’s recent efforts on macro
extraction, normalization and canonization, we feel the first steps have
been taken towards “bridging the gap” between the two approaches.

Yeah, but how is that now reflected in the UI? Am not seeing a
“generic” template (which in my view should be the only one visible to
the user when they open the UI), and from what I can tell, the
“fields” are in fact simple variables; not macros. If that’s true,
then it’s impossible to do really important things, like configuring
substitution behavior for authors.

In any case, a good start!

Bruce

Sorry, access should be working now!

Yeah, but how is that now reflected in the UI? Am not seeing a “generic”

template (which in my view should be the only one visible to the user when
they open the UI), and from what I can tell, the “fields” are in fact simple
variables; not macros. If that’s true, then it’s impossible to do really
important things, like configuring substitution behavior for authors.

To be honest, I don’t know yet either. But I think we had to get started
somewhere - I’m sure we’ll figure it out as we go along!

Cheers,
Victor

Sorry, access should be working now!

I’m not much of a PHP or JS coder, but looks nice and clean to me (so
is CSLEditor a JQuery plugin?)! Hopefully other people will have a
chance to take a look at and hack on it.

Yeah, but how is that now reflected in the UI? Am not seeing a “generic”
template (which in my view should be the only one visible to the user when
they open the UI), and from what I can tell, the “fields” are in fact simple
variables; not macros. If that’s true, then it’s impossible to do really
important things, like configuring substitution behavior for authors.

To be honest, I don’t know yet either. But I think we had to get started
somewhere - I’m sure we’ll figure it out as we go along!

Yup.

Tom, if you’re here, let us know if you have any thoughts of how this
moves forward, or if you’re looking for any particular feedback at
this point.

Bruce

Also, probably worth moving discussion about details to the BB project
tracker. There’s already an issue for a split between a beginner and
expert interface, which I support.

http://bitbucket.org/csledit/csl-wysiwyg-editor/issue/1/provide-beginner-expert-interface

Bruce

One other thing: I don’t see any license statement in the repository.
You might want to fix that? I think we talked about GPL being
acceptable for everyone?

Bruce

Hi Bruce,

Tom, if you’re here, let us know if you have any thoughts of how this
moves forward, or if you’re looking for any particular feedback at
this point.

I’m coordinating Tom’s work from Mendeley’s side. We’ve set up an internal
project roadmap and will need some more time.
But we’ll be happy to request and receive feedback on specific issues from
you and the list at a later time.

Sorry about the missing licence, will add that ASAP. Currently catching up
on previous licensing discussions, will keep you updated on any decisions
taken.

Best regards,

Philipp

Hi Bruce,

Tom, if you’re here, let us know if you have any thoughts of how this
moves forward, or if you’re looking for any particular feedback at
this point.

I’m coordinating Tom’s work from Mendeley’s side. We’ve set up an internal
project roadmap and will need some more time.
But we’ll be happy to request and receive feedback on specific issues from
you and the list at a later time.

Sorry about the missing licence, will add that ASAP. Currently catching up
on previous licensing discussions, will keep you updated on any decisions
taken.

Victor, Philipp, Tom, everyone,

Thanks for the news update, good to see this! If it’s helpful to the
cause, I can keep tinkering with the csl-lib tool, with an eventual
target of getting it to go round-trip and produce valid CSL 1.0
styles.

Don’t know how it might fit into your development plans, but for
repository housecleaning and maintenance, it would be useful to have
an emacs mode that is capable of renaming a macro and the calls made
to it across the archive. With that in hand, we could work toward a
setup where all macros with the same base name are drop-in
replacements of one another, which should make it simpler to leverage
them through the editor UI.

In any case, will look forward to further news and developments.

Frank

Well, what is the general roadmap?

I still think you guys are doing this backward (that you should start
with a UI based on the general (macros) and then extend it to allow
editing/creating those macros), but I guess that’s up to you, so long
as the final result is more-or-less equivalent.

Bruce

Dear Bruce, dear list,

sorry that I didn’t manage to reply any earlier.

As for the license: We’ve decided to go with the ECL for this project.

Well, what is the general roadmap?

Here’s a quick overview of the milestones and dates.

M1: Drag&drop prototype (Feb 05)
M2: Live-Preview (Mar 12)
M3: Additional formatting features (Mar 26)
M4: Back-End, CSL output generator (Apr 02)
M5: Back-End, CSL input reader (own files) (Apr 16)
M6: Back-End, CSL input reader (all files) (Apr 23)

Regards

Philipp