X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchords.itely;h=e6bd3c8a21caa877294ea677a93555dc6935a300;hb=d3bad5fe744ee308c06ab68ab3260c60c2e92e60;hp=9922c33fc7a5610eeb6b5f9f8138b762c78b5e12;hpb=3041efc015981820dc85fd078197c2eb6e8d1580;p=lilypond.git

diff --git a/Documentation/user/chords.itely b/Documentation/user/chords.itely
index 9922c33fc7..e6bd3c8a21 100644
--- a/Documentation/user/chords.itely
+++ b/Documentation/user/chords.itely
@@ -13,12 +13,12 @@
 @section Chord notation
 
 Chords can be entered in chord mode, which recognizes some
-traditional European chord naming conventions. Chord names can also
-be displayed. In addition, figured bass notation can be displayed.
+traditional European chord naming conventions.  Chord names can also
+be displayed.  In addition, figured bass notation can be displayed.
 
 @menu
 * Chord mode::
-* old Modern chords::
+* Displaying chords::
 * Figured bass::
 @end menu
 
@@ -28,12 +28,13 @@ be displayed. In addition, figured bass notation can be displayed.
 
 @cindex chord chords
 
+Chord mode is used to enter chords using an indicator of the chord
+structure, rather than the chord pitches.
+
 @menu
 * Chord mode overview::
-* Triads::
-* Seventh chords::
-* Extended chords::
-* Complex chords::
+* Common chords::
+* Extended and altered chords::
 @end menu
 
 @node Chord mode overview
@@ -45,18 +46,29 @@ be displayed. In addition, figured bass notation can be displayed.
 Chords can be entered as simultaneous music, as discussed in
 @ref{Chorded notes}.
 
-Chords can also be entered in chord mode, which is an input mode
-that focuses on the structures of chords in traditional European
-music, rather than on specific pitches. This is convenient for those
-who are familiar with using chord names to describe chords.
+Chords can also be entered in @qq{chord mode}, which is an input
+mode that focuses on the structures of chords in traditional
+European music, rather than on specific pitches.  This is
+convenient for those who are familiar with using chord names to
+describe chords.  More information on different input modes can be
+found at @ref{Input modes}.
+
+@lilypond[verbatim,quote,ragged-right,relative=1]
+\chordmode { c1 g a g c }
+@end lilypond
 
 Chords entered using chord mode are music elements, and can be
 transposed just like chords entered using simultaneous music.
 
-@code{\chordmode} is similar to @code{\lyricmode}, etc.  Most of
-the commands continue to work, for example, @code{r} and
-@code{\skip} can be used to insert rests and spaces, and property
-commands may be used to change various settings.
+Chord mode and note mode can be mixed in sequential music:
+
+@lilypond[verbatim,quote,ragged-right,relative=1]
+<c e g>2 < g b d >
+\chordmode { c2 f}
+< c e g > < g' b d >
+\chordmode { f g}
+@end lilypond
+
 
 @seealso
 
@@ -64,139 +76,208 @@ Music Glossary:
 @rglos{chord}.
 
 Notation Reference:
-@ref{Chorded notes}.
-
+@ref{Chorded notes},
+@ref{Input modes}.
 
-@node Triads
-@unnumberedsubsubsec Triads
+Snippets:
+@rlsr{Chords}
 
-@cindex triads
-@cindex root of chord
+@knownissues
 
-Major triads are entered by including the root and a duration:
+When chord mode and note mode are mixed in sequential music, and
+chord mode comes first, the note mode will create a new @code{Staff}
+context.
 
-@lilypond[verbatim,quote,relative=1,ragged-right]
-\chordmode { c2 f4. g8 }
+@lilypond[verbatim,quote,ragged-right,relative=1]
+\chordmode { c2 f}
+< c e g > < g' b d >
 @end lilypond
 
-Minor, augmented, and diminished triads are entered by placing
-@code{:} and a quality modifier string after the duration:
+To avoid this behavior, explicitly create the @code{Staff} context:
 
 @lilypond[verbatim,quote,ragged-right,relative=1]
-\chordmode { c2:m f4:aug g4:dim}
+\new Staff {
+  \chordmode { c2 f}
+  < c e g > < g' b d >
+}
 @end lilypond
 
-The possible quality modifier strings are explained in @ref{Complex
-chords}
-
-@seealso
-
-Notation Reference:
-@ref{Complex chords}
-
-@node Seventh chords
-@unnumberedsubsubsec Seventh chords
+@node Common chords
+@unnumberedsubsubsec Common chords
 
+@cindex triads
 @cindex seventh chords
 @cindex root of chord
+@cindex modifiers, in chords.
+@cindex chord quality
 
-@node Extended chords
-@unnumberedsubsubsec Extended chords
-
-@cindex extended chords
-
-Modifiers can be used to extend a chord, specify the @q{quality} of
-the chord, add or remove chord steps, raise or lower chord steps,
-and add a bass note or create an inversion.
-
-The first number following the colon is taken to be the extent of
-the chord. The chord is constructed by sequentially adding thirds
-to the root until the specified number has been reached.
+Major triads are entered by including the root and an
+optional duration:
 
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11}
+@lilypond[verbatim,quote,relative=1,ragged-right]
+\chordmode { c2 f4 g }
 @end lilypond
 
-Since an unaltered 11 does not sound good when combined with an
-unaltered 13, the 11 is removed from a :13 chord (unless it is
-added explicitly).
+Minor, augmented, and diminished triads are entered by placing
+@code{:} and a quality modifier string after the duration:
 
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c:13 c:13.11 c:m13 }
+@lilypond[verbatim,quote,ragged-right,relative=1]
+\chordmode { c2:m f4:aug g:dim }
 @end lilypond
 
-@cindex additions, in chords
+Seventh chords can be created:
 
-@node Complex chords
-@unnumberedsubsubsec Complex chords
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+\chordmode { c1:7 c:m7 c:maj7 c:dim7 c:aug7 }
+@end lilypond
 
-The quality of a chord can be set according to standard chord naming
-conventions. The following quality modifiers are supported:
+@funindex aug
+@funindex dim
+@funindex maj
+@funindex m
 
+The table belows shows the actions of the quality modifiers on
+triads and seventh chords.
 
 @table @code
-@item m The minor chord.  This modifier lowers the 3rd
-and (if present) the 7th step.
 
-@item dim The diminished chord.  This modifier lowers the 3rd, 5th
-and (if present) the 7th step.
+@item m
+The minor chord.  This modifier lowers the 3rd and (if present) the
+7th step.
+
+@item dim
+The diminished chord.  This modifier lowers the 3rd, 5th and (if
+present) the 7th step.
 
 @item aug
 The augmented chord.  This modifier raises the 5th step.
 
 @item maj
-The major 7th chord.  This modifier adds a raised the 7th step
-to the chord.  The @code{7} following @code{maj} is optional.
+The major 7th chord.  This modifier adds a raised 7th step.  The
+@code{7} following @code{maj} is optional.  Do NOT use this modifier
+to create a major triad.
 
-@item sus
-The suspended 4th or 2nd.  This modifier removes the 3rd
-step.  Append either @code{2} or @code{4} to add the 2nd or 4th
-step to the chord.
 @end table
 
-@cindex modifiers, in chords.
-@cindex chord quality
-@funindex aug
-@funindex dim
-@funindex maj
-@funindex sus
-@funindex m
+@c TODO -- perhaps add warning about c and c:maj being different, while
+@c   c:maj and c:maj7 are the same
+
+@seealso
+
+Snippets:
+@rlsr{Chords}
+
+@node Extended and altered chords
+@unnumberedsubsubsec Extended and altered chords
+
+@cindex extended chords
+@cindex altered chords
+
+Chord structures of arbitrary complexity can be created in chord
+mode.  The modifier string can be used to extend a chord, add or
+remove chord steps, raise or lower chord steps, and add a bass note
+or create an inversion.
+
+The first number following the @code{:} is taken to be the extent
+of the chord.  The chord is constructed by sequentially adding
+thirds to the root until the specified number has been reached.
+If the extent is not a third (e.g., 6), thirds are added up to the
+highest third below the extent, and then the step of the extent is
+added.  The largest possible value for the extent is 13.  Any
+larger value is interpreted as 13.
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+\chordmode {
+  c:2 c:3 c:4 c:5
+  c:6 c:7 c:8 c:9
+  c:10 c:11 c:12 c:13
+}
+@end lilypond
+
+Since an unaltered 11 does not sound good when combined with an
+unaltered 13, the 11 is removed from a @code{:13} chord (unless it
+is added explicitly).
 
+@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+\chordmode {
+  c1:13 c:13.11 c:m13
+}
+@end lilypond
+
+@cindex additions, in chords
 
-Individual steps can be added to or removed from a chord.
-Additions are added after the chord type and are prefixed by dots.
+Individual steps can be added to a chord.  Additions follow the
+extent and are prefixed by a dot (@code{.}).
 
-@lilypond[quote,verbatim,fragment]
-\chordmode { c:5.6 c:3.7.8 c:3.6.13 }
+@lilypond[quote,verbatim,fragment,relative=1]
+\chordmode {
+  c1:5.6 c:3.7.8 c:3.6.13
+}
 @end lilypond
 
-Chord steps can be altered by suffixing a @code{-} or @code{+}
-sign to the number.
+Added steps can be as high as desired.
 
-@lilypond[quote,verbatim,fragment]
-\chordmode { c:7+ c:5+.3- c:3-.5-.7- }
+@lilypond[quote,verbatim,fragment,relative=1]
+\chordmode {
+  c4:5.15 c:5.20 c:5.25 c:5.30
+}
 @end lilypond
 
 @cindex chord steps, altering
 
+Added chord steps can be altered by suffixing a @code{-} or @code{+}
+sign to the number.  To alter a step that is automatically included
+as part of the basic chode structure, add it as an altered step.
+
+@lilypond[quote,verbatim,fragment,relative=1]
+\chordmode {
+  c1:7+ c:5+.3- c:3-.5-.7-
+}
+@end lilypond
+
 @cindex removals, in chords
 
 @funindex ^
-Steps to be removed are listed following the additions and are
-prefixed by @code{^}.
 
-@lilypond[quote,verbatim,fragment]
-\chordmode { c^3 c:7^5 c:9^3.5 }
+A step to be removed from the chord  must come at the end of a
+modifier string and be prefixed by @code{^}.  Only one removal with @code{^}
+is allowed in a modifier string.
+
+@lilypond[quote,verbatim,fragment,relative=1]
+\chordmode {
+  c1^3 c:7^5 c:9^3.5
+}
+@end lilypond
+
+@funindex sus
+
+The modifier @code{sus} can be added to the modifier string to
+create suspended chords.  This removes the 3rd step from the chord.
+Append either @code{2} or @code{4} to add the 2nd or 4th step to the
+chord.  @code{sus} is equivalent to @code{^3}; @code{sus4} is
+equivalent to @code{.4^3}.
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\chordmode {
+  c1:sus c:sus2 c:sus4 c:5.4^3
+}
 @end lilypond
 
+It is possible to remove the 3rd step with @code{sus} and remove
+another step with @code{^} in one modifier string.
+
 @funindex /
+@cindex chord inversions
+@cindex bass note, for chords
 
-Inversions (putting a pitch other than the root on the bottom of
-the chord) and added bass notes, can be specified by appending
+Inversions (putting a pitch other than the root on the bottom of the
+chord) and added bass notes can be specified by appending
 @code{/}@var{pitch} to the chord.
 
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c1 c/g c/f }
+@lilypond[quote,ragged-right,fragment,verbatim, relative=2]
+\chordmode {
+  c1 c/g c/f
+}
 @end lilypond
 
 @funindex /+
@@ -205,11 +286,15 @@ A bass note that is part of the chord can be added, instead of
 moved as part of an inversion, by using @code{/+}@var{pitch}.
 
 @lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c1 c/+g c/+f }
+\chordmode {
+  c1 c/g c/+g
+}
 @end lilypond
 
 @seealso
 
+Snippets:
+@rlsr{Chords}
 
 @knownissues
 
@@ -217,141 +302,172 @@ Each step can only be present in a chord once.  The following
 simply produces the augmented chord, since @code{5+} is
 interpreted last.
 
-
 @lilypond[quote,ragged-right,verbatim,fragment]
-\chordmode { c:5.5-.5+ }
+\chordmode { c1:5.5-.5+ }
 @end lilypond
 
+Only one step can be removed from a chord.  If a chord with multiple
+removed steps is desired, it must be built through addition of
+multiple steps.
 
 
-@ignore
-@n ode Displaying chords
-@s ubsection Displaying chords
-
+@node Displaying chords
+@subsection Displaying chords
 
+Chords can be displayed by name, in addition to the standard display
+as notes on a staff.
 
 @menu
 * Printing chord names::
 * Customizing chord names::
-* Lead sheets::
 @end menu
 
-@n ode Printing chord names
-@u nnumberedsubsubsec Printing chord names
+@node Printing chord names
+@unnumberedsubsubsec Printing chord names
 
 @cindex printing chord names
 @cindex chord names
 @cindex chords
 
-LilyPond has support for printing chord names.  Because chords are
-music elements, they can be transposed, and the chord names will be
-transposed along with the chords.
-
-Chords can be entered using @code{< .. >} or through the use of
-chord mode.  The displayed chord name will sometimes be different
-depending upon the entry mode:
+Chord names are printed in the @code{ChordNames} context:
 
-@lilypond[quote,ragged-right,verbatim,ragged-right]
-twoWays = \transpose c c' {
+@lilypond[verbatim,quote,relative=1,ragged-right]
+\new ChordNames {
   \chordmode {
-    c1 f:sus4 bes/f
+    c2 f4. g8
+  }
+}
+@end lilypond
+
+Chords can be entered as simultaneous notes or through the use of
+chord mode.  The displayed chord name will be the same, regardless
+of the mode of entry, unless there are inversions or added bass notes:
+
+@lilypond[quote,ragged-right,verbatim,relative=1]
+<<
+  \new ChordNames {
+    <c e g>2  <f bes c>
+    <f c' e g>1
+    \chordmode {
+      c2 f:sus4 c1:/f
+    }
   }
-  <c e g>
-  <f bes c'>
-  <f bes d'>
+  {
+    <c e g>2  <f bes c>
+    <f, c' e g>1
+    \chordmode {
+      c2 f:sus4 c1:/f
+    }
+  }
+>>
+@end lilypond
+
+@funindex{\chords}
+
+@code{\chords @{ ... @}} is a shortcut notation for
+@code{\new ChordNames @{\chordmode @{ ... @}@}}.
+
+@lilypond[verbatim,quote,ragged-right, relative=1]
+\chords {
+  c2 f4.:m g8:maj7
 }
+@end lilypond
 
-<< \new ChordNames \twoWays
-   \new Voice \twoWays >>
+@lilypond[verbatim,quote,ragged-right, relative=1]
+\new ChordNames {
+  \chordmode {
+    c2 f4.:m g8:maj7
+  }
+}
 @end lilypond
 
-This example also shows that the chord printing routines cannot
-correctly identify the root of a chord if it has been entered using
-@code{< .. >} instead of named chord entry.  Therefore, the sixth
-chord (@code{f bes d}) is not interpreted as an inversion.   In
-contrast, the third chord, which contains the same notes as the sixth
-chord, is correctly identified because it was entered in the named
-chord mode.
+@snippets
 
-For displaying printed chord names, use the @rinternals{ChordNames}
-context.
+@c TODO -- replace this with a snippet
+Chord names can be displayed only at the start of lines and when
+the chord changes.
 
 @lilypond[quote,verbatim,ragged-right]
-harmonies = {
-  \chordmode {a1 b c} <d' f' a'> <e' g' b'>
+harmonies = \chordmode {
+  c1:m c:m \break c:m c:m d
 }
 <<
-  \new ChordNames \harmonies
-  \new Staff \harmonies
+  \new ChordNames {
+    \set chordChanges = ##t
+    \harmonies
+  }
+  \new Staff {
+    \relative c' { \harmonies }
+  }
 >>
 @end lilypond
 
-The previous examples all show chords over a staff.  This is not
-necessary.  Chords may also be printed separately.  It may be necessary
-to add @rinternals{Volta_engraver} and @rinternals{Bar_engraver}
-for showing repeats.
+@c TODO -- replace this with a snippet
+To add bar indications in the @code{ChordNames}
+context, add @rinternals{Bar_engraver}.
 
 @lilypond[ragged-right,verbatim]
 \new ChordNames \with {
   \override BarLine #'bar-size = #4
-  \consists Bar_engraver
-  \consists "Volta_engraver"
-}
-\chordmode { \repeat volta 2 {
-  f1:maj7 f:7 bes:7
-  c:maj7
-} \alternative {
-  es e
+  \consists "Bar_engraver"
 }
+\chordmode {
+  f1:maj7 f:7 bes:7 c:maj7 ees e
 }
 @end lilypond
 
-@code{\chords} is a shortcut method used to change the input mode to
-@code{\chordmode} and create a @code{ChordNames} context, with the
-following result:
+@c TODO -- replace this with a snippet
+When put together, chord names, a melody, and lyrics form a lead
+sheet:
 
 @lilypond[verbatim,quote,ragged-right]
-\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+<<
+  \chords { c2 g:sus4 f e }
+  \relative c'' {
+    a4 e c8 e r4
+    b2 c4( d)
+  }
+  \addlyrics { One day this shall be free __ }
+>>
 @end lilypond
 
-@c @predefined
-
-@c @snippets
-
 @seealso
-@c Music Glossary:
-@c @rglos{}.
 
-@c Learning Manual:
-@c @rlearning{}.
+Music Glossary:
+@rglos{chord}.
 
-@c Notation Reference:
-@c @ruser{}.
 
-@c Application Usage:
-@c @rprogram{}.
+Notation Reference:
+@ref{Writing music in parallel}.
 
-@c Installed Files:
-@c @file{}.
 
-@c Snippets:
-@c @rlsr{}.
+Snippets:
+@rlsr{Chords}.
 
-@c Internals Reference:
-@c @rinternals{}.
+Internals Reference:
+@rinternals{ChordNames},
+@rinternals{Volta_engraver},
+@rinternals{Bar_engraver}.
 
-@c @knownissues
+@knownissues
+
+Chords containing inversions or altered bass notes are not named
+properly if entered using simultaneous music.
 
 
-@n ode Customizing chord names
-@u nnumberedsubsubsec Customizing chord names
+@node Customizing chord names
+@unnumberedsubsubsec Customizing chord names
 
 @cindex customizing chord names
 
 There is no unique system for naming chords.  Different musical
-traditions use different names for the same set of chords. There are
-also different symbols displayed for a given chord name.   The names
-and symbols displayed for chord names are customizable.
+traditions use different names for the same set of chords.  There
+are also different symbols displayed for a given chord name.   The
+names and symbols displayed for chord names are customizable.
+
+@cindex Banter
+@cindex jazz chords
+@cindex chords, jazz
 
 The default chord name layout is a system for Jazz music, proposed
 by Klaus Ignatzek (see @ref{Literature list}).  There are also two
@@ -371,137 +487,70 @@ The effect is demonstrated here:
 If none of the default settings give the desired output, the chord
 name display can be tuned through the following properties.
 
-@c TODO Generate snippet based on the following
-@c      and add explanation -td
-
-@table
-@item
-@funindex chordNameExceptions
-
-@code{chordNameExceptions} contains a list of markups used to follow
-the root note name based on the pitches in the chord.  Creating the
-list requires four steps.
-
-The first step is to define sequential music that has the chords to
-be named with the desired markup (except for the root name) attached
-to the chord:
-
-@example
-FGGChordNames = @{
-  <c e g b d'>1-\markup @{ \super "maj9" @}
-  <c e g a d'>1-\markup @{ \super "6(add9)" @}
-@}
-@end example
-
-The second step is to convert the music from the first step to an
-exceptions list:
-
-@example
-FGGExceptions = #(sequential-music-to-chord-exceptions
-FGGChordNames #t)
-@end example
+@table @code
 
-The third step is to append the default exceptions list (in this
-case, the Ignatzek exceptions) to the newly-defined exceptions list:
+@funindex chordRootNamer
 
-@example
-chExceptions = #(append FGGExceptions ignatzekExceptions)
-@end example
+@item chordRootNamer
 
-The final step is to set @code{chordNameExceptions} to the
-newly-created exceptions list:
+The chord name is usually printed as a letter for the root with an
+optional alteration.  The transformation from pitch to letter is
+done by this function.  Special note names (for example, the German
+@q{H} for a B-chord) can be produced by storing a new function in
+this property.
 
-@example
-\set chordNameExceptions = #chExceptions
-@end example
+@funindex majorSevenSymbol
 
-The entire process is illustrated below:
+@item majorSevenSymbol
 
-@lilypond[quote,ragged-right,verbatim,ragged-right]
-FGGChordNames = {
-  <c e g b d'>1-\markup { \super "maj9" }
-  <c e g a d'>1-\markup { \super "6(add9)" }
-}
-FGGExceptions = #(sequential-music-to-chord-exceptions
-FGGChordNames #t)
-chExceptions = #(append FGGChordNames
- ignatzekExceptions)
-
-chordStuff = \chordmode
-{
-% standard names
-g1:maj9
-g1:6.9
-% names with FGG's custom exceptions
-\set chordNameExceptions = #chExceptions
-g1:maj9
-g1:6.9
-}
+This property contains the markup object used to follow the output
+of @code{chordRootNamer} to dentify a major 7 chord. Predefined
+options are @code{whiteTriangleMarkup} and
+@code{blackTriangleMarkup}.
 
-\score
-{
-\new ChordNames \chordStuff
-}
-@end lilypond
+@funindex chordNoteNamer
 
+@item chordNoteNamer
 
-@funindex majorSevenSymbol
-@item majorSevenSymbol
-This property contains the markup object used as part of the printed
-chord name to identify a major 7 chord. Predefined options are
-@code{whiteTriangleMarkup} and @code{blackTriangleMarkup}.
+When the chord name contains additional pitches other than the root
+(e.g., an added bass note), this function is used to print the
+additional pitch.  By default the pitch is printed using
+@code{chordRootNamer}. The @code{chordNoteNamer} property can be set
+to a specialized function to change this behavior.  For example, the
+bass note can be printed in lower case.
 
 @funindex chordNameSeparator
+
 @item chordNameSeparator
+
 Different parts of a chord name are normally separated by a slash.
 By setting @code{chordNameSeparator}, you can use any desired markup
-for a separator, e.g.,
-@lilypond[quote,ragged-right,fragment,verbatim]
-\new ChordNames \chordmode {
-  c:7sus4
-  \set chordNameSeparator
-    = \markup { \typewriter "|" }
-  c:7sus4
-}
-@end lilypond
+for a separator.
 
-@funindex chordRootNamer
-@item chordRootNamer
-The chord name is usually printed as a letter for the root with an
-optional alteration.  The transformation from pitch to letter is
-done by this function.  Special note names (for example, the German
-@q{H} for a B-chord) can be produced by storing a new function in
-this property.
+@funindex chordNameExceptions
 
-@funindex chordNoteNamer
-@item chordNoteNamer
-When the chord name contains an additional pitch besides the root
-(e.g., an added bass note), this function is used to print the
-additional pitch. By default the pitch is printed using
-@code{chordRootNamer}. The @code{chordNoteNamer} property can be set
-to a specialized function to change this behavior.  For example, the
-bass note can be printed in lower case.
+@item chordNameExceptions
+
+This property is a list of pairs.  The first item in each pair
+is a set of pitches used to identify the steps present in the chord.
+The second item is a markups that will follow the @code{chordRootNamer}
+output to create the chord name.
 
 @funindex chordPrefixSpacer
 @item chordPrefixSpacer
+
 The @q{m} for minor chords is usually printed immediately to the
 right of the root of the chord.  By setting
-@code{chordPrefixSpacer}, you can fix a spacer between the root and
-@q{m}.  The spacer is not used when the root is altered.
+@code{chordPrefixSpacer}, you can fix a spacer between the root
+and @q{m}.  The spacer is not used when the root is altered.
 
 @end table
 
-
-
-
-@cindex Banter
-@cindex jazz chords
-@cindex chords, jazz
-
 @predefined
+
 @funindex major seven symbols
-@code{\whiteTriangleMarkup}
-@code{\blackTriangleMarkup}
+@code{\whiteTriangleMarkup},
+@code{\blackTriangleMarkup},
 @funindex \germanChords
 @code{\germanChords},
 @funindex \semiGermanChords
@@ -513,561 +562,76 @@ right of the root of the chord.  By setting
 
 
 @snippets
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{chord-names-jazz.ly}
 
+@c TODO fix indentation of snippet -- lots of tabs!
+@cindex exceptions, chord names.
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {chord-name-exceptions.ly}
-@cindex exceptions, chord names.
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {chord-name-major7.ly}
 
-@seealso
-@c Music Glossary:
-@c @rglos{}.
+@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@c {adding-bars-to-chordnames.ly)
 
-@c Learning Manual:
-@c @rlearning{}.
+@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@c {volta-brackets-over-chord-names.ly}
 
-@c Notation Reference:
-@c @ruser{}.
+@c TODO  convert to snippet
+The separator between different parts of a chord name
+can be set to any markup.
 
-@c Application Usage:
-@c @rprogram{}.
+@lilypond[quote,ragged-right,fragment,verbatim]
+\chords {
+  c:7sus4
+  \set chordNameSeparator
+    = \markup { \typewriter "|" }
+  c:7sus4
+}
+@end lilypond
+
+
+@seealso
+
+Notation Reference:
+@ref{Chord name chart}.
 
 Installed Files:
 @file{scm/@/chords@/-ignatzek@/.scm},
 @file{scm/@/chord@/-entry@/.scm},
 @file{ly/@/chord@/-modifier@/-init@/.ly}.
 
-@c Snippets: @c @rlsr{}.
+Snippets:
+@rlsr{Chords}.
 
 @c Internals Reference:
-@c @rinternals{}.
+@c @r internals{}.
 
 @knownissues
 
-When chords are entered with the @code{< .. >} syntax, the root and
-any added bass notes are not identified.  In this  case, chord names
-are determined solely from the list of pitches.  This may result in
-strange chord names
-
-@n ode Lead sheets
-@u nnumberedsubsubsec Lead sheets
-
-@cindex lead sheet
-
-For lead sheets, chords are not printed on staves, but as names on a
-line for themselves.  This is achieved by using a @code{ChordNames}
-context simultaneously with the @code{Staff} context.  The
-@code{\chords} keyword can be used as a shortcut for @code{\new
-ChordNames \chordmode}.
+Chord names are determined from both the pitches that are present
+in the chord and the information on the chord structure that may
+have been entered in @code{\chordmode}.  If the simultaneous pitches
+method of entering chords is used, undesired names result from
+inversions or bass notes.
 
-When put together, chord names, a melody, and lyrics form a lead
-sheet:
-
-@lilypond[verbatim,quote,ragged-right]
-<<
-  \chords { c2 g:sus4 f e }
-  \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
-  }
-  \addlyrics { One day this shall be free __ }
->>
-@end lilypond
-
-@c @predefined
-
-@c @snippets
-
-@seealso
-@c Music Glossary:
-@c @rglos{}.
-
-@c Learning Manual:
-@c @rlearning{}.
-
-@c Notation Reference:
-@c @ruser{}.
-
-@c Application Usage:
-@c @rprogram{}.
-
-@c Installed Files:
-@c @file{}.
-
-@c Snippets:
-@c @rlsr{}.
-
-@c Internals Reference:
-@c @rinternals{}.
-
-@c @knownissues
-
-
-
-
-@end ignore
-
-
-@node old Modern chords
-@subsection old Modern chords
-
-@menu
-* Chord modes::
-* Entering chord names::
-* Building chords::
-* Lead sheets::
-* Printing chord names::
-@end menu
-
-@cindex chords
-@cindex chord names
-
-@node Chord modes
-@subsubsection Chord modes
-
-In popular music it is common to denote accompaniment with chord
-names.  Such chords can be entered like notes,
-
-@lilypond[verbatim,quote,ragged-right]
-\chordmode { c2 f4. g8 }
-@end lilypond
-
-Now each pitch is read as the root of a chord instead of a note.
-This mode is switched on with @code{\chordmode}.  Other chords can
-be created by adding modifiers after a colon.  The following
-example shows a few common modifiers:
-
-@lilypond[verbatim,quote,ragged-right]
-\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
-@end lilypond
-
-@cindex Chords mode
-
-In chord mode sets of pitches (chords) are entered with normal note
-names.  A chord is entered by the root, which is entered like a
-normal pitch
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { es4. d8 c2 }
-@end lilypond
-
-@noindent
-The mode is introduced by the keyword @code{\chordmode}.
-
-@cindex chord entry
-@cindex chord mode
-
-Chords is a mode similar to @code{\lyricmode}, etc.  Most
-of the commands continue to work, for example, @code{r} and
-@code{\skip} can be used to insert rests and spaces, and property
-commands may be used to change various settings.
-It uses the same syntax as
-@code{\chordmode}, but renders the notes in a @code{ChordNames}
-context, with the following result:
-
-@lilypond[verbatim,quote,ragged-right]
-\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
-@end lilypond
-
-
-@knownissues
-
-Each step can only be present in a chord once.  The following
-simply produces the augmented chord, since @code{5+} is interpreted
-last
-@cindex clusters
-@lilypond[quote,ragged-right,verbatim,fragment]
-\chordmode { c:5.5-.5+ }
-@end lilypond
-
-
-@node Entering chord names
-@subsubsection Entering chord names
-@cindex chord names
-
-LilyPond has support for printing chord names.  Chords may be entered
-in musical chord notation, i.e., @code{< .. >}, but they can also be
-entered by name.  Internally, the chords are represented as a set of
-pitches, so they can be transposed
-
-
-@lilypond[quote,ragged-right,verbatim,ragged-right]
-twoWays = \transpose c c' {
-  \chordmode {
-    c1 f:sus4 bes/f
-  }
-  <c e g>
-  <f bes c'>
-  <f bes d'>
-}
-
-<< \new ChordNames \twoWays
-   \new Voice \twoWays >>
-@end lilypond
-
-This example also shows that the chord printing routines do not try to
-be intelligent.  The last chord (@code{f bes d}) is not interpreted as
-an inversion.
-
-Note that the duration of chords must be specified outside the
-@code{<>}.
-
-@example
-<c e g>2
-@end example
-
-@c TODO Generate snippet based on the following
-@c      and add explanation -td
-
-Custom chord names may be generated:
-
-@lilypond[quote,ragged-right,verbatim,ragged-right]
-FGGChordNames = {
-  <c e g b d'>1-\markup { \super "maj9" }
-  <c e g a d'>1-\markup { \super "6(add9)" }
-}
-chExceptions = #(append
-(sequential-music-to-chord-exceptions
-FGGChordNames #t) ignatzekExceptions)
-
-chordStuff = \chordmode
-{
-% standard names
-g1:maj9
-g1:6.9
-% names with FGG's custom exceptions
-\set chordNameExceptions = #chExceptions
-g1:maj9
-g1:6.9
-}
-
-\score
-{
-\new ChordNames \chordStuff
-}
-@end lilypond
-
-@node Building chords
-@subsubsection Building chords
-
-Other chords may be entered by suffixing a colon and introducing a
-modifier (which may include a number if desired)
-
-@lilypond[quote,fragment,verbatim]
-\chordmode { e1:m e1:7 e1:m7 }
-@end lilypond
-
-The first number following the root is taken to be the @q{type} of the
-chord, thirds are added to the root until it reaches the specified
-number.  The exception is @code{c:13}, for which the 11 is omitted.
-
-@lilypond[quote,fragment,verbatim]
-\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 c:13 }
-@end lilypond
-
-@cindex root of chord
-@cindex additions, in chords
-@cindex removals, in chords
-
-More complex chords may also be constructed adding separate steps
-to a chord.  Additions are added after the number following
-the colon and are separated by dots
-
-@lilypond[quote,verbatim,fragment]
-\chordmode { c:5.6 c:3.7.8 c:3.6.13 }
-@end lilypond
-
-Chord steps can be altered by suffixing a @code{-} or @code{+} sign
-to the number
-
-@lilypond[quote,verbatim,fragment]
-\chordmode { c:7+ c:5+.3- c:3-.5-.7- }
-@end lilypond
-
-Removals are specified similarly and are introduced by a caret.  They
-must come after the additions
-
-@lilypond[quote,verbatim,fragment]
-\chordmode { c^3 c:7^5 c:9^3.5 }
-@end lilypond
-
-Modifiers can be used to change pitches.  The following modifiers are
-supported
-
-@table @code
-@item m
-The minor chord.  This modifier lowers the 3rd and (if present) the 7th step.
-
-@item dim
-The diminished chord.  This modifier lowers the 3rd, 5th and (if present)
-the 7th step.
-
-@item aug
-The augmented chord.  This modifier raises the 5th step.
-
-@item maj
-The major 7th chord.  This modifier raises the 7th step if present.
-
-@item sus
-The suspended 4th or 2nd.  This modifier removes the 3rd
-step.  Append either @code{2} or @code{4} to add the 2nd or 4th step to
-the chord.
-@end table
-
-Modifiers can be mixed with additions
-@lilypond[quote,verbatim,fragment]
-  \chordmode { c:sus4 c:7sus4 c:dim7 c:m6 }
-@end lilypond
-
-@cindex modifiers, in chords.
-@funindex aug
-@funindex dim
-@funindex maj
-@funindex sus
-@funindex m
-
-Since an unaltered 11 does not sound good when combined with an
-unaltered 13, the 11 is removed in this case (unless it is added
-explicitly)
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c:13 c:13.11 c:m13 }
-@end lilypond
-
-@funindex /
-
-An inversion (putting one pitch of the chord on the bottom), as well
-as bass notes, can be specified by appending
-@code{/}@var{pitch} to the chord
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c1 c/g c/f }
-@end lilypond
-@funindex /+
-
-A bass note can be added instead of transposed out of the chord,
-by using @code{/+}@var{pitch}.
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c1 c/+g c/+f }
-@end lilypond
-
-
-@node Lead sheets
-@subsubsection Lead sheets
-
-@cindex lead sheet
-
-For lead sheets, chords are not printed on staves, but as names on
-a line for themselves.  This is achieved by using @code{\chords}
-instead of @code{\chordmode}.
-
-When put together, chord names, lyrics and a melody form a lead
-sheet,
-
-@lilypond[verbatim,quote,ragged-right]
-<<
-  \chords { c2 g:sus4 f e }
-  \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
-  }
-  \addlyrics { One day this shall be free __ }
->>
-@end lilypond
-
-
-
-@node Printing chord names
-@subsubsection Printing chord names
-
-@cindex printing chord names
-@cindex chord names
-@cindex chords
-
-For displaying printed chord names, use the @rinternals{ChordNames} context.
-The chords may be entered either using the notation
-described above, or directly using @code{<} and @code{>}
-
-@lilypond[quote,verbatim,ragged-right]
-harmonies = {
-  \chordmode {a1 b c} <d' f' a'> <e' g' b'>
+@lilypond[quote,ragged-right,verbatim]
+myChords = \relative c' {
+  \chordmode{ c1 c/g c/f }
+  <c e g> <g c e> <f c' e g>
 }
 <<
-  \new ChordNames \harmonies
-  \new Staff \harmonies
->>
-@end lilypond
-
-You can make the chord changes stand out by setting
-@rinternals{ChordNames}.@code{chordChanges} to true.  This will only
-display chord names when there is a change in the chords scheme and at
-the start of a new line
-
-@lilypond[quote,verbatim,ragged-right]
-harmonies = \chordmode {
-  c1:m c:m \break c:m c:m d
-}
-<<
-  \new ChordNames {
-    \set chordChanges = ##t
-    \harmonies }
-  \new Staff \transpose c c' \harmonies
+  \new ChordNames { \myChords }
+  \new Staff { \myChords }
 >>
 @end lilypond
 
-The previous examples all show chords over a staff.  This is not
-necessary.  Chords may also be printed separately.  It may be necessary
-to add @rinternals{Volta_engraver} and @rinternals{Bar_engraver}
-for showing repeats.
-
-@lilypond[ragged-right,verbatim]
-\new ChordNames \with {
-  \override BarLine #'bar-size = #4
-  \consists Bar_engraver
-  \consists "Volta_engraver"
-}
-\chordmode { \repeat volta 2 {
-  f1:maj7 f:7 bes:7
-  c:maj7
-} \alternative {
-  es e
-}
-}
-@end lilypond
-
-
-The default chord name layout is a system for Jazz music, proposed by
-Klaus Ignatzek (see @ref{Literature list}).  It can be tuned through the
-following properties
-
-@table @code
-@funindex chordNameExceptions
-@item chordNameExceptions
-This is a list that contains the chords that have special formatting.
-
-The exceptions list should be encoded as
-@example
-@{ <c f g bes>1 \markup @{ \super "7" "wahh" @} @}
-@end example
-
-To get this information into @code{chordNameExceptions} takes a little
-maneuvering.  The following code transforms @code{chExceptionMusic}
-(which is a sequential music) into a list of exceptions.
-@example
-(sequential-music-to-chord-exceptions chExceptionMusic #t)
-@end example
-Then,
-@example
-(append
- (sequential-music-to-chord-exceptions chExceptionMusic #t)
- ignatzekExceptions)
-@end example
-adds the new exceptions to the default ones, which are defined in
-@file{ly/@/chord@/-modifier@/-init@/.ly}.
-
-For an example of tuning this property, see also
-@c @lsr{chords,chord@/-name@/-exceptions@/.ly}
-@cindex exceptions, chord names.
-
-
-@funindex majorSevenSymbol
-@item majorSevenSymbol
-This property contains the markup object used for the 7th step, when
-it is major.  Predefined options are @code{whiteTriangleMarkup} and
-@code{blackTriangleMarkup}.  See
-@c @lsr{chords,chord@/-name@/-major7@/.ly} for an example.
-
-@funindex chordNameSeparator
-@item chordNameSeparator
-Different parts of a chord name are normally separated by a
-slash.  By setting @code{chordNameSeparator}, you can specify other
-separators, e.g.,
-@lilypond[quote,ragged-right,fragment,verbatim]
-\new ChordNames \chordmode {
-  c:7sus4
-  \set chordNameSeparator
-    = \markup { \typewriter "|" }
-  c:7sus4
-}
-@end lilypond
-
-@funindex chordRootNamer
-@item chordRootNamer
-The root of a chord is usually printed as a letter with an optional
-alteration.  The transformation from pitch to letter is done by this
-function.  Special note names (for example, the German @q{H} for a
-B-chord) can be produced by storing a new function in this property.
-
-@funindex chordNoteNamer
-@item chordNoteNamer
-The default is to print single pitch, e.g., the bass note, using the
-@code{chordRootNamer}.  The @code{chordNoteNamer} property can be set
-to a specialized function to change this behavior.  For example, the
-base can be printed in lower case.
-
-@funindex chordPrefixSpacer
-@item chordPrefixSpacer
-The @q{m} for minor chords is usually printed right after the root of
-the chord.  By setting @code{chordPrefixSpacer}, you can fix a spacer
-between the root and @q{m}.  The spacer is not used when the root
-is altered.
-
-@end table
-
-The predefined variables @code{\germanChords},
-@code{\semiGermanChords}, @code{\italianChords} and @code{\frenchChords}
-set these variables.  The effect is
-demonstrated here,
-
-@lilypondfile[ragged-right]{chord-names-languages.ly}
-
-There are also two other chord name schemes implemented: an alternate
-Jazz chord notation, and a systematic scheme called Banter chords.  The
-alternate Jazz notation is also shown on the chart in @ref{Chord name
-chart}.  Turning on these styles is demonstrated in
-@c @lsr{chords,chord-names-jazz.ly}.
-
-@cindex Banter
-@cindex jazz chords
-@cindex chords, jazz
-
-
-@predefined
-
-@funindex \germanChords
-@code{\germanChords},
-@funindex \semiGermanChords
-@code{\semiGermanChords}.
-@funindex \italianChords
-@code{\italianChords}.
-@funindex \frenchChords
-@code{\frenchChords}.
-
-
-
-
-@seealso
-
-Examples:
-
-Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and
-@file{scm/@/chord@/-entry@/.scm}.
-
-
-@knownissues
-
-Chord names are determined solely from the list of pitches.  Chord
-inversions are not identified, and neither are added bass notes.  This
-may result in strange chord names when chords are entered with the
-@code{< .. >} syntax.
-
 
 @node Figured bass
 @subsection Figured bass
 
+Figured bass notation can be displayed.
+
 @menu
 * Introduction to figured bass::
 * Entering figured bass::
@@ -1075,181 +639,142 @@ may result in strange chord names when chords are entered with the
 @end menu
 
 @node Introduction to figured bass
-@subsubsection Introduction to figured bass
+@unnumberedsubsubsec Introduction to figured bass
 
 @cindex Basso continuo
+@cindex Thorough bass
+@cindex Figured bass
+@cindex Bass, thorough
+@cindex Bass, figured
 
 @c TODO: musicological blurb about FB
 
-LilyPond has support for figured bass
+LilyPond has support for figured bass, also called thorough bass
+or basso continuo:
 
 @lilypond[quote,ragged-right,verbatim,fragment]
 <<
   \new Voice { \clef bass dis4 c d ais g fis}
-  \new FiguredBass \figuremode {
-    < 6 >4 < 7\+ >8 < 6+ [_!] >
-    < 6 >4 <6 5 [3+] >
-    < _ >4 < 6 5/>4
+  \new FiguredBass {
+    \figuremode {
+      < 6 >4 < 7\+ >8 < 6+ [_!] >
+      < 6 >4 <6 5 [3+] >
+      < _ >4 < 6 5/>4
+    }
   }
 >>
 @end lilypond
 
 The support for figured bass consists of two parts: there is an
-input mode, introduced by @code{\figuremode}, where you can enter
-bass figures as numbers, and there is a context named
-@rinternals{FiguredBass} that takes care of making
-@rinternals{BassFigure} objects.
+input mode, introduced by @code{\figuremode}, that accepts
+entry of bass figures, and there is a context named
+@code{FiguredBass} that takes care of displaying
+@code{BassFigure} objects.  Figured bass can also be displayed
+in @code{Staff} contexts.
 
-Although the support for figured bass may superficially resemble chord
-support, it is much simpler.  The @code{\figuremode} mode simply
-stores the numbers and @rinternals{FiguredBass} context prints them
-as entered.  There is no conversion to pitches and no realizations of
-the bass are played in the MIDI file.
+@code{\figures@{ ... @}} is a shortcut notation for
+@code{\new FiguredBass @{\figuremode @{ ... @}@}}.
 
-Internally, the code produces markup texts.  You can use any of the
-markup text properties to override formatting.  For example, the
-vertical spacing of the figures may be set with @code{baseline-skip}.
 
+Although the support for figured bass may superficially resemble chord
+support, it is much simpler.  @code{\figuremode} mode simply
+stores the figures and the @code{FiguredBass} context prints them
+as entered.  There is no conversion to pitches.
 
-@menu
-* Entering figured bass::
-* Displaying figured bass::
-@end menu
+Figures are created as markup texts.  Any of the standard markup
+properties can be used to modify the display of figures.  For
+example, the vertical spacing of the figures may be set with
+@code{baseline-skip}.
 
 @node Entering figured bass
 @unnumberedsubsubsec Entering figured bass
 
+@code{\figuremode} is used to switch the input mode to figure mode.
+More information on different input modes can be
+found at @ref{Input modes}.
 
-In figures input mode, a group of bass figures is delimited by
-@code{<} and @code{>}.  The duration is entered after the @code{>}
-@example
-<4 6>2
-@end example
-@lilypond[quote,ragged-right,fragment]
-\new FiguredBass
-\figuremode { <4 6>2 }
+In figure mode, a group of bass figures is delimited by
+@code{<} and @code{>}.  The duration is entered after the @code{>}.
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\new FiguredBass {
+  \figuremode {
+    <4 6>2
+  }
+}
 @end lilypond
 
-Accidentals are added when you append @code{-}, @code{!}, and @code{+}
-to the numbers.  A plus sign is added when you append @code{\+}, and
-diminished fifths and sevenths can be obtained with @code{5/} and @code{7/}.
+Accidentals can be added to figures:
 
-@example
-<4- 6+ 7!>3 <5++> <3--> <7/> r <6\+ 5/>
-@end example
-@lilypond[quote,ragged-right,fragment]
-\figures { <4- 6+ 7!>4 <5++> <3--> <7/> r <6\+ 5/> }
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  <4- 6+ 7!> <5++> <3-->
+}
 @end lilypond
 
-Spaces may be inserted by using @code{_}.  Brackets are
-introduced with @code{[} and @code{]}.  You can also include text
-strings and text markups, see @ref{Text markup commands}.
+Plus signs, diminished fifths, and diminished sevenths
+can be notated.
 
-@example
-< [4 6] 8 [_! 12] >4 < 5 \markup @{ \number 6 \super (1) @} >
-@end example
-@lilypond[quote,ragged-right,fragment]
-\new FiguredBass
-\figuremode { < [4 6] 8 [_! 12] >4 < 5 \markup{ \tiny \number 6 \super (1)} > }
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  <6\+ 5/> <7/>
+}
 @end lilypond
 
+Vertical spaces and brackets can be be included in figures:
 
-It is also possible to use continuation lines for repeated figures,
-
-@lilypond[verbatim,relative=1]
-<<
-  \new Staff {
-    \clef bass
-    c4 c c
-  }
-  \figures {
-    \set useBassFigureExtenders = ##t
-    <4 6>4 <3 6> <3 7>
-  }
->>
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  < [4 6] 8 [_! 12] >
+}
 @end lilypond
 
-@noindent
-In this case, the extender lines always replace existing figures.
 
-The @code{FiguredBass} context doesn't pay attention to the actual
-bass line.  As a consequence, you may have to insert extra figures to
-get extender lines below all notes, and you may have to add @code{\!}
-to avoid getting an extender line, e.g.
+Any text markup can be inserted as a figure:
 
-@lilypond[relative=1]
-<<
-  \new Voice
-  \figures {
-    \set useBassFigureExtenders = ##t
-    <6 4->4. <6 4->16. <6 4->32 <5>8. r16 <6>8 <6\! 5->
-  }
-  {
-    \clef bass
-    f16. g32 f16. g32 f16. g32 f16. g32 f8. es16 d8 es
-  }
->>
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  < 5 \markup{ \tiny \number 6 \super (1)} >
+}
 @end lilypond
 
-When using continuation lines, common figures are always put in the
-same vertical position.  When this is unwanted, you can insert a rest
-with @code{r}.  The rest will clear any previous alignment.  For
-example, you can write
+Continuation lines can be used to indicate repeated figures:
 
-@example
-<4 6>8 r8
-@end example
+@c  \set to be replaced with predefined command once it is
+@c   included in property-init.ly
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  \set useBassFigureExtenders = ##t
+  <4 6> <3 6> <3 7>
+}
+@end lilypond
 
 @noindent
-instead of
-@example
-<4 6>4
-@end example
+In this case, the extender lines always replace existing figures.
+
+@c @predefined
 
+@c @snippets
+@c  This probably isn't notation, but rather adjusting output.  I guess this
+@c  should be converted to a snippet?  -cds
 Accidentals and plus signs can appear before or after the numbers,
 depending on the @code{figuredBassAlterationDirection} and
 @code{figuredBassPlusDirection}
 properties
 
+@c  TODO Need to set predefined commands for these directions as well. -cs
 @lilypond
   \figures {
     <6\+> <5+> <6 4-> r
-    \set figuredBassAlterationDirection = #1
+    \set figuredBassAlterationDirection = #RIGHT
     <6\+> <5+> <6 4-> r
-    \set figuredBassPlusDirection = #1
+    \set figuredBassPlusDirection = #LEFT
     <6\+> <5+> <6 4-> r
-    \set figuredBassAlterationDirection = #-1
+    \set figuredBassAlterationDirection = #LEFT
     <6\+> <5+> <6 4-> r
   }
 @end lilypond
 
-
-Figured bass can also be added to @code{Staff} contexts
-directly.  In this case, their vertical position is adjusted
-automatically.
-
-@lilypond[ragged-right,fragment,quote]
-<<
-  \new Staff = someUniqueName
-  \relative c'' {
-    c4 c'8 r8 c,4 c'
-  }
-
-  %% send to existing Staff.
-  \context Staff = someUniqueName
-  \figuremode {
-    <4>4 <6 10>8 s8
-
-    \set Staff.useBassFigureExtenders = ##t
-    <4 6>4 <4 6>
-  }
->>
-@end lilypond
-
-@c @predefined
-
-@c @snippets
-
 @seealso
 @c Music Glossary:
 @c @rglos{}.
@@ -1266,18 +791,87 @@ automatically.
 @c Installed Files:
 @c @file{}.
 
-@c Snippets:
-@c @rlsr{}.
+Snippets:
+@rlsr{Figured Bass}.
 
 @c Internals Reference:
-@c @rinternals{}.
+@rinternals{NewBassFigure},
+@rinternals{BassFigureAlignment},
+@rinternals{BassFigureLine},
+@rinternals{BassFigureBracket},
+@rinternals{BassFigureContinuation},
+@rinternals{FiguredBass}.
 
 @c @knownissues
 
 @node Displaying figured bass
 @unnumberedsubsubsec Displaying figured bass
 
-Figured bass is displayed using the @code{FiguredBass} context.
+Figured bass can be displayed using the @code{FiguredBass} context,
+or in most staff contexts.
+
+When displayed in a @code{FiguredBass} context, the vertical location
+of the figures is independent of the notes on the staff.
+
+@lilypond[verbatim,ragged-right,fragment,quote]
+<<
+  \relative c'' {
+    c4 c'8 r8 c,4 c'
+  }
+  \new FiguredBass {
+    \figuremode {
+      <4>4 <6 10>8 s8
+      <4 6>4 <4 6>
+    }
+  }
+>>
+@end lilypond
+
+@noindent
+In the example above, the @code{FiguredBass} context must be
+explicitly instantiated to avoid creating a second (empty) staff.
+
+
+Figured bass can also be added to @code{Staff} contexts
+directly.  In this case, the vertical position of the
+figures is adjusted automatically.
+
+@c  TODO change to use predefined command once it is added to
+@c  property-init.ly  -cds
+@lilypond[verbatim,ragged-right,fragment,quote]
+<<
+  \new Staff = myStaff
+  \figuremode {
+    \override Staff.BassFigureAlignmentPositioning #'direction = #DOWN
+    <4>4 <6 10>8 s8
+    <4 6>4 <4 6>
+  }
+  %% Put notes on same Staff as figures
+  \context Staff = myStaff
+  \relative c'' {
+    c4 c'8 r8 c,4 c'
+  }
+>>
+@end lilypond
+
+
+@ignore
+@c I don't understand this -cs
+When using continuation lines, common figures are always put in the
+same vertical position.  When this is unwanted, you can insert a rest.
+The rest will clear any previous alignment.  For
+example, you can write
+
+@example
+<4 6>8 r8
+@end example
+
+@noindent
+instead of
+@example
+<4 6>4
+@end example
+@end ignore
 
 @c @predefined
 
@@ -1300,7 +894,7 @@ Figured bass is displayed using the @code{FiguredBass} context.
 @c @file{}.
 
 @c Snippets:
-@c @rlsr{}.
+@rlsr{Figured Bass}.
 
 Internals Reference:
 @rinternals{NewBassFigure},
@@ -1312,13 +906,40 @@ Internals Reference:
 
 @knownissues
 
-By default, this method produces figures above the notes.  To get
-figures below the notes, use
+To ensure that continuation lines work properly, it is
+safest to use the same rhythm in the figure line as in
+the bass line.
 
-@example
-\override Staff.BassFigureAlignmentPositioning #'direction = #DOWN
-@end example
+@lilypond[verbatim,ragged-right,fragment,quote]
+<<
+  {
+    \clef bass
+    \repeat unfold 4 {f16. g32} f8. es16 d8 es
+  }
+  \figures {
+    \set useBassFigureExtenders = ##t
+    % The extenders are correct here, with the same rhythm as the bass
+    \repeat unfold 4 {<6 4->16. <6 4->32}
+    <5>8. r16 <6>8 <6\! 5->
+  }
+>>
+<<
+  {
+    \clef bass
+    \repeat unfold 4 {f16. g32} f8. es16 d8 es
+  }
+  \figures {
+    \set useBassFigureExtenders = ##t
+    % The extenders are incorrect here, even though the timing is the same
+    <6 4->4 <6 4->4
+    %\repeat unfold 4 {<6 4->16. <6 4->32}
+    <5>8. r16 <6>8 <6\! 5->
+  }
+>>
+@end lilypond
 
+@c I have no idea what this means -cds
+@c A predefined command for changing this has been proposed -cds
 When using figured bass above the staff with extender lines and
 @code{implicitBassFigures} the lines may become swapped around.
 Maintaining order consistently will be impossible when multiple figures