Re: Discuss signature for new function \annotate (new version)

[Urs Liska]

Am 10.06.2013 18:52, schrieb David Kastrup:
> Richard Shann <address@hidden> writes:
>
> > This looks great Urs. I wrote a CriticalComment command for Denemo
> > that allows you to attach comments to notes in a score. These comments
> > can include \score {} blocks so that the music being commented on can
> > be engraved within the sentence.
> Sounds like issue 3187
> <URL:http://code.google.com/p/lilypond/issues/detail?id=3187> committed
> to version 2.17.14 would have a very relevant impact on that feature.
> I'm interested in your opinion on that.
I think we should clarify if we are talking about the same thing.
If we're not (which I assume) we should
a) try to convince each other that our own approach is better,
b) try to find a way to harmonize and complement the approaches or
c) accept that we have different things at hand.

Definitely my favourite is b) of course.

_My_ idea is/was to have a function \annotate that lets you enter 
annotations.
These should go
a) to the console output so anybody compiling the file can see the 
annotations
b) to an intermediate file to be used later
- as an overview (with backlinking to the source code)
- in separate (text) documents
c) (optionally) color the items in the score and (maybe) enter things 
like balloon tips in the score

I did _not_ think of entering the annotations as markup anywhere in the 
score.
Of course all this is heavily based on my own interests and working styles.
For example I wouldn't usually typeset a critical report within the 
LilyPond score, just because they usually are too voluminous.

Programs like Denemo, laborejo or Frescobaldi can make use of such a 
function by providing tools to insert and edit entries. So of course it 
would be good to design a function in a way that it is useful for these 
programs.

That said:
Having a feature to enter a list of annotations at any point in the 
score would be a good thing to have.
I identified your CriticalComment... commands in the manual.
But from looking at the source tree I can't tell anything. Would be too 
complicated for now to start trying to understand that. So please allow 
me the question:
How do your critical comments work? Do they write something down that 
CriticalCommentary reads in or do you just fill some variables array 
that CriticalCommentary uses?

If I see the situation correctly the best way to integrate would be:
- having the \annotate function like I sketched it, and modify it so it 
can handle the information you give to critical comments
- have a function \annotations that can be entered as a top-level 
command that will be turned into a \markup.
This function should have an argument that filters the list by its type 
(e.g. only "critical-remarks") and also takes the Intro as an argument.

Where do you define CriticalCommentary in your source code? I'd like to 
have a look at it.
Maybe it would make sense to move these functions to an external library 
(i.e. my lilypond-doc) so Denemo and any other tools can just _use_ it...

Best
Urs