Markup command documentation: categories and properties

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

diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely
index b019606cbda18b0186cd0857fc9432529870d2b0..dda447e28eab2a85d3b050b07ba0429f0cd5377e 100644 (file)
--- 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]
@@ -92,7 +92,7 @@ c4.-> d8---3
 
 Font size changes are achieved by scaling the design size that is
 closest to the desired size.  The standard font size (for
-@code{font-size = #0}), depends on the standard staff height.
+@code{font-size = #0}) depends on the standard staff height.
 For a 20pt staff, a 10pt font is selected.
 
 The @code{font-size} property can only be set on layout objects
@@ -146,8 +146,8 @@ c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
 
 @cindex thumb-script
 
-You can use the thumb-script (e.g., in cello music) to indicate that a 
-note should be played with the thumb. 
+A thumb-script can be added (e.g., in cello music) to indicate
+that a note should be played with the thumb. 
 
 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 <a_\thumb a'-3>2 <b_\thumb b'-3>
@@ -212,8 +212,20 @@ b
 c
 @end lilypond
 
+Notation objects which are attached to invisible notes are still
+visible.
+
+@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+c4( d)
+\hideNotes
+e4(\p f)--
+@end lilypond
+
+
 @predefined
 
+@funindex \hideNotes
+@funindex \unHideNotes
 @code{\hideNotes}, @code{\unHideNotes}
 
 @seealso
@@ -287,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
@@ -330,12 +339,13 @@ Notes in a chord cannot be colored with @code{\override}; use
 @cindex parentheses
 
 Objects may be parenthesized by prefixing @code{\parenthesize} to
-the music event.  When applied to a chord, it parenthesizes every
-note.
+the music event.  When prefixed to a chord, it parenthesizes every
+note.  Individual notes inside a chord may also be parenthesized.
 
 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 c2 \parenthesize d
 c2 \parenthesize <c e g>
+c2 <c \parenthesize e g>
 @end lilypond
 
 Non-note objects may be parenthesized as well.
@@ -355,6 +365,12 @@ Internals Reference:
 @internalsref{ParenthesesItem},
 @internalsref{parentheses-interface}.
 
+@knownissues
+
+Parenthesizing a chord prints parentheses around each individual
+note, instead of a single large parenthesis around the entire
+chord.
+
 
 @node Stems
 @unnumberedsubsubsec Stems
@@ -428,13 +444,36 @@ notation.
 }
 @end lilypond
 
+@cindex balloon
+@cindex notation, explaining
+
 There are two music functions, @code{balloonGrobText} and
 @code{balloonText};  the former is used like @code{\once \override} to 
 attach text to any grob, and the latter is used like @code{\tweak}, 
 typically within chords, to attach text to an individual note.
 
-@cindex balloon
-@cindex notation, explaining
+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 balloonLengthOn
+@funindex balloonLengthOff
+@code{\balloonLengthOn}, @code{\balloonLengthOff}
 
 @seealso
 
@@ -453,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"
   }
 }
@@ -520,7 +562,7 @@ pieces.  Simple horizontal brackets are supported.
 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {
-    \Staff
+    \Voice
     \consists "Horizontal_bracket_engraver"
   }
 }
@@ -535,7 +577,7 @@ Analysis brackets may be nested.
 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {
-    \Staff
+    \Voice
     \consists "Horizontal_bracket_engraver"
   }
 }