Documentation fixes, updates, and changes

[Jonathan Henkelman]

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:

Section 7.2.2 – Chords mode (pg. 106, final para): should read "... does not 
sound good when combined with an unaltered _13_,..."

Section 7.2.2 - Chords mode (pg. 106, para. 2): should read "...bass note can 
be added instead _of_ transposed..."

Section 8.1.2 - Text Spanners (pg. 159, Predefined Commands section): all 
predefined commands up to this point have included the leading '\'.  They 
should be included here also.

Section 8.4.8 - Selecting notation font size (pg. 196, first two examples):  
It took me quite a while to get the difference between these two examples.  I 
would propose adding the following to the end of the paragraph preceeding the 
second example. "The font-size property can also be set directly, so that all 
layout obejcts are not affected."

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.1 - Context explained (pg. 207, para 1): should read "... 
notational elements must be added to the _output_."

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?

Section 9.2.5 - Layout Tunings within Contexts (pg. 213, para 4): Paragraph 
starts "Analagous...".  In this sentance it isn't clear if leaving out the 
context will _always_ default to voice, or just in this instance.  If it is 
the former, change the first sentance to: "Analogous to \set, the context 
argument may be left out, causing the default context Voice to always be 
used." If it is the second, change the first sentance to: "Analogous to \set, 
the context argument may be left out, causing it to apply to the current 
context (in this case Voice)."

Same place: make the last comma segment a sentance (it introduces a new idea) 
as follows: "Adding \once applies the change during one timestep only"

Section 9.2.6 - Changing context default settings (pg. 214, para 2 "Here 
\Staff..."): I'm not even quite sure what this is trying to say.  How about 
changing it to? "Here the \Staff command identifies this section as changing 
the settings for the staff context."  Or how about "The \staff command brings 
in the existing definition of the staff context so that it can be modified."

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."

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."

Section 9.2.7 - Defining new context (pg. 215, para 4): should read "In the 
following discussion, the example input shown should go in place of the ... in 
the previous fragment."

In general this section could be enhanced by providing further expainations of 
commands rather than just showing a single example.  I've done my best below:

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.

Next paragraph: Even after reading this I don't really understand what \alias 
does.  Can someone provide a quick definition of what \alias does.  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".

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,"

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???

Section 9.3 The \override command & 9.3.1 Constructing a tweak (pgs. 216-7): 
It seems to me that this should start with some sort of definition.

How about changing the entire 9.3 to: 
**start quote**
9.3 The \override command

In the previous section, we have already touched on a command that changes 
layout details: the \override command. In this section, we will look in more 
detail at how to use the command in practice.  The general syntax of this 
command is:

\override context.layout_object layout_property = value

This will set the layout_property of the specified layout object, which is a 
member of the context, to the value.

9.3.1

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

\override Voice.Stem #'thickness = #3.0

To construct this tweak we must determine these bits of information: ...
** end quote **

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.

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.

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?

Section 9.3.3 - Layout interfaces (pg. 218, end of para 2): should 
read "...kept at a distance of at least _0.5_ _from_ the note head."

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

Section 10.1.1 - File structure (introduction) (pg. 223, last para, last 
sentace): should read "Section 10.1.4 enumerates them all." as 10.1.2 does not 
enumerate them!

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:

** start quote **
Sec. 10.1.1 - File Structure (introduction): should stay where it is.
Sec. 10.1.4 - File Structure: should become 10.1.2
Sec. 10.1.5 - A single music expression: should become 10.1.3
Sec. 10.1.2 - Multiple scores in a book: should beomce 10.1.4 since it needs 
to have both score and book introduced by (current) section 10.1.4, with the 
expansion of the idea expressed in 10.1.5 about building a score before also.
Sec. 10.1.6 - Including Lilypond files: should be 10.1.5
Sec. 10.1.7 - Text encoding: should be 10.1.6
Sec. 10.1.3 - Extracing fragments of notation: should be 10.1.7 as it the 
least likely to be used and the most esoteric section in 10.1
** end quote **

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."?

Section 10.3.1 - Creating MIDI files (pg. 232, first eg.): delete FIXME, or 
fixme then delete FIXME

Section 10.3.2 - MIDI block (pg. 223): should appear before 10.3.1 - Creating 
MIDI files, since it introduces the midi block which "Creating MIDI files" 
uses.

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

Section 11.3.1 - Vertical spacing inside a system (pg. 240, para 3): I can't 
really understand what this is trying to say.  I would have to fool around 
with it to see how it works before coming up with a concrete replacement.  
Would someone be willing to have a peak and see if it couldn't be made a bit 
clearer?

Section 11.4.2 - New spacing area (pgs. 245-6, two examples):  I really can't 
see a difference between the output of these two examples.  Could it be that 
the wrong output files were linked, or there is a scaling problem?  Not sure 
what is wrong, but in my PDF, they appear identical. Or perhaps some text 
could be included as to what to look for that is different?

Section 11.5.4 - Optimal page turning (pg. 259, para 5): I'm afraid as a 
relative newbie reading this I still don't understand what the arguments to 
minimumPageTurnLength are.  I can make a guess that the following might 
do? "...#(ly:make-moment 1 1) i.e. one whole note. If you ... very large.  In 
this example it is set to 5 half notes:"

*** 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!

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...

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 much,
Jonathan Henkelman