Re: Documentation fixes, updates, and changes

[Graham Percival]

Jonathan Henkelman wrote:
> I recently read the manual and took notes on, among other things, the errata I 
> found.  Here is a list.  All references refer to 2.10.0 PDF version.  Also 
> remember the caveat that editors make errors too:

Thanks!  Some of these have already been fixed; the 2.10.0 docs were
released three months ago.

Given the amount of changes, if I have implemented the change you
suggest, I simply deleted it from the email instead of saying "thanks,
fixed" after each one -- but be assured that I am very grateful for all
these comments!

> Note: I had quite a few problems with section 9.  I am hoping to spend some 
> time rewritting portions of this section and adding a few sections in the 
> future.  Here are my (relatively) short changes.



> Section 9.2.2 - Creating contexts (pg. 209, third bullet in section, para 2): 
> should read? "... but matches _all_ context_s_ of type...".  I assume changes 
> made to a context this way will apply to _all_ contexts of that type?

I'm not certain whether this should read "any" or "all".

> Same section (pg. 215, para. 1): What does \RemoveEmptyStaffContext do?  Does 
> it remove all previous settings i.e. return Staff to its default values?  Can 
> this paragraph be clarified?  How about: "\RemoveEmptyStaffContext will return 
> the staff context to its default values." or "\RemoveEmptyStaffContext will 
> remove any setting you have applied already within the current context 
> definition."

The former sentence looks better, but it isn't quite true -- the
\Remove... does _not_ return staff to the default values; it sets up a
Staff with mostly default values, but also sets the propertie(s) that
remove the staff when appropriate.

In this case, I think the current language is good: using \Remove...
overwrites the current Staff settings.

> Same paragraph: Does this also apply to other contexts?  Is there a 
> \RemoveEmptyVoiceContext?  If so, please add the following sentance after the 
> example: "There are analagous functions for returning other contexts to thier 
> default settings, for example \RemoveEmptyVoiceContext."

No, there is no such command.


> Next paragraph: replace with "First it is necessary to define a name for the 
> new context <LF>\name ImproVoice". We don't need the comparison with Voice 
> because it doesn't have a name yet and the next sentance deals with how to 
> link in the voice context.

Done.

> Next paragraph: Even after reading this I don't really understand what \alias 
> does.  Can someone provide a quick definition of what \alias does.

Sorry, I can't; hopefully somebody else can.

>  How about 
> something like replacing the last sentance ("This is acheived...") with "The 
> \alias command links the current context to an already existing context so 
> that functions that work on the old one will work on this one also.  In this 
> case we need to link to the Voice context so that functions that work on Voice 
> will also operate on ImproVoice." or "The \alias command sets the default 
> values of this context to the values of an already existing context.  This 
> allows functions that operate on the other context to also operate on this 
> one.  In this case we need the functionality of the Voice context so that 
> functions that work on Voice will also operate on ImproVoice".

I haven't made any of these changes; please resubmit when we hear about
\alias.


> Next paragraph: should read "The context will print notes, and instructive 
> texts so we need to add the engravers which provide this functionality"
>
> Next sentance: should read "We only need this on the center of the line so,"

Both done.

> Paragraph starting "All these plug-ins...", last sentace: should read "This 
> type should always be Engraver_group and it should appear immediately after 
> the name definition."  If this is _always_ the case, why do we need the 
> definition.  Couldn't we just assume it was the case for any new context and 
> include it as part of \name???

I'm not certain, so I haven't made these changes.



> 9.3.1
>
> To try and explain how to construct an \override some examples will be worked 
> through

I think the current text explains this in fewer words.

> Section 9.3.2 - Navigating the program reference (pg. 217, para 3 "Follow the 
> link..."): I found this section extremely difficult to follow as I am using 
> the PDF docs and it took my a while to figure out why there weren't links. 
> Also, I couldn't find the programmers reference and the single page version 
> was (temporarily) broken.
>
> Replace with: "The programmers reference is an HTML document. The simplest way 
> to navigate through the programmers reference is to use the online version.  
> This section will be much more difficult to understand if you are using the 
> PDF manual, so please consider reading this section in conjunction with the 
> online programmers reference.  If you have limited internet access, consider 
> downloading the programmers reference as a single page.  It is not as easy to 
> follow as the online version because the formatting is more limited, but it 
> contains all the necessary links to understand these examples."  Thanks, I had 
> no end of frustration/confustion over this!  Perhaps this would better fit 
> somewhere at the beginning so all the references to PR in the docs so far 
> would make some sense - I couldn't figure out how one was supposed to use them.

I rewrote this somewhat, and it's been added to the non-HTML docs.  I 
don't think it's necessary to change all the "follow the link" language 
as long as it's clear that HTML is recommended for the program reference.

If you can suggest exactly where to include info about references to the 
PR earlier in the docs, I'd be happy to add it.


> Next para ("By clicking..."): replace sentance with "By following related 
> links inside the programmers reference, we can figure out that the flow of 
> information moves like this:" This is more formal and gives the user the sense 
> that there it isn't just random or aprior knowledge.

Done.

> I am hoping to expand this section to explain the logic behind the links...  
> Also, I have a note that the terms used in this doc to not match those used in 
> the PR (e.g. object, event, expression).  I don't know enough yet to address 
> this.  Would somebody else be willing to look into it?

Maybe -- when I have time to work on lilypond and don't have anything 
more urgent.  If you would like to see this done within the next six 
months, I recommend that you do this.

> Section 9.3.6 - \set vs. \override (pg. 220, para 2, line 2): should read "... 
> from music to _notation_,...

I believe that a music event is a specific thing.  Actually, this 
comment doesn't make sense -- could you look at the latest docs 
(2.11.18) and check if this has already been updated (since 2.10.0) ?


> Section 10.1.3 - Extracting fragments of notation: This section doesn't belong 
> here.  In fact I think the sections here should be arranged as follows:

Yes, two doc sections were inserted into a non-optimal place.  Fixed.

> Section 10.2.1 - Creating titles (pg. 227, para 1): I don't understand what 
> this sentance is trying to say.  Should it read "Titles are created for each 
> \score block within a \book."?

I rewrote this as:
Titles are created for each @code{\score} block, as well as for the full
input file (or @code{\book} block).

Is that more clear?

> Section 10.3.3 - MIDI instrument names (pg. 223): should appear before 10.3.1 
> as one is more likely to need to know about defining instruments before 
> defining volumes and relative volumes. It is also a good intro to \set 
> Staff.midiproperty ... before the more complicated example in 10.3.1

I disagree; finding out how to get any MIDI output at all is more 
important than setting up special instrument names.  That said, I'm not 
opposed to moving volume info out of 10.3.1 and making a new 10.3.4 for 
such info.

> Section 11.3.1 - Vertical spacing inside a system (pg. 240, para 3): I can't 

Trevor is currently rewriting huge portions of chapter 11, so I won't 
make any of these changes.  When he's finished, could you take a look at 
the new chapter and let me know if any of your concerns apply to the new 
text?


> *** That end the specific changes section.  A few further comments:
>
> Throughout the manual there is not a standard for "music, music expression, 
> musicexpr".  I assume that if I think that should be standardized I should 
> come up with a punch list of changes (or better, learn how to use diff -u!

"musicexpr" is a "music expression".  Using "music" instead of "music 
expression" is a bit informal.  It would be nice to fix this everywhere 
that it occurs, but we can't do a global "music->music expression" 
change, because sometimes "music" is used in a more general sense.

> I think the manual uses a notation standard for different LP grammer elements 
> e.g. engravers, events etc.  Is there a table somewhere that outlines this 
> notational convention i.e. engravers have first letter caps, underscores, and 
> no second work caps.  If so, I apologize for missing it.  If not, could it be 
> added by someone who knows the convention...

There is a convention about AllCapitalLetters and notAllCapitalLetters, 
but I'm not certain what it is.  It has to do with whether one uses \set 
or \override.

> I want to add that the only reason I'm being so fine tuned about the manual is 
> that I think it is well worth supporting.  Good work to all involved.

Thanks!

In the future, could you separate long emails into emails about 
chapters?  Having four or five shorter emails is easier for me to handle 
than one long thing -- then I can easily change one or two chapters, 
instead of doing everything at once.

Cheers,
- Graham