Minor improvement

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

diff --git a/Documentation/user/chords.itely b/Documentation/user/chords.itely
index 9922c33fc7a5610eeb6b5f9f8138b762c78b5e12..a6a163e0ed9f2dba31161f1767835cd59c04f1b3 100644 (file)
--- 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
 @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::
 
 @menu
 * Chord mode::

-* old Modern chords::
+* Displaying chords::

 * Figured bass::
 @end menu
 
 * Figured bass::
 @end menu
 


@@ -28,12 +28,13 @@ be displayed. In addition, figured bass notation can be displayed.
 
 @cindex chord chords
 
 
 @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::
 @menu
 * Chord mode overview::

-* Triads::
-* Seventh chords::
-* Extended chords::
-* Complex chords::
+* Common chords::
+* Extended and altered chords::

 @end menu
 
 @node Chord mode overview
 @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 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.
 
 
 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
 
 
 @seealso
 


@@ -64,139 +76,211 @@ Music Glossary:
 @rglos{chord}.
 
 Notation Reference:
 @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
 
 @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]
 
 @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
 
 @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 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
 
 @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
 
 @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
 
 @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
 
 @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
 
 @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
+
+@noindent
+Note that @code{c:5} is identical to @code{c} -- both produce a C major triad.

 
 

+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

 
 

-Individual steps can be added to or removed from a chord.
-Additions are added after the chord type and are prefixed by dots.
+@cindex additions, in chords
+
+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
 
 @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
 
 @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 ^
 @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 indicated in a
+modifier string with a prefix of @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
 
 @end lilypond
 

+It is possible to remove the 3rd step with @code{sus} and remove
+another step with @code{^} in one modifier string.
+

 @funindex /
 @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.
 
 @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 /+
 @end lilypond
 
 @funindex /+


@@ -205,11 +289,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]
 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
 
 @end lilypond
 
 @seealso
 

+Snippets:
+@rlsr{Chords}

 
 @knownissues
 
 
 @knownissues
 


@@ -217,141 +305,142 @@ Each step can only be present in a chord once.  The following
 simply produces the augmented chord, since @code{5+} is
 interpreted last.
 
 simply produces the augmented chord, since @code{5+} is
 interpreted last.
 

-

 @lilypond[quote,ragged-right,verbatim,fragment]
 @lilypond[quote,ragged-right,verbatim,fragment]

-\chordmode { c:5.5-.5+ }
+\chordmode { c1:5.5-.5+ }

 @end lilypond
 
 @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.

 
 

+Only the first inversion can be created by adding a bass note.  The
+second inversion requires changing the root of the chord.

 
 

-@ignore
-@n ode Displaying chords
-@s ubsection Displaying chords
+@lilypond[quote,ragged-right,verbatim,fragment]
+\chordmode {
+  c'1: c':/g e:6-3-^5 e:m6-^5
+}
+@end lilypond

 
 

+@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::
 
 @menu
 * Printing chord names::
 * Customizing chord names::

-* Lead sheets::

 @end menu
 
 @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
 
 
 @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 {
   \chordmode {

-    c1 f:sus4 bes/f
+    c2 f4. g8

   }
   }

-  <c e g>
-  <f bes c'>
-  <f bes d'>

 }
 }

-
-<< \new ChordNames \twoWays
-   \new Voice \twoWays >>

 @end lilypond
 
 @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.
-
-For displaying printed chord names, use the @rinternals{ChordNames}
-context.
+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,verbatim,ragged-right]
-harmonies = {
-  \chordmode {a1 b c} <d' f' a'> <e' g' b'>
-}
+@lilypond[verbatim,quote,relative=1]

 <<
 <<

-  \new ChordNames \harmonies
-  \new Staff \harmonies
+  \new ChordNames {
+    <c e g>2  <f bes c>
+    <f c' e g>1
+    \chordmode {
+      c2 f:sus4 c1:/f
+    }
+  }
+  {
+    <c e g>2  <f bes c>
+    <f, c' e g>1
+    \chordmode {
+      c2 f:sus4 c1:/f
+    }
+  }

 >>
 @end lilypond
 
 >>
 @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.
+@funindex{\chords}

 
 

-@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
+@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
+
+@lilypond[verbatim,quote,ragged-right, relative=1]
+\new ChordNames {
+  \chordmode {
+    c2 f4.:m g8:maj7
+  }

 }
 @end lilypond
 
 }
 @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:
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{showing-chords-at-changes.ly}

 
 

-@lilypond[verbatim,quote,ragged-right]
-\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
-@end lilypond
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@c {adding-bar-lines-to-chordnames-context.ly}

 
 

-@c @predefined
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{simple-lead-sheet.ly}

 
 

-@c @snippets

 
 @seealso
 
 @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
 
 @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
 
 The default chord name layout is a system for Jazz music, proposed
 by Klaus Ignatzek (see @ref{Literature list}).  There are also two


@@ -360,6 +449,10 @@ notation, and a systematic scheme called Banter chords.  The
 alternate Jazz notation is also shown on the chart in @ref{Chord
 name chart}.
 
 alternate Jazz notation is also shown on the chart in @ref{Chord
 name chart}.
 

+@c TODO --  Change this so we don't have a non-verbatim example.
+@c  Make short example in docs, then move longer example to
+@c  appendix, where the length of the snippet won't matter.
+

 In addition to the different naming systems, different note names
 are used for the root in different languages.  The predefined
 variables @code{\germanChords}, @code{\semiGermanChords},
 In addition to the different naming systems, different note names
 are used for the root in different languages.  The predefined
 variables @code{\germanChords}, @code{\semiGermanChords},


@@ -371,137 +464,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.
 
 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
 
 @funindex chordNameSeparator

+

 @item 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
 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
 
 @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
 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
 
 
 @end table
 

-
-
-
-@cindex Banter
-@cindex jazz chords
-@cindex chords, jazz
-

 @predefined
 @predefined

+

 @funindex major seven symbols
 @funindex major seven symbols

-@code{\whiteTriangleMarkup}
-@code{\blackTriangleMarkup}
+@code{\whiteTriangleMarkup},
+@code{\blackTriangleMarkup},

 @funindex \germanChords
 @code{\germanChords},
 @funindex \semiGermanChords
 @funindex \germanChords
 @code{\germanChords},
 @funindex \semiGermanChords


@@ -513,691 +539,361 @@ right of the root of the chord.  By setting
 
 
 @snippets
 
 
 @snippets

-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{chord-names-jazz.ly}

 
 

+@cindex exceptions, chord names.

 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {chord-name-exceptions.ly}
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {chord-name-exceptions.ly}

-@cindex exceptions, chord names.

 
 

+@c TODO - tweak snippet to use \blackTriangleMarkup as well

 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {chord-name-major7.ly}
 
 @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
+@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@c {changing-chord-separator.ly}

 
 

-@c Application Usage:
-@c @rprogram{}.
+The separator between different parts of a chord name
+can be set to any markup.
+
+@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}.
 
 
 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 Internals Reference:

-@c @rinternals{}.
+@c @r internals{}.

 
 @knownissues
 
 
 @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
+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.

 
 

-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}.
-
-When put together, chord names, a melody, and lyrics form a lead
-sheet:
-
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[quote,ragged-right,verbatim]
+myChords = \relative c' {
+  \chordmode{ c1 c/g c/f }
+  <c e g> <g c e> <f c' e g>
+}

 <<
 <<

-  \chords { c2 g:sus4 f e }
-  \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
-  }
-  \addlyrics { One day this shall be free __ }
+  \new ChordNames { \myChords }
+  \new Staff { \myChords }

 >>
 @end lilypond
 
 >>
 @end lilypond
 

-@c @predefined

 
 

-@c @snippets
+@node Figured bass
+@subsection Figured bass

 
 

-@seealso
-@c Music Glossary:
-@c @rglos{}.
+Figured bass notation can be displayed.

 
 

-@c Learning Manual:
-@c @rlearning{}.
+@menu
+* Introduction to figured bass::
+* Entering figured bass::
+* Displaying figured bass::
+@end menu

 
 

-@c Notation Reference:
-@c @ruser{}.
+@node Introduction to figured bass
+@unnumberedsubsubsec Introduction to figured bass

 
 

-@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 Basso continuo
+@cindex Thorough bass
+@cindex Figured bass
+@cindex Bass, thorough
+@cindex Bass, figured

 
 

-@cindex Chords mode
+@c TODO: musicological blurb about FB

 
 

-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 has support for figured bass, also called thorough bass
+or basso continuo:

 
 

-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { es4. d8 c2 }
+@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
+    }
+  }
+>>

 @end lilypond
 
 @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
+The support for figured bass consists of two parts: there is an
+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.

 
 

+@code{\figures@{ ... @}} is a shortcut notation for
+@code{\new FiguredBass @{\figuremode @{ ... @}@}}.

 
 

-@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
+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.

 
 

+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 chord names
-@subsubsection Entering chord names
-@cindex chord names
+@node Entering figured bass
+@unnumberedsubsubsec Entering figured bass

 
 

-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
+@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 figure mode, a group of bass figures is delimited by
+@code{<} and @code{>}.  The duration is entered after the @code{>}.

 
 

-@lilypond[quote,ragged-right,verbatim,ragged-right]
-twoWays = \transpose c c' {
-  \chordmode {
-    c1 f:sus4 bes/f
+@lilypond[verbatim,quote,ragged-right,fragment]
+\new FiguredBass {
+  \figuremode {
+    <6 4>2

   }
   }

-  <c e g>
-  <f bes c'>
-  <f bes d'>

 }
 }

-
-<< \new ChordNames \twoWays
-   \new Voice \twoWays >>

 @end lilypond
 
 @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
-}
+Accidentals (including naturals) can be added to figures:

 
 

-\score
-{
-\new ChordNames \chordStuff
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  <7! 6+ 4-> <5++> <3-->

 }
 @end lilypond
 
 }
 @end lilypond
 

-@node Building chords
-@subsubsection Building chords
+Augmented and diminished steps can be indicated.

 
 

-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 }
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  <6\+ 5/> <7/>
+}

 @end lilypond
 
 @end lilypond
 

-Chord steps can be altered by suffixing a @code{-} or @code{+} sign
-to the number
+A backward slash through a figure (typically used for raised
+sixth steps) can be created.

 
 

-@lilypond[quote,verbatim,fragment]
-\chordmode { c:7+ c:5+.3- c:3-.5-.7- }
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+<6>
+% FIXME: broken.
+  %<6\\>
+}

 @end lilypond
 
 @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
+Vertical spaces and brackets can be be included in figures:

 
 

-@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 }
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  <[12 _!] 8 [6  4]>
+}

 @end lilypond
 
 @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}.
+Any text markup can be inserted as a figure:

 
 

-@lilypond[quote,ragged-right,fragment,verbatim]
-\chordmode { c1 c/+g c/+f }
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  <  \markup{ \tiny \number 6 \super (1)} 5 >
+}

 @end lilypond
 
 @end lilypond
 

+@c TODO We need to include notes any time we use extenders to
+@c avoid extraneous staff creation due to Staff.use... in
+@c \bassFigureExtendersOn

 
 

-@node Lead sheets
-@subsubsection Lead sheets
-
-@cindex lead sheet
+Continuation lines can be used to indicate repeated figures:

 
 

-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]
+@lilypond[verbatim,quote,ragged-right,fragment]

 <<
 <<

-  \chords { c2 g:sus4 f e }
-  \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
+  {
+    \clef bass
+    e d c b,
+    e d c b,
+  }
+  \figures {
+    \bassFigureExtendersOn
+    <6 4> <6 3> <7 3> <7 3>
+    \bassFigureExtendersOff
+    <6 4> <6 3> <7 3> <7 3>

   }
   }

-  \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'>
-}
-<<
-  \new ChordNames \harmonies
-  \new Staff \harmonies

 >>
 @end lilypond
 
 >>
 @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
+@noindent
+In this case, the extender lines replace existing figures,
+unless the continuation lines have been explicitly terminated.

 
 

-@lilypond[quote,verbatim,ragged-right]
-harmonies = \chordmode {
-  c1:m c:m \break c:m c:m d
-}
+@lilypond[verbatim,quote,ragged-right,fragment]

 <<
 <<

-  \new ChordNames {
-    \set chordChanges = ##t
-    \harmonies }
-  \new Staff \transpose c c' \harmonies
+  \figures {
+    \bassFigureExtendersOn
+    <6 4> <6 4> <6\! 4\!> <6 4>
+  }
+  {
+    \clef bass
+    d d c c
+  }

 >>
 @end lilypond
 
 >>
 @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
 
 
 @predefined

-
-@funindex \germanChords
-@code{\germanChords},
-@funindex \semiGermanChords
-@code{\semiGermanChords}.
-@funindex \italianChords
-@code{\italianChords}.
-@funindex \frenchChords
-@code{\frenchChords}.
-
+@cindex figured bass extender lines
+@code{\bassFigureExtendersOn},
+@code{\bassFigureExtendersOff}.

 
 
 
 

+@snippets
+@c TODO  Fix this snippet -- Plus direction should be RIGHT.
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-positions-of-figured-bass-alterations.ly}

 
 @seealso
 
 @seealso

+@c Music Glossary:
+@c @rglos{}.

 
 

-Examples:
-
-Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and
-@file{scm/@/chord@/-entry@/.scm}.
-
+@c Learning Manual:
+@c @rlearning{}.

 
 

-@knownissues
+@c Notation Reference:
+@c @ruser{}.

 
 

-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.
+@c Application Usage:
+@c @rprogram{}.

 
 

+@c Installed Files:
+@c @file{}.

 
 

-@node Figured bass
-@subsection Figured bass
+Snippets:
+@rlsr{Chords}.

 
 

-@menu
-* Introduction to figured bass::
-* Entering figured bass::
-* Displaying figured bass::
-@end menu
+Internals Reference:
+@rinternals{NewBassFigure},
+@rinternals{BassFigureAlignment},
+@rinternals{BassFigureLine},
+@rinternals{BassFigureBracket},
+@rinternals{BassFigureContinuation},
+@rinternals{FiguredBass}.

 
 

-@node Introduction to figured bass
-@subsubsection Introduction to figured bass
+@c @knownissues

 
 

-@cindex Basso continuo
+@node Displaying figured bass
+@unnumberedsubsubsec Displaying figured bass

 
 

-@c TODO: musicological blurb about FB
+Figured bass can be displayed using the @code{FiguredBass} context,
+or in most staff contexts.

 
 

-LilyPond has support for figured bass
+When displayed in a @code{FiguredBass} context, the vertical location
+of the figures is independent of the notes on the staff.

 
 

-@lilypond[quote,ragged-right,verbatim,fragment]
+@lilypond[verbatim,ragged-right,fragment,quote]

 <<
 <<

-  \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
+  \relative c'' {
+    c4 c'8 r8 c,4 c'
+  }
+  \new FiguredBass {
+    \figuremode {
+      <4>4 <10 6>8 s8
+      <6 4>4 <6 4>
+    }

   }
 >>
 @end lilypond
 
   }
 >>
 @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.
-
-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.
-
-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}.
-
-
-@menu
-* Entering figured bass::
-* Displaying figured bass::
-@end menu
-
-@node Entering figured bass
-@unnumberedsubsubsec Entering figured bass
-
-
-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 }
-@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/}.
-
-@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/> }
-@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}.
+@noindent
+In the example above, the @code{FiguredBass} context must be
+explicitly instantiated to avoid creating a second (empty) staff.

 
 

-@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)} > }
-@end lilypond

 
 

+Figured bass can also be added to @code{Staff} contexts
+directly.  In this case, the vertical position of the
+figures is adjusted automatically.

 
 

-It is also possible to use continuation lines for repeated figures,
+@c TODO add a second paragraph to show direction change.  First
+@c   example should be UP (default), second should be DOWN.

 
 

-@lilypond[verbatim,relative=1]
+@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 {
-    \clef bass
-    c4 c c
+  \new Staff = myStaff
+  \figuremode {
+    <4>4 <10 6>8 s8
+    <6 4>4 <6 4>

   }
   }

-  \figures {
-    \set useBassFigureExtenders = ##t
-    <4 6>4 <3 6> <3 7>
+  %% Put notes on same Staff as figures
+  \context Staff = myStaff
+  {
+    \clef bass
+    c4 c'8 r8 c4 c'

   }
 >>
 @end lilypond
 
   }
 >>
 @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.
+When added in a Staff context, figured bass can be displayed above
+or below the staff.

 
 

-@lilypond[relative=1]
+@lilypond[verbatim,ragged-right,fragment,quote]

 <<
 <<

-  \new Voice
-  \figures {
-    \set useBassFigureExtenders = ##t
-    <6 4->4. <6 4->16. <6 4->32 <5>8. r16 <6>8 <6\! 5->
+  \new Staff = myStaff
+  \figuremode {
+    <4>4 <10 6>8 s8
+    \bassFigureStaffAlignmentDown
+    <6 4>4 <6 4>

   }
   }

+  %% Put notes on same Staff as figures
+  \context Staff = myStaff

   {
     \clef bass
   {
     \clef bass

-    f16. g32 f16. g32 f16. g32 f16. g32 f8. es16 d8 es
+    c4 c'8 r8 c4 c'

   }
 >>
 @end lilypond
 
   }
 >>
 @end lilypond
 

+
+@ignore
+@c I don't understand this -cs

 When using continuation lines, common figures are always put in the
 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
+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
 example, you can write
 
 @example

-<4 6>8 r8
+<6 4>8 r8

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -1205,83 +901,15 @@ instead of
 @example
 <4 6>4
 @end example
 @example
 <4 6>4
 @end example

+@end ignore

 
 

-Accidentals and plus signs can appear before or after the numbers,
-depending on the @code{figuredBassAlterationDirection} and
-@code{figuredBassPlusDirection}
-properties
-
-@lilypond
-  \figures {
-    <6\+> <5+> <6 4-> r
-    \set figuredBassAlterationDirection = #1
-    <6\+> <5+> <6 4-> r
-    \set figuredBassPlusDirection = #1
-    <6\+> <5+> <6 4-> r
-    \set figuredBassAlterationDirection = #-1
-    <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{}.
-
-@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
-
-@node Displaying figured bass
-@unnumberedsubsubsec Displaying figured bass
-
-Figured bass is displayed using the @code{FiguredBass} context.
-
-@c @predefined
+@predefined
+@cindex figured bass alignment
+@code{\bassFigureStaffAlignmentDown},
+@code{\bassFigureStaffAlignmentUp},
+@code{\bassFigureStaffAlignmentNeutral}.

 
 

-@c @snippets
+@snippets

 
 @seealso
 @c Music Glossary:
 
 @seealso
 @c Music Glossary:


@@ -1300,7 +928,7 @@ Figured bass is displayed using the @code{FiguredBass} context.
 @c @file{}.
 
 @c Snippets:
 @c @file{}.
 
 @c Snippets:

-@c @rlsr{}.
+@rlsr{Figured Bass}.

 
 Internals Reference:
 @rinternals{NewBassFigure},
 
 Internals Reference:
 @rinternals{NewBassFigure},


@@ -1312,13 +940,41 @@ Internals Reference:
 
 @knownissues
 
 
 @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 {
+    \bassFigureExtendersOn
+    % 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 {
+    \bassFigureExtendersOn
+    % 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
+@c TODO -- put stacking direction snippet here -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
 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