version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.38"
+@c \version "2.11.61"
@node Chord notation
@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.
+@lilypondfile[quote]{chords-headword.ly}
+
+Chords can be entered either as normal notes or in chord mode and displayed
+using a variety of traditional European chord naming conventions. Chord
+names and figured bass notation can also be displayed.
@menu
-* Chord mode::
-* Displaying chords::
-* old Modern chords::
-* Figured bass::
+* Chord mode::
+* Displaying chords::
+* Figured bass::
@end menu
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
Chords entered using chord mode are music elements, and can be
transposed just like chords entered using simultaneous music.
-@seealso
+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>2 <g' b d>
+\chordmode { f2 g }
+@end lilypond
+
+@seealso
Music Glossary:
@rglos{chord}.
Snippets:
@rlsr{Chords}
+
+@knownissues
+
+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,ragged-right,relative=1]
+\chordmode { c2 f }
+<c e g>2 <g' b d>
+@end lilypond
+
+To avoid this behavior, explicitly create the @code{Staff} context:
+
+@lilypond[verbatim,quote,ragged-right,relative=1]
+\new Staff {
+ \chordmode { c2 f }
+ <c e g>2 <g' b d>
+}
+@end lilypond
+
@node Common chords
@unnumberedsubsubsec Common chords
\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
-}
+\chordmode { c1:7 c:m7 c:maj7 c:dim7 c:aug7 }
@end lilypond
@funindex aug
@funindex m
The table belows shows the actions of the quality modifiers on
-triads and seventh chords.
-
-@table @code
+triads and seventh chords. A more complete table of modifier usage
+is found at @ref{Common chord modifiers}.
+
+@c @table @code
+@multitable @columnfractions .2 .4 .3
+
+@item
+@b{Modifier}
+@tab
+@b{Action}
+@tab
+@b{Example}
+
+@item
+None
+@tab
+The default action; produces a major triad.
+@tab
+@lilypond[line-width=4\cm, noragged-right]
+\chordmode {
+ \override Staff.TimeSignature #'stencil = ##f
+ c1
+}
+@end lilypond
-@item m
+@item
+m, m7
+@tab
The minor chord. This modifier lowers the 3rd and (if present) the
7th step.
+@tab
+@lilypond[line-width=4\cm, noragged-right]
+\chordmode {
+ \override Staff.TimeSignature #'stencil = ##f
+ c1:m c:m7
+}
+@end lilypond
+
-@item dim
+@item
+dim, dim7
+@tab
The diminished chord. This modifier lowers the 3rd, 5th and (if
present) the 7th step.
+@tab
+@lilypond[line-width=4\cm, noragged-right]
+\chordmode {
+ \override Staff.TimeSignature #'stencil = ##f
+ c1:dim c:dim7
+}
+@end lilypond
-@item aug
+@item
+aug
+@tab
The augmented chord. This modifier raises the 5th step.
+@tab
+@lilypond[line-width=4\cm, noragged-right]
+\chordmode {
+ \override Staff.TimeSignature #'stencil = ##f
+ c1:aug
+}
+@end lilypond
-@item maj
+@item
+maj, maj7
+@tab
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.
+@tab
+@lilypond[line-width=4\cm, noragged-right]
+\chordmode {
+ \override Staff.TimeSignature #'stencil = ##f
+ c1:maj c:maj7
+}
+@end lilypond
+
+@end multitable
-@end table
@seealso
+Notation Reference:
+@ref{Common chord modifiers}.
Snippets:
-@rlsr{Chords}
+@rlsr{Chords}.
+
@node Extended and altered chords
@unnumberedsubsubsec Extended and altered chords
@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
+ c1:2 c:3 c:4 c:5
+ c1:6 c:7 c:8 c:9
+ c1:10 c:11 c:12 c:13
+ c1:14
}
@end lilypond
+@noindent
+Note that both @code{c:5} and @code{c} 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
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
Added chord steps can be altered by suffixing a @code{-} or @code{+}
-sign to the number. To alter a step that is lower than the extent,
-add it as an altered step.
+sign to the number. To alter a step that is automatically included
+as part of the basic chord 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 by @code{^}. Only one removal with @code{^}
-is allowed in a modifier string.
+Following any steps to be added, a series of steps to be removed
+is introduced in a modifier string with a prefix of @code{^}.
+If more than one step is to be removed, the steps to be
+removed are separated by @code{.} following the
+initial @code{^}.
@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 c:9^3.5 c:13.11^3.7
+}
@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
+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
-another step with @code{^} in one modifier string.
-
@funindex /
@cindex chord inversions
@cindex bass note, for chords
@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 /+
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
+Chord modifiers that can be used to produce a variety of
+standard chords are shown in
+@ref{Common chord modifiers}.
+
+
@seealso
+Notation Reference:
+@ref{Common chord modifiers}.
Snippets:
@rlsr{Chords}
+
@knownissues
Each step can only be present in a chord once. The following
\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.
+Only the second inversion can be created by adding a bass
+note. The first 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
as notes on a staff.
@menu
-* Printing chord names::
-* Customizing chord names::
-* Lead sheets::
+* Printing chord names::
+* Customizing chord names::
@end menu
@node Printing chord names
@cindex chord names
@cindex chords
-LilyPond has support for printing chord names. Chord names are
-printed in a special context, called @rinternals{ChordNames}.
+Chord names are printed in the @code{ChordNames} context:
@lilypond[verbatim,quote,relative=1,ragged-right]
-\new ChordNames \chordmode { c2 f4. g8 }
-@end lilypond
-
-To display both chord names and the notes of chords, use the
-technique in @ref{Writing music in parallel}.
-
-@lilypond[verbatim,quote,ragged-right]
-myChords = \chordmode { c2 f4. g8 }
-<<
-\new ChordNames \myChords
-\myChords
->>
+\new ChordNames {
+ \chordmode {
+ 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:
+of the mode of entry, unless there are inversions or added bass notes:
-@lilypond[quote,ragged-right,verbatim]
-twoWays = \relative c' {
- \chordmode { c2 f:sus4 }
- { <c e g> <f bes c> }
-}
+@lilypond[verbatim,quote,relative=1]
<<
-\new ChordNames \twoWays
-\new Voice \twoWays
+ \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
+@funindex{\chords}
-If repeats are used in the music, and the volta brackets are to be
-dispayed above the chord names, @code{voltaOnThisStaff} must be set
-to @code{##t}. To add bar indications in the @code{ChordNames}
-context, add @rinternals{Bar_engraver}.
+@code{\chords @{ ... @}} is a shortcut notation for
+@code{\new ChordNames @{ \chordmode @{ ... @} @}}.
-@lilypond[ragged-right,verbatim]
-\new ChordNames \with {
- \override BarLine #'bar-size = #4
- voltaOnThisStaff = ##t
- \consists "Bar_engraver"
-}
-\chordmode { \repeat volta 2 {
- f1:maj7 f:7 bes:7
- c:maj7
-} \alternative {
- ees e
-}
+@lilypond[verbatim,quote,ragged-right, relative=1]
+\chords {
+ c2 f4.:m g8:maj7
}
@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:
-
@lilypond[verbatim,quote,ragged-right, relative=1]
-\chords { c2 f4.:m g8:maj7 }
+\new ChordNames {
+ \chordmode {
+ c2 f4.:m g8:maj7
+ }
+}
@end lilypond
+@snippets
-@seealso
+@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}
+
+@seealso
Music Glossary:
@rglos{chord}.
-
Notation Reference:
@ref{Writing music in parallel}.
-
Snippets:
-@c @rlsr{Chords}.
+@rlsr{Chords}.
Internals Reference:
@rinternals{ChordNames},
+@rinternals{ChordName},
+@rinternals{Chord_name_engraver},
@rinternals{Volta_engraver},
@rinternals{Bar_engraver}.
+
@knownissues
Chords containing inversions or altered bass notes are not named
-properly.
+properly if entered using simultaneous music.
@node Customizing chord names
are also different symbols displayed for a given chord name. The
names and symbols displayed for chord names are customizable.
-The default chord name layout is a system for Jazz music, proposed
-by Klaus Ignatzek (see @ref{Literature list}). 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
+@cindex jazz chords
+@cindex chords, jazz
+
+The basic chord name layout is a system for Jazz music, proposed
+by Klaus Ignatzek (see @ref{Literature list}). The chord naming
+system can be modified as described below. An alternate jazz
+chord system has been developed using these modifications.
+The Ignatzek and alternate
+Jazz notation are 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},
@lilypondfile[ragged-right]{chord-names-languages.ly}
-@c TODO - this paragraph is moved here from an earlier section
-@c and needs to be corrected.
-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.
-
-If none of the default settings give the desired output, the chord
+If none of the existing settings give the desired output, the chord
name display can be tuned through the following properties.
-@ignore
-@c TODO Generate snippet based on the following
-@c and add explanation -td
-
-@funindex chordNameExceptions
-
@table @code
-@item 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
-
-The third step is to append the default exceptions list (in this
-case, the Ignatzek exceptions) to the newly-defined exceptions list:
-
-@example
-chExceptions = #(append FGGExceptions ignatzekExceptions)
-@end example
-The final step is to set @code{chordNameExceptions} to the
-newly-created exceptions list:
-
-@example
-\set chordNameExceptions = #chExceptions
-@end example
-
-The entire process is illustrated below:
-
-@lilypond[quote,ragged-right,verbatim]
-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
-}
+@funindex chordRootNamer
-\score
-{
-\new ChordNames \chordStuff
-}
-@end lilypond
+@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 majorSevenSymbol
@item majorSevenSymbol
-This property contains the markup object used as part of the
-printed chord name to identify a major 7 chord. Predefined
+This property contains the markup object used to follow the output
+of @code{chordRootNamer} to identify a major 7 chord. Predefined
options are @code{whiteTriangleMarkup} and
@code{blackTriangleMarkup}.
+@funindex chordNoteNamer
+
+@item chordNoteNamer
+
+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.,
+By setting @code{chordNameSeparator}, you can use any desired markup
+for a separator.
-@lilypond[quote,ragged-right,fragment,verbatim]
-\new ChordNames \chordmode {
- c:7sus4
- \set chordNameSeparator
- = \markup { \typewriter "|" }
- c:7sus4
-}
-@end lilypond
-
-@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
+@item chordNameExceptions
-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.
+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 markup 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.
+right of the root of the chord. A spacer can be placed between
+the root and @q{m} by setting @code{chordPrefixSpacer}.
+The spacer is not used when the root is altered.
@end table
-@end ignore
-
-@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
@code{\italianChords},
@funindex \frenchChords
@code{\frenchChords}.
+@endpredefined
@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}
-@seealso
-@c Music Glossary:
-@c @rglos{}.
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{adding-bar-lines-to-chordnames-context.ly}
-@c Learning Manual:
-@c @rlearning{}.
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{volta-below-chords.ly}
-@c Notation Reference:
-@c @ruser{}.
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-chord-separator.ly}
-@c Application Usage:
-@c @rprogram{}.
+
+@seealso
+Notation Reference:
+@ref{Chord name chart},
+@ref{Common chord modifiers}.
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
+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.
-@node Lead sheets
-@unnumberedsubsubsec Lead sheets
+@lilypond[quote,ragged-right,verbatim]
+myChords = \relative c' {
+ \chordmode { c1 c/g c/f }
+ <c e g>1 <g c e> <f c' e g>
+}
+<<
+ \new ChordNames { \myChords }
+ \new Staff { \myChords }
+>>
+@end lilypond
-@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}.
+@node Figured bass
+@subsection Figured bass
-When put together, chord names, a melody, and lyrics form a lead
-sheet:
+@lilypondfile[quote]{figured-bass-headword.ly}
-@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
+Figured bass notation can be displayed.
-@c @predefined
+@menu
+* Introduction to figured bass::
+* Entering figured bass::
+* Displaying figured bass::
+@end menu
-@c @snippets
+@node Introduction to figured bass
+@unnumberedsubsubsec Introduction to figured bass
-@seealso
-@c Music Glossary:
-@c @rglos{}.
+@cindex Basso continuo
+@cindex Thorough bass
+@cindex Figured bass
+@cindex Bass, thorough
+@cindex Bass, figured
-@c Learning Manual:
-@c @rlearning{}.
+@c TODO: musicological blurb about FB
-@c Notation Reference:
-@c @ruser{}.
-@c Application Usage:
-@c @rprogram{}.
+LilyPond has support for figured bass, also called thorough bass
+or basso continuo:
-@c Installed Files:
-@c @file{}.
+@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
-@c Snippets:
-@c @rlsr{}.
+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.
-@c Internals Reference:
-@c @rinternals{}.
+@code{\figures@{ ... @}} is a shortcut notation for
+@code{\new FiguredBass @{ \figuremode @{ ... @} @}}.
-@c @knownissues
+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.
+@ignore
+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}.
+@end ignore
-@node old Modern chords
-@subsection old Modern chords
+@seealso
+Music Glossary:
+@rglos{figured bass}.
-@menu
-* Entering chord names::
-* old Lead sheets::
-* old Printing chord names::
-@end menu
+Snippets:
+@rlsr{Chords}
-@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
+@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}.
-@lilypond[quote,ragged-right,verbatim,ragged-right]
-twoWays = \transpose c c' {
- \chordmode {
- c1 f:sus4 bes/f
+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
}
- <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{<>}.
+Accidentals (including naturals) can be added to figures:
-@example
-<c e g>2
-@end example
-
-@c TODO Generate snippet based on the following
-@c and add explanation -td
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+ <7! 6+ 4-> <5++> <3-->
+}
+@end lilypond
-Custom chord names may be generated:
+Augmented and diminished steps can be indicated:
-@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
+@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:
-\score
-{
-\new ChordNames \chordStuff
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+ <6> <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
-@node old Lead sheets
-@subsubsection old Lead sheets
+Any text markup can be inserted as a figure:
-@cindex lead sheet
+@lilypond[verbatim,quote,ragged-right,fragment]
+\figures {
+ <\markup { \tiny \number 6 \super (1) } 5>
+}
+@end lilypond
-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}.
+@c NOTE: We need to include notes any time we use extenders to
+@c avoid extraneous staff creation due to Staff.use... in
+@c \bassFigureExtendersOn
-When put together, chord names, lyrics and a melody form a lead
-sheet,
+Continuation lines can be used to indicate repeated figures:
-@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
+ e4 d c b,
+ e4 d c b,
+ }
+ \figures {
+ \bassFigureExtendersOn
+ <6 4>4 <6 3> <7 3> <7 3>
+ \bassFigureExtendersOff
+ <6 4>4 <6 3> <7 3> <7 3>
}
- \addlyrics { One day this shall be free __ }
>>
@end lilypond
+@noindent
+In this case, the extender lines replace existing figures,
+unless the continuation lines have been explicitly terminated.
-
-@node old Printing chord names
-@subsubsection old 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[verbatim,quote,ragged-right,fragment]
<<
- \new ChordNames \harmonies
- \new Staff \harmonies
+ \figures {
+ \bassFigureExtendersOn
+ <6 4>4 <6 4> <6\! 4\!> <6 4>
+ }
+ {
+ \clef bass
+ d4 d c c
+ }
>>
@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
+The table below summarizes the figure modifiers available.
+
+@multitable @columnfractions .1 .5 .4
+
+@item
+@b{Modifier}
+@tab
+@b{Purpose}
+@tab
+@b{Example}
+
+@item
++, -, !
+@tab
+Accidentals
+@tab
+@lilypond[line-width=4\cm]
+\figures {
+ <7! 6+ 4-> <5++> <3-->
}
-<<
- \new ChordNames {
- \set chordChanges = ##t
- \harmonies }
- \new Staff \transpose c 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.
-
-@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
-}
+@item
+\+, /
+@tab
+Augmented and diminished steps
+@tab
+@lilypond[line-width=4\cm]
+\figures {
+ <6\+ 5/> <7/>
}
@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
+@item
+\\
+@tab
+Raised sixth step
+@tab
+@lilypond[line-width=4\cm]
+\figures {
+ <6\\>
}
@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
-
-@menu
-* Introduction to figured bass::
-* Entering figured bass::
-* Displaying figured bass::
-@end menu
-
-@node Introduction to figured bass
-@subsubsection Introduction to figured bass
-
-@cindex Basso continuo
-
-@c TODO: musicological blurb about FB
-
-LilyPond has support for figured bass
-
-@lilypond[quote,ragged-right,verbatim,fragment]
+@item
+\!
+@tab
+End of continuation line
+@tab
+@lilypond[line-width=4\cm]
<<
- \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
+ \figures {
+ \bassFigureExtendersOn
+ <6 4> <6 4> <6\! 4\!> <6 4>
+ }
+ {
+ \clef bass
+ d d c c
}
>>
@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.
+@end multitable
-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}.
+@predefined
+@cindex figured bass extender lines
+@code{\bassFigureExtendersOn},
+@code{\bassFigureExtendersOff}.
+@endpredefined
-@menu
-* Entering figured bass::
-* Displaying figured bass::
-@end menu
+@snippets
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-positions-of-figured-bass-alterations.ly}
-@node Entering figured bass
-@unnumberedsubsubsec Entering figured bass
+@seealso
+@c Music Glossary:
+@c @rglos{}.
+@c
+@c Learning Manual:
+@c @rlearning{}.
+@c
+@c Notation Reference:
+@c @ref{}.
+@c
+@c Application Usage:
+@c @rprogram{}.
+@c
+@c Installed Files:
+@c @file{}.
+@c
+Snippets:
+@rlsr{Chords}.
-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
+Internals Reference:
+@rinternals{BassFigure},
+@rinternals{BassFigureAlignment},
+@rinternals{BassFigureLine},
+@rinternals{BassFigureBracket},
+@rinternals{BassFigureContinuation},
+@rinternals{FiguredBass}.
-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
+@c @knownissues
-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}.
-@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
+@node Displaying figured bass
+@unnumberedsubsubsec Displaying figured bass
+Figured bass can be displayed using the @code{FiguredBass} context,
+or in most staff contexts.
-It is also possible to use continuation lines for repeated figures,
+When displayed in a @code{FiguredBass} context, the vertical location
+of the figures is independent of the notes on the staff.
-@lilypond[verbatim,relative=1]
+@lilypond[verbatim,ragged-right,fragment,quote]
<<
- \new Staff {
- \clef bass
- c4 c c
+ \relative c'' {
+ c4 c'8 r8 c,4 c'
}
- \figures {
- \set useBassFigureExtenders = ##t
- <4 6>4 <3 6> <3 7>
+ \new FiguredBass {
+ \figuremode {
+ <4>4 <10 6>8 s8
+ <6 4>4 <6 4>
+ }
}
>>
@end lilypond
@noindent
-In this case, the extender lines always replace existing figures.
+In the example above, the @code{FiguredBass} context must be
+explicitly instantiated to avoid creating a second (empty) staff.
+
-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.
+Figured bass can also be added to @code{Staff} contexts
+directly. In this case, the vertical position of the
+figures is adjusted automatically.
-@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
+ <6 4>4 <6 4>
}
+ %% Put notes on same Staff as figures
+ \context Staff = myStaff
{
\clef bass
- f16. g32 f16. g32 f16. g32 f16. g32 f8. es16 d8 es
+ c4 c'8 r8 c4 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
+When added in a @code{Staff} context, figured bass can be displayed above
+or below the staff.
-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]
+@lilypond[verbatim,ragged-right,fragment,quote]
<<
- \new Staff = someUniqueName
- \relative c'' {
- c4 c'8 r8 c,4 c'
- }
-
- %% send to existing Staff.
- \context Staff = someUniqueName
+ \new Staff = myStaff
\figuremode {
- <4>4 <6 10>8 s8
-
- \set Staff.useBassFigureExtenders = ##t
- <4 6>4 <4 6>
+ <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
-@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.
+@predefined
+@cindex figured bass alignment
+@code{\bassFigureStaffAlignmentDown},
+@code{\bassFigureStaffAlignmentUp},
+@code{\bassFigureStaffAlignmentNeutral}.
+@endpredefined
-@c @predefined
@c @snippets
+
@seealso
@c Music Glossary:
@c @rglos{}.
-
+@c
@c Learning Manual:
@c @rlearning{}.
-
+@c
@c Notation Reference:
-@c @ruser{}.
-
+@c @ref{}.
+@c
@c Application Usage:
@c @rprogram{}.
-
+@c
@c Installed Files:
@c @file{}.
-
-@c Snippets:
-@c @rlsr{}.
+@c
+Snippets:
+@rlsr{Chords}.
Internals Reference:
-@rinternals{NewBassFigure},
+@rinternals{BassFigure},
@rinternals{BassFigureAlignment},
@rinternals{BassFigureLine},
@rinternals{BassFigureBracket},
@rinternals{BassFigureContinuation},
@rinternals{FiguredBass}.
+
@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
+ <5>8. r16 <6>8 <6\! 5->
+ }
+>>
+@end lilypond
-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
-have overlapping extender lines. To avoid this problem, please
-use @code{stacking-dir} on @code{BassFigureAlignment}.
+When using extender lines, adjacent figures with the same number in
+a different figure location can cause the figure positions to invert.
+@lilypond[verbatim,ragged-right,fragment,quote,relative=1]
+<<
+ { fis4 g g, e' }
+ \figures {
+ \bassFigureExtendersOn
+ <6 5>4 <5\! 4> < 5 _!> <6>
+ }
+>>
+@end lilypond
+
+To avoid this problem, simply turn on extenders after the figure that
+begins the extender line and turn them off at the end of the extender line.
+
+@lilypond[verbatim,ragged-right,fragment,quote,relative=1]
+<<
+ { fis4 g g, e' }
+ \figures {
+ <6 5>4 <5 4>
+ \bassFigureExtendersOn
+ < 5 _!>4 <6>
+ \bassFigureExtendersOff
+ }
+>>
+@end lilypond
-@seealso