Merge branch 'master' into dev/jmandereau

[lilypond.git] / Documentation / user / editorial.itely

diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely
index 5a361fda2dae2124bbb09ba2e50224f0e0b4dbca..674605cb26caa2b4804133e15c4501871f2d8735 100644 (file)
--- a/Documentation/user/editorial.itely
+++ b/Documentation/user/editorial.itely
@@ -233,13 +233,8 @@ string in the form @var{"FooBar"}.  The first form is quicker to
 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.
-
-This example illustrates the use of @code{x11-color}.  Notice that
-the stem color remains black after being set to @code{(x11-color
-'Boggle)}, which is deliberate nonsense.
+If @code{x11-color} cannot make sense of the parameter then the
+color returned defaults to black. 
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
@@ -253,13 +248,14 @@ 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
 @end lilypond
 
 You can get exact RGB colors by specifying the rgb-color number.
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 {
   \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
   \set Staff.instrumentName = \markup {
@@ -287,13 +283,13 @@ the input}.
 Snippets: @lsrdir{Editorial,Editorial-annotations}.
 
 @knownissues
-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. (#blue,
-#green, #red)
-
 An x11 color is not necessarily exactly the same shade as a
-similarly named normal color.
+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).
+
 
 Notes in a chord cannot be colored with @code{\override}; use
 @code{\tweak} instead.  See @ref{Objects connected to the input},
@@ -309,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
@@ -405,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
@@ -436,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 <<
@@ -455,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 {