]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/chords.itely
Merge branch 'lilypond/translation' of ssh://trettig@git.sv.gnu.org/srv/git/lilypond...
[lilypond.git] / Documentation / user / chords.itely
index a26064547ff4f9866246827f99c8811423344f99..a6a163e0ed9f2dba31161f1767835cd59c04f1b3 100644 (file)
@@ -17,9 +17,9 @@ traditional European chord naming conventions.  Chord names can also
 be displayed.  In addition, figured bass notation can be displayed.
 
 @menu
-* Chord mode::                  
-* Displaying chords::           
-* Figured bass::                
+* Chord mode::
+* Displaying chords::
+* Figured bass::
 @end menu
 
 
@@ -32,9 +32,9 @@ Chord mode is used to enter chords using an indicator of the chord
 structure, rather than the chord pitches.
 
 @menu
-* Chord mode overview::         
-* Common chords::               
-* Extended and altered chords::  
+* Chord mode overview::
+* Common chords::
+* Extended and altered chords::
 @end menu
 
 @node Chord mode overview
@@ -61,12 +61,12 @@ Chords entered using chord mode are music elements, and can be
 transposed just like chords entered using simultaneous music.
 
 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}
-}
+<c e g>2 < g b d >
+\chordmode { c2 f}
+< c e g > < g' b d >
+\chordmode { f g}
 @end lilypond
 
 
@@ -89,10 +89,8 @@ chord mode comes first, the note mode will create a new @code{Staff}
 context.
 
 @lilypond[verbatim,quote,ragged-right,relative=1]
-{
-  \chordmode { c2 f}
-  < c e g > < g' b d >
-}
+\chordmode { c2 f}
+< c e g > < g' b d >
 @end lilypond
 
 To avoid this behavior, explicitly create the @code{Staff} context:
@@ -127,7 +125,7 @@ Minor, augmented, and diminished triads are entered by placing
 \chordmode { c2:m f4:aug g:dim }
 @end lilypond
 
-Seventh chords may be created:
+Seventh chords can be created:
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
 \chordmode { c1:7 c:m7 c:maj7 c:dim7 c:aug7 }
@@ -196,12 +194,17 @@ larger value is interpreted as 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 }
+\chordmode {
+  c1:13 c:13.11 c:m13
+}
 @end lilypond
 
 @cindex additions, in chords
@@ -210,13 +213,17 @@ Individual steps can be added to a chord.  Additions follow the
 extent and are prefixed by a dot (@code{.}).
 
 @lilypond[quote,verbatim,fragment,relative=1]
-\chordmode { c1:5.6 c:3.7.8 c:3.6.13 }
+\chordmode {
+  c1:5.6 c:3.7.8 c:3.6.13
+}
 @end lilypond
 
 Added steps can be as high as desired.
 
 @lilypond[quote,verbatim,fragment,relative=1]
-\chordmode { c4:5.15 c:5.20 c:5.25 c:5.30 }
+\chordmode {
+  c4:5.15 c:5.20 c:5.25 c:5.30
+}
 @end lilypond
 
 @cindex chord steps, altering
@@ -226,19 +233,23 @@ 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- }
+\chordmode {
+  c1:7+ c:5+.3- c:3-.5-.7-
+}
 @end lilypond
 
 @cindex removals, in chords
 
 @funindex ^
 
-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{^}
+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 }
+\chordmode {
+  c1^3 c:7^5 c:9^3.5
+}
 @end lilypond
 
 @funindex sus
@@ -250,7 +261,9 @@ 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 }
+\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
@@ -265,7 +278,9 @@ chord) and added bass notes can be specified by appending
 @code{/}@var{pitch} to the chord.
 
 @lilypond[quote,ragged-right,fragment,verbatim, relative=2]
-\chordmode { c1 c/g c/f }
+\chordmode {
+  c1 c/g c/f
+}
 @end lilypond
 
 @funindex /+
@@ -274,7 +289,9 @@ 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
@@ -296,6 +313,14 @@ 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.
+
+@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
@@ -304,8 +329,8 @@ Chords can be displayed by name, in addition to the standard display
 as notes on a staff.
 
 @menu
-* Printing chord names::        
-* Customizing chord names::     
+* Printing chord names::
+* Customizing chord names::
 @end menu
 
 @node Printing chord names
@@ -319,50 +344,17 @@ Chord names are printed in the @code{ChordNames} context:
 
 @lilypond[verbatim,quote,relative=1,ragged-right]
 \new ChordNames {
-  \chordmode { c2 f4. g8 }
-}
-@end lilypond
-
-Both chord names and the notes can be displayed:
-
-@lilypond[verbatim,quote,ragged-right]
-myChords = \relative c'{
-  \chordmode { c2 f4. g8 }
-}
-<<
-  \new ChordNames {
-    \chordmode { c2 f4. g8 }
-  }
-  {
-    \chordmode { c2 f4. g8 }
+  \chordmode {
+    c2 f4. g8
   }
->>
-@end lilypond
-
-Setting @rinternals{ChordNames}.@code{chordChanges} to true causes
-chords names to be displayed only when the chord changes or 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 {
-    \relative c' { \harmonies }
-  }
->>
 @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]
+@lilypond[verbatim,quote,relative=1]
 <<
   \new ChordNames {
     <c e g>2  <f bes c>
@@ -383,45 +375,34 @@ of the mode of entry, unless there are inversions or added bass notes:
 
 @funindex{\chords}
 
-@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:
+@code{\chords @{ ... @}} is a shortcut notation for
+@code{\new ChordNames @{\chordmode @{ ... @}@}}.
 
 @lilypond[verbatim,quote,ragged-right, relative=1]
-\chords { c2 f4.:m g8:maj7 }
+\chords {
+  c2 f4.:m g8:maj7
+}
 @end lilypond
 
-@cindex lead sheet
-
-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)
+@lilypond[verbatim,quote,ragged-right, relative=1]
+\new ChordNames {
+  \chordmode {
+    c2 f4.:m g8:maj7
   }
-  \addlyrics { One day this shall be free __ }
->>
+}
 @end lilypond
 
 @snippets
 
-@c TODO -- replace this with a snippets
-To add bar indications in the @code{ChordNames}
-context, add @rinternals{Bar_engraver}.
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{showing-chords-at-changes.ly}
+
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@c {adding-bar-lines-to-chordnames-context.ly}
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{simple-lead-sheet.ly}
 
-@lilypond[ragged-right,verbatim]
-\new ChordNames \with {
-  \override BarLine #'bar-size = #4
-  \consists "Bar_engraver"
-}
-\chordmode {
-  f1:maj7 f:7 bes:7 c:maj7 ees e
-}
-@end lilypond
 
 @seealso
 
@@ -468,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}.
 
+@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},
@@ -517,16 +502,7 @@ bass note can be printed in lower case.
 
 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]
-\chords {
-  c:7sus4
-  \set chordNameSeparator
-    = \markup { \typewriter "|" }
-  c:7sus4
-}
-@end lilypond
+for a separator.
 
 @funindex chordNameExceptions
 
@@ -535,8 +511,7 @@ for a separator, e.g.,
 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.  See @code{FIXME -- future ref to snippet}
-for information on creating this list.
+output to create the chord name.
 
 @funindex chordPrefixSpacer
 @item chordPrefixSpacer
@@ -551,8 +526,8 @@ and @q{m}.  The spacer is not used when the root is altered.
 @predefined
 
 @funindex major seven symbols
-@code{\whiteTriangleMarkup}
-@code{\blackTriangleMarkup}
+@code{\whiteTriangleMarkup},
+@code{\blackTriangleMarkup},
 @funindex \germanChords
 @code{\germanChords},
 @funindex \semiGermanChords
@@ -564,31 +539,43 @@ and @q{m}.  The spacer is not used when the root is altered.
 
 
 @snippets
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{chord-names-jazz.ly}
 
+@cindex exceptions, chord names.
 @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}
 
-@c  This has yet to be approved
-@ignore
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{adding-bars-to-chordnames.ly)
-@end ignore
+@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@c {adding-bars-to-chordnames.ly)
 
-@c This has yet to be made a docs snippet
-@ignore
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-(volta-brackets-over-chord-names.ly)
-@end ignore
+@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@c {volta-brackets-over-chord-names.ly}
+
+@c TODO  convert to snippet
+@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@c {changing-chord-separator.ly}
+
+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},
@@ -597,8 +584,8 @@ Installed Files:
 Snippets:
 @rlsr{Chords}.
 
-Internals Reference:
-@c @rinternals{}.
+@c Internals Reference:
+@c @r internals{}.
 
 @knownissues
 
@@ -623,187 +610,176 @@ myChords = \relative c' {
 @node Figured bass
 @subsection Figured bass
 
+Figured bass notation can be displayed.
+
 @menu
-* Introduction to figured bass::  
-* Entering figured bass::       
-* Displaying figured bass::     
+* Introduction to figured bass::
+* Entering figured bass::
+* Displaying figured bass::
 @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 {
+    <6 4>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 (including naturals) 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 {
+  <7! 6+ 4-> <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}.
+Augmented and diminished steps can be indicated.
 
-@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
+
+A backward slash through a figure (typically used for raised
+sixth steps) can be created.
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+<6>
+% FIXME: broken.
+  %<6\\>
+}
+@end lilypond
+
+
+Vertical spaces and brackets can be be included in figures:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  <[12 _!] 8 [6  4]>
+}
+@end lilypond
+
+
+Any text markup can be inserted as a figure:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+  <  \markup{ \tiny \number 6 \super (1)} 5 >
+}
 @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
 
-It is also possible to use continuation lines for repeated figures,
+Continuation lines can be used to indicate repeated figures:
 
-@lilypond[verbatim,relative=1]
+@lilypond[verbatim,quote,ragged-right,fragment]
 <<
-  \new Staff {
+  {
     \clef bass
-    c4 c c
+    e d c b,
+    e d c b,
   }
   \figures {
-    \set useBassFigureExtenders = ##t
-    <4 6>4 <3 6> <3 7>
+    \bassFigureExtendersOn
+    <6 4> <6 3> <7 3> <7 3>
+    \bassFigureExtendersOff
+    <6 4> <6 3> <7 3> <7 3>
   }
 >>
 @end lilypond
 
 @noindent
-In this case, the extender lines always replace existing figures.
+In this case, the extender lines replace existing figures,
+unless the continuation lines have been explicitly terminated.
 
-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.
-
-@lilypond[relative=1]
+@lilypond[verbatim,quote,ragged-right,fragment]
 <<
-  \new Voice
   \figures {
-    \set useBassFigureExtenders = ##t
-    <6 4->4. <6 4->16. <6 4->32 <5>8. r16 <6>8 <6\! 5->
+    \bassFigureExtendersOn
+    <6 4> <6 4> <6\! 4\!> <6 4>
   }
   {
     \clef bass
-    f16. g32 f16. g32 f16. g32 f16. g32 f8. es16 d8 es
+    d d c c
   }
 >>
 @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
-
-@example
-<4 6>8 r8
-@end example
-
-@noindent
-instead of
-@example
-<4 6>4
-@end example
-
-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
+@predefined
+@cindex figured bass extender lines
+@code{\bassFigureExtendersOn},
+@code{\bassFigureExtendersOff}.
 
-@c @predefined
 
-@c @snippets
+@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
 @c Music Glossary:
@@ -821,22 +797,119 @@ automatically.
 @c Installed Files:
 @c @file{}.
 
-@c Snippets:
-@c @rlsr{}.
+Snippets:
+@rlsr{Chords}.
 
-@c Internals Reference:
-@c @rinternals{}.
+Internals Reference:
+@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.
 
-@c @predefined
+When displayed in a @code{FiguredBass} context, the vertical location
+of the figures is independent of the notes on the staff.
 
-@c @snippets
+@lilypond[verbatim,ragged-right,fragment,quote]
+<<
+  \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
+
+@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 add a second paragraph to show direction change.  First
+@c   example should be UP (default), second should be DOWN.
+
+@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 {
+    <4>4 <10 6>8 s8
+    <6 4>4 <6 4>
+  }
+  %% Put notes on same Staff as figures
+  \context Staff = myStaff
+  {
+    \clef bass
+    c4 c'8 r8 c4 c'
+  }
+>>
+@end lilypond
+
+
+When added in a Staff context, figured bass can be displayed above
+or below the staff.
+
+@lilypond[verbatim,ragged-right,fragment,quote]
+<<
+  \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
+    c4 c'8 r8 c4 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
+<6 4>8 r8
+@end example
+
+@noindent
+instead of
+@example
+<4 6>4
+@end example
+@end ignore
+
+@predefined
+@cindex figured bass alignment
+@code{\bassFigureStaffAlignmentDown},
+@code{\bassFigureStaffAlignmentUp},
+@code{\bassFigureStaffAlignmentNeutral}.
+
+@snippets
 
 @seealso
 @c Music Glossary:
@@ -855,7 +928,7 @@ Figured bass is displayed using the @code{FiguredBass} context.
 @c @file{}.
 
 @c Snippets:
-@c @rlsr{}.
+@rlsr{Figured Bass}.
 
 Internals Reference:
 @rinternals{NewBassFigure},
@@ -867,13 +940,41 @@ 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 {
+    \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