On 13 April 2018 at 11:48, David Kastrup <d...@gnu.org> wrote:
> Gianmaria Lari <gianmarial...@gmail.com> writes:
>
> > On 13 April 2018 at 10:00, David Kastrup <d...@gnu.org> 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 <<c''>> } }
> > {
> > \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 <<c' e' g'>> 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
