Re: Comments on Learning Manual 3 -- Fundamental concepts

[Trevor Daniels]

John, you wrote Saturday, August 09, 2008 5:15 PM
> I proofread chapter 3 of the Learning Manual up to 3.1.4 'Modifying
> context properties'.  This is globally great work, I wish I could read
> such docs instead of spending hours in trial-and-error and reading
> Mats' explanations on -user, when I started with LilyPond 4 years ago
> :-).

Actually, much of what you have read so far was Graham's work.  Mine
comes mainly after this.

> I read it in Info format within Emacs, so I saw some issues with the
> way cross-references look; it might be useful to nitpick about this
> output format if we distribute Info docs with GUB later, and anyway
> LilyPond packages for GNU/Linux distros (e.g Fedora) certainly already
> include Info docs.

I don't have a means of checking this, so thanks for that.

> I made many changes in a commit (patch attached), the detailed message
> gives motivation for some changes.  After second thought, I think
> changes that intend to explain some details better are not welcome in
> LM, because it's not worth the effort for beginners making the effort
> to understand such details.  Current explanations I propose to replace
> should probably remain intact: even if they simplify some details and
> are even sometimes a bit wrong, they are simple enough for beginners;

Yes.  A key design consideration was never to use a concept which
had not been explained earlier.  This meant some details had to be
omitted in places.  I think this consideration should be retained.

> if we go this way hiding details and lying a little, we must add 'See
> also' links to NR sections where details are well expained.  If
> necessary, I can make a new patch to add to NR changes that can't be
> added to LM, and a new patch for LM3.  What do you think?

Absolutely.  When the LM was written the appropriate sections in the
NR did not exist, or at least the headings were expected to change.
Now the headings have stabilised (more or less) the refs can be added.

Could you please make a new patch, taking into account the
comments made yesterday by others and push it to origin/master,
as you now have git access?  I'm pretty happy with all your changes,
and the odd nit I can pick up afterwards.  This will be easier than
trying to discuss little points in a long patch.

> There are also two details below I'm not sure about.
>
> 3.1.2 Score is a (single) compound musical expression
> -----------------------------------------------------
>
> """Start with the outer layer"""
> I thought that the common word for this was "level", but maybe "layer"
> makes more sense or is easier to understand.

We should change this to "level", as "layer" is a grob property with
quite a different meaning.  Using "layer" is potentially a misleading
hang-up for a newcomer.  Could you add this to your new patch, please?

> 3.2.1 I'm hearing Voices
> ------------------------
>
> """the notes from the third and fourth voices are
> displaced to if necessary to avoid the note heads colliding."""
>          ^^
> Is the first "to" intentional? (Oh, I'm not an English grammar
> specialist, you know, I probably sound like a dummy Frog here :-p)

No, you're quite right - this is a typo.  I'd prefer:

"the notes from the third and fourth voices are displaced, if
necessary, to avoid the note heads colliding."

> I'll come back again later with comments and changes on LM 3-4.

Thanks

> Cheers,
> John

Trevor