Re: \pushToTag and \appendToTag examples

[David Kastrup]

Gianmaria Lari <gianmarialari@gmail.com> writes:

>>
>> > Nota bene: I didn't yet add any examples that take advantage of David new
>> > possibilities:
>>
>> Ah, but that was sort of the point.
>>
>
> Sure, I'm sorry :(
> I'll help with that too when I will be able to access this new feature.
>
>> P.S. I would have liked to add a screenshot of the generated output
>> > immediately after each piece of code.
>> > This would make this much more interesting, easy to follow and discuss.
>> But
>> > I remember that on this mailing list pictures have to be attached and not
>> > put inside the mail.
>>
>> I use inline MIME attachments and there are few complaints, but some
>> mail clients do some sort of HTML contraption not working in text mode
>> and those will not make it through a lot of mail clients or mailing list
>> summarisers.
>>
>
> I guessed what the problem was and I hope it will change in the following
> years so that we will be able to write clearer posts.
> For me, reading (and writing) an email with pictures attached is like
> reading a book with numbered photographs placed at the end of the
> book.

"inline attachments" appear where you place them in the text if your
mail reader is not overly weird.  Like this:

> But I know that this is an old argument on which many of us are
> hypersensitive. My apologies.
>
>> %%%%%%%%%%%%%%%%%%%%%%%
>> > \markup {"Simple \appendToTag with {}"}
>> > \version "2.23.2"
>> > music = {c'1 \tag #'here {} c''1}
>> > {\music}
>> > {\appendToTag #'here g'1 \music}
>> > {\pushToTag   #'here g'1 \music}
>>
>> Tagging an empty {} and pushing a single element means that there is no
>> visible difference between \appendToTag and \pushToTag .
>>
>
> David, this was the point of the example!

Doesn't really help decision-making, does it?

> You read this short code, you see the output, you think about these
> two things and because of the simplicity of the example you understand
> how it works *without* reading long explanations.

How can you understand what the respective commands do when there isn't
even a difference in the result?

>> > {\appendToTag #'here {e'4 f' g' a'} \music}
>> > {\pushToTag   #'here {e'4 f' g' a'} \music}
>>
>> Same here, and the example is more complex than necessary for bringing
>> the point across.
>>
>
> I'm sorry I am of exactly the opposite opinion!
> In the previous example you see the simplest possible \pushToTag and
> \appendToTag example. It adds a single note.
> And now you see an example just a bit more complex with a compound musical
> expression.

It does nothing different from the first example and it still does not
distinguish between \appendToTag and \pushToTag .  While regtests do not
suffer from redundance all too much, it does not help.  But the manual
already is far too long, so one has to make as little material as
possible count.

>> This at least shows a difference between \appendToTag and \pushToTag
>>
>
> Yes, but this in my opinion makes sense only *after* you saw and you
> understood the other examples.

I don't really think so.  There are two differences involved:

a) pushing/appending to a non-empty target leads to different results
b) the commands may be done several times for successive changes

b) may warrant a separate example (it doesn't have one in the current
version of the docs).  I don't see a gain for a).  When one also
documents pushing of articulations, it is sort of a natural example to
push to a note/chord that has no articulations yet.  So then it would
make some sense to illustrate pushing to an empty list (which is less
explicit with articulations and thus more important to illustrate)
there.

> And you compare it with the previous example.
>
>> \markup {"\appendToTag with {} and multiple different tag"}
>> > \version "2.23.2"
>> > music = {c'4 d' e' f' \tag #'firstLocation {}
>> >          g' a' b' c'' \tag #'secondLocation {} }
>> > {\music}
>> > {\appendToTag #'secondLocation {d''2 e''} \appendToTag #'firstLocation
>> {g'4
>> > f' g' f'} \music}
>> >
>> > \markup {"\appendToTag with {} and multiple equal tag"}
>> > \version "2.23.2"
>> > music = {c'4 d' e' f' \tag #'firstLocation {}
>> >          g' a' b' c'' \tag #'firstLocation {}
>> >          b' a' g' f'  \tag #'firstLocation {} }
>> > {\music}
>> > {\appendToTag #'firstLocation {g'2 r} \music}
>>
>> This just makes the example more complicated without demonstrating any
>> additional functionality or use.  Makes it hard to interpret either
>> manual entry or regtest.
>>
>
> This shows something different and that in my opinion you should know and
> it was not visible in the previous examples.

The "multiple different tag" part is an example more complicated without
demonstrating any additional functionality or use.  The "multiple equal
tag" part indeed shows something different.  I did not pick this apart
carefully enough.

> If you read it after the previous example you should very easily
> understand it and put it aside for when you will need it.

The notation reference is not a tutorial.  It isn't really supposed to
form a set of lessons in increasing order of difficulty.  In that
respect, it's reminiscent of the message in that Voltaire quote of "I
apologise for writing such a long letter but I didn't have the time for
writing a shorter one".

> Playing with lilypond I personally needed a way to indicate a location
> inside a musical expression where I could add some musical material. I have
> absolutely no idea if others have the same need or not. But if you have
> this specific need then I think the following is extra clear:
>
> music = {c'1 \tag #'here {} c''1}
>
>
> the "{}" indicate the location.
>
> When you start making something like this:
>
>   music = {c'1 \tag #'here {d'2 e'} c''1}
>
>
> you're mixing things and making them more complex. And to *me* is not clear
> why I should use/explain this.

That's the point of an example pushing/appending two items to an empty
expressions.  It shows a difference, but it also shows starting with an
empty point.

> Actually the comment at the beginning of the example saying "I don't see
> any good reason etc." was to start a discussion about something that
> probably I didn't understand well and NOT to suggest to not use it.
>
>
>> > % {\appendToTag #'here <e' g' b'>1 \music} % Doesn't work. Adding a chord
>> > to a chord is not defined/allowed
>>
>> Should it, though?  Should there be something else for achieving that
>> effect?  If so, what interface?
>>
>
> Ahem. This code for me doesn't make sense. And I have no idea how we could
> interpret it so that it could be meaningful.

Sure.  This was not a critique.  It was a question of whether there
should also be something for _this_ purpose/functionality, possibly with
a different command.  It's not really relevant to this
discussion/doc/regtest, just something that might warrant keeping an eye
out for.

>> % {\appendToTag #'here {e'1 g'1 b'1} \music} % Doesn't work. Adding a
>> > compound music expression to a  chord not defined/allowed
>>
>> I have no problem with _that_ not being allowed.
>>
>
> Same for me :) And same as my previous comment.
>
>
>> \markup {"\appendToTag with <c' e'>"}
>> > \version "2.23.2"
>> > music = {c'1 \tag #'here <c' e'>1 c''1}
>> > {\music}
>> > {\appendToTag #'here g'1 \appendToTag #'here b'1 \music}
>> > % {\appendToTag #'here g'4 \music} % Doesn't work. Adding a 4 duration
>> note
>> > to a 1 duration chord is not defined/allowed
>>
>> In my book, there is no big point served in trying to prohibit it, and[...]
>>
>
> I have no clear idea about it and I didn't consider it very important. I
> mentioned it because during my "playing" activity with lilypond I tried it.
>
> By the way, I didn't mentioned it but I made some "test" also with
>
> {c'1 \tag #'here <<>> c''1}
>
>
> Maybe I will write about them in the future :)
>
> Do you see why I hate writing documentation and regtests?
>>
>
> In my humble opinion I see why you should not write documentation.

Well, the documentation for a feature has to start somewhere so I cannot
avoid it.  But it might be more productive to discuss documentation
writing with people like James and Trevor who are more experienced in
producing and maintaining user-level documentation.

> But I'm extremely fallible and this is my (actual) opinion.  I also
> think you have some nice communication problems (that I know and I
> like). I have (many) communication problems too.  I guess, but it's
> only a guess, you write very good regtests even if you don't like to
> write them.
>
> Ciao,
> Gianmaria
>
> P.S. This is the only example of \pushToTag and \endToTag I found in the
> documentation.
>
> test = { \tag #'here { \tag #'here <<c''>> } }
> {
>   \pushToTag #'here c'
>   \pushToTag #'here e'
>   \pushToTag #'here g' \test
>   \appendToTag #'here c'
>   \appendToTag #'here e'
>   \appendToTag #'here g' \test
> }
>
> In my opinion this is a fantastic zen exercise. You read it, you
> appreciate the esthetic aspects (output also!), and you can meditate
> on it.  But I think it is also very well done to make people (people
> like me, of course) don't understand how \pushToTag and \appendToTag
> work.  It is possible that I have already moaned about this, sorry.

Well, the whole point of this thread is that I am not satisfied with
what I wrote there, and it doesn't extend to the new functionality in a
sane manner either.  That example makes some sense for a regtest since
it checks a significant amount of stuff with a reasonably small amount
of code.

It does not really have much of a place in user-level documentation
except as a very clear indication that someone was too lazy or
uncreative to actually write useful documentation yet.

It more or less indicates the place where someone™ should put something
more useful at some point of time.

-- 
David Kastrup