From fdaa134db4de594edb7557af6aba2c6fa8866819 Mon Sep 17 00:00:00 2001
From: Graham Percival <graham@percival-music.ca>
Date: Wed, 16 Apr 2008 22:20:12 -0700
Subject: [PATCH] Misc proofreading and policy.

---
 Documentation/user/editorial.itely     | 35 +++++++++++++++++++-------
 Documentation/user/pitches.itely       | 14 +++++------
 Documentation/user/writing-texinfo.txt |  3 +++
 3 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely
index 7a96ed3928..e234e8b303 100644
--- a/Documentation/user/editorial.itely
+++ b/Documentation/user/editorial.itely
@@ -46,7 +46,7 @@ inside the staff.
 The font size of notation elements may be altered.  It does not
 change the size of variable symbols, such as beams or slurs.
 
-@warning{For @strong{text} font sizes, see
+@warning{For font sizes of text, see
 @ref{Common markup commands}.}
 
 @lilypond[quote,fragment,relative=2,verbatim,ragged-right]
@@ -299,13 +299,10 @@ Exact RGB colors can be specified using the Scheme function
   \with-color #(x11-color 'navy) "Clarinet"
 }
   
-% black
 \override Stem #'color = #(rgb-color 0 0 0)
 gis8 a
-% white
 \override Stem #'color = #(rgb-color 1 1 1)
 gis8 a
-% dark blue
 \override Stem #'color = #(rgb-color 0 0 0.5) 
 gis4 a
 @end lilypond
@@ -455,6 +452,23 @@ There are two music functions, @code{balloonGrobText} and
 attach text to any grob, and the latter is used like @code{\tweak}, 
 typically within chords, to attach text to an individual note.
 
+Balloon text normally influences note spacing, but this can be
+altered:
+
+@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+\new Voice \with { \consists "Balloon_engraver" }
+{
+  \balloonLengthOff
+  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
+  a8 
+  \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
+  r
+  \balloonLengthOn
+  <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2. 
+}
+@end lilypond
+
+
 @predefined
 
 @funindex ballonLengthOn
@@ -478,20 +492,23 @@ Internals Reference:
 Vertical lines can be drawn between staves synchronized with the
 notes.
 
+The @code{Grid_point_engraver} must be used to create the end
+points of the lines, while the @code{Grid_line_span_engraver} must
+be used to actually draw the lines.  By default this centers grid
+lines horizontally below and to the left side of each note head.
+Grid lines extend from the middle lines of each staff.  The
+@code{gridInterval} must specify the duration between the grid
+lines.
+
 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {
     \Staff
-    % set up grids
     \consists "Grid_point_engraver" 
-    % set the grid interval to one quarter note
     gridInterval = #(ly:make-moment 1 4)
   }
   \context {
     \Score
-    % by default this centers grid lines horizontally below
-    % and to the left side of the note head, the grid lines
-    % extending from the middle lines of each staff
     \consists "Grid_line_span_engraver"
   }
 }
diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index cb69d4d27f..e1ad2ca5ca 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -166,15 +166,14 @@ large intervals:
 If the preceding item is a chord, the first note of the chord is
 used as the reference point for the octave placement of a
 following note or chord.  Inside chords, the next note is always
-relative to the preceding one.
+relative to the preceding one.  Examine the next example
+carefully, paying attention to the @code{c} notes.
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c' {
   c
   <c e g>
-  % the C is now an octave higher
   <c' e g'>
-  % the C returns to the original pitch
   <c, e, g''>
 }
 @end lilypond
@@ -967,7 +966,9 @@ concert pitch.
 Here are a few notes for violin and B-flat clarinet where the
 parts have been entered using the notes and key as they appear in
 each part of the conductor's score.  The two instruments are
-playing in unison.
+playing in unison.  Adding the @code{\transposition c'} to the
+violin part is not strictly necessary, but it is a useful
+reminder.
 
 @lilypond[verbatim,quote,ragged-right]
 \new GrandStaff <<
@@ -975,7 +976,6 @@ playing in unison.
     \relative c'' {
       \set Staff.instrumentName = "Vln"
       \set Staff.midiInstrument = "violin"
-      % strictly speaking not necessary, but a good reminder
       \transposition c'
 
       \key c \major
@@ -988,7 +988,6 @@ playing in unison.
       \set Staff.midiInstrument = "clarinet"
       \transposition bes
 
-      % not concert pitch
       \key d \major
       a4( d8) r d r d4
     }
@@ -1099,12 +1098,10 @@ musicB = {
 \new PianoStaff {
   <<
     \context Staff = "up" {
-      %%% change the next line as desired:
       #(set-accidental-style 'default)
       \musicA
     }
     \context Staff = "down" {
-      %%% change the next line as desired:
       #(set-accidental-style 'default)
       \musicB
     }
@@ -1115,6 +1112,7 @@ musicB = {
 Note that the last lines of this example can be replaced by the
 following, as long as the same accidental style should be used in
 both staves.
+
 @example
 \new PianoStaff @{
   <<
diff --git a/Documentation/user/writing-texinfo.txt b/Documentation/user/writing-texinfo.txt
index c6ca460136..d8d5f6cdac 100644
--- a/Documentation/user/writing-texinfo.txt
+++ b/Documentation/user/writing-texinfo.txt
@@ -105,6 +105,9 @@ commands.
 
 * Use two spaces after a period.
 
+* In examples of syntax, use @var{musicexpr} for a music
+  expression.
+
 * Variables or numbers which consist of a single character
   (probably followed by a punctuation mark) should be tied
   properly, either to the previous or the next word.  Example:
-- 
2.39.5