]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/editorial.itely
DOC -- Index editorial, pitches, staff. Ralph Palmer's work
[lilypond.git] / Documentation / user / editorial.itely
index 342cf58ad71ce9721612c206fb1339e992477fc2..568356bef9f4732fb87fd9a5a0e7761fe4a09c7b 100644 (file)
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
+@c \version "2.11.61"
+
 @node Editorial annotations
 @section Editorial annotations
 
-@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
-{editorial-headword.ly}
+@lilypondfile[quote]{editorial-headword.ly}
 
-This section discusses the various ways to change the appearance of 
+This section discusses the various ways to change the appearance of
 notes and add analysis or educational emphasis.
 
 @menu
-* Inside the staff::            
-* Outside the staff::           
+* Inside the staff::
+* Outside the staff::
 @end menu
 
 
 @node Inside the staff
 @subsection Inside the staff
 
-This section discusses how to add emphasis to elements that are 
+This section discusses how to add emphasis to elements that are
 inside the staff.
 
 @menu
-* Selecting notation font size::  
-* Fingering instructions::      
-* Hidden notes::                
-* Coloring objects::            
-* Parentheses::                 
-* Stems::                       
+* Selecting notation font size::
+* Fingering instructions::
+* Hidden notes::
+* Coloring objects::
+* Parentheses::
+* Stems::
 @end menu
 
 @node Selecting notation font size
-@subsubsection Selecting notation font size
-
-@cindex font size
-@cindex font size, selecting
-@cindex selecting font size
-
-The easiest method of setting the font size of any context is by
-setting the @code{fontSize} property.
-
-@lilypond[quote,fragment,relative=2,verbatim,ragged-right]
-c4
-\set fontSize = #-4
-c f
-\set fontSize = #3
-g8 a
+@unnumberedsubsubsec Selecting notation font size
+
+@cindex font size (notation) scaling
+@cindex font size (notation)
+@cindex selecting font size (notation)
+@cindex notation font size
+@cindex note heads
+
+@funindex fontSize
+@funindex font-size
+@funindex magstep
+@funindex \huge
+@funindex \large
+@funindex \normalsize
+@funindex \small
+@funindex \tiny
+@funindex \teeny
+@funindex huge
+@funindex large
+@funindex normalsize
+@funindex small
+@funindex tiny
+@funindex teeny
+
+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 font sizes of text, see
+@ref{Selecting font and font size}.}
+
+@lilypond[verbatim,quote,relative=2]
+\huge
+c4.-> d8---3
+\large
+c4.-> d8---3
+\normalsize
+c4.-> d8---3
+\small
+c4.-> d8---3
+\tiny
+c4.-> d8---3
+\teeny
+c4.-> d8---3
 @end lilypond
 
-@noindent
-It does not change the size of variable symbols, such as beams or
-slurs.
-
-@cindex font size scaling
-
-Internally, the @code{fontSize} context property will cause the
-@code{font-size} property to be set in all layout objects.  The
-value of @code{font-size} is a number indicating the size relative
-to the standard size for the current staff height.  Each step up
-is an increase of approximately 12% of the font size.  Six steps
-is exactly a factor two.  The Scheme function @code{magstep}
-converts a @code{font-size} number to a scaling factor.  The
-@code{font-size} property can also be set directly, so that only
-certain layout objects are affected.
-
-@lilypond[quote,fragment,relative=2,verbatim,ragged-right]
-c4
+Internally, this sets the @code{fontSize} property.  This in turn
+causes the @code{font-size} property to be set in all layout
+objects.  The value of @code{font-size} is a number indicating the
+size relative to the standard size for the current staff height.
+Each step up is an increase of approximately 12% of the font size.
+Six steps is exactly a factor of two.  The Scheme function
+@code{magstep} converts a @code{font-size} number to a scaling
+factor.  The @code{font-size} property can also be set directly,
+so that only certain layout objects are affected.
+
+@lilypond[verbatim,quote,relative=2]
+\set fontSize = #3
+c4.-> d8---3
 \override NoteHead #'font-size = #-4
-c f
-\override NoteHead #'font-size = #3
-g8 a
+c4.-> d8---3
+\override Script #'font-size = #2
+c4.-> d8---3
+\override Stem #'font-size = #-5
+c4.-> d8---3
 @end lilypond
 
-@cindex standard font size
-@cindex font size, standard
+@cindex standard font size (notation)
+@cindex font size (notation), standard
+
+@funindex font-interface
+@funindex font-size
 
 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} equals 0), depends on the standard staff height.
+@w{@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 that
-use fonts.  These are the ones supporting the @code{font-interface}
-layout interface.
+The @code{font-size} property can only be set on layout objects
+that use fonts.  These are the ones supporting the
+@code{font-interface} layout interface.
 
-@predefined
-
-The following commands set @code{fontSize} for the current voice:
 
-@funindex \tiny
+@predefined
+@code{\teeny},
 @code{\tiny},
-@funindex \small
 @code{\small},
-@funindex \normalsize
-@code{\normalsize}.
+@code{\normalsize},
+@code{\large},
+@code{\huge}.
+@endpredefined
 
-@seealso
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+@seealso
+Snippets:
+@rlsr{Editorial annotations}.
 
-Internals Reference: @internalsref{font-interface}.
+Internals Reference:
+@rinternals{font-interface}.
 
 
 @node Fingering instructions
-@subsubsection Fingering instructions
+@unnumberedsubsubsec Fingering instructions
 
 @cindex fingering
 @cindex finger change
 
+@funindex \finger
+@funindex finger
+
 Fingering instructions can be entered using
 @var{note}-@var{digit}:
 
-Fingering instructions may be manually placed above or below the
-staff, see @ref{Controlling direction and placement}.
-
-@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c4-1 d-2 f-4 e-3
 @end lilypond
 
-Use markup texts for finger changes. 
+Markup texts may be used for finger changes.
 
-@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
 @end lilypond
 
 @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. 
+@funindex \thumb
+@funindex thumb
 
-@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
+A thumb-script can be added (e.g., in cello music) to indicate
+that a note should be played with the thumb.
+
+@lilypond[verbatim,quote,relative=2]
 <a_\thumb a'-3>2 <b_\thumb b'-3>
 @end lilypond
 
 @cindex fingering chords
+@cindex fingering instructions for chords
 @cindex chords, fingering
 
 Fingerings for chords can also be added to individual notes of the
 chord by adding them after the pitches.
 
-@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
-< c-1 e-2 g-3 b-5 >2 < d-1 f-2 a-3 c-5 >
+@lilypond[verbatim,quote,relative=2]
+<c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
 @end lilypond
 
+Fingering instructions may be manually placed above or below the
+staff, see @ref{Direction and placement}.
 
 @snippets
 
-@code{fingeringOrientations} are used to control where the fingering
-numbers are placed.
-
-@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
-\set fingeringOrientations = #'(left)
-<c-1 e-3 a-5 > 4
-\set fingeringOrientations = #'(down)
-<c-1 e-3 a-5 > 
-\set fingeringOrientations = #'(right)
-<c-1 e-3 a-5 > 
-\set fingeringOrientations = #'(up)
-<c-1 e-3 a-5 > 
-\set fingeringOrientations = #'(left down)
-<c-1 e-3 a-5 > 2
-\set fingeringOrientations = #'(up right down)
-<c-1 e-3 a-5 >
-@end lilypond
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{controlling-the-placement-of-chord-fingerings.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{allowing-fingerings-to-be-printed-inside-the-staff.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{avoiding-collisions-of-chord-fingering-with-beams.ly}
+
 
 @seealso
+Notation Reference:
+@ref{Direction and placement}
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+Snippets:
+@rlsr{Editorial annotations}.
 
-Internals Reference: @internalsref{Fingering}.
+Internals Reference:
+@rinternals{FingeringEvent},
+@rinternals{fingering-event},
+@rinternals{Fingering_engraver},
+@rinternals{New_fingering_engraver},
+@rinternals{Fingering}.
 
 
 @node Hidden notes
-@subsubsection Hidden notes
+@unnumberedsubsubsec Hidden notes
+
+@cindex hidden notes
+@cindex invisible notes
+@cindex transparent notes
+@cindex notes, hidden
+@cindex notes, invisible
+@cindex notes, transparent
 
-@cindex Hidden notes
-@cindex Invisible notes
-@cindex Transparent notes
 @funindex \hideNotes
+@funindex hideNotes
 @funindex \unHideNotes
+@funindex unHideNotes
 
 Hidden (or invisible or transparent) notes can be useful in
 preparing theory or composition exercises.
 
-@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+@lilypond[verbatim,quote,relative=2]
 c4 d
 \hideNotes
 e4 f
 \unHideNotes
 g a
-\hideNotes 
+\hideNotes
 b
 \unHideNotes
 c
 @end lilypond
 
+Notation objects which are attached to invisible notes are still
+visible.
+
+@lilypond[verbatim,quote,relative=2]
+c4( d)
+\hideNotes
+e4(\p f)--
+@end lilypond
+
+
 @predefined
+@code{\hideNotes},
+@code{\unHideNotes}.
+@endpredefined
 
-@code{\hideNotes}, @code{\unHideNotes}
 
 @seealso
+Snippets:
+@rlsr{Editorial annotations}.
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+Internals Reference:
+@rinternals{Note_spacing_engraver},
+@rinternals{NoteSpacing}.
 
 
 @node Coloring objects
-@subsubsection Coloring objects
+@unnumberedsubsubsec Coloring objects
 
 @cindex colored objects
+@cindex objects, colored
 @cindex colors
 @cindex coloring objects
 @cindex colored notes
 @cindex coloring notes
 @cindex notes, colored
+@cindex x11 color
+@cindex x11-color
+@cindex with-color
+
+@funindex color
+@funindex \with-color
+@funindex with-color
+@funindex x11-color
 
-Individual objects may be assigned colors.  You may use the color
-names listed in the @ref{List of colors}.
+Individual objects may be assigned colors.  Valid color names
+are listed in the @ref{List of colors}.
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 \override NoteHead #'color = #red
 c4 c
 \override NoteHead #'color = #(x11-color 'LimeGreen)
@@ -232,7 +299,6 @@ d
 e
 @end lilypond
 
-@cindex x11-color
 
 The full range of colors defined for X11 can be accessed by using
 the Scheme function @code{x11-color}.  The function takes one
@@ -242,13 +308,14 @@ 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. 
+color returned defaults to black.
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
 \set Staff.instrumentName = \markup {
   \with-color #(x11-color 'navy) "Clarinet"
 }
+
 gis8 a
 \override Beam #'color = #(x11-color "medium turquoise")
 gis a
@@ -261,92 +328,130 @@ gis a
 b2 cis
 @end lilypond
 
-You can get exact RGB colors by specifying the rgb-color number.
+@cindex rgb-color
+@cindex color, rgb
+@cindex rgb color
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-{
-  \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
-  \set Staff.instrumentName = \markup {
-    \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
+@funindex rgb-color
+
+Exact RGB colors can be specified using the Scheme function
+@code{rgb-color}.
+
+@lilypond[verbatim,quote,relative=2]
+\override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
+\set Staff.instrumentName = \markup {
+  \with-color #(x11-color 'navy) "Clarinet"
 }
+
+\override Stem #'color = #(rgb-color 0 0 0)
+gis8 a
+\override Stem #'color = #(rgb-color 1 1 1)
+gis8 a
+\override Stem #'color = #(rgb-color 0 0 0.5)
+gis4 a
 @end lilypond
 
+
 @seealso
+Notation Reference:
+@ref{List of colors}, @ref{The
+tweak command}.
+
+Snippets:
+@rlsr{Editorial annotations}.
 
-Notation Reference: @ref{List of colors}, @ref{Objects connected to
-the input}.
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+@cindex x11 color
+@cindex colored notes in chords
+@cindex notes, colored in chords
+@cindex color in chords
+
+@funindex x11-color
 
 @knownissues
-An x11 color is not necessarily exactly the same shade as a
-similarly named normal color.  
+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).
+Not all X11 colors are distinguishable in a web browser, i.e.,
+a web browser might not display a difference between @code{'LimeGreen}
+and @code{'ForestGreen}.  For web use normal colors are recommended
+(i.e., @code{#blue}, @code{#green}, @code{#red}).
 
 
 Notes in a chord cannot be colored with @code{\override}; use
-@code{\tweak} instead, see @ref{Objects connected to the input}.
+@code{\tweak} instead, see @ref{The tweak command}.
 
 
 @node Parentheses
-@subsubsection Parentheses
+@unnumberedsubsubsec Parentheses
 
 @cindex ghost notes
 @cindex notes, ghost
 @cindex notes, parenthesized
 @cindex parentheses
 
+@funindex \parenthesize
+@funindex parenthesize
+
 Objects may be parenthesized by prefixing @code{\parenthesize} to
-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.
+the music event.  When prefixed to a chord, it parenthesizes every
+note.  Individual notes inside a chord may also be parenthesized.
 
-@lilypond[relative=2,fragment,verbatim,ragged-right]
-c2 < \parenthesize d>
+@lilypond[verbatim,quote,relative=2]
+c2 \parenthesize d
+c2 \parenthesize <c e g>
+c2 <c \parenthesize e g>
 @end lilypond
 
 Non-note objects may be parenthesized as well.
 
-@lilypond[relative=2,fragment,verbatim,ragged-right]
-< c d g >2-\parenthesize -. d
+@lilypond[verbatim,quote,relative=2]
+c2-\parenthesize -. d
+c2 \parenthesize r
 @end lilypond
 
+
 @seealso
+Snippets:
+@rlsr{Editorial annotations}.
+
+Internals Reference:
+@rinternals{Parenthesis_engraver},
+@rinternals{ParenthesesItem},
+@rinternals{parentheses-interface}.
+
+
+@knownissues
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+Parenthesizing a chord prints parentheses around each individual
+note, instead of a single large parenthesis around the entire
+chord.
 
 
 @node Stems
-@subsubsection Stems
+@unnumberedsubsubsec Stems
 
 @cindex stem
+@cindex stem, invisible
+@cindex invisible stem
+
+@funindex \stemUp
+@funindex stemUp
+@funindex \stemDown
+@funindex stemDown
+@funindex \stemNeutral
+@funindex stemNeutral
 
 Whenever a note is found, a @code{Stem} object is created
 automatically.  For whole notes and rests, they are also created but
 made invisible.
 
-@predefined
 
-@funindex \stemUp
+@predefined
 @code{\stemUp},
-@funindex \stemDown
 @code{\stemDown},
-@funindex \stemNeutral
 @code{\stemNeutral}.
+@endpredefined
 
 
 @snippets
@@ -356,189 +461,237 @@ made invisible.
 @cindex stem, down
 @cindex stem, neutral
 
-To change the direction of stems on the center line of the staff, use
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{default-direction-of-stems-on-the-center-line-of-the-staff.ly}
 
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-a4 b c b
-\override Stem #'neutral-direction = #up
-a4 b c b
-\override Stem #'neutral-direction = #down
-a4 b c b
-@end lilypond
 
 @seealso
+Notation Reference:
+@ref{Direction and placement}.
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+Snippets:
+@rlsr{Editorial annotations}.
+
+Internals Reference:
+@rinternals{Stem_engraver},
+@rinternals{Stem},
+@rinternals{stem-interface}.
 
 
 @node Outside the staff
 @subsection Outside the staff
 
-This section discusses how to add emphasis to elements in the staff 
-from outside of the staff. 
+This section discusses how to add emphasis to elements in the staff
+from outside of the staff.
 
 @menu
-* Balloon help::                
-* Grid lines::                  
-* Analysis brackets::           
+* Balloon help::
+* Grid lines::
+* Analysis brackets::
 @end menu
 
 @node Balloon help
-@subsubsection Balloon help
+@unnumberedsubsubsec Balloon help
+
+@cindex balloon
+@cindex notation, explaining
+@cindex balloon help
+@cindex help, balloon
+
+@funindex \balloonGrobText
+@funindex \balloonText
+@funindex Balloon_engraver
+@funindex balloonGrobText
+@funindex balloonText
+@funindex \balloonLengthOn
+@funindex balloonLengthOn
+@funindex \balloonLengthOff
+@funindex balloonLengthOff
 
 Elements of notation can be marked and named with the help of a
 square balloon.  The primary purpose of this feature is to explain
 notation.
 
-The following example demonstrates its use.
-
-@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+@lilypond[verbatim,quote,relative=2]
 \new Voice \with { \consists "Balloon_engraver" }
-     {
-      \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. 
-     }
+{
+  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
+  a8
+  \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
+  r
+  <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2.
+}
 @end lilypond
 
+
 There are two music functions, @code{balloonGrobText} and
-@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.
+@code{balloonText};  the former is used like
+@w{@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:
 
-@seealso
+@lilypond[verbatim,quote,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
+@code{\balloonLengthOn},
+@code{\balloonLengthOff}.
+@endpredefined
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
 
-Internals Reference: @internalsref{text-balloon-interface}.
+@seealso
+Snippets:
+@rlsr{Editorial annotations}.
+
+Internals Reference:
+@rinternals{Balloon_engraver},
+@rinternals{BalloonTextItem},
+@rinternals{balloon-interface}.
 
 
 @node Grid lines
-@subsubsection Grid lines
+@unnumberedsubsubsec Grid lines
+
+@cindex grid lines
+@cindex lines, grid
+@cindex vertical lines between staves
+@cindex lines, vertical between staves
+
+@funindex Grid_point_engraver
+@funindex Grid_line_span_engraver
+@funindex gridInterval
 
 Vertical lines can be drawn between staves synchronized with the
 notes.
 
-@lilypond[ragged-right,quote,verbatim]
+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[verbatim,quote]
 \layout {
   \context {
     \Staff
-    \consists "Grid_point_engraver" 
-    % sets up grids
+    \consists "Grid_point_engraver"
     gridInterval = #(ly:make-moment 1 4)
-    % this sets the grid interval to 1 quarternote (crotchet)
-  }
-}
-
-\new Score \with {
-  \consists "Grid_line_span_engraver"
-  %% by default this centers grid lines horizontally below and to the 
-  % left side of the notehead, the grid lines extend from 
-  % the middle lines of each staff
-}
-
-\new ChoirStaff <<
-  \new Staff {
-    \stemUp
-    \relative {
-      c'4. d8 e8 f g4
-    }
-  }
-  \new Staff {
-    \stemDown
-    \clef bass
-    \relative c {
-      c4  g'  f  e
-    }
   }
->>
-@end lilypond
-
-To change the grid lines use \override.
-
-
-@lilypond[ragged-right,quote,verbatim]
-\layout {
   \context {
-    \Staff
-    \consists "Grid_point_engraver" 
-    % sets up grids
-       gridInterval = #(ly:make-moment 1 4)
-       % this sets the grid interval to 1 quarternote (crotchet)
+    \Score
+    \consists "Grid_line_span_engraver"
   }
 }
 
-\new Score \with {
-  \consists "Grid_line_span_engraver"
-  \override NoteColumn #'X-offset = #-0.5
-  % this moves them to the right half a staff space
-}
-
-\new ChoirStaff <<
-  \new Staff {
-    \stemUp
-    \relative {
-      c'4. d8 e8 f g4
+\score {
+  \new ChoirStaff <<
+    \new Staff \relative c'' {
+      \stemUp
+      c4. d8 e8 f g4
     }
-  }
-  \new Staff {
-    \override Score.GridLine #'extra-offset = #'( 0.0 . 1.0 )
-    % this moves them up one staff space from the default position
-    \stemDown
-    \clef bass
-    \relative c {
-      c4  g'  f  e
+    \new Staff \relative c {
+      \clef bass
+      \stemDown
+      c4 g' f e
     }
-  }
->>
+  >>
+}
 @end lilypond
 
-@seealso
+@snippets
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{grid-lines--changing-their-appearance.ly}
 
 
+@seealso
+Snippets:
+@rlsr{Editorial annotations}.
+
+Internals Reference:
+@rinternals{Grid_line_span_engraver},
+@rinternals{Grid_point_engraver},
+@rinternals{GridLine},
+@rinternals{GridPoint},
+@rinternals{grid-line-interface},
+@rinternals{grid-point-interface}.
 
 
 @node Analysis brackets
-@subsubsection Analysis brackets
+@unnumberedsubsubsec Analysis brackets
 
 @cindex brackets
-@cindex phrasing brackets
+@cindex bracket, phrasing
+@cindex phrasing bracket
 @cindex musicological analysis
+@cindex analysis, musicological
 @cindex note grouping bracket
+@cindex horizontal bracket
+@cindex bracket, horizontal
+
+@funindex Horizontal_bracket_engraver
+@funindex \startGroup
+@funindex startGroup
+@funindex \stopGroup
+@funindex stopGroup
 
 Brackets are used in musical analysis to indicate structure in musical
-pieces.  LilyPond supports a simple form of nested horizontal
-brackets.  To use this, add the @code{Horizontal_bracket_engraver} to
-the @code{Staff} context.  A bracket is started with
-@code{\startGroup} and closed with @code{\stopGroup}.
+pieces.  Simple horizontal brackets are supported.
 
-@lilypond[quote,ragged-right,verbatim]
-\score {
-  \relative c'' {
-    c4\startGroup\startGroup
-    c4\stopGroup
-    c4\startGroup
-    c4\stopGroup\stopGroup
-  }
-  \layout {
-    \context {
-      \Staff \consists "Horizontal_bracket_engraver"
-    }
+@lilypond[verbatim,quote]
+\layout {
+  \context {
+    \Voice
+    \consists "Horizontal_bracket_engraver"
   }
 }
+\relative c'' {
+  c2\startGroup
+  d\stopGroup
+}
 @end lilypond
 
-@seealso
+Analysis brackets may be nested.
 
-Snippets: @lsrdir{Editorial,Editorial-annotations}.
+@lilypond[verbatim,quote]
+\layout {
+  \context {
+    \Voice
+    \consists "Horizontal_bracket_engraver"
+  }
+}
+\relative c'' {
+  c4\startGroup\startGroup
+  d4\stopGroup
+  e4\startGroup
+  d4\stopGroup\stopGroup
+}
+@end lilypond
 
-Internals Reference: @internalsref{HorizontalBracket},
-@internalsref{Horizontal_bracket_engraver}, @internalsref{Staff}.
+
+@seealso
+Snippets:
+@rlsr{Editorial annotations}.
+
+Internals Reference:
+@rinternals{Horizontal_bracket_engraver},
+@rinternals{HorizontalBracket},
+@rinternals{horizontal-bracket-interface},
+@rinternals{Staff}.