Editorial Commands - Githubissues

This thread is for discussing the specific goals related to the functions for showing editorial decisions in scores.

To continue the thoughts listed on the wiki page, this means these should be classified into general edition types, such as..

addition (items that were missing previously)
emendation (alteration to pitch, text, key, phrase marks, etc.)
subtraction / deletion / removal?
I also suggest - inquiry, or question, or something along those lines (e.g. I suggest we remove this slur - should we?)
(more) ?

These classes might affect similar items differently (addition of a slur appears dashed, while altered slurs appear dotted, while inquiry about a slur appears with wider dashes). Those differences should be easily defined by the user (and perhaps there should be default stylesheet?).

If these are to be usable standalone, then I suggest the functionality be optionally triggered by each annotation (but not mandatorily), since this ultimately will affect the appearance of the score - and there may be some additions that are worth noting, but not necessarily needed (or desired) to be reflected in the notation by the author.

The suggestion to define classes of commands is a good one. Although I'm not sure if it is actually referring to classes of commands because - in my understanding - I would have thought one command for the use cases should be sufficient. Please give a few examples where you can think of multiple commands belonging to one class.

addition and emendation are clear, and it's the proper name.

With subtraction / deletion / removal I vote for deletion as the term that sounds best to my ears. But I'm not a native speaker, and one should confirm that with a native speaker explicitly experienced with critical editions (I will send around a few emails for this). If I pass the term used in German ("Tilgung") to a dictionary there are two English translations that seem to make sense to me: deletion and expunction. However, there are two different cases and we have to think about whether we have to deal with that explicitly or not: a deletion can refer a) to something that has been deleted in the source (typically an erasure) or b) to something that was in the source and has been removed by the editor. My guess is that we should initially provide a command for b) and can put a) somewhere in the queue. Visually indicating that something has been deleted in the source is usually only done in diplomatic editing, for example of sketches. There the deletion may be marked by strike-through or similar means.

My first though was that inquiry isn't necessary because it's only what \musicalIssue does (and should only be indicated by coloring the object). But of course: if the editorial commands are to be usable standalone then we should have the equivalent of \musicalIssue as an editorial command. Then again, I'm not so sure about that. Using such an inquiry (or the equivalent to \lilypondIssue where this would apply equally) without the real annotation (i.e. without the corresponding message context) doesn't seem to make much sense to me. If someone really wants to highlight this kind of elements in a score without using the annotations they can easily write a coloring command themselves. But please discuss if you think I'm missing something.

Of course the application of such visual commands from annotations has to be optional. Firstly we don't know if a user actually wants that and second there's no mapping between annotation type and highlighting type.

I suggest having a property that when present triggers the application of the command specified by the property value. For example highlight = emendation or apply = addition. Maybe it will be necessary to provide means of configuring individual commands through additional properties.

There's another aspect we should consider now: how to deal with a draft mode.

I think differently from the LaTeX package the LilyPond draft mode must not affect the layout and should exclusively work through coloring, and basically that's in place already. So basically there are two issues to be discussed:

Naming: I think it would make sense to copy the LaTeX naming scheme of final/draft with final being the implicit default. However, earlier discussions on the LilyPond mailing list seem to have raised reservations about the term draft, and I would like to re-open that discussion so we can safely assume that our stuff will be welcomed by the LilyPond community. This discussion should include the LilyPond community, and so I suggest you open it by writing to the lilypond-user list.

Handling in context: This is especially important as we should discuss this matter in the context of openLilyLib in general. Basically there should be a draft (or whatever) mode that can be switched on/off on the openLilyLib level so any package can respond individually to that. In addition our package should provide the option to override the general setting, similar to what \finalfordraft does.

The coloring and its configuration itself is already working so you won't have to implement that, but of course you're free to modify things.

Please give a few examples where you can think of multiple commands belonging to one class.

I would think that a "critical remark" could be concerned with the addition of something, just as well as another critical remark could be concerned with the deletion of something. A musical issue could add something, or it could delete something. Right? Maybe this is presumptuous, but I would think it prudent to at least consider a flexible functionality that would allow the user to decide for themselves.

Perhaps, since that would be a more advanced part of this feature, we could keep that possibility in mind, and for the time-being have rigid associations between annotation type and class (which will later be the default associations, which the user can (eventually) easily override).

inquiry isn't necessary because it's only what \musicalIssue does (and should only be indicated by coloring the object)

Okay, I agree about leaving out inquiry then, since it wouldn't make sense to reflect that inside the actual score outside of frescobaldi.

there's no mapping between annotation type and highlighting type

Can you clarify what exactly that means? I thought that was what \registerOption scholarly.annotate.colors does.

For example highlight = emendation or apply = addition.

So this, if I understand, will mean that by default nothing is highlighted? I think apply=addition syntax makes sense.

I'll start a discussion on the lilypond user list about the "draft"/final naming scheme for that context.

Handling in context: ...

So - we want to be able to set openLilyLib in draft mode (or implicitly final), which then toggles all child packages, such as scholarLY, along with it; and those packages can themselves use a command like to finalfordraft to keep their final mode functionality in place. Is that correct?

Please give a few examples where you can think of multiple commands belonging to one class.

I would think that a "critical remark" could be concerned with the addition of something, just as well as another critical remark could be concerned with the deletion of something. A musical issue could add something, or it could delete something. Right?

OK, now I see what you mean, and actually it's probably more or less the same that I introduced as an independent issue #23 (having forgotten about this current issue ...).

I think that what you refer to as classes of annotation types should rather be properties of the annotation. An example of such a property could be “deletion“ as you suggest. And “deletion” can be a property of a musical issue as well as of a critical remark.

But I'm struggling with the question if we have to differentiate between types the denote what the annotation refers to and what it does. Let's stick to “deletion” to clarify this:

An annotation may for example refer to something that has been deleted in the source, for example by striking through it or an erasure. But an annotation can also refer to something that the edition deletes from the source, for example “remove redundant accidental”. These are indeed two different perspectives, but I'm not completely sure if it needs two independent properties. And the second may even interfere with the question of the choice of editorial commands.

I will start a discussion about this on lilypond-user.

there's no mapping between annotation type and highlighting type

Can you clarify what exactly that means? I thought that was what \registerOption scholarly.annotate.colors does.

“highlighting” is ambiguous here, sorry. What I mean is: An annotation can trigger different sorts of highlighting, described either in terms of dashed / parenthesized / smaller or (by function) added / modified / deleted. But the choice of this highlighting does not correlate to whether we have a musicalIssue, criticalRemark or whatever. The question of coloring the output and choosing the colors according to annotation type is yet another issue.

So I think (hope) we should be able to summarize the following:

Annotation type (1):

What kind of issue do we have, e.g. musical questions vs. tasks vs. critical remarks
This is expressed through the choice of LilyPond command (\criticalRemark)

Annotation category:

What type of facts in the sources does the annotation refer to (examples: “pitch”, “rhythm”, ”paper”, ”watermark”, ”erasure”)
This should be expressed through a new annotation property, e.g. “category”
There should be a list of preset categories, but project can extend the list through openLilyLib's option interface.

Annotation type (2):

What type of editorial decision/action does the annotation refer to? Examples: “emendation”, ”addition”, “deletion”
I'm not sure what a proper name for that could be (to discern from type (1))
I'm not sure how that should be expressed in the annotation. Maybe through another property? Maybe through an apply property that would at the same time trigger editorial commands that apply highlighting (for example dashing for added items)

So - we want to be able to set openLilyLib in draft mode (or implicitly final), which then toggles all child packages, such as scholarLY, along with it; and those packages can themselves use a command like to finalfordraft to keep their final mode functionality in place. Is that correct?

Yes. Maybe for completeness put the other way round: there should be a global draft/final option for openLilyLib. Packages are encouraged to respond to that option, usually by applying coloring for draft mode (but other actions are possible as well). And packages should have the option to ignore/override the global setting. So when compiling in final mode the user may still want to see ScholarLY's color highlightings.

Ah, okay I think "type" is an appropriate word in both cases.

Perhaps simply updating our phrasing to "annotation type" and "edition type" - the former describing the general angle of attention to whatever issue (critical remark, or a question, etc.), and the latter describing the application type (if any) by the editor/annotation.

If later (or soon, I guess) the desire to be able to toggle some applications (e.g. dashed slur) for annotations, but to also be able to hard-apply (whereby regardless of toggling on/off applications, the hard-applied edition would always remain), we could add an option to hard-apply = addition (or whatever).

Since I think at some point (maybe in another thread) it was mentioned that "addition", for example, could not necessarily mean that we are even applying an addition, but rather observing one that was made (and therefore that wouldn't be something we necessarily want to "apply"), we could consider a third type: observation type, or similar. In context, here is the distinction I am making, which is not yet addressed:

\criticalRemark % annotation type
    \with {
        message = "This slur was added later by the composer."
        observation = addition % observation type
}

\musicalIssue % annotation type
    \with {
        message = "I am adding a slur."
        apply = addition % edition type
}

And to be completely clear, this is not mistaken with your meaning of "category". That could be a separate property, as you had suggested; in the above cases, that would mean additionally category = slur or category = phrasing or whatever.

The issue of modes I think should be distinguished as a separate issue, since that is an effect that ultimately will wrap this one, and not the other way around.

Observation types would be another way of filtering/sorting annotations as well, similar to priorities, and of course author, location, etc.

And also, rather than apply = ... for edition type, we could go with edition = ....

openlilylib / scholarly

Editorial Commands #22

This thread is for discussing the specific goals related to the functions for showing editorial decisions in scores.

Annotation type (1):

Annotation category:

Annotation type (2):