From 1773bc10cb85bf13d2bfaa957fc053462fe9355e Mon Sep 17 00:00:00 2001
From: Carl Sorensen <c_sorensen@byu.edu>
Date: Wed, 10 Dec 2008 21:54:21 -0700
Subject: [PATCH] Revert "DOC -- Index editorial, pitches, staff.  Ralph
 Palmer's work"

This reverts commit 24a0f9cfb8746e118d8acad35feda38a0f3172f4.
---
 Documentation/user/editorial.itely |   38 +-
 Documentation/user/pitches.itely   |  105 +-
 Documentation/user/staff.itely     | 1475 ++++++++++++++++++----------
 3 files changed, 1011 insertions(+), 607 deletions(-)

diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely
index 568356bef9..c8d021a84a 100644
--- a/Documentation/user/editorial.itely
+++ b/Documentation/user/editorial.itely
@@ -45,7 +45,6 @@ inside the staff.
 @cindex selecting font size (notation)
 @cindex notation font size
 @cindex note heads
-
 @funindex fontSize
 @funindex font-size
 @funindex magstep
@@ -106,7 +105,6 @@ c4.-> d8---3
 
 @cindex standard font size (notation)
 @cindex font size (notation), standard
-
 @funindex font-interface
 @funindex font-size
 
@@ -121,11 +119,17 @@ that use fonts.  These are the ones supporting the
 
 
 @predefined
+@funindex \teeny
 @code{\teeny},
+@funindex \tiny
 @code{\tiny},
+@funindex \small
 @code{\small},
+@funindex \normalsize
 @code{\normalsize},
+@funindex \large
 @code{\large},
+@funindex \huge
 @code{\huge}.
 @endpredefined
 
@@ -143,7 +147,6 @@ Internals Reference:
 
 @cindex fingering
 @cindex finger change
-
 @funindex \finger
 @funindex finger
 
@@ -161,7 +164,6 @@ c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
 @end lilypond
 
 @cindex thumb-script
-
 @funindex \thumb
 @funindex thumb
 
@@ -222,7 +224,6 @@ Internals Reference:
 @cindex notes, hidden
 @cindex notes, invisible
 @cindex notes, transparent
-
 @funindex \hideNotes
 @funindex hideNotes
 @funindex \unHideNotes
@@ -272,7 +273,6 @@ Internals Reference:
 @unnumberedsubsubsec Coloring objects
 
 @cindex colored objects
-@cindex objects, colored
 @cindex colors
 @cindex coloring objects
 @cindex colored notes
@@ -281,7 +281,6 @@ Internals Reference:
 @cindex x11 color
 @cindex x11-color
 @cindex with-color
-
 @funindex color
 @funindex \with-color
 @funindex with-color
@@ -331,7 +330,6 @@ b2 cis
 @cindex rgb-color
 @cindex color, rgb
 @cindex rgb color
-
 @funindex rgb-color
 
 Exact RGB colors can be specified using the Scheme function
@@ -365,7 +363,6 @@ Snippets:
 @cindex colored notes in chords
 @cindex notes, colored in chords
 @cindex color in chords
-
 @funindex x11-color
 
 @knownissues
@@ -389,7 +386,6 @@ Notes in a chord cannot be colored with @code{\override}; use
 @cindex notes, ghost
 @cindex notes, parenthesized
 @cindex parentheses
-
 @funindex \parenthesize
 @funindex parenthesize
 
@@ -435,21 +431,17 @@ chord.
 @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
 @code{\stemUp},
+@funindex \stemDown
 @code{\stemDown},
+@funindex \stemNeutral
 @code{\stemNeutral}.
 @endpredefined
 
@@ -497,16 +489,11 @@ from outside of the staff.
 @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
@@ -548,7 +535,11 @@ altered:
 
 
 @predefined
+@funindex balloonLengthOn
+@funindex \balloonLengthOn
 @code{\balloonLengthOn},
+@funindex \balloonLengthOff
+@funindex balloonLengthOff
 @code{\balloonLengthOff}.
 @endpredefined
 
@@ -570,7 +561,6 @@ Internals Reference:
 @cindex lines, grid
 @cindex vertical lines between staves
 @cindex lines, vertical between staves
-
 @funindex Grid_point_engraver
 @funindex Grid_line_span_engraver
 @funindex gridInterval
@@ -640,11 +630,9 @@ Internals Reference:
 @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
diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index 9224f8e1bb..977ac59fe3 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -47,9 +47,7 @@ mode.  In most cases, relative mode will be more convenient.
 @cindex pitches
 @cindex absolute
 @cindex absolute octave specification
-@cindex octave specification, absolute
 @cindex absolute octave entry
-@cindex octave entry, absolute
 
 A pitch name is specified using lowercase letters@tie{}@code{a}
 through@tie{}@code{g}.  The note names @code{c} to @code{b} are
@@ -64,7 +62,6 @@ d e f g
 @end lilypond
 
 @cindex octave changing mark
-
 @funindex '
 @funindex ,
 
@@ -96,11 +93,7 @@ Snippets:
 
 @cindex relative
 @cindex relative octave entry
-@cindex octave entry, relative
 @cindex relative octave specification
-@cindex ocatve specification, relative
-
-@funindex relative
 @funindex \relative
 
 When octaves are specified in absolute mode it is easy to
@@ -175,9 +168,6 @@ large intervals:
 }
 @end lilypond
 
-@cindex chords and relative octave entry
-@cindex relative octave entry and chords
-
 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
@@ -229,13 +219,9 @@ Internals Reference:
 
 @cindex relative octave entry and transposition
 @cindex transposition and relative octave entry
-
 @funindex \transpose
-@funindex transpose
 @funindex \chordmode
-@funindex chordmode
 @funindex \relative
-@funindex relative
 
 
 @knownissues
@@ -270,7 +256,6 @@ see @rlearning{Accidentals and key signatures}.}
 
 @cindex note names, Dutch
 @cindex note names, default
-@cindex default note names
 @cindex sharp
 @cindex flat
 @cindex double sharp
@@ -301,8 +286,7 @@ a4 aes a2
 @end lilypond
 
 @cindex quarter tones
-@cindex semi-flats
-@cindex semi-sharps
+@cindex semi-flats, semi-sharps
 
 Quarter tones may be added; the following is a series of Cs with
 increasing pitches:
@@ -317,13 +301,11 @@ ceseh1 ces ceh c cih cis cisih
 @cindex accidental, cautionary
 @cindex accidental, parenthesized
 @cindex reminder accidental
+@funindex ?
 @cindex cautionary accidental
 @cindex parenthesized accidental
-
-@funindex ?
 @funindex !
 
-
 Normally accidentals are printed automatically, but you may also
 print them manually.  A reminder accidental can be forced by
 adding an exclamation mark@tie{}@code{!} after the pitch.  A
@@ -548,10 +530,8 @@ This section discusses how to modify pitches.
 @cindex octave correction
 @cindex octave check
 @cindex control pitch
-
 @funindex =
 @funindex \octaveCheck
-@funindex octaveCheck
 @funindex controlpitch
 
 In relative mode, it is easy to forget an octave changing mark.
@@ -625,9 +605,7 @@ Internals Reference:
 @cindex transposition of notes
 @cindex pitches, transposition of
 @cindex notes, transposition of
-
 @funindex \transpose
-@funindex transpose
 
 A music expression can be transposed with @code{\transpose}.  The
 syntax is
@@ -692,6 +670,8 @@ music = \relative c' { c d e f }
 }
 @end lilypond
 
+@cindex transposing instruments
+@cindex instruments, transposing
 
 @code{\transpose} may also be used in a different way, to input
 written notes for a transposing instrument.  The previous examples
@@ -739,11 +719,8 @@ Internals Reference:
 
 
 @funindex \transpose
-@funindex transpose
 @funindex \chordmode
-@funindex chordmode
 @funindex \relative
-@funindex relative
 
 @knownissues
 
@@ -771,6 +748,7 @@ This section discusses how to alter the output of pitches.
 @node Clef
 @unnumberedsubsubsec Clef
 
+@funindex \clef
 @cindex G clef
 @cindex C clef
 @cindex F clef
@@ -803,9 +781,6 @@ This section discusses how to alter the output of pitches.
 @cindex clef, varbaritone
 @cindex subbass clef, subbass
 
-@funindex \clef
-@funindex clef
-
 The clef may be altered.  Middle C is shown in every example.
 
 @lilypond[verbatim,quote,relative=1]
@@ -850,7 +825,6 @@ and @ref{Gregorian clefs}.
 @cindex clef, transposing
 @cindex octave transposition
 @cindex choral tenor clef
-@cindex tenor clef, choral
 
 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
 clef is transposed one octave down or up, respectively,
@@ -892,9 +866,7 @@ Internals Reference:
 @unnumberedsubsubsec Key signature
 
 @cindex key signature
-
 @funindex \key
-@funindex key
 
 @c duplicated in Key signature and Accidentals
 @warning{New users are sometimes confused about accidentals and
@@ -913,24 +885,14 @@ at the start of the staff.  The key signature may be altered:
 @end example
 
 @funindex \major
-@funindex major
 @funindex \minor
-@funindex minor
 @funindex \ionian
-@funindex ionian
 @funindex \locrian
-@funindex locrian
 @funindex \aeolian
-@funindex aeolian
 @funindex \mixolydian
-@funindex mixolydian
 @funindex \lydian
-@funindex lydian
 @funindex \phrygian
-@funindex phrygian
 @funindex \dorian
-@funindex dorian
-
 @cindex church modes
 @cindex modes
 @cindex major
@@ -996,10 +958,7 @@ Internals Reference:
 @cindex 8va
 @cindex 8ve
 @cindex octavation
-
 @funindex set-octavation
-@funindex \ottava
-@funindex ottava
 
 @notation{Ottava brackets} introduce an extra transposition of an
 octave for the staff:
@@ -1043,9 +1002,7 @@ Internals Reference:
 @cindex transposing instrument
 @cindex MIDI
 @cindex MIDI transposition
-
 @funindex \transposition
-@funindex transposition
 
 When typesetting scores that involve transposing instruments, some
 parts can be typeset in a different pitch than the
@@ -1139,10 +1096,8 @@ Snippets:
 @cindex accidentals, automatic
 @cindex automatic accidentals
 @cindex default accidental style
-
 @funindex set-accidental-style
 @funindex voice
-@funindex default
 
 There are many different conventions on how to typeset
 accidentals.  LilyPond provides a function to specify which
@@ -1169,6 +1124,7 @@ style in all staves of the current @code{StaffGroup}, use:
 The following accidental styles are supported.  To demonstrate
 each style, we use the following example:
 
+@funindex default
 
 @lilypond[verbatim,quote]
 musicA = {
@@ -1242,7 +1198,6 @@ both staves.
 
 @cindex default accidental style
 @cindex accidental style, default
-
 @funindex default
 
 This is the default typesetting behavior.  It corresponds to
@@ -1306,7 +1261,6 @@ musicB = {
 @cindex modern accidental style
 @cindex accidental style, modern-cautionary
 @cindex modern-cautionary accidental style
-
 @funindex voice
 
 The normal behavior is to remember the accidentals at
@@ -1374,7 +1328,6 @@ musicB = {
 
 @cindex accidentals, modern style
 @cindex modern style accidentals
-
 @funindex modern
 
 This rule corresponds to the common practice in the twentieth
@@ -1439,7 +1392,6 @@ musicB = {
 @cindex modern cautionary accidental style
 @cindex modern style accidentals
 @cindex modern style cautionary accidentals
-
 @funindex modern-cautionary
 
 This rule is similar to @code{modern}, but the @q{extra}
@@ -1503,7 +1455,6 @@ musicB = {
 @cindex modern accidental style
 @cindex modern accidentals
 @cindex multivoice accidentals
-
 @funindex modern-voice
 
 This rule is used for multivoice accidentals to be read both by
@@ -1564,7 +1515,6 @@ musicB = {
 @cindex accidental style, cautionary, modern voice
 @cindex accidental style, modern voice cautionary
 @cindex accidental style, voice, modern cautionary
-
 @funindex modern-voice-cautionary
 
 @item modern-voice-cautionary
@@ -1627,7 +1577,6 @@ musicB = {
 @cindex accidentals, piano
 @cindex piano accidental style
 @cindex piano accidentals
-
 @funindex piano
 
 This rule reflects twentieth-century practice for piano notation.
@@ -1686,6 +1635,7 @@ musicB = {
 
 @item piano-cautionary
 
+@funindex piano-cautionary
 @cindex accidentals, piano cautionary
 @cindex cautionary accidentals, piano
 @cindex piano cautionary accidentals
@@ -1693,8 +1643,6 @@ musicB = {
 @cindex cautionary accidental style, piano
 @cindex piano cautionary accidental style
 
-@funindex piano-cautionary
-
 This is the same as @code{piano} but with the extra accidentals
 typeset as cautionaries.
 
@@ -1746,11 +1694,10 @@ musicB = {
 
 @item neo-modern
 
+@funindex neo-modern
 @cindex neo-modern accidental style
 @cindex accidental style, neo-modern
 
-@funindex neo-modern
-
 This rule reproduces a common practice in contemporary music:
 accidentals are printed like with @code{modern}, but they are printed
 again if the same note appears later in the same measure -- except
@@ -1804,11 +1751,10 @@ musicB = {
 
 @item neo-modern-cautionary
 
+@funindex neo-modern-cautionary
 @cindex neo-modern-cautionary accidental style
 @cindex accidental style, neo-modern-cautionary
 
-@funindex neo-modern-cautionary
-
 This rule is similar to @code{neo-modern}, but the extra
 accidentals are printed as cautionary accidentals.
 
@@ -1861,11 +1807,10 @@ musicB = {
 
 @item dodecaphonic
 
+@funindex dodecaphonic
 @cindex dodecaphonic accidental style
 @cindex dodecaphonic style, neo-modern
 
-@funindex dodecaphonic
-
 This rule reflects a practice introduced by composers at
 the beginning of the 20th century, in an attempt to
 abolish the hierarchy between natural and non-natural notes.
@@ -1921,11 +1866,10 @@ musicB = {
 
 @item teaching
 
+@funindex teaching
 @cindex teaching accidental style
 @cindex accidental style, teaching
 
-@funindex teaching
-
 This rule is intended for students, and makes it easy to create
 scale sheets with automagically created cautionary accidentals.
 Accidentals are printed like with @code{modern}, but cautionary
@@ -1984,11 +1928,10 @@ musicB = {
 
 @item no-reset
 
+@funindex no-reset
 @cindex accidental style, no reset
 @cindex no reset accidental style
 
-@funindex no-reset
-
 This is the same as @code{default} but with accidentals lasting
 @q{forever} and not only within the same measure:
 
@@ -2040,11 +1983,10 @@ musicB = {
 
 @item forget
 
+@funindex forget
 @cindex forget accidental style
 @cindex accidental style, forget
 
-@funindex forget
-
 This is the opposite of @code{no-reset}: Accidentals are not
 remembered at all -- and hence all accidentals are typeset
 relative to the key signature, regardless of what came before in
@@ -2231,7 +2173,6 @@ This section suggests ways of altering note heads.
 @cindex guitar note heads
 @cindex note head styles
 @cindex styles, note heads
-
 @funindex cross
 
 Note heads may be altered:
@@ -2286,11 +2227,6 @@ Internals Reference:
 @cindex easy play note heads
 @cindex note heads, easy play
 
-@funindex \easyHeadsOn
-@funindex easyHeadsOn
-@funindex \easyHeadsOff
-@funindex easyHeadsOff
-
 The @q{easy play} note head includes a note name inside the head.
 It is used in music for beginners.  To make the letters readable,
 it should be printed in a large font size.  To print with a larger
@@ -2309,7 +2245,9 @@ font, see @ref{Setting the staff size}.
 
 
 @predefined
+@funindex \easyHeadsOn
 @code{\easyHeadsOn},
+@funindex \easyHeadsOff
 @code{\easyHeadsOff}.
 @endpredefined
 
@@ -2337,13 +2275,9 @@ Internals Reference:
 @cindex shape notes
 @cindex Aiken shape note heads
 @cindex sacred harp note heads
-
 @funindex \key
-@funindex key
 @funindex \aikenHeads
-@funindex aikenHeads
 @funindex \sacredHarpHeads
-@funindex sacredHarpHeads
 
 In shape note head notation, the shape of the note head
 corresponds to the harmonic function of a note in the scale.  This
@@ -2362,7 +2296,9 @@ base of the scale is determined by the @code{\key} command.
 
 
 @predefined
+@funindex \aikenHeads
 @code{\aikenHeads},
+@funindex \sacredHarpHeads
 @code{\sacredHarpHeads}.
 @endpredefined
 
@@ -2398,11 +2334,6 @@ Internals Reference:
 @cindex note heads, improvisation
 @cindex note heads, slashed
 
-@funindex \improvisationOn
-@funindex improvisationOn
-@funindex \improvisationOff
-@funindex improvisationOff
-
 Improvisation is sometimes denoted with slashed note heads, where
 the performer may choose any pitch but should play the specified
 rhythm.  Such note heads can be created:
@@ -2423,7 +2354,9 @@ rhythm.  Such note heads can be created:
 
 
 @predefined
+@funindex \improvisationOn
 @code{\improvisationOn},
+@funindex \improvisationOff
 @code{\improvisationOff}.
 @endpredefined
 
diff --git a/Documentation/user/staff.itely b/Documentation/user/staff.itely
index acb129d021..3791eacb71 100644
--- a/Documentation/user/staff.itely
+++ b/Documentation/user/staff.itely
@@ -6,412 +6,852 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
+@c \version "2.11.64"
+
 @node Staff notation
 @section Staff notation
 
-@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-{staff-headword.ly}
-
-Notes, dynamic signs, rests, etc., are grouped with a set of horizontal
-lines, called a staff (plural @q{staves}).  In LilyPond, these
-lines are drawn using a separate layout object called @code{staff
-symbol}.
-
-Two or more staves can be grouped vertically in a @code{GrandStaff}, a
-@code{StaffGroup}, or a @code{ChoirStaff}.
+@lilypondfile[quote]{staff-headword.ly}
 
+This section explains how to influence the appearance of staves,
+how to print scores with more than one staff, and how to add tempo
+indications and cue notes to staves.
 
 @menu
-* Displaying staves::           
-* Writing parts::               
+* Displaying staves::
+* Modifying single staves::
+* Writing parts::
 @end menu
 
 
 @node Displaying staves
 @subsection Displaying staves
 
+This section describes the different methods of creating and
+grouping staves.
+
 @menu
-* System start delimiters::     
-* Staff symbol::                
-* Hiding staves::               
+* Instantiating new staves::
+* Grouping staves::
+* Nested staff groups::
 @end menu
 
-@node System start delimiters
-@unnumberedsubsubsec System start delimiters
+
+@node Instantiating new staves
+@unnumberedsubsubsec Instantiating new staves
+
+@cindex new staff
+@cindex staff initiation
+@cindex staff instantiation
+@cindex staff, new
+@cindex staff, single
+@cindex drum staff
+@cindex percussion staff
+@cindex Gregorian transcription staff
+@cindex rhythmic staff
+@cindex tabstaff
+@cindex tablature
+
+@notation{Staves} (singular: @notation{staff}) are created with
+the @code{\new} or @code{\context} commands.  For details, see
+@ref{Creating contexts}.
+
+The basic staff context is @code{Staff}:
+
+@lilypond[verbatim,quote,relative=2]
+\new Staff { c4 d e f }
+@end lilypond
+
+The @code{DrumStaff} context creates a five-line staff set up for
+a typical drum set.  Each instrument is shown with a different
+symbol.  The instruments are entered in drum mode following a
+@code{\drummode} command, with each instrument specified by name.
+For details, see @ref{Percussion staves}.
+
+@lilypond[verbatim,quote]
+\new DrumStaff {
+  \drummode { cymc hh ss tomh }
+}
+@end lilypond
+
+@code{RhythmicStaff} creates a single-line staff that only
+displays the rhythmic values of the input.  Real durations are
+preserved. For details, see @ref{Showing melody rhythms}.
+
+@lilypond[verbatim,quote,relative=2]
+\new RhythmicStaff { c4 d e f }
+@end lilypond
+
+@code{TabStaff} creates a tablature with six strings in standard
+guitar tuning.  For details, see @ref{Default tablatures}.
+
+@lilypond[verbatim,quote,relative=2]
+\new TabStaff { c4 d e f }
+@end lilypond
+
+There are two staff contexts specific for the notation of ancient
+music: @code{MensuralStaff} and @code{VaticanaStaff}.  They are
+described in @ref{Pre-defined contexts}.
+
+The @code{GregorianTranscriptionStaff} context creates a staff to
+notate modern Gregorian chant.  It does not show bar lines.
+
+@lilypond[verbatim,quote,relative=2]
+\new GregorianTranscriptionStaff { c4 d e f e d }
+@end lilypond
+
+New single staff contexts may be defined.  For details, see
+@ref{Defining new contexts}.
+
+
+@seealso
+Music Glossary:
+@rglos{staff},
+@rglos{staves}.
+
+Notation Reference:
+@ref{Creating contexts},
+@ref{Percussion staves},
+@ref{Showing melody rhythms},
+@ref{Default tablatures},
+@ref{Pre-defined contexts},
+@ref{Staff symbol},
+@ref{Gregorian chant contexts},
+@ref{Mensural contexts},
+@ref{Defining new contexts}.
+
+Snippets:
+@rlsr{Staff notation}.
+
+Internals Reference:
+@rinternals{Staff},
+@rinternals{DrumStaff},
+@rinternals{GregorianTranscriptionStaff},
+@rinternals{RhythmicStaff},
+@rinternals{TabStaff},
+@rinternals{MensuralStaff},
+@rinternals{VaticanaStaff},
+@rinternals{StaffSymbol}.
+
+
+@node Grouping staves
+@unnumberedsubsubsec Grouping staves
 
 @cindex start of system
 @cindex staff, multiple
-@cindex vertical bracket
+@cindex staves, multiple
+@cindex system start delimiters
 @cindex bracket, vertical
 @cindex brace, vertical
-@cindex vertical brace
+@cindex choir staff
 @cindex grand staff
+@cindex piano staff
 @cindex staff group
 @cindex staff, choir
+@cindex staff, piano
 @cindex system
 
-Many scores consist of more than one staff.  These staves can be
-grouped in several different ways:
+Various contexts exist to group single staves together in order to
+form multi-stave systems.  Each grouping context sets the style of
+the system start delimiter and the behavior of bar lines.
 
-@itemize
-@item
-In a @code{GrandStaff}, the group is started with a brace
-at the left, and bar lines are connected between the staves. 
+If no context is specified, the default properties will be used:
+the group is started with a vertical line, and the bar lines are
+not connected.
 
-@lilypond[verbatim,ragged-right,quote]
-\new GrandStaff
-\relative <<
+@lilypond[verbatim,quote,relative=2]
+<<
+  \new Staff { c1 c }
   \new Staff { c1 c }
-  \new Staff { c c }
 >>
 @end lilypond
 
-@item
-In a @code{StaffGroup}, the bar lines will be drawn through
-all the staves, but the group is started with a bracket.
+In the @code{StaffGroup} context, the group is started with a
+bracket and bar lines are drawn through all the staves.
 
-@lilypond[verbatim,ragged-right,quote]
-\new StaffGroup
-\relative <<
+@lilypond[verbatim,quote,relative=2]
+\new StaffGroup <<
+  \new Staff { c1 c }
   \new Staff { c1 c }
-  \new Staff { c c }
 >>
 @end lilypond
 
-@item
-In a @code{ChoirStaff}, the group is started with a
-bracket, but bar lines are not connected. 
+In a @code{ChoirStaff}, the group starts with a bracket, but bar
+lines are not connected.
 
-@lilypond[verbatim,ragged-right,quote]
-\new ChoirStaff
-\relative <<
+@lilypond[verbatim,quote,relative=2]
+\new ChoirStaff <<
+  \new Staff { c1 c }
   \new Staff { c1 c }
-  \new Staff { c c }
 >>
 @end lilypond
 
-@item
-If no context is specified, the default properties for the score
-will be used: the group is started with a vertical line, and the
-bar lines are not connected.  
+In a @code{GrandStaff}, the group begins with a brace, and bar
+lines are connected between the staves.
 
-@lilypond[verbatim,ragged-right,quote]
-\relative <<
+@lilypond[verbatim,quote,relative=2]
+\new GrandStaff <<
+  \new Staff { c1 c }
   \new Staff { c1 c }
-  \new Staff { c c }
 >>
 @end lilypond
-@end itemize
 
-@cindex Mensurstriche layout
-@cindex Renaissance music
+The @code{PianoStaff} is identical to a @code{GrandStaff}, except
+that it supports printing the instrument name directly.  For
+details, see @ref{Instrument names}.
 
-In addition to these four staff group types, other groupings can
-be produced by changing various properties. E.g., the
-@q{Mensurstriche} layout common in Renaissance music, with
-bar lines running between but not through the staves, can be
-produced from a @code{StaffGroup} or @code{GrandStaff} context if
-the bar lines are made transparent in the @code{Staff} itself, with
-the command @code{\override Staff.BarLine #'transparent = ##t}
+@lilypond[verbatim,quote,relative=2]
+\new PianoStaff <<
+  \set PianoStaff.instrumentName = "Piano"
+  \new Staff { c1 c }
+  \new Staff { c1 c }
+>>
+@end lilypond
 
-@cindex staff, nested
+Each staff group context sets the property
+@code{systemStartDelimiter} to one of the following values:
+@code{SystemStartBar}, @code{SystemStartBrace}, or
+@code{SystemStartBracket}.  A fourth delimiter,
+@code{SystemStartSquare}, is also available, but it must be
+explicitly specified.
+
+New staff group contexts may be defined.  For details, see
+@ref{Defining new contexts}.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{use-square-bracket-at-the-start-of-a-staff-group.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{display-bracket-with-only-one-staff-in-a-system.ly}
+
+@cindex mensurstriche layout
+@cindex renaissance music
+@cindex transcription of mensural music
+@cindex mensural music, transcription of
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{mensurstriche-layout-bar-lines-between-the-staves.ly}
+
+
+@seealso
+Music Glossary:
+@rglos{brace},
+@rglos{bracket},
+@rglos{grand staff}.
+
+Notation Reference:
+@ref{Instrument names},
+@ref{Defining new contexts}.
+
+Snippets:
+@rlsr{Staff notation}.
 
-Staff groups can be nested, using the context
-@code{InnerStaffGroup} or @code{InnerChoirStaff}; see
-@lsr{staff,staff-brackets.ly}
-@c snippet 137
-
-@commonprop
-
-More complex nesting can be accomplished using the property
-@code{systemStartDelimiterHierarchy}: 
-
-@lilypond[quote,ragged-right,verbatim]
-\new StaffGroup
-\relative <<
-  \set StaffGroup.systemStartDelimiterHierarchy
-    = #'(SystemStartSquare (SystemStartBracket a
-                             (SystemStartSquare b)) d)
-  \new Staff { c1 }
-  \new Staff { c1 }
-  \new Staff { c1 }
-  \new Staff { c1 }
-  \new Staff { c1 }
+Internals Reference:
+@rinternals{Staff},
+@rinternals{StaffGroup},
+@rinternals{ChoirStaff},
+@rinternals{GrandStaff},
+@rinternals{PianoStaff},
+@rinternals{SystemStartBar},
+@rinternals{SystemStartBrace},
+@rinternals{SystemStartBracket},
+@rinternals{SystemStartSquare}.
+
+
+@node Nested staff groups
+@unnumberedsubsubsec Nested staff groups
+
+@cindex staff, nested
+@cindex staves, nested
+@cindex nesting of staves
+@cindex system start delimiters, nested
+@cindex nested staff brackets
+@cindex brackets, nesting of
+@cindex braces, nesting of
+
+Staff-group contexts can be nested to arbitrary depths.  In this
+case, each child context creates a new bracket adjacent to the
+bracket of its parent group.
+
+@lilypond[verbatim,quote,relative=2]
+\new StaffGroup <<
+  \new Staff { c2 c | c2 c }
+  \new StaffGroup <<
+    \new Staff { g2 g | g2 g }
+    \new StaffGroup \with {
+      systemStartDelimiter = #'SystemStartSquare
+    }
+    <<
+      \new Staff { e2 e | e2 e }
+      \new Staff { c2 c | c2 c }
+    >>
+  >>
 >>
 @end lilypond
 
-Each staff group context sets the property
-@code{systemStartDelimiter} to one of the values
-@internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
-and @internalsref{SystemStartBracket}.  A fourth delimiter,
-@code{systemStartSquare}, is also available, but must be
-instantiated manually.
-
-@c FIXME: Graham will deal with this.  -gp
-@c snippet 201
-To display a bracket even if there is only one staff, see
-@lsr{staff,display-bracket-with-only-one-staff-in-a
-system.ly}
+New nested staff group contexts can be defined.  For details, see
+@ref{Defining new contexts}.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{nesting-staves.ly}
+
 
 @seealso
+Notation Reference:
+@ref{Grouping staves},
+@ref{Instrument names},
+@ref{Defining new contexts}.
+
+Snippets:
+@rlsr{Staff notation}.
 
-Music Glossary: @rglos{brace}, @rglos{staff}, @rglos{staves}
-@rglos{bracket}.
+Internals Reference:
+@rinternals{StaffGroup},
+@rinternals{ChoirStaff},
+@rinternals{SystemStartBar},
+@rinternals{SystemStartBrace},
+@rinternals{SystemStartBracket},
+@rinternals{SystemStartSquare}.
 
-Snippets: @lsrdir{staff}
 
-Internals Reference: @internalsref{ChoirStaff},
-@internalsref{GrandStaff}, @internalsref{StaffGroup},
-@internalsref{SystemStartBar}, @internalsref{SystemStartBrace},
-@internalsref{SystemStartBracket},
-@internalsref{systemStartDelimiterHierarchy}.
+@node Modifying single staves
+@subsection Modifying single staves
+
+This section explains how to change specific attributes of one
+staff: for example, modifying the number of staff lines or the
+staff size.  Methods to start and stop staves and set ossia
+sections are also described.
+
+@menu
+* Staff symbol::
+* Ossia staves::
+* Hiding staves::
+@end menu
 
 
 @node Staff symbol
 @unnumberedsubsubsec Staff symbol
 
-@cindex staff symbol, adjusting
-@cindex staff, starting
-@cindex staff, stopping
+@cindex adjusting staff symbol
+@cindex drawing staff symbol
+@cindex staff symbol, setting of
+@cindex stop staff lines
+@cindex start staff lines
+@cindex staff lines, amount of
+@cindex staff lines, number of
+@cindex staff line, thickness of
+@cindex amount of staff lines
+@cindex thickness of staff lines
+@cindex ledger lines, setting
+@cindex setting of ledger lines
+@cindex spacing of ledger lines
+@cindex number of staff lines
+
+The lines of a staff belong to the @code{StaffSymbol} grob.
+@code{StaffSymbol} properties can be modified to change the
+appearance of a staff, but they must be modified before the staff
+is created.
+
+The number of staff lines may be changed.  The clef position and
+the position of middle C may need to be modified to fit the new
+staff.  For an explanation, refer to the snippet section in
+@ref{Clef}.
+
+@lilypond[verbatim,quote,relative=2]
+\new Staff \with {
+  \override StaffSymbol #'line-count = #3
+}
+{ d4 d d d }
+@end lilypond
+
+Staff line thickness can be modified.  The thickness of ledger
+lines and stems are also affected, since they depend on staff line
+thickness.
 
-@fundindex \startStaff
-@funindex startStaff
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'thickness = #3
+}
+{ e4 d c b }
+@end lilypond
+
+Ledger line thickness can be set independently of staff line
+thickness.  In the example the two numbers are factors multiplying
+the staff line thickness and the staff line spacing.  The two
+contributions are added to give the ledger line thickness.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
+}
+{ e4 d c b }
+@end lilypond
+
+The distance between staff lines can be changed.  This setting
+affects the spacing of ledger lines as well.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'staff-space = #1.5
+}
+{ a4 b c d }
+@end lilypond
+
+Further details about the properties of @code{StaffSymbol} can be
+found in @rinternals{staff-symbol-interface}.
+
+@funindex \startStaff
 @funindex \stopStaff
-@funindex stopStaff
-
-The layout object which draws the lines of a staff is called
-@code{staff symbol}.  The staff symbol may be tuned in the number,
-thickness and distance of lines, using properties.  This is
-demonstrated in the example files
-@lsr{staff,changing-the-number-of-lines-in-a-staff.ly} and
-@lsr{staff,changing-the-staff-size.ly}.
-
-In addition, staves may be started and stopped at will.  This is
-done with @code{\startStaff} and @code{\stopStaff}.
-
-@lilypond[verbatim,relative=2,fragment]
-b4 b
-\override Staff.StaffSymbol #'line-count = 2
-\stopStaff \startStaff
-b b
+
+Modifications to staff properties in the middle of a score can be
+placed between @code{\stopStaff} and @code{\startStaff}:
+
+@lilypond[verbatim,quote,relative=2]
+c2 c
+\stopStaff
+\override Staff.StaffSymbol #'line-count = #2
+\startStaff
+b2 b
+\stopStaff
 \revert Staff.StaffSymbol #'line-count
-\stopStaff \startStaff
-b b
+\startStaff
+a2 a
 @end lilypond
 
-@cindex staves, Frenched
+@cindex stopping a staff
+
+@noindent
+In general, @code{\startStaff} and @code{\stopStaff} can be used
+to stop or start a staff in the middle of a score.
+
+@lilypond[verbatim,quote,relative=2]
+c4 b a2
+\stopStaff
+b4 c d2
+\startStaff
+e4 d c2
+@end lilypond
+
+
+@predefined
+@code{\startStaff},
+@code{\stopStaff}.
+@endpredefined
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{making-some-staff-lines-thicker-than-the-others.ly}
+
+
+@seealso
+Music Glossary:
+@rglos{line},
+@rglos{ledger line},
+@rglos{staff}.
+
+Notation Reference:
+@ref{Clef}.
+
+Snippets:
+@rlsr{Staff notation}.
+
+Internals Reference:
+@rinternals{StaffSymbol},
+@rinternals{staff-symbol-interface}.
+
+
+@knownissues
+
+When setting vertical staff line positions manually, bar lines are
+always centered on position 0, so the maximum distance between the
+outermost bar lines in either direction must be equal.
+
+
+@node Ossia staves
+@unnumberedsubsubsec Ossia staves
+
+@cindex staff, Frenched
 @cindex ossia
 @cindex Frenched staves
+@cindex staff, resizing of
+@cindex resizing of staves
+
+@notation{Ossia} staves can be set by creating a new simultaneous
+staff in the appropriate location:
+
+@lilypond[verbatim,quote]
+\new Staff \relative c'' {
+  c4 b d c
+  <<
+    { c4 b d c }
+    \new Staff { e4 d f e }
+  >>
+  c4 b c2
+}
+@end lilypond
 
-In combination with Frenched staves, this may be used to typeset
-@emph{ossia} sections.  An example is shown here
+@noindent
+However, the above example is not what is usually desired.  To
+create ossia staves that are above the original staff, have no
+time signature or clef, and have a smaller font size, tweaks must
+be used.  The Learning Manual describes a specific technique to
+achieve this goal, beginning with
+@rlearning{Nesting music expressions}.
+
+The following example uses the @code{alignAboveContext} property
+to align the ossia staff.  This method is most appropriate when
+only a few ossia staves are needed.
+
+@lilypond[verbatim,quote]
+\new Staff = main \relative c'' {
+  c4 b d c
+  <<
+    { c4 b d c }
+
+    \new Staff \with {
+      \remove "Time_signature_engraver"
+      alignAboveContext = #"main"
+      fontSize = #-3
+      \override StaffSymbol #'staff-space = #(magstep -3)
+      \override StaffSymbol #'thickness = #(magstep -3)
+      firstClef = ##f
+    }
+    { e4 d f e }
+  >>
+  c4 b c2
+}
+@end lilypond
+
+If many isolated ossia staves are needed, creating an empty
+@code{Staff} context with a specific @emph{context id} may be more
+appropriate; the ossia staves may then be created by
+@emph{calling} this context and using @code{\startStaff} and
+@code{\stopStaff} at the desired locations.  The benefits of this
+method are more apparent if the piece is longer than the following
+example.
 
-@lilypond[verbatim,relative=2,quote]
+@lilypond[verbatim,quote,ragged-right]
 <<
-  \new Staff \with
-  {
+  \new Staff = ossia \with {
     \remove "Time_signature_engraver"
-    fontSize = #-2
-    \override StaffSymbol #'staff-space = #(magstep -2)
-    firstClef = ##f
+    \override Clef #'transparent = ##t
+    fontSize = #-3
+    \override StaffSymbol #'staff-space = #(magstep -3)
+    \override StaffSymbol #'thickness = #(magstep -3)
   }
-  \relative c'' {
-    \stopStaff
-    \skip 2
-
-    \startStaff
-    \clef treble
-    bes8[^"ossia" g bes g]
-    \stopStaff
+  { \stopStaff s1*6 }
+
+  \new Staff \relative c' {
+    c4 b c2
+    <<
+      { e4 f e2 }
+      \context Staff = ossia {
+        \startStaff e4 g8 f e2 \stopStaff
+      }
+    >>
+    g4 a g2 \break
+    c4 b c2
+    <<
+      { g4 a g2 }
+      \context Staff = ossia {
+        \startStaff g4 e8 f g2 \stopStaff
+      }
+    >>
+    e4 d c2
+  }
+>>
+@end lilypond
 
-    s2
+Using the @code{\RemoveEmptyStaffContext} command to create ossia
+staves may be used as an alternative.  This method is most
+convenient when ossia staves occur immediately following a line
+break.  In this case, spacer rests do not need to be used at all;
+only @code{\startStaff} and @code{\stopStaff} are necessary.  For
+more information about @code{\RemoveEmptyStaffContext}, see
+@ref{Hiding staves}.
 
-    \startStaff
-    f8 d g4 
+@lilypond[verbatim,quote,ragged-right]
+<<
+  \new Staff = ossia \with {
+    \remove "Time_signature_engraver"
+    \override Clef #'transparent = ##t
+    fontSize = #-3
+    \override StaffSymbol #'staff-space = #(magstep -3)
+    \override StaffSymbol #'thickness = #(magstep -3)
   }
-  \new Staff  \relative
-  {
-    \time 2/4
-    c4 c g' g a a g2
+  \new Staff \relative c' {
+    c4 b c2
+    e4 f e2
+    g4 a g2 \break
+    <<
+      { c4 b c2 }
+      \context Staff = ossia {
+        c4 e8 d c2 \stopStaff
+      }
+    >>
+    g4 a g2
+    e4 d c2
   }
-
 >>
+
+\layout {
+  \context {
+    \RemoveEmptyStaffContext
+    \override VerticalAxisGroup #'remove-first = ##t
+  }
+}
 @end lilypond
 
-@cindex staff lines, setting number of
-@cindex staff lines, setting thickness of
-@cindex thickness of staff lines, setting
-@cindex number of staff lines, setting
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{vertically-aligning-ossias-and-lyrics.ly}
+
 
 @seealso
+Music Glossary:
+@rglos{ossia},
+@rglos{staff},
+@rglos{Frenched staff}.
 
-Music Glossary: @rglos{ossia}, @rglos{staff}, @rglos{Frenched staff}.
+Learning Manual:
+@rlearning{Nesting music expressions},
+@rlearning{Size of objects},
+@rlearning{Length and thickness of objects}.
 
-Snippets: @lsrdir{staff}
+Notation Reference:
+@ref{Hiding staves}.
 
-Internals Reference: @internalsref{StaffSymbol},
-@internalsref{DrumStaff}.
+Snippets:
+@rlsr{Staff notation}.
+
+Internals Reference:
+@rinternals{StaffSymbol}.
 
 
 @node Hiding staves
 @unnumberedsubsubsec Hiding staves
 
-@cindex Frenched scores
-@cindex staves, hiding empty
-@cindex hiding empty staves
+@cindex Frenched score
+@cindex Frenched staff
+@cindex staff, hiding
+@cindex staff, empty
+@cindex hiding of staves
+@cindex empty staves
+
+Staff lines can be hidden by removing the
+@code{Staff_symbol_engraver} from the @code{Staff} context.  As an
+alternative, @code{\stopStaff} may be used.
+
+@lilypond[verbatim,quote]
+\new Staff \with {
+  \remove "Staff_symbol_engraver"
+}
+\relative c''' { a8 f e16 d c b a2 }
+@end lilypond
+
+@funindex \RemoveEmptyStaffContext
 
-In orchestral scores, staff lines that only have rests are usually
-removed; this saves some space.  This style is called @q{French
-Score}.  For @code{Lyrics}, @code{ChordNames} and
-@code{FiguredBass}, this is switched on by default.  When
-the lines of these contexts turn out empty after the line-breaking
-process, they are removed.
+Empty staves can be hidden by setting the
+@code{\RemoveEmptyStaffContext} command in the @code{\layout}
+block.  In orchestral scores, this style is known as @q{Frenched
+Score}.  By default, this command hides and removes all empty
+staves in a score except for those in the first system.
 
-For normal staves, a specialized @code{Staff} context is
-available, which does the same: staves containing nothing (or only
-multi-measure rests) are removed.  The context definition is
-stored in @code{\RemoveEmptyStaffContext} variable.  Observe how
-the second staff in this example disappears in the second line
+@warning{A staff is considered empty when it contains only
+multi-measure rests, skips, spacer rests, or a combination of these
+elements.}
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \layout {
-  \context { \RemoveEmptyStaffContext }
+  \context {
+    \RemoveEmptyStaffContext
+  }
 }
 
-{
-  \relative c' <<
-    \new Staff { e4 f g a \break c1 }
-    \new Staff { c4 d e f \break R1 }
-  >>
-}
+\relative c' <<
+  \new Staff {
+    e4 f g a \break
+    b1 \break
+    a4 b c2
+  }
+  \new Staff {
+    c,4 d e f \break
+    R1 \break
+    f4 g c,2
+  }
+>>
 @end lilypond
 
-The first system shows all staves in full.  If empty staves should
-be removed from the first system too, set @code{remove-first} to
-true in @code{VerticalAxisGroup}.
+@cindex ossia
 
-@example
-\override Score.VerticalAxisGroup #'remove-first = ##t
-@end example
+@noindent
+@code{\RemoveEmptyStaffContext} can also be used to create ossia
+sections for a staff.  For details, see @ref{Ossia staves}.
 
-To remove other types of contexts, use
-@code{\AncientRemoveEmptyStaffContext} or
-@code{\RemoveEmptyRhythmicStaffContext}.
+@cindex hiding ancient staves
+@cindex hiding rhythmic staves
+@funindex \AncientRemoveEmptyStaffContext
+@funindex \RemoveEmptyRhythmicStaffContext
 
-@cindex ossia
+The @code{\AncientRemoveEmptyStaffContext} command may be used to
+hide empty staves in ancient music contexts.  Similarly,
+@code{\RemoveEmptyRhythmicStaffContext} may be used to hide empty
+@code{RhythmicStaff} contexts.
 
-Another application of the @code{\RemoveEmptyStaffContext} is to
-make ossia sections, i.e., alternative melodies on a separate
-piece of staff, with help of a Frenched staff.  See @ref{Staff
-symbol}. 
 
-You can make the staff lines invisible by removing the
-@code{Staff_symbol_engraver} from the @code{Staff} context.
+@predefined
+@code{\RemoveEmptyStaffContext},
+@code{\AncientRemoveEmptyStaffContext},
+@code{\RemoveEmptyRhythmicStaffContext}.
+@endpredefined
 
 
-@lilypond[quote,ragged-right,verbatim]
-\score {
-  \context Staff \relative c'' { c8 c c16 c c c }
-  \layout{
-    \context {
-      \Staff
-      \remove Staff_symbol_engraver
-    }
-  }
-}
-@end lilypond
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{removing-the-first-empty-line.ly}
+
 
 @seealso
+Music Glossary:
+@rglos{Frenched staff}.
+
+Notation Reference:
+@ref{Staff symbol},
+@ref{Ossia staves}.
 
-Notation Reference: @ref{Staff symbol}.
+Snippets:
+@rlsr{Staff notation}.
 
-Snippets: @lsrdir{staff}
+Internals Reference:
+@rinternals{ChordNames},
+@rinternals{FiguredBass},
+@rinternals{Lyrics},
+@rinternals{Staff},
+@rinternals{VerticalAxisGroup},
+@rinternals{Staff_symbol_engraver}.
+
+
+@knownissues
+
+Removing @code{Staff_symbol_engraver} also hides bar lines.  If
+bar line visibility is forced, formatting errors may occur.  In
+this case, use the following overrides instead of removing the
+engraver:
+
+@example
+\override StaffSymbol #'stencil = ##f
+\override NoteHead #'no-ledgers = ##t
+@end example
 
-Internals Reference: @internalsref{ChordNames},
-@internalsref{FiguredBass}, @internalsref{Lyrics},
-@internalsref{Staff}, @internalsref{VerticalAxisGroup}.
 
 @node Writing parts
 @subsection Writing parts
 
+This section explains how to insert tempo indications and
+instrument names into a score.  Methods to quote other voices and
+format cue notes are also described.
+
 @menu
-* Metronome marks::             
-* Instrument names::            
-* Quoting other voices::        
-* Formatting cue notes::        
+* Metronome marks::
+* Instrument names::
+* Quoting other voices::
+* Formatting cue notes::
 @end menu
 
+
 @node Metronome marks
 @unnumberedsubsubsec Metronome marks
 
 @cindex tempo
 @cindex beats per minute
 @cindex metronome marking
-
+@cindex metronome marking with text
 @funindex \tempo
-@funindex tempo
 
-Metronome settings can be entered as follows
+A basic metronome mark is simple to write:
 
-@example
-\tempo @var{duration} = @var{per-minute}
-@end example
+@lilypond[verbatim,quote,relative=1]
+\tempo 4 = 120
+c2 d
+e4. d8 c2
+@end lilypond
 
-In the MIDI output, they are interpreted as a tempo change.  In
-the layout output, a metronome marking is printed
+Tempo indications with text can be used instead:
 
+@lilypond[verbatim,quote,relative=2]
+\tempo "Allegretto"
+c4 e d c
+b4. a16 b c4 r4
+@end lilypond
+
+Combining a metronome mark and text will automatically place the
+metronome mark within parentheses:
 
-@lilypond[quote,ragged-right,verbatim,fragment]
-\tempo 8.=120 c''1
+@lilypond[verbatim,quote,relative=2]
+\tempo "Allegro" 4 = 160
+g4 c d e
+d4 b g2
 @end lilypond
 
+In general, the text can be any markup object:
 
-@commonprop
+@lilypond[verbatim,quote,relative=2]
+\tempo \markup { \italic Faster } 4 = 132
+a8-. r8 b-. r gis-. r a-. r
+@end lilypond
 
-To change the tempo in the MIDI output without printing anything,
-make the metronome marking invisible @example \once \override
-Score.MetronomeMark #'transparent = ##t @end example
+A parenthesized metronome mark with no textual indication may be
+written by including an empty string in the input:
 
-To print other metronome markings, use these markup commands
-@lilypond[quote,ragged-right,verbatim,relative,fragment]
-c4^\markup {
-  (
-  \smaller \general-align #Y #DOWN \note #"16." #1
-  =
-  \smaller \general-align #Y #DOWN \note #"8" #1
-  ) }
+@lilypond[verbatim,quote,relative=2]
+\tempo "" 8 = 96
+d4 g e c
 @end lilypond
 
-@noindent
-For more details, see @ref{Text markup}.
 
+@snippets
 
-@seealso
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{printing-metronome-and-rehearsal-marks-below-the-staff.ly}
 
-Music Glossary: @rglos{metronome}, @rglos{metronomic indication},
-@rglos{tempo indication}, @rglos{metronome mark}.
+@c perhaps also an example of how to move it horizontally?
 
-Notation Reference: @ref{Text markup}.
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-tempo-without-a-metronome-mark.ly}
 
-Snippets: @lsrdir{staff}.
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{creating-metronome-marks-in-markup-mode.ly}
 
-Internals Reference: @internalsref{MetronomeMark}, @ref{MIDI
-output}.
+For more details, see @ref{Formatting text}.
 
 
-@refbugs
+@seealso
+Music Glossary:
+@rglos{metronome},
+@rglos{metronomic indication},
+@rglos{tempo indication},
+@rglos{metronome mark}.
 
-Collisions are not checked.  If you have notes above the top line
-of the staff (or notes with articulations, slurs, text, etc), then
-the metronome marking may be printed on top of musical symbols.
-If this occurs, increase the padding of the metronome mark to
-place it further away from the staff.
+Notation Reference:
+@ref{Formatting text},
+@ref{MIDI output}.
 
-@example
-\override Score.MetronomeMark #'padding = #2.5
-@end example
+Snippets:
+@rlsr{Staff notation}.
 
-@c perhaps also an example of how to move it horizontally?
+Internals Reference:
+@rinternals{MetronomeMark}.
 
 
 @node Instrument names
@@ -420,100 +860,92 @@ place it further away from the staff.
 @cindex instrument names
 @cindex instrument names, short
 
-In an orchestral score, instrument names are printed at the left
-side of the staves.
-
-This can be achieved by setting @code{Staff}.@code{instrumentName} and
-@code{Staff}.@code{shortInstrumentName}, or
-@code{PianoStaff}.@code{instrumentName} and
-@code{PianoStaff}.@code{shortInstrumentName}.  This will print text
-before the start of the staff.  For the first staff,
-@code{instrumentName} is used.  If set, @code{shortInstrumentName} is
-used for the following staves.
+Instrument names can be printed on the left side of staves in the
+@code{Staff} and @code{PianoStaff} contexts.  The value of
+@code{instrumentName} is used for the first staff, and the value
+of @code{shortInstrumentName} is used for all succeeding staves.
 
-@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
-\set Staff.instrumentName = "Ploink "
-\set Staff.shortInstrumentName = "Plk "
-c1
+@lilypond[verbatim,quote,ragged-right,relative=1]
+\set Staff.instrumentName = "Violin "
+\set Staff.shortInstrumentName = "Vln "
+c4.. g'16 c4.. g'16
 \break
-c''
+c1
 @end lilypond
 
-You can also use markup texts to construct more complicated
-instrument names, for example
+Markup mode can be used to create more complicated instrument
+names:
 
-@lilypond[quote,fragment,verbatim,ragged-right]
+@lilypond[verbatim,quote,relative=2]
 \set Staff.instrumentName = \markup {
   \column { "Clarinetti"
             \line { "in B" \smaller \flat } } }
-c''1
+c4 c,16 d e f g2
 @end lilypond
 
 @cindex instrument names, centering
-@cindex centering instrument names
-@cindex aligning instrument names
-@cindex instrument names, aligning
-
-If you wish to center the instrument names, you must center all of
-them individually:
-
-@lilypond[quote,verbatim,ragged-right]
-{ <<
-\new Staff {
-  \set Staff.instrumentName = \markup {
-    \center-align { "Clarinetti"
-      \line { "in B" \smaller \flat } } }
-  c''1
-}
-\new Staff {
-  \set Staff.instrumentName =
-       \markup{ \center-align { Vibraphone }}
-  c''1
-}
+
+When two or more staff contexts are grouped together, the
+instrument names and short instrument names are centered by
+default.  To center multi-line instrument names,
+@code{\center-column} must be used:
+
+@lilypond[verbatim,quote,indent=1.5\cm,relative=2]
+<<
+  \new Staff {
+    \set Staff.instrumentName = "Flute"
+    f2 g4 f
+  }
+  \new Staff {
+    \set Staff.instrumentName = \markup \center-column {
+      Clarinet
+      \line { "in B" \smaller \flat }
+    }
+    c4 b c2
+  }
 >>
-}
 @end lilypond
 
-For longer instrument names, it may be useful to increase the
-@code{indent} setting in the @code{\layout} block.
+@cindex indent
+@cindex short-indent
 
-To center instrument names while leaving extra space to the right,
+However, if the instrument names are longer, the instrument names
+in a staff group may not be centered unless the @code{indent} and
+@code{short-indent} settings are increased.  For details about
+these settings, see @ref{Horizontal dimensions}.
 
-@lilypond[quote,verbatim,ragged-right]
-\new StaffGroup \relative
-<<
+@lilypond[verbatim,quote,ragged-right]
+\layout {
+  indent = 3.0\cm
+  short-indent = 1.5\cm
+}
+
+\relative c'' <<
   \new Staff {
-    \set Staff.instrumentName =
-        \markup { \hcenter-in #10 "blabla" }
-    c1 c1
+    \set Staff.instrumentName = "Alto Flute in G"
+    \set Staff.shortInstrumentName = "Fl."
+    f2 g4 f \break
+    g4 f g2
   }
   \new Staff {
-    \set Staff.instrumentName =
-         \markup { \hcenter-in #10 "blo" }
-    c1 c1
+    \set Staff.instrumentName = "Clarinet"
+    \set Staff.shortInstrumentName = "Clar."
+    c,4 b c2 \break
+    c2 b4 c
   }
 >>
 @end lilypond
 
 To add instrument names to other contexts (such as
-@code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}), the
-engraver must be added to that context.
-
-@example
-\layout@{
-  \context @{\GrandStaff \consists "Instrument_name_engraver"@}
-@}
-@end example
-
-@noindent
-More information about adding and removing engravers can be found
-in @ref{Modifying context plug-ins}.
+@code{GrandStaff}, @code{ChoirStaff}, or @code{StaffGroup}),
+@code{Instrument_name_engraver} must be added to that context.
+For details, see @ref{Modifying context plug-ins}.
 
 @cindex instrument names, changing
 
-Instrument names may be changed in the middle of a piece,
+Instrument names may be changed in the middle of a piece:
 
-@lilypond[quote,fragment,verbatim,ragged-right]
+@lilypond[verbatim,quote,ragged-right,relative=1]
 \set Staff.instrumentName = "First"
 \set Staff.shortInstrumentName = "one"
 c1 c c c \break
@@ -524,15 +956,56 @@ c1 c c c \break
 c1 c c c \break
 @end lilypond
 
+@cindex instrument switch
+@cindex switching instruments
+
+If an instrument @emph{switch} is needed,
+@code{\addInstrumentDefinition} may be used in combination with
+@code{\instrumentSwitch} to create a detailed list of the
+necessary changes for the switch.  The
+@code{\addInstrumentDefinition} command has two arguments: an
+identifying string, and an association list of context properties
+and values to be used for the instrument.  It must be placed in
+the toplevel scope.  @code{\instrumentSwitch} is used in the music
+expression to declare the instrument switch:
+
+@lilypond[verbatim,quote,ragged-right]
+\addInstrumentDefinition #"contrabassoon"
+  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
+     (shortInstrumentName . "Cbsn.")
+     (clefGlyph . "clefs.F")
+     (middleCPosition . 6)
+     (clefPosition . 2)
+     (instrumentCueName . ,(make-bold-markup "cbsn."))
+     (midiInstrument . "bassoon"))
+
+\new Staff \with {
+  instrumentName = "Bassoon"
+}
+\relative c' {
+  \clef tenor
+  \compressFullBarRests
+  c2 g'
+  R1*16
+  \instrumentSwitch "contrabassoon"
+  c,,2 g \break
+  c,1 ~ | c1
+}
+@end lilypond
 
-@seealso
 
-Notation Reference: @ref{Modifying context plug-ins}.
+@seealso
+Notation Reference:
+@ref{Horizontal dimensions},
+@ref{Modifying context plug-ins}.
 
-Snippets: @lsrdir{staff}
+Snippets:
+@rlsr{Staff notation}.
 
-Internals Reference: @internalsref{InstrumentName},
-@internalsref{PianoStaff}, @internalsref{Staff}.
+Internals Reference:
+@rinternals{InstrumentName},
+@rinternals{PianoStaff},
+@rinternals{Staff}.
 
 
 @node Quoting other voices
@@ -542,114 +1015,113 @@ Internals Reference: @internalsref{InstrumentName},
 @cindex quoting other voices
 @cindex fragments
 @cindex cue notes
-@cindex cue transposition
-@cindex trasposition of cue notes
-@cindex quote transposition
-@cindex transposition of quotes
-
-@funindex \addQuote
-@funindex addQuote
-@funindex \quoteDuring
-@funindex quoteDuring
-@funindex \cueDuring
-@funindex cueDuring
-@funindex \transposition
-@funindex transposition
-
-With quotations, fragments of other parts can be inserted into a
-part directly.  Before a part can be quoted, it must be marked
-especially as quotable.  This is done with the @code{\addQuote}
-command.
 
-@example
-\addQuote @var{name} @var{music}
-@end example
+It is very common for one voice to double some of the music from
+another voice.  For example, the first and second violins may play the
+same notes during a passage of music.  In LilyPond this is accomplished
+by letting one voice @emph{quote} the other voice without having to
+re-enter it.
 
-
-@noindent
-Here, @var{name} is an identifying string.  The @var{music} is any
-kind of music.  Here is an example of @code{\addQuote}
-
-@example
-\addQuote clarinet \relative c' @{
-  f4 fis g gis
-@}
-@end example
-
-This command must be entered at toplevel, i.e., outside any music
-blocks.  Typically, one would use an already defined music event
-as the @var{music}:
+Before a part can be quoted, the @code{\addQuote} command must be used
+to initialize the quoted fragment.  This command must be used in the
+toplevel scope.  The first argument is an identifying string, and the
+second is a music expression:
 
 @example
-clarinet = \relative c' @{
-  f4 fis g gis
+flute = \relative c'' @{
+  a4 gis g gis
 @}
-\addQuote clarinet @{ \clarinet @}
+\addQuote "flute" @{ \flute @}
 @end example
 
+The @code{\quoteDuring} command is used to indicate the point where the
+quotation begins.  It is followed by two arguments: the name of the
+quoted voice, as defined with @code{\addQuote}, and a music expression
+that indicates the duration of the quote, usually spacer rests or
+multi-measure rests.  The corresponding music from the quoted voice is
+inserted into the music expression:
 
-After calling @code{\addQuote}, the quotation may then be done
-with @code{\quoteDuring} or @code{\cueDuring},
-
-@example
-\quoteDuring #@var{name} @var{music}
-@end example
-
-During a part, a piece of music can be quoted with the
-@code{\quoteDuring} command.
+@lilypond[verbatim,quote]
+flute = \relative c'' {
+  a4 gis g gis
+}
+\addQuote "flute" { \flute }
 
-@example
-\quoteDuring #"clarinet" @{ s2. @}
-@end example
+\relative c' {
+  c4 cis \quoteDuring #"flute" { s2 }
+}
+@end lilypond
 
-This would cite three quarter notes (the duration of @code{s2.})
-of the previously added @code{clarinet} voice.
+If the music expression used for @code{\quoteDuring} contains
+anything but a spacer rest or multi-measure rest, a polyphonic
+situation is created, which is often not desirable:
 
-More precisely, it takes the current time-step of the part being
-printed, and extracts the notes at the corresponding point of the
-@code{\addQuote}d voice.  Therefore, the argument to
-@code{\addQuote} should be the entire part of the voice to be
-quoted, including any rests at the beginning.
+@lilypond[verbatim,quote]
+flute = \relative c'' {
+  a4 gis g gis
+}
+\addQuote "flute" { \flute }
 
-It is possible to use another music expression instead of
-@code{s}, thus creating a polyphonic section, but this may not
-always give the desired result.
+\relative c' {
+  c4 cis \quoteDuring #"flute" { c4 b }
+}
+@end lilypond
 
-Quotations take into account the transposition of both source and
-target instruments, if they are specified using the
-@code{\transposition} command.
+Quotations recognize instrument transposition settings for both
+the source and target instruments if the @code{\transposition}
+command is used.  For details about @code{\transposition}, see
+@ref{Instrument transpositions}.
 
-@lilypond[quote,ragged-right,verbatim]
-\addQuote clarinet \relative c' {
+@lilypond[verbatim,quote]
+clarinet = \relative c'' {
   \transposition bes
-  f4 fis g gis
+  a4 gis g gis
 }
+\addQuote "clarinet" { \clarinet }
 
-{
-  e'8 f'8 \quoteDuring #"clarinet" { s2 }
+\relative c' {
+  c4 cis \quoteDuring #"clarinet" { s2 }
 }
 @end lilypond
 
-The type of events that are present in the quoted music can be
-trimmed with the @code{quotedEventTypes} property.  The default
-value is @code{(note-event rest-event)}, which means that only
-notes and rests of the quoted voice end up in the
-@code{\quoteDuring}.  Setting
+It is possible to tag quotations with unique names in order to
+process them in different ways.  For details about this procedure,
+see @ref{Using tags}.
 
-@example
-\set Staff.quotedEventTypes =
-       #'(note-event articulation-event dynamic-event)
-@end example
 
-@noindent
-will quote notes (but no rests), together with scripts and
-dynamics.
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{quoting-another-voice-with-transposition.ly}
+
+@cindex note-event
+@cindex articulation-event
+@cindex dynamic-event
+@cindex rest-event
+@funindex quotedEventTypes
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{quoting-another-voice.ly}
 
-@refbugs
+
+@seealso
+Notation Reference:
+@ref{Instrument transpositions},
+@ref{Using tags}.
+
+Snippets:
+@rlsr{Staff notation}.
+
+Internals Reference:
+@rinternals{QuoteMusic},
+@rinternals{Voice}.
+
+
+@knownissues
 
 Only the contents of the first @code{Voice} occurring in an
 @code{\addQuote} command will be considered for quotation, so
-@var{music} can not contain @code{\new} and @code{\context Voice}
+@var{music} cannot contain @code{\new} and @code{\context Voice}
 statements that would switch to a different Voice.
 
 Quoting grace notes is broken and can even cause LilyPond to
@@ -660,14 +1132,6 @@ Quoting nested triplets may result in poor notation.
 In earlier versions of LilyPond (pre 2.11), @code{addQuote} was
 written entirely in lower-case letters: @code{\addquote}.
 
-@seealso
-
-Notation Reference: @ref{Instrument transpositions}.
-
-Snippets: @lsrdir{staff}
-
-Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
-
 
 @node Formatting cue notes
 @unnumberedsubsubsec Formatting cue notes
@@ -676,119 +1140,138 @@ Internals Reference: @internalsref{QuoteMusic}, @internalsref{Voice}.
 @cindex cue notes
 @cindex cue notes, formatting
 @cindex fragments
-@cindex quoting other voices 
+@cindex quoting other voices
 @cindex cues, formatting
-@cindex transposing cue notes
-@cindex transposing cues
-@cindex cues, transposing
-@cindex cue notes, transposing
-
-@funindex \cueDuring
-@funindex cueDuring
-@funindex \transposedCueDuring
-@funindex transposedCueDuring
 
-The previous section deals with inserting notes from another
-voice.  There is a more advanced music function called
-@code{\cueDuring}, which makes formatting cue notes easier.
-
-The syntax is
+The previous section explains how to create quotations.  The
+@code{\cueDuring} command is a more specialized form of
+@code{\quoteDuring}, being particularly useful for inserting cue
+notes into a part.  The syntax is as follows:
 
 @example
-  \cueDuring #@var{name} #@var{updown} @var{music}
+\cueDuring #@var{partname} #@var{voice} @var{music}
 @end example
 
-This will insert notes from the part @var{name} into a
-@code{Voice} called @code{cue}.  This happens
-simultaneously with @var{music}, which usually is a rest.  When
-the cue notes start, the staff in effect becomes polyphonic for a
-moment.  The argument @var{updown} determines whether the cue
-notes should be notated as a first or second voice.
-
-
-@lilypond[verbatim,ragged-right]
-smaller = {
-  \set fontSize = #-2
-  \override Stem #'length-fraction = #0.8
-  \override Beam #'thickness = #0.384
-  \override Beam #'length-fraction = #0.8
+This command copies the corresponding measures from @var{partname}
+into a @code{CueVoice} context.  The @code{CueVoice} is created
+implicitly, and occurs simultaneously with @var{music}, which
+creates a polyphonic situation.  The @var{voice} argument
+determines whether the cue notes should be notated as a first or
+second voice; @code{UP} corresponds to the first voice, and
+@code{DOWN} corresponds to the second.
+
+@lilypond[verbatim,quote]
+oboe = \relative c'' {
+  r2 r8 d16 f e g f a
+  g8 g16 g g2.
 }
+\addQuote "oboe" { \oboe }
 
-\addQuote clarinet \relative {
-  R1*20
-  r2 r8 c' f f
+\new Voice \relative c'' {
+  \cueDuring #"oboe" #UP { R1 }
+  g2 c,
 }
+@end lilypond
 
-\new Staff \relative  <<
+@noindent
+In the above example, the @code{Voice} context had to be
+explicitly declared, or else the entire music expression would
+belong to the @code{CueVoice} context.
 
-  % setup a context for cue notes.
-  \new Voice = "cue" { \smaller \skip 1*21 }
+The name of the cued instrument can be printed by setting the
+@code{instrumentCueName} property in the @code{CueVoice} context.
 
-  \set Score.skipBars = ##t
+@lilypond[verbatim,quote]
+oboe = \relative c''' {
+  g4 r8 e16 f e4 d
+}
+\addQuote "oboe" { \oboe }
 
+\new Staff \relative c'' <<
+  \new CueVoice \with {
+    instrumentCueName = "ob."
+  }
   \new Voice {
-    R1*20
-    \cueDuring #"clarinet" #UP {
-      R1
-    }
-    g4 g2.
+    \cueDuring #"oboe" #UP { R1 }
+    g4. b8 d2
   }
 >>
 @end lilypond
 
+In addition to printing the name of the cued instrument, when cue
+notes end, the name of the original instrument should be printed,
+and any other changes introduced by the cued part should be
+undone.  This can be accomplished by using
+@code{\addInstrumentDefinition} and @code{\instrumentSwitch}.  For
+an example and explanation, see @ref{Instrument names}.
 
-Here are a couple of hints for successful cue notes:
-
-@itemize
-@item
-Cue notes have smaller font sizes.
-
-@item
-The cued part is marked with the instrument playing the cue.
-
-@item
-When the original part takes over again, this should be marked
-with the name of the original instrument.
-
-@item
-Any other changes introduced by the cued part should also be
-undone.  For example, if the cued instrument plays in a different
-clef, the original clef should be stated once again.
+The @code{\killCues} command removes cue notes from a music
+expression.  This can be useful if cue notes need to be removed
+from a part but may be restored at a later time.
 
-@end itemize
+@lilypond[verbatim,quote]
+flute = \relative c''' {
+  r2 cis2 r2 dis2
+}
+\addQuote "flute" { \flute }
 
+\new Voice \relative c'' {
+  \killCues {
+    \cueDuring #"flute" #UP { R1 }
+    g4. b8 d2
+  }
+}
+@end lilypond
 
-The macro @code{\transposedCueDuring} is useful to add cues to
-instruments which use a completely different octave range (for
-example, having a cue of a piccolo flute within a contra bassoon
-part).
+The @code{\transposedCueDuring} command is useful for adding
+instrumental cues from a completely different register.  The
+syntax is similar to @code{\cueDuring}, but it requires one extra
+argument to specify the transposition of the cued instrument.  For
+more information about transposition, see
+@ref{Instrument transpositions}.
 
-@lilypond[verbatim,ragged-right,quote]
-picc = \relative c''' {
+@lilypond[verbatim,quote]
+piccolo = \relative c''' {
   \clef "treble^8"
-  R1 |
-  c8 c c e g2 |
-  a4 g g2 |
+  R1
+  c8 c c e g2
+  a4 g g2
 }
-\addQuote "picc" { \picc }
+\addQuote "piccolo" { \piccolo }
 
-cbsn = \relative c, {
+cbassoon = \relative c, {
   \clef "bass_8"
   c4 r g r
-  \transposedCueDuring #"picc" #UP c,, { R1 } |
-  c4 r g r |
+  \transposedCueDuring #"piccolo" #UP c,, { R1 }
+  c4 r g r
 }
 
 <<
-  \context Staff = "picc" \picc
-  \context Staff = "cbsn" \cbsn
+  \new Staff = "piccolo" \piccolo
+  \new Staff = "cbassoon" \cbassoon
 >>
 @end lilypond
 
+It is possible to tag cued parts with unique names in order to
+process them in different ways.  For details about this procedure,
+see @ref{Using tags}.
+
+
 @seealso
+Notation Reference:
+@ref{Instrument transpositions},
+@ref{Instrument names},
+@ref{Using tags}.
+
+Snippets:
+@rlsr{Staff notation}.
 
-Snippets: @lsrdir{staff}.
+Internals Reference:
+@rinternals{CueVoice},
+@rinternals{Voice}.
 
-Internals Reference: @internalsref{Voice}.
 
+@knownissues
 
+Collisions can occur with rests, when using @code{\cueDuring},
+between @code{Voice} and @code{CueVoice} contexts.
-- 
2.39.2