On 13 April 2018 at 11:48, David Kastrup <address@hidden> wrote:
Gianmaria Lari <address@hidden> writes:
> On 13 April 2018 at 10:00, David Kastrup <address@hidden> 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.