Re: Advice on naming and structuring scholarLY commands

[Urs Liska]

Well, it seems my post was too extensive (and at the same time not controversial enough) to trigger serious discussion (or any feedback at all) - so basically I've made most decisions myself and with some private feedback. What I would still like to discuss are two function names.

What I'm doing right now is implementing a function to mark up music as a "finding" or decision. This will be one generic command that is specified by a mandatory <type> argument. Currently the command is named \edit, but I'm really doubting this is the best word for it - both semantically and with regard to possible clashes with existing libraries or future LilyPond keywords. To show what I mean I give a few examples:

\edit sic { c \ff }
\edit abbr { \repeat tremolo 16 c32 }
\edit rgd \with { source = w9tn-a item = Accidental } { cis }

Every edit type can be given a highlighting function, which by default causes the music to be colored with a color corresponding to the edit type.
If an ann-type attribute (plus a few more mandatory arguments) is present an edit will implicitly create an annotation with all the features already present in the scholarly.annotate module. While I will keep the annotations code as it is and will only print a deprecation message I think this is a much better approach because in most cases an annotation refers to such a "finding", and with this approach we cannot only mark up single grobs but the whole music _expression_.

So, is \edit the appropriate function name here?
This function is used to mark up editorial decisions or findings from the source.

###

The \edit commands don't only work as standalone markup but can be enclosed in a choice element to encode alternative versions of a music. The basic syntax is the same, with a generic command name, a mandatory <type> argument and an optional \with {} block for further specification of the construct. Here I'm more or less settled on \variants but wanted to give the list the opportunity to object. An alternative would be \choice, which corresponds to the MEI element name, <choice>.
A \variants _expression_ includes an arbitrary number (usually 2) of \edit-s and will only produce one of them, depening on configuration. Additionally there will be rather sophisticated support for generating annotations, with the idea of mergin annotations on the \variants and on the \edit level (so there can be one annotation with some variable content depending on which \edit is selected). This will look like this:

\variants emendation \with {
  ann-type = critical-remark
  author = UL
  cert = certain
  item = Accidental
} {
  \edit sic \with {
    message = "Missing \\sharp. Cf. violin 2."
    footnote-offset = #'(1 . -2)
  } { g8 }
  \edit corr \with {
    message = "\\sharp supplied as per violin 2."
  }
}

This will do a number of things:
- choose one out of the two supplied music expressions
- create a critical remark annotation with the message taken from the selected variant
- create a footnote when the 'sic variant is chosen
- if present the corresponding highlighting function is invoked
- alternatively the music will be simply colored



To cut the long story short: basically I'd like to get the encouragment to use \edit and \variants, or suggestions for better names.
Thanks
Urs

Am 11.06.2018 um 11:14 schrieb Urs Liska:

Hi all,

I've started some serious work on the scholarLY package (https://github.com/openlilylib/scholarly) and will presumably have a bunch of questions over the next few weeks, both on design/interface, and implementation.

[For all users of scholarLY: I also expect that this *may* end up in breaking changes. I hope to avoid that but it's possible that substantial enhancements can't be accommodated with the existing interface.]

One thing I'm going to add is the ability to encode variants of various kinds (some examples: readings of different sources; original text vs. regularized/corrected/edited text; substitutions/deletions (i.e. the writer of the source edited the text)). The model for this are the respective sections of the MEI specification (http://music-encoding.org/guidelines/v3/content/critapp.html, http://music-encoding.org/guidelines/v3/content/edittrans.html), although I have come to the conclusion that it's not worth implementing it as an exact match.

As a first step I've identified the overall structure this should get:

• There are unary commands to mark up a music _expression_ as an editorial element like (MEI:) <sic>/<corr>, <reg>/<orig> etc. These may or may not (at the discretion of the editor) produce some visual highlighting (e.g. printing errors in the source in red).
• There is a choice (or variant) command that can wrap multiple of the unary commands and the editor can decide which ones to engrave (e.g. always the corrected text, always the original etc.)
• (I'm not fully clear yet how that will relate to the existing annotations. Probably it will be possible to use such a choice as the "target" of an annotation *or* include annotation(s) within the alternatives. I'll discuss this a little bit at the end, but this should actually be discussed in a separate thread)

###

My question for today is: both the choice and the unary commands can have a number of types, and I'm not sure if it's better to provide individual commands for each of them or a structure where the type is given as a key. To clarify I'll show the options, first for the choice command:

\choice <choice-type> (<attributes>) {
  <alternative-one>
  <alternative-two>
  ...
}

<choice-type> would be a keyword out of the list of supported choice types (so far [source|abbreviation|correction|regularization|substitution] or reasonable shorthands).

<attributes> is an optional \with {} block where information such as responsibility for the decision or comments can be included.

<alternative...> is a list of music expressions that stand for the alternatives. In the example above this would expect the two being of certain types, but that is handled below with the unary commands.

1)
Is \choice an appropriate name (it's the name used in MEI)? An alternative would be \variant

2)
From the perspective of the user entering the stuff it would be nicer and cleaner to not use \choice <choice-type> but have dedicated commands like \correction \regularization etc. Internally these would be wrappers to a generic command. But I'd like to have some feedback about whether this would be inappropriately "polluting" the namespace (since I'm not doing this for a private project but for a general-purpose library).

###

For the unary commands it's the same question. They could be encoded like

\toBeFoundGenericName sic (<attributes>) { <original-erroneous-content> }
\toBeFoundGenericName unclear (<attributes>) { <dubious-text> }
etc.

or there could be dedicated commands

\sic { c' }
\corr { cis' }

Of course this would be nicer to enter but also clutter the namespace with a dozen or more commands which may even be pretty prone to clashing with either future LilyPond keywords or existing users' functions. If going for the MEI namings that would be:

• \abbr
• \expan
• \cpMark (indications like percent repeats, textual indicators for copied content etc.)
• \sic
• \corr
• \gap
• \unclear
• \reg (regularized text)
• \orig
• \add
• \del
• \restore
• \handShift
  

###

Summarizing I'll give a concrete example in both ways:

{
  \choice correction \with {
    author = UL
    cert = high
    comment = "This is obviously wrong, cf. flute 2"
  } {
    \edit sic { c' } % \edit is a first shot at a generic name
    \edit corr { cis' }
  }
}

{
  \correction \with {
    resp = UL
    cert = high
    comment = "This is obviously wrong, cf. flute 2"
  } {
    \sic { c' }
    \corr { cis' }
  }
}

There are cases where simpler encoding is sufficient too (just to give some more context):

% Just *stating* a correction (can be highlighted visually)
\relative {
  c' d e \corr { fis } | g1
}

% Concise encoding of a variant (the writer of the source has replaced a \p with a \f),
% giving the option to choose which variant is rendered
\relative {
  % would generally be configured in global place:
  \setOption scholarly.variants.render.substitution add
  c' d e \substitution { \del \p \add \f } | g1
}

###

Encoding such variants of course has implications for how annotations are handled, and it will add functionality I have always missed. A "traditional" annotation might look like this:

{
  \criticalRemark \with {
    author = UL
    message = "Original edition erroneously prints c' \\natural"
  } Accidental
  cis'
}

With the encoding of variants this might be extended to:

{
  \criticalRemark \with {
    author = UL
    message = "Original edition erroneously prints c' \\natural"
  } Accidental
  \correction { \sic c' \corr cis' }
}

This would be the easiest integration where \correction (or \choice) simply evaluates to a single music _expression_ that is then annotated. However, it might make more sense to integrate the \choice part in the annotation mechanism, to say e.g.

{
  \criticalRemark \with {
    author = UL
    message = "c' \\natural in OE surely erroneous, cf. flute 2"
    item = Accidental
    choice = \with {
      type = correction
      sic = { c' }
      corr = { cis' }
  } 
}

or the other way round (integrate the annotation feature in the choice, create an annotation when 'annotation-type' is given):

{
  \correction \with {
    annotation-type = critical-remark
    author = UL
    item = Accidental
    message = "c' \\natural in OE surely erroneous, cf. flute 2"
    } {
      \sic { c' }
      \corr { cis' }
    }
  }
} 

To be thought through (but definitely in its own thread) is the issue that annotations currently insert a \once \override, but should actually be able to affect a SequentialMusic _expression_ as well. And of course all these new twists should also still be compatible with elements that have to be \tweak-ed.

I'd be happy about any constructive feedback.
Urs

_______________________________________________
lilypond-user mailing list
address@hidden
https://lists.gnu.org/mailman/listinfo/lilypond-user