xbiblio-devel Digest, Vol 40, Issue 1

CSL Development
1

Hi all,

i don’t have much to add besides what is already in the conversation i had
with Bruce some time ago (to which he already linked in an earlier message).
but i thought i might mention a few things about where my rough prototype
came from in case it might be useful those new to the discussion.

Mainly, i would suggest that before a conversation about UI specs can be
truly productive, it needs to be decided (at least by those developing the
UI) whether the UI will be organized around macros or types (as has already
been mentioned a few times in this conversation). Certainly there are a
number of smaller configuration options that once can quibble about, but the
macro/type distinction seems crucial to me because it dictates the
fundamental visual structures of the interface and the fundamental logic
behind the code.

Personally, I developed my rudimentary tool under the assumptions: 1) that
users don’t want to know or care about macros or any other underlying
structure of CSL files, and 2) that they think about styles predominately in
terms of item type. My tool obviously reflects that.

I also thought, and still think, that it would be unnecessarily difficult to
maintain a type-based UI that creates CSL files that were heavily macro
oriented, so I was content to use more explicit type definitions in the CSL
files. But I don’t think this is a compromise in creating good CSL files.
While using macros for creators and dates and other important exceptions is
entirely necessary (and good practice), I don’t believe that the best CSL
files best are organized fundamentally around macros and are light on
explicit type definitions. While more macros and fewer type definitions get
you more generic functionality from a CSL file, I think they make
maintaining and extending the CSL much more difficult, especially with a
tool, and especially if that tool presents a type-based UI.

This philosophy grows out my belief that CSL files are most useful and
powerful when easily editable by a number of people who will be correcting
the styles to work with rare item types and non-standardized sources over
time. It is most commonly in the edge cases, I think, when people get
frustrated with citation software that doesn’t allow small formatting
adjustments either in common or rare citation cases. I created the tool
largely with that audience in mind. Macros, as the term itself implies, are
best at generic behavior, and there certainly is a lot of that in a given
style. But 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. So it was my conclusion in groping towards a prototype
that the advantages of explicit types definitions far outweighs the coding
complexity to maintain macros.

The above is true of course only if the UI is style-based, as mine is. But
one could create a macro oriented UI that eliminates some if not much of the
coding complexity I have just alluded to. So I return to my initial point
that the type vs. macro approach in the UI is a fundamental driver of how
things will unfold both in the UI and the code.

best,
fred2009/11/1 xbiblio-devel-request@lists.sourceforge.net

2

i don’t have much to add besides what is already in the conversation i had
with Bruce some time ago (to which he already linked in an earlier message).
but i thought i might mention a few things about where my rough prototype
came from in case it might be useful those new to the discussion.

Thanks for this Fred; it’s helpful!

Mainly, i would suggest that before a conversation about UI specs can be
truly productive, it needs to be decided (at least by those developing the
UI) whether the UI will be organized around macros or types (as has already
been mentioned a few times in this conversation). Certainly there are a
number of smaller configuration options that once can quibble about, but the
macro/type distinction seems crucial to me because it dictates the
fundamental visual structures of the interface and the fundamental logic
behind the code.

Correct.

Personally, I developed my rudimentary tool under the assumptions: 1) that
users don’t want to know or care about macros or any other underlying
structure of CSL files, and 2) that they think about styles predominately in
terms of item type. My tool obviously reflects that.

Right, and I don’t share those assumptions, or at least the way you’ve
characterized them.

My fundamental assumptions are:

  1. users only care about types when stuff doesn’t work

  2. different users and user communities care about different types

…

This philosophy grows out my belief that CSL files are most useful and
powerful when easily editable by a number of people who will be correcting
the styles to work with rare item types and non-standardized sources over
time.

I just want to note here that this is partly you speaking as an historian.

It is most commonly in the edge cases, I think, when people get
frustrated with citation software that doesn’t allow small formatting
adjustments either in common or rare citation cases. I created the tool
largely with that audience in mind.

Right.

But my issue is that we don’t want to force people to have to worry
about all this type-specific detail if they don’t have to. To quote
the old Perl adage (right?), the easy stuff needs to be really easy,
and the hard stuff should be possible. We need to design for the 80%,
not the last 5% or 10%.

Macros, as the term itself implies, are
best at generic behavior, and there certainly is a lot of that in a given
style. But 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. So it was my conclusion in groping towards a prototype
that the advantages of explicit types definitions far outweighs the coding
complexity to maintain macros.

But I think you need to step back here and reassess your assumptions
and tighten up your language, because after now literally years of
talking about this, we’re not any closer on this issue.

So let me ask a specific question: please clarify the following two statements:

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

  2. “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?

The above is true of course only if the UI is style-based, as mine is. But
one could create a macro oriented UI that eliminates some if not much of the
coding complexity I have just alluded to. So I return to my initial point
that the type vs. macro approach in the UI is a fundamental driver of how
things will unfold both in the UI and the code.

Yes, though it’s possible to see them as not necessarily mutually-exclusive.

Bruce