Re: Tip: lyrics with polyphony / stem directions (without specifically instantiated voices)

[Mark Dewey]

Mats Bengtsson wrote:
. . .
> Mark, what do you say? Is the current example in the manual too complex so
> that the main points are not clear enough? Should we replace that example
> by Kieren's?

I didn't mean to imply anything about the documentation earlier.

But, since you asked . . .

Perhaps Kieren's example would be helpful instead.  I'm not exactly sure.  I'm 
colorblind, though (slightly), so I don't know how much adding the color would 
help me specifically.  I think hints like color, size, and shape only help some 
people, and only in some circumstances.  For me, in this case, I think a 
detailed explanation would be better.

It's not 'usually' the complexity of the documentation that causes problems for 
me.  It's normally just matters of syntax, what relates to what, and what means 
what  that I need clarification on (i.e. little specific details of how things 
are implemented).  I like details and specifics a lot (so a detailed 
explanation isn't something I consider complicated, though I'm sure that's not 
what you meant).  A nested explanation might be something I'd consider 
complicated.

For instance, the documentation says this:
. . .
<< \upper \\ \lower >>
is equivalent to
<<
 \new Voice = "1" { \voiceOne \upper}
 \new Voice = "2" { \voiceTwo \lower}
> >

I think the \upper and \lower thing in the documentation is syntactically 
confusing, without specifically saying they represent the notes there, seeing 
as \upper and \lower are also used in the piano staff context, as people will 
actually try to put \upper and \lower in their code (without instantiating 
them).

I would recommend either replacing these with notes directly, or showing their instantiation above 
the example (and explaining the significance of the voice names "1" and "2"; 
plus, a mention of when/why it is good to leave them out would be nice—maybe it's already mentioned 
somewhere else, and if so, perhaps I might recommend pointing us there from here).

I might recommend adding an example like this somewhere below that:
<<{\voiceOne (upper notes here)} \new Voice {\voiceTwo (lower notes here)}>> 
\oneVoice
is the preferred way over
<<{(upper notes here)} \\ {(lower notes here)}>>
for polyphonic chords used with lyrics, since the \\ method automatically gives the names "1" and 
"2" to the voices, which are not the names of the voice the lyrics are following (i.e. 
"sopranos", etc.)

Where to look for what, in the documentation generally, is also an issue at 
times.  I might recommend giving us some tips on how to find things (generally 
speaking), and how to glean information, as it seems to be easier for you.

All in all, though, I didn't mean to bring up the documentation, myself.  It 
normally works well for me in connection with the forums—lately, at least.  I 
understand if you don't want to put this in the documentation (that's fine with 
me)—after all, it is on the forums now in a way people who think like me could 
find it.

> (For the record, there are plenty of answers to similar questions in the 
> mailing list
> archives, that show exactly the same construct. I'm surprised that you 
> didn't find them.)

I only found such as the links I included in one of the earlier posts of this 
thread (but I only made a few different search criteria: i.e. polyphony lyrics, 
and . . . I forgot what else).  I didn't bother to look further since one of 
the threads I saw made it look like a known issue that we just had to deal with 
(and that's another reason I didn't look at the manual further; I had no reason 
to believe I could find anything more on the subject there, because of what I 
saw in the threads).

It's possible that I saw the answers/questions you mentioned, but thought they 
were talking about something else, or something irrelevant.  I mean, it could 
have been a matter of semantics.  People are easy to misunderstand (especially 
when they talk about familiar things with unfamiliar terminology).

As long as I know what I want, though, the clarity of the documentation isn't a 
'huge' deal for me, seeing as I don't view documentation in the same light as a 
tutorial (I mean, it seems more for advanced reference than a teaching aid for 
new and semi-intermediate users).  I'm at a point where things are becoming 
more clear and using the documentation for reference isn't that bad 
(understanding how voices works helps a lot for this; I think this is probably 
one of the most important sections to make clear, and add detail).  I mean, the 
documentation seems to require a certain amount of knowledge about LilyPond in 
order to learn (some sections more than others) as sometimes answers are given 
using principles the learner may not have learned yet.

Documentation isn't something I generally expect to read through in a linear 
fashion (usually I use it more on a want/need-to-know basis), while a tutorial 
or a textbook is.  Is one supposed to read the documentation in a linear 
fashion?  I don't know, personally, but the knowledge would be extremely 
helpful, now that I consider it.  I mean, do present parts only reference 
future parts due to the assumption that past parts are known?  This would be 
useful to know, especially for beginners.  That way, one could expect to start 
from the beginning, or if the contrary be the case, know that it doesn't matter 
where one starts.  If it is linear (like a college textbook), and if we are 
meant to read it through and through, this could explain why a lot of people 
ask questions about things they should know, and why the documentation seems 
daunting for many: because they don't know it's linear, if it is, I mean.  I 
myself, have not read the beginning, nor anything in any particular or
der: I generally just look for what I want to know while I'm on a project (and 
I'm sure many others do that, too).

Anyway, thanks for the help, and do well!

Sorry if I've misunderstood something, or haven't researched all I should have 
quite.