X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fuser%2Feditorial.itely;h=674605cb26caa2b4804133e15c4501871f2d8735;hb=b0984ac0eae12ef21adcdbc4922354e731e8f22d;hp=e5020e71e757106af41a4df49be2591a4e00162a;hpb=9fe3479ffc5a214ef9c5059de63b8777f5137b93;p=lilypond.git

diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely
index e5020e71e7..674605cb26 100644
--- a/Documentation/user/editorial.itely
+++ b/Documentation/user/editorial.itely
@@ -234,8 +234,7 @@ write and is more efficient.  However, using the second form it is
 possible to access X11 colors by the multi-word form of its name.
 
 If @code{x11-color} cannot make sense of the parameter then the
-color returned defaults to black.  It should be obvious from the
-final score that something is wrong.
+color returned defaults to black. 
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
@@ -249,7 +248,6 @@ gis a
 gis a
 \override NoteHead #'color = #(x11-color "LimeGreen")
 gis a
-
 % this is deliberate nonsense; note that the stems remain black
 \override Stem #'color = #(x11-color 'Boggle)
 b2 cis
@@ -289,8 +287,8 @@ An x11 color is not necessarily exactly the same shade as a
 similarly named normal color.  
 
 Not all x11 colors are distinguishable in a web browser i.e. a web browser
-might not display a difference between 'LimeGreen and 'ForestGreen.  For web
-use normal colors are recommended (i.e. #blue, #green, #red).
+might not display a difference between 'LimeGreen and 'ForestGreen.  For 
+web use normal colors are recommended (i.e. #blue, #green, #red).
 
 
 Notes in a chord cannot be colored with @code{\override}; use
@@ -307,33 +305,20 @@ for details.
 @cindex parentheses
 
 Objects may be parenthesized by prefixing @code{\parenthesize} to
-the music event,
+the music event.  This only functions inside chords; to
+parenthesize a single note it must be enclosed with @code{<>} as
+if it is a chord.
 
 @lilypond[relative=2,fragment,verbatim,ragged-right]
-<
-  c
-  \parenthesize d
-  g
->2-\parenthesize -.
-d g 
-<
-  c,
-  \parenthesize fis
->
+c2 < \parenthesize d>
+<\parenthesize e> d
 @end lilypond
 
-This only functions inside chords, to parenthesize a single note it 
-must be enclosed with @code{<>} as if it is a chord.
-
-@example
-< \parenthesize NOTE>
-@end example
+Non-note objects may be parenthesized as well.
 
 @lilypond[relative=2,fragment,verbatim,ragged-right]
-c4
-<\parenthesize d>
-g
-<\parenthesize d>
+< c \parenthesize d g >2-\parenthesize -. d
+g < c, \parenthesize fis >
 @end lilypond
 
 @seealso
@@ -403,16 +388,19 @@ The following example demonstrates its use.
 
 @lilypond[quote,verbatim,fragment,ragged-right,relative=2]
 \new Voice \with { \consists "Balloon_engraver" }
-{
-  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
-  <a-\balloonText #'(-2 . -2) \markup { "I'm a note head" }  >8
-}
+     {
+      \time 2/4
+       \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
+       a'8
+       <c' g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } 
+c''>4. 
+     }
 @end lilypond
 
 There are two music functions, @code{balloonGrobText} and
-@code{balloonText}; the former takes the name of the grob to adorn,
-while the latter may be used as an articulation on a note.  The other
-arguments are the offset and the text of the label.
+@code{balloonText};  The former is used like \once \override to 
+attach text to any grob, and the latter is used like \tweak, 
+typically within chords, to attach text to an individual note.
 
 @cindex balloon
 @cindex notation, explaining
@@ -434,15 +422,19 @@ notes.
 \layout {
   \context {
     \Staff
-    \consists "Grid_point_engraver" %% sets of grid
+    \consists "Grid_point_engraver" 
+    % sets up grids
     gridInterval = #(ly:make-moment 1 4)
+    % this sets the grid interval to 1 quarternote (crotchet)
   }
 }
 
 \new Score \with {
   \consists "Grid_line_span_engraver"
-  %% centers grid lines  horizontally below note heads
+  %% centers grid lines  horizontally below note heads by default 
+  %the grid lines are aligned with the left side of the notehead
   \override NoteColumn #'X-offset = #-0.5
+  % this moves them to the right half a staff space
 }
 
 \new ChoirStaff <<
@@ -453,8 +445,9 @@ notes.
     }
   }
   \new Staff {
-    %% centers grid lines  vertically
     \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
+    % by default the grid lines join the middle line of each staff,
+    % this moves them up one staff space
     \stemDown
     \clef bass
     \relative c {