Re: \pushToTag and \appendToTag help

[Johan Vromans]

On Fri, 13 Apr 2018 22:25:17 +0200, Gianmaria Lari
 wrote:

> I'm not 100% sure having understood how to use \pushToTag but the
> following are the examples I personally would put in the manual.

I find your examples very enlightening.

___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

Re: \pushToTag and \appendToTag help

[Gianmaria Lari]

On 13 April 2018 at 11:48, David Kastrup  wrote:

> Gianmaria Lari  writes:
>
> > On 13 April 2018 at 10:00, David Kastrup  wrote:
> >
> >> How about pointing out what you find hard to understand in the
> >> documentation then?
> >
> >
> > I'm not a musician and I'm a young lilypond user. So I don't like come
> > here and say that this part of the documentation is not clear even if
> > I would specify that it is not clear *to me*. Report this type of
> > things is difficult without hurt the persons that write the
> > documentation work.
>
> The point of the documentation is not to look pretty.  It is also not to
> explain things to masters of deduction and LilyPond: those will just
> look in the source code of LilyPond for a definite answer.
>
> A lot of pain goes into the documentation _exactly_ so that people have
> a dependable, infinitely patient and replicable resource for learning to
> work with LilyPond without requiring personal assistance.
>
> Pointing to it is for the sake of making people stop asking questions
> and start working with LilyPond.  Not for making people stop asking
> questions and stop working with LilyPond.
>
> One surprisingly hard lesson to learn as a project lead is that "it's
> too hard for me to understand" is perfectly equivalent to "it's too hard
> to understand" when I can consider myself to be part of the core
> audience, whether we are talking about code, comments, or documentation.
>
> There may be better ways to sugarcoat stuff than I manage, but in the
> end it boils down to any material needing to be able to be accessible to
> its core audience.  More often than not, that requires several
> iterations, partly because the people initially writing the
> documentation are too intimate with what they are writing about to
> properly channel their core audience.
>

Sure!!


> If you have to fight tooth and nail for any bit of feedback, that
> doesn't help.


David I agree... in theory. But personally, I found very often difficult to
read the lilypond documentation. Because of that I consider this a personal
idiosyncrasy and I 'tend' to avoid to comment it.


> > And of course, I appreciate who made the effort to write it.
> >
> > Regarding the example in the documentation: here it is.
> >
> > test = { \tag #'here { \tag #'here <> } }
> > {
> >   \pushToTag #'here c'
> >   \pushToTag #'here e'
> >   \pushToTag #'here g' \test
> >   \appendToTag #'here c'
> >   \appendToTag #'here e'
> >   \appendToTag #'here g' \test
> > }
> >
> > I simply don't understand it. I don't understand it because: it is too
> > long, there are too many things, I don't understand the example goal,
> and I
> > don't understand the explication following the code.
>
> It adds material at two points to \test: in the inner parallel music,
> and the outer sequential music.  The first version adds successively g',
> e', and c' at the front of those expression, the second at the end of
> those expressions.
>
> Ok, it is probably trying to show to much at once.  What's the scope
> that you think you could deal with?  Two separate examples for
> sequential and parallel music (probably not a good idea to work on
> multiple tags here)?  Not adding more than a single term?
>

I'm not 100% sure having understood how to use \pushToTag but the following
are the examples I personally would put in the manual.

First example:

\version "2.19.81"
test = { a a  \tag #'here {} a  }
{ \test }
{ \pushToTag #'here c' \test }




Second example:

\version "2.19.81"
test = { a a  \tag #'here <<>> a  }
{ \test }
{ \pushToTag #'here c' \pushToTag #'here e' \pushToTag #'here g' \test }



Third example:

\version "2.19.81"
test = { a a  \tag #'here <> a  }
{ \test }
{ \pushToTag #'here b' \test }


(sorry if I put the image here, but it is more clear)

... and then I would put the example about \appenWithTag (that I didn't
test yet).



> But then my above simple example prompted by you only added a single
> term and you stated that this was not what you considered helpful.
>
> > But I'm sure, this is very probably my specific problem. Of course, I
> > could spend some hours on it and discover how \pushToTag works, but,
> > well, you can't do this for any things like this to discover that you
> > don't need this commands :)
>
> So instead I spend hours on explaining and the documentation stays the
> way it is, so we get that discussion with the next person next time
> round?  I'd rather get the documentation problem solved if I am
> investing that amount of time.


If you really think I can be useful I will be glad to help. Anyway, I took
many very simple example for my personal use. One day I will put them
online so that other can take advantage of it.

Thank you.
g.
___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

Re: \pushToTag and \appendToTag help

[David Kastrup]

Mark Knoop  writes:

> At 11:48 on 13 Apr 2018, David Kastrup wrote:
>>Gianmaria Lari  writes:
>>> I simply don't understand it. I don't understand it because: it is
>>> too long, there are too many things, I don't understand the example
>>> goal, and I don't understand the explication following the code.  
>>
>>It adds material at two points to \test: in the inner parallel music,
>>and the outer sequential music.  The first version adds successively
>>g', e', and c' at the front of those expression, the second at the end
>>of those expressions.
>>
>>Ok, it is probably trying to show to much at once.  What's the scope
>>that you think you could deal with?  Two separate examples for
>>sequential and parallel music (probably not a good idea to work on
>>multiple tags here)?  Not adding more than a single term?
>
> I remember studying this section of documentation and having to try
> several things before understanding how these commands work. I
> probably should have made a patch at the time... Probably a simpler 
> example would be more helpful, perhaps something like:
>
> melody = { c' \tag #'append { d' } \tag #'push 2 }
>
> {
>   \melody
>   \pushToTag #'push e'2 \melody
>   \appendToTag #'append e'2 \melody
> }
>
> Perhaps I'm wrong, but it's my understanding that \pushToTag requires 
> that the tagged expression is simultaneous music (enclosed within <>),
> and that \appendToTag requires that the tagged expression is 
> sequential music (enclosed within {}).

No.  Either can be either.

> Or, at least, if in the above example, melody is defined as:
>
> melody = { c' \tag #'append d' \tag #'push f'2 }
>
> then it doesn't work.

The documentation is explicit that you need a kind of music expression
making use of the "elements" field.  Sequential music and simultaneous
music are explicitly listed, chords work (assuming you only add chord
constituents), volta repeats would somewhat obscurely work (you add
alternatives).

-- 
David Kastrup

___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

Re: \pushToTag and \appendToTag help

[Mark Knoop]

At 11:48 on 13 Apr 2018, David Kastrup wrote:
>Gianmaria Lari  writes:
>> I simply don't understand it. I don't understand it because: it is
>> too long, there are too many things, I don't understand the example
>> goal, and I don't understand the explication following the code.  
>
>It adds material at two points to \test: in the inner parallel music,
>and the outer sequential music.  The first version adds successively
>g', e', and c' at the front of those expression, the second at the end
>of those expressions.
>
>Ok, it is probably trying to show to much at once.  What's the scope
>that you think you could deal with?  Two separate examples for
>sequential and parallel music (probably not a good idea to work on
>multiple tags here)?  Not adding more than a single term?

I remember studying this section of documentation and having to try
several things before understanding how these commands work. I
probably should have made a patch at the time... Probably a simpler 
example would be more helpful, perhaps something like:

melody = { c' \tag #'append { d' } \tag #'push 2 }

{
  \melody
  \pushToTag #'push e'2 \melody
  \appendToTag #'append e'2 \melody
}

Perhaps I'm wrong, but it's my understanding that \pushToTag requires 
that the tagged expression is simultaneous music (enclosed within <>),
and that \appendToTag requires that the tagged expression is 
sequential music (enclosed within {}). Or, at least, if in the above 
example, melody is defined as:

melody = { c' \tag #'append d' \tag #'push f'2 }

then it doesn't work.

-- 
Mark Knoop

___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

Re: \pushToTag and \appendToTag help

[David Kastrup]

Gianmaria Lari  writes:

> On 13 April 2018 at 10:00, David Kastrup  wrote:
>
>> How about pointing out what you find hard to understand in the
>> documentation then?
>
>
> I'm not a musician and I'm a young lilypond user. So I don't like come
> here and say that this part of the documentation is not clear even if
> I would specify that it is not clear *to me*. Report this type of
> things is difficult without hurt the persons that write the
> documentation work.

The point of the documentation is not to look pretty.  It is also not to
explain things to masters of deduction and LilyPond: those will just
look in the source code of LilyPond for a definite answer.

A lot of pain goes into the documentation _exactly_ so that people have
a dependable, infinitely patient and replicable resource for learning to
work with LilyPond without requiring personal assistance.

Pointing to it is for the sake of making people stop asking questions
and start working with LilyPond.  Not for making people stop asking
questions and stop working with LilyPond.

One surprisingly hard lesson to learn as a project lead is that "it's
too hard for me to understand" is perfectly equivalent to "it's too hard
to understand" when I can consider myself to be part of the core
audience, whether we are talking about code, comments, or documentation.

There may be better ways to sugarcoat stuff than I manage, but in the
end it boils down to any material needing to be able to be accessible to
its core audience.  More often than not, that requires several
iterations, partly because the people initially writing the
documentation are too intimate with what they are writing about to
properly channel their core audience.

If you have to fight tooth and nail for any bit of feedback, that
doesn't help.

> And of course, I appreciate who made the effort to write it.
>
> Regarding the example in the documentation: here it is.
>
> test = { \tag #'here { \tag #'here <> } }
> {
>   \pushToTag #'here c'
>   \pushToTag #'here e'
>   \pushToTag #'here g' \test
>   \appendToTag #'here c'
>   \appendToTag #'here e'
>   \appendToTag #'here g' \test
> }
>
> I simply don't understand it. I don't understand it because: it is too
> long, there are too many things, I don't understand the example goal, and I
> don't understand the explication following the code.

It adds material at two points to \test: in the inner parallel music,
and the outer sequential music.  The first version adds successively g',
e', and c' at the front of those expression, the second at the end of
those expressions.

Ok, it is probably trying to show to much at once.  What's the scope
that you think you could deal with?  Two separate examples for
sequential and parallel music (probably not a good idea to work on
multiple tags here)?  Not adding more than a single term?

But then my above simple example prompted by you only added a single
term and you stated that this was not what you considered helpful.

> But I'm sure, this is very probably my specific problem. Of course, I
> could spend some hours on it and discover how \pushToTag works, but,
> well, you can't do this for any things like this to discover that you
> don't need this commands :)

So instead I spend hours on explaining and the documentation stays the
way it is, so we get that discussion with the next person next time
round?  I'd rather get the documentation problem solved if I am
investing that amount of time.

> So this is why I avoided to complain about the documentation.

-- 
David Kastrup

___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

Re: \pushToTag and \appendToTag help

[Gianmaria Lari]

On 13 April 2018 at 10:00, David Kastrup  wrote:

> Gianmaria Lari  writes:
>
> > On 13 April 2018 at 09:17, David Kastrup  wrote:
> >
> >> Gianmaria Lari  writes:
> >>
> >> > I didn't understand what I can do and how to use the \pushToTag and
> >> > \appendToTag.
> >> >
> >> > Do you have a very simple example?
> >>
> >> \pushToTag #'tag c' \tag #'tag {}
> >>
> > Thank you for the example. It is simple in the sense that it is concise
> > but for me it is not clear.
>
> Which is exactly what I was anticipating.  If you bothered actually
> mentioning just _what_ you want explained or _what_ is unclear with the
> existing documentation, this would be less of a fumbling around in the
> dark.
>
> > But playing with it you probably make me understand.
>
> I think you can perfectly well play with it yourself.
>
> >> How about stating what you _want_ to do?
> >>
> >
> > Yesterday you point out to me these two commands and I just would like to
> > "learn them".
>
> How about pointing out what you find hard to understand in the
> documentation then?


I'm not a musician and I'm a young lilypond user. So I don't like come here
and say that this part of the documentation is not clear even if I would
specify that it is not clear *to me*. Report this type of things is
difficult without hurt the persons that write the documentation work. And
of course, I appreciate who made the effort to write it.

Regarding the example in the documentation: here it is.

test = { \tag #'here { \tag #'here <> } }
{
  \pushToTag #'here c'
  \pushToTag #'here e'
  \pushToTag #'here g' \test
  \appendToTag #'here c'
  \appendToTag #'here e'
  \appendToTag #'here g' \test
}

I simply don't understand it. I don't understand it because: it is too
long, there are too many things, I don't understand the example goal, and I
don't understand the explication following the code. But I'm sure, this is
very probably my specific problem. Of course, I could spend some hours on
it and discover how \pushToTag works, but, well, you can't do this for any
things like this to discover that you don't need this commands :)

So this is why I avoided to complain about the documentation.

P.S. Be patient with my english, I hope what I have written was clear.
___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

Re: \pushToTag and \appendToTag help

[David Kastrup]

Gianmaria Lari  writes:

> On 13 April 2018 at 09:17, David Kastrup  wrote:
>
>> Gianmaria Lari  writes:
>>
>> > I didn't understand what I can do and how to use the \pushToTag and
>> > \appendToTag.
>> >
>> > Do you have a very simple example?
>>
>> \pushToTag #'tag c' \tag #'tag {}
>>
> Thank you for the example. It is simple in the sense that it is concise
> but for me it is not clear.

Which is exactly what I was anticipating.  If you bothered actually
mentioning just _what_ you want explained or _what_ is unclear with the
existing documentation, this would be less of a fumbling around in the
dark.

> But playing with it you probably make me understand.

I think you can perfectly well play with it yourself.

>> How about stating what you _want_ to do?
>>
>
> Yesterday you point out to me these two commands and I just would like to
> "learn them".

How about pointing out what you find hard to understand in the
documentation then?

-- 
David Kastrup

___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

Re: \pushToTag and \appendToTag help

[Gianmaria Lari]

On 13 April 2018 at 09:17, David Kastrup  wrote:

> Gianmaria Lari  writes:
>
> > I didn't understand what I can do and how to use the \pushToTag and
> > \appendToTag.
> >
> > Do you have a very simple example?
>
> \pushToTag #'tag c' \tag #'tag {}
>
> Thank you for the example. It is simple in the sense that it is concise
but for me it is not clear. But playing with it you probably make me
understand. Is the following the way I should use \pushToTag ?

\version "2.19.81"
var = { a \tag #'ex {} b }

{ \var }
{ \pushToTag #'ex {d' e' } \var }
{ \pushToTag #'ex {a  a  } \var }



> How about stating what you _want_ to do?
>

Yesterday you point out to me these two commands and I just would like to
"learn them".

Thank you David for you help. I appreciate it.
g.
___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

Re: \pushToTag and \appendToTag help

[David Kastrup]

Gianmaria Lari  writes:

> I didn't understand what I can do and how to use the \pushToTag and
> \appendToTag.
>
> Do you have a very simple example?

\pushToTag #'tag c' \tag #'tag {}

How about stating what you _want_ to do?

-- 
David Kastrup

___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user

\pushToTag and \appendToTag help

[Gianmaria Lari]

I didn't understand what I can do and how to use the \pushToTag and
\appendToTag.

Do you have a very simple example?

Thank you, g.
___
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user