Sorting out annotation interface questions (GSoC)

[Urs Liska]

Hi all,

our GSoC student Jeffery has done quite some work on writing a
comprehensive LaTeX package to typeset annotations produced from a
LilyPond document. I assume he'll soon wrap it up to merge something
like a V1.0, but we've started turning to work on the LilyPond side of
things already, enhancing the existing state of the ScholarLY package
(https://github.com/openlilylib/scholarly).

Right now we're discussing a few things on the interface for defining
annotations, and I suggested to extend this discussion to the
lilypond-user list.

Right now we have a number of annotation *types*, expressed through the
commands \musicalIssue, \criticalRemark, \lilypondIssue, \question and
\todo. They are used as (e.g.)

\criticalRemark \with {
  author = "Urs Liska"
  context = "Piano, r.h."
  message = "Incredibly sophisticated observation"
  my-arbitrary-prop = "User can use custom properties"
} Slur c ( d )

Annotations (can) *refer* to a type of fact in the sources, for example:
“pitch”, “rhythm”, ”paper”, ”watermark”, ”erasure”.
I think it's natural to express this as an additional property (e.g.)
"category":

\musicalIssue \with {
  author = "Urs Liska"
  context = "lyrics"
  message = "Should ß be changed to ss here?"
  category = lyrics-modernization
} LyricText
Fluß

(Instead of a symbol this can also accept a symbol list for multiple
categories.)
Maybe that's better called "tags"?

Finally annotations can refer to the type of editorial action/decision
it does. At least for musical issues and critical remarks. The
annotation can refer to an editorial addition, deletion or emendation.
Here it is currently not clear whether this would warrant a separate
property or if it can be understood as a kind of subset of the tags
discussed before. But it should be considered in the context of another
issue:

Annotations can trigger (to-be-implemented) "editorial functions" that
apply visible highlighting, for example produce dashing for slurs that
have been added by the editor. This could be expressed by a property
*apply*:

\musicalIssue \with {
  author = "Urs Liska"
  context = "violin 1"
  message = "Slur obviously forgotten in original edition"
  apply = addition
} Slur

My question is: is this "application" the same as the type of annotation
action from the previous issue? Or could it occur that a project wants
to document types of editorial decisions independently from applying
visual indications of that?

Any feedback appreciated
Urs