Macro condition

CSL Development
21

I still think we need to start with first principles: do we really want to
make CSL “modular”?

Or do we merely want to make it easy for its most complete and widely used
implementation to add the benefits of such modularity?

Do these benefits only really apply to the legal use case, or are they
potentially much more general?

How do we imagine this unfolding over next five years vis-à-vis style
content?

How will it intersect with things like repositories?

My initial answer to first question is no, and that maybe this feature
should not be core to CSL, but an extension attribute. But this would also
have downsides, and opens up further questions (like, what’s our long term
strategy on CSL evolution, extensions, etc.?).

I’ll step aside here, as I have a clear interest that is well known.
These will be questions for the rest of the group to settle.

Frank

(If there are any questions about what will happen in MLZ and CSL-m,
just give a shout.)

22

Thanks Frank.

I wonder if email is best medium for these more wide-ranging and
complicated topics?

23

The main benefit of such modularity would be that it could help with
style development and maintenance, right? (e.g. by providing a library
of common macros)

I was curious to see how many duplicate macros there are currently
across the official styles, so I wrote a quick script to check for
macros that have an identical structure. This is just a quick hack, so
apologies in advance if there are any errors!

In total there are only 44 duplicate macros, so this list does not seem
to indicate very high demand for macro-reuse across style boundaries.

Like I said, it’s just a quick hack, so please let me know if you spot
any errors!

Sylvester

signature.asc (181 Bytes)

24

Hi,On 27 February 2015 at 16:22, Sylvester Keil <@Sylvester_Keil> wrote:

On Fri, 2015-02-27 at 05:14 -0500, Bruce D’Arcus wrote:

I still think we need to start with first principles: do we really
want to make CSL “modular”?

Or do we merely want to make it easy for its most complete and widely
used implementation to add the benefits of such modularity?

The main benefit of such modularity would be that it could help with
style development and maintenance, right? (e.g. by providing a library
of common macros)

I was curious to see how many duplicate macros there are currently
across the official styles, so I wrote a quick script to check for
macros that have an identical structure. This is just a quick hack, so
apologies in advance if there are any errors!

Duplicate CSL Macros · GitHub

In total there are only 44 duplicate macros, so this list does not seem
to indicate very high demand for macro-reuse across style boundaries.

44 is fewer than I expected, but another question and harder to ask
is… how many should be? :slight_smile:
(I’d expect that there are many “almost duplicates”, some maybe on
purpose and some “almost duplicates” that should be duplicates?).

25

sorry, don’t have time to look at the script right now, but that’s not
right. E.g. it doesn’t show any chicago manual styles, although all note
versions of them are largely identical (I maintain them with a diff viewer,
so I’m sure about that). Same for APA and several other styles that are
near copies.

26

Yes, that’s right. But there’s a difference between (I’m not sure what to
call them) back end vs runtime modularity.

It just seems to me if we want to embrace the latter, we probably have a
lot more thinking to do. Frank’s mechanism makes certain assumptions about
how he loads modules, for example, that I’m not sure we’d want to
generalize.

27

One critical point in Bruce’s question is to consider the user’s perspective, not just the CSL contributors, editors, implementors and clients.

I think what matters the most for all of us is that the user of CSL can format their manuscript with a minimal amount of fuss and time. To be honest, in my case, I’d go as far as to say they should not even know what CSL is. Typically, they are busy just formatting their damn f*** manuscript, and they want to submit asap, and not have to deal with the internals of their tools.

So I’ll talk about the module idea from the perspective of an end user.

From a user’s perspective, styles can come in 2 flavors:

  1. it’s integrated into their bibliography tool (Papers, Zotero, Mendeley, etc.) and they just pick the style
  2. a style is a file they receive from a colleague, a journal, from support, downloaded from the web

In case 1, modularity does not really matter, as long as the client app is not buggy and maintains a consistent repository with all the moving part.

In case 2, modularity can be an issue. The style would have to be packaged with all its dependencies, which means someone somewhere has to deal with the modularity.

Note that the above discussion also applies to dependent styles already today.

I don’t have an answer at this point. What I am leaning towards is a model where modularity is handled high up in the chain at the repository level, by the CSL contributors and editors. Styles could come in 2 flavors: with dependencies exposed (more flexible, but more brittle), and already pre-compiled (monolithic and solid). The transition between the 2 could mean 2 repositories, with one created from the other. The clients could decide to use one or the other. The implementors would have to write code that handles both types (the monolithic simply being a subtype of the more flexible one).

These are really my immediate thoughts without much more reflexion beyond the above. But I think the points about the user’s perspectives are critical and should guide everything else: whatever happens, CSL should stay easy to use and its internals transparent to the end user.

Charles

28

Sebastian, thanks for the sanity check – those numbers were a bit
off :slight_smile:

I updated the gist and now it looks like 1,590 out of 13,649 macros are
exact duplicates.

signature.asc (181 Bytes)

29

(I’ll just note that dynamic linking is a completely separate topic
from the style modularity requirement that prompted this thread.)

30

Sebastian, thanks for the sanity check – those numbers were a bit
off :slight_smile:

I updated the gist and now it looks like 1,590 out of 13,649 macros are
exact duplicates.

Sorry, this means there are 1,590 sets of duplicate macros; in total
these are 9,531 macros.

So in other words we currently have 13,649 macros across all styles, but
only 5,708 of them are unique.

signature.asc (181 Bytes)

31

Sebastian, thanks for the sanity check – those numbers were a bit
off :slight_smile:

I updated the gist and now it looks like 1,590 out of 13,649 macros are
exact duplicates.

Sorry, this means there are 1,590 sets of duplicate macros; in total
these are 9,531 macros.

So in other words we currently have 13,649 macros across all styles, but
only 5,708 of them are unique.

So for a developer to train up to work fluidly with a dynamically
linked library of named macros, you would be looking at the rough
equivalent of mastering kyouiku kanji:

http://en.wikipedia.org/wiki/Ky%C5%8Diku_kanji

That’s a four-year learning curve for a quick study.

32
  • As @Carles Pina, I guess there are much more macros that render the same
    or nearly the same (e.g. see
    https://github.com/citation-style-language/styles/issues/1301#issuecomment-68300855
    ).
  • I don’t think a CSL developer has to learn all 1,6 K macros by hard.
    Actually, I would state the opposite, it should be possible to write a CSL
    style without knowing any previously entered macro.
  • Currently, every unique CSL style contains 1,3 new macros
    (1,3=1590/1174). And? What are the numbers tell us?
  • @Charles Parnot: I like your ideas and I think we definitely should think
    also about distribution and update mechanisms for styles.2015-02-27 23:57 GMT+01:00 Frank Bennett <@Frank_Bennett>:
33

@Aurimas: We could adapt this idea in an attribute of cs:group where we
already have an implicit rendering condition: “cs:group implicitly acts as
a conditional: cs:group and its child elements are suppressed if a) at
least one rendering element in cs:group calls a variable (either directly
or via a macro), and b) all variables that are called are empty.” (from the
CSL specification).

Maybe, something like
=


2015-02-28 9:57 GMT+01:00 Philipp Zumstein <@Philipp_Zumstein>:

34

@Aurimas: We could adapt this idea in an attribute of cs:group where we
already have an implicit rendering condition: “cs:group implicitly acts as a
conditional: cs:group and its child elements are suppressed if a) at least
one rendering element in cs:group calls a variable (either directly or via a
macro), and b) all variables that are called are empty.” (from the CSL
specification).

Maybe, something like
=


The thread now appears to be about dynamic linking from a standard
macro library. I don’t think output testing is necessary in that
context: since you already know what the components are in the macros
that are called, you can just test for its preconditions directly.

35

The move toward groups and delimiters is a good thing.

  • I don’t think a CSL developer has to learn all 1,6 K macros by hard.
    Actually, I would state the opposite, it should be possible to write a CSL
    style without knowing any previously entered macro.
  • Currently, every unique CSL style contains 1,3 new macros (1,3=1590/1174).
    And? What are the numbers tell us?
  • @Charles Parnot: I like your ideas and I think we definitely should think
    also about distribution and update mechanisms for styles.

If there were a standard macro library that processors and
applications were required to ship, you would need one of two things -
either (a) a comprehensive style-level test suite, to be sure that
changes to a macro for one style do not have bad effects on others
that depend on it; or (b) make the standard macros immutable. Of the
two choices, probably (b) is the only feasible option.

If you have a standard set of macros that never change, an author’s
tool for quick clipboard copy-paste would have the same benefits as a
standard macro library, without the complexity and risk of completely
re-engineering the CSL distribution chain.

36

The example in your first post could be written as

37

The example in your first post could be written as

If the plan were to add a new, general class of conditionals that test
macros for output, this would be the syntax to go with; but I don’t
think CSL needs that, and I haven’t meant to propose it. Given the
narrow requirement (to test for output from a small black-box macro),
and the lack of any more general need (at least I can’t think of one),
a single attribute seems a simple solution: it is easy to implement,
and it does not add significant syntax to CSL. Minimal is good in this
case, I think.

The one thing that a cs:group-based syntax would add is the ability to
apply outer styles (affixes, etc) independently to each of the child
elements. I don’t think that is needed for the narrow use case this is
attempting to address.

Bruce has raised the larger question of whether CSL should concern
itself with any sort of modularity. I’m firm that basic office-quality
support for legal materials is impossible to achieve without
content-driven dynamic loading of modular jurisdiction-specific
styles. If there is a possibility of getting an extension mechanism in
place, and of placing validated legal styles in the CSL repository,
that will be a very good thing. If that possibility is foreclosed,
there will have to be a permanent fork: what I am trying to accomplish
in legal circles can’t be done without this.

38

…

Bruce has raised the larger question of whether CSL should concern
itself with any sort of modularity. I’m firm that basic office-quality
support for legal materials is impossible to achieve without
content-driven dynamic loading of modular jurisdiction-specific
styles. If there is a possibility of getting an extension mechanism in
place, and of placing validated legal styles in the CSL repository,
that will be a very good thing. If that possibility is foreclosed,
there will have to be a permanent fork: what I am trying to accomplish
in legal circles can’t be done without this.

To be clear, I think if you need this requirement addressed, we should
support it.

My question is more how.

So let’s say we have two options: a) add the attribute as Frank
proposes to the CSL schema and specification, b) add the ability to
add arbitrary non-CSL attributes to CSL elements (e.g. extension).

In each case, what would the specific proposed schema and (in
particular) spec changes be?

For b, I would say:

SpecOn Sat, Feb 28, 2015 at 5:43 AM, Frank Bennett <@Frank_Bennett> wrote:

CSL allows arbitrary extension attributes with names prefixed with
“extension-” (for example, “extension-random”). Processors may ignore
these attributes.

Schema

extension-attribute = attribute extension-* { text } [not sure this is
legal; if not, need to reassess; alternative is to use foreign
namespaces]

[not sure; key question is where the pattern gets allowed]

What about for option a?

Bruce

39

…

Bruce has raised the larger question of whether CSL should concern
itself with any sort of modularity. I’m firm that basic office-quality
support for legal materials is impossible to achieve without
content-driven dynamic loading of modular jurisdiction-specific
styles. If there is a possibility of getting an extension mechanism in
place, and of placing validated legal styles in the CSL repository,
that will be a very good thing. If that possibility is foreclosed,
there will have to be a permanent fork: what I am trying to accomplish
in legal circles can’t be done without this.

To be clear, I think if you need this requirement addressed, we should
support it.

My question is more how.

If an extension mechanism is possible, that would be great.

40

@Charles, it would e.g. be relatively simple to convert all our
dependent styles to independent styles when we transfer them to
https://github.com/citation-style-language/styles-distribution. That
would free the CSL software products from having to look up the parent
styles, but it would complicate contributions to the CSL style
repository, since users would start to modify and submit changes to
those monolithic, formerly dependent styles.

@Bruce, Frank, is there really a need for a general extension
mechanism? I think it would be of limited use if it only covers XML
attributes. And wouldn’t an uncontrolled extension mechanism encourage
forking of CSL? How would we deal with arbitrary style extensions that
are submitted to the style repository? I would also like to stress
that CSL can already be extended through an extension schema, as we
did for Frank’s CSL-m fork
(https://github.com/fbennett/schema/blob/master/csl-mlz.rnc), although
that of course breaks compatibility with the regular CSL schema.

Rintze