Re: Comments on Learning Manual 3 -- Fundamental concepts

[Graham Percival]

On Sat, 9 Aug 2008 18:15:35 +0200
"John Mandereau" <address@hidden> wrote:

> In 'Introduction to the LilyPond file structure':
> by default, \header does not use the same fields depending on its
> scope (\book or \score), so IMO it's better to show the more standard
> file structure with a \header outside the \score.

I disagree.  Shoving \header outside of a \book or \score is a
shorthand, and I'd rather keep the "basic" example as basic as
(reasonably) possibly.  Also, having a \header on its own will
result in it being applied to either the \book or \score -- if we
explicitly stick \header inside the \score, there's no ambiguity.

> In 'Score is a (single) compound musical expression':
> whichever type (simultaneous or sequential) you use to enclose the
> music in the Staff, you can nest inside it the other type, e.g.
> 
> "<< \new Staff { \foo } >>" or "\new Staff { << \bar \baz >> }",
> 
> so on the practical side, using `<< .. >>' should depend on what your
> Staff contains.

The first example uses {}, and the fifth paragraph explains about
{} vs. << >>.  I don't see the problem here.

> About the correction made in "notes, which are introduced with
> `\relative',": let's not make newbies think that notes are only
> introduced with \relative, 

Actually, one of the whole points of the rewritten tutorial a year
and a half ago *is* to make newbies think that notes are only
introduced with \relative.  Absolute mode is mentioned, but we use
\relative in the overwhelming majority of cases.

NR 3 should be clear that absolute mode is ok, but I don't think
it's a bad thing that LM 3 only discusses \relative in this
context.


> @@ -187,8 +185,8 @@ separate output file.
>  
>  In summary:
>  
> -Every @code{\book} block creates a separate output file (e.g., a
> -pdf file).  If you haven't explicitly added one, LilyPond wraps
> +Every @code{\book} block creates a separate output file, e.g., a
> +PDF file.  If you haven't explicitly added one, LilyPond wraps

This must be a Frenchism; I winced when I saw it in some of
Valentin's text.itely changes.  Why on earth remove the
parentheses?  They help clarify the structure of the sentence.

> address@hidden Dynamic_engraver
> address@hidden The old Dynamic_engraver is deprecated. -jm
> address@hidden New_dynamic_engraver

Other than specific warnings about formatting issues, don't add
comments to the .tely files.  If you feel the need to comment
something about the content, it just means that the docs aren't
clear enough.

This case certainly doesn't need such a comment.


Cheers,
- Graham