X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchords.itely;h=c1b6c03d75729d3b3bb9bfe2e562806ea1716591;hb=b97565a9af1c13369ac7e7e9ea80c2638dbc0e51;hp=15f3d7dc819465b2c1129d1424c7608c609db762;hpb=0985c0decc5c85f7e33e8464b19d7babcc3f026f;p=lilypond.git

diff --git a/Documentation/user/chords.itely b/Documentation/user/chords.itely
index 15f3d7dc81..c1b6c03d75 100644
--- a/Documentation/user/chords.itely
+++ b/Documentation/user/chords.itely
@@ -6,7 +6,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.12.0"
 
 
 @node Chord notation
@@ -61,19 +61,21 @@ found at @ref{Input modes}.
 
 Chords entered using chord mode are music elements, and can be
 transposed just like chords entered using simultaneous music.
+@code{\chordmode} is absolute, as @code{\relative} has no effect
+on @code{chordmode} blocks. However, in @code{\chordmode} the
+absolute pitches are one octave higher than in note mode.
 
 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>2 <g' b d>
+\chordmode { f2 g }
 @end lilypond
 
 
 @seealso
-
 Music Glossary:
 @rglos{chord}.
 
@@ -84,6 +86,7 @@ Notation Reference:
 Snippets:
 @rlsr{Chords}
 
+
 @knownissues
 
 When chord mode and note mode are mixed in sequential music, and
@@ -91,16 +94,16 @@ 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>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 > < g' b d >
+  \chordmode { c2 f }
+  <c e g>2  <g' b d>
 }
 @end lilypond
 
@@ -139,7 +142,10 @@ Seventh chords can be created:
 @funindex m
 
 The table belows shows the actions of the quality modifiers on
-triads and seventh chords.  A more complete table of modifier usage
+triads and seventh chords.  The default seventh step added to
+chords is a minor or flatted seventh, which makes the dominant
+seventh the basic seventh chord.  All alterations are relative to
+the dominant seventh.  A more complete table of modifier usage
 is found at @ref{Common chord modifiers}.
 
 @c @table @code
@@ -164,11 +170,10 @@ The default action; produces a major triad.
 }
 @end lilypond
 
-@item 
+@item
 m, m7
 @tab
-The minor chord.  This modifier lowers the 3rd and (if present) the
-7th step.
+The minor chord.  This modifier lowers the 3rd.
 @tab
 @lilypond[line-width=4\cm, noragged-right]
 \chordmode {
@@ -178,7 +183,7 @@ The minor chord.  This modifier lowers the 3rd and (if present) the
 @end lilypond
 
 
-@item 
+@item
 dim, dim7
 @tab
 The diminished chord.  This modifier lowers the 3rd, 5th and (if
@@ -191,7 +196,7 @@ present) the 7th step.
 }
 @end lilypond
 
-@item 
+@item
 aug
 @tab
 The augmented chord.  This modifier raises the 5th step.
@@ -203,7 +208,7 @@ The augmented chord.  This modifier raises the 5th step.
 }
 @end lilypond
 
-@item 
+@item
 maj, maj7
 @tab
 The major 7th chord.  This modifier adds a raised 7th step.  The
@@ -221,13 +226,22 @@ to create a major triad.
 
 
 @seealso
-
 Notation Reference:
-@ref{Common chord modifiers}.
+@ref{Common chord modifiers},
+@ref{Extended and altered chords}.
 
 Snippets:
 @rlsr{Chords}.
 
+@knownissues
+Only one quality modifier should be used per chord, typically on the
+highest step present in the chord.  Chords with more than quality
+modifier will be parsed without an error or warning, but the results
+are unpredictable.  Chords that cannot be achieved with a single
+quality modifier should be altered by individual pitches, as described
+in @ref{Extended and altered chords}.
+
+
 @node Extended and altered chords
 @unnumberedsubsubsec Extended and altered chords
 
@@ -242,6 +256,8 @@ 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.
+Note that the seventh step added as part of an extended chord will be the
+minor or flatted seventh, not the major seventh.
 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
@@ -250,9 +266,9 @@ larger value is interpreted as 13.
 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
 \chordmode {
   c1:2 c:3 c:4 c:5
-  c:6 c:7 c:8 c:9
-  c:10 c:11 c:12 c:13
-  c:14
+  c1:6 c:7 c:8 c:9
+  c1:10 c:11 c:12 c:13
+  c1:14
 }
 @end lilypond
 
@@ -272,7 +288,9 @@ is added explicitly).
 @cindex additions, in chords
 
 Individual steps can be added to a chord.  Additions follow the
-extent and are prefixed by a dot (@code{.}).
+extent and are prefixed by a dot (@code{.}).  The basic seventh
+step added to a chord is the minor or flatted seventh, rather than
+the major seventh.
 
 @lilypond[quote,verbatim,fragment,relative=1]
 \chordmode {
@@ -292,7 +310,7 @@ Added steps can be as high as desired.
 
 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.
+as part of the basic chord structure, add it as an altered step.
 
 @lilypond[quote,verbatim,fragment,relative=1]
 \chordmode {
@@ -304,11 +322,11 @@ as part of the basic chode structure, add it as an altered step.
 
 @funindex ^
 
-Following any steps to be added, a series of steps to be removed 
-is introduced in a modifier string with a prefix of @code{^}.  
+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{^}. 
+initial @code{^}.
 
 @lilypond[quote,verbatim,fragment,relative=1]
 \chordmode {
@@ -356,17 +374,18 @@ moved as part of an inversion, by using @code{/+}@var{pitch}.
 @end lilypond
 
 Chord modifiers that can be used to produce a variety of
-standard chords are shown in 
+standard chords are shown in
 @ref{Common chord modifiers}.
 
-@seealso
 
+@seealso
 Notation Reference:
 @ref{Common chord modifiers}.
 
 Snippets:
 @rlsr{Chords}
 
+
 @knownissues
 
 Each step can only be present in a chord once.  The following
@@ -438,10 +457,34 @@ of the mode of entry, unless there are inversions or added bass notes:
 >>
 @end lilypond
 
+@cindex no chord symbol
+@cindex N.C. symbol
+@cindex indicating No Chord in ChordNames
+
+Rests passed to a @code{ChordNames} context will cause the
+@code{noChordSymbol} markup to be displayed.
+
+@lilypond[verbatim, quote, relative=1]
+<<
+  \new ChordNames \chordmode {
+    c1
+    r1
+    g1
+    c1
+  }
+  \new Score \chordmode {
+    c1
+    r1
+    g1
+    c1
+  }
+>>
+@end lilypond
+
 @funindex{\chords}
 
 @code{\chords @{ ... @}} is a shortcut notation for
-@code{\new ChordNames @{\chordmode @{ ... @}@}}.
+@code{\new ChordNames @{ \chordmode @{ ... @} @}}.
 
 @lilypond[verbatim,quote,ragged-right, relative=1]
 \chords {
@@ -470,23 +513,23 @@ of the mode of entry, unless there are inversions or added bass notes:
 
 
 @seealso
-
 Music Glossary:
 @rglos{chord}.
 
-
 Notation Reference:
 @ref{Writing music in parallel}.
 
-
 Snippets:
 @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
@@ -546,7 +589,7 @@ this property.
 @item majorSevenSymbol
 
 This property contains the markup object used to follow the output
-of @code{chordRootNamer} to dentify a major 7 chord. Predefined
+of @code{chordRootNamer} to identify a major 7 chord. Predefined
 options are @code{whiteTriangleMarkup} and
 @code{blackTriangleMarkup}.
 
@@ -575,21 +618,21 @@ for a separator.
 
 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}
+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
 
-@predefined
 
+@predefined
 @funindex major seven symbols
 @code{\whiteTriangleMarkup},
 @code{\blackTriangleMarkup},
@@ -601,6 +644,7 @@ and @q{m}.  The spacer is not used when the root is altered.
 @code{\italianChords},
 @funindex \frenchChords
 @code{\frenchChords}.
+@endpredefined
 
 
 @snippets
@@ -624,7 +668,6 @@ and @q{m}.  The spacer is not used when the root is altered.
 
 
 @seealso
-
 Notation Reference:
 @ref{Chord name chart},
 @ref{Common chord modifiers}.
@@ -640,6 +683,7 @@ Snippets:
 @c Internals Reference:
 @c @r internals{}.
 
+
 @knownissues
 
 Chord names are determined from both the pitches that are present
@@ -650,8 +694,8 @@ inversions or bass notes.
 
 @lilypond[quote,ragged-right,verbatim]
 myChords = \relative c' {
-  \chordmode{ c1 c/g c/f }
-  <c e g> <g c e> <f c' e g>
+  \chordmode { c1 c/g c/f }
+  <c e g>1 <g c e> <f c' e g>
 }
 <<
   \new ChordNames { \myChords }
@@ -709,7 +753,7 @@ entry of bass figures, and there is a context named
 in @code{Staff} contexts.
 
 @code{\figures@{ ... @}} is a shortcut notation for
-@code{\new FiguredBass @{\figuremode @{ ... @}@}}.
+@code{\new FiguredBass @{ \figuremode @{ ... @} @}}.
 
 
 Although the support for figured bass may superficially resemble chord
@@ -717,13 +761,15 @@ 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
 
-@seealso
 
+@seealso
 Music Glossary:
 @rglos{figured bass}.
 
@@ -758,7 +804,7 @@ Accidentals (including naturals) can be added to figures:
 }
 @end lilypond
 
-Augmented and diminished steps can be indicated.
+Augmented and diminished steps can be indicated:
 
 @lilypond[verbatim,quote,ragged-right,fragment]
 \figures {
@@ -767,12 +813,11 @@ Augmented and diminished steps can be indicated.
 @end lilypond
 
 A backward slash through a figure (typically used for raised
-sixth steps) can be created.
+sixth steps) can be created:
 
 @lilypond[verbatim,quote,ragged-right,fragment]
 \figures {
-  <6>
-  <6\\>
+  <6> <6\\>
 }
 @end lilypond
 
@@ -788,7 +833,7 @@ Any text markup can be inserted as a figure:
 
 @lilypond[verbatim,quote,ragged-right,fragment]
 \figures {
-  <  \markup{ \tiny \number 6 \super (1)} 5 >
+  <\markup { \tiny \number 6 \super (1) } 5>
 }
 @end lilypond
 
@@ -802,14 +847,14 @@ Continuation lines can be used to indicate repeated figures:
 <<
   {
     \clef bass
-    e d c b,
-    e d c b,
+    e4 d c b,
+    e4 d c b,
   }
   \figures {
     \bassFigureExtendersOn
-    <6 4> <6 3> <7 3> <7 3>
+    <6 4>4 <6 3> <7 3> <7 3>
     \bassFigureExtendersOff
-    <6 4> <6 3> <7 3> <7 3>
+    <6 4>4 <6 3> <7 3> <7 3>
   }
 >>
 @end lilypond
@@ -822,11 +867,11 @@ unless the continuation lines have been explicitly terminated.
 <<
   \figures {
     \bassFigureExtendersOn
-    <6 4> <6 4> <6\! 4\!> <6 4>
+    <6 4>4 <6 4> <6\! 4\!> <6 4>
   }
   {
     \clef bass
-    d d c c
+    d4 d c c
   }
 >>
 @end lilypond
@@ -880,7 +925,7 @@ Raised sixth step
 @tab
 End of continuation line
 @tab
-@lilypond[line-width=1.5\cm]
+@lilypond[line-width=4\cm]
 <<
   \figures {
     \bassFigureExtendersOn
@@ -896,46 +941,49 @@ End of continuation line
 @end multitable
 
 
-
 @predefined
 @cindex figured bass extender lines
 @code{\bassFigureExtendersOn},
 @code{\bassFigureExtendersOff}.
+@endpredefined
 
 
 @snippets
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {changing-the-positions-of-figured-bass-alterations.ly}
 
+
 @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:
 @rlsr{Chords}.
 
 Internals Reference:
-@rinternals{NewBassFigure},
+@rinternals{BassFigure},
 @rinternals{BassFigureAlignment},
 @rinternals{BassFigureLine},
 @rinternals{BassFigureBracket},
 @rinternals{BassFigureContinuation},
 @rinternals{FiguredBass}.
 
+
 @c @knownissues
 
+
 @node Displaying figured bass
 @unnumberedsubsubsec Displaying figured bass
 
@@ -985,7 +1033,7 @@ figures is adjusted automatically.
 @end lilypond
 
 
-When added in a Staff context, figured bass can be displayed above
+When added in a @code{Staff} context, figured bass can be displayed above
 or below the staff.
 
 @lilypond[verbatim,ragged-right,fragment,quote]
@@ -1011,36 +1059,40 @@ or below the staff.
 @code{\bassFigureStaffAlignmentDown},
 @code{\bassFigureStaffAlignmentUp},
 @code{\bassFigureStaffAlignmentNeutral}.
+@endpredefined
+
 
 @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:
 @rlsr{Chords}.
 
 Internals Reference:
-@rinternals{NewBassFigure},
+@rinternals{BassFigure},
 @rinternals{BassFigureAlignment},
 @rinternals{BassFigureLine},
 @rinternals{BassFigureBracket},
 @rinternals{BassFigureContinuation},
 @rinternals{FiguredBass}.
 
+
 @knownissues
 
 To ensure that continuation lines work properly, it is
@@ -1051,19 +1103,19 @@ the bass line.
 <<
   {
     \clef bass
-    \repeat unfold 4 {f16. g32} f8. es16 d8 es
+    \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}
+    \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
+    \repeat unfold 4 { f16. g32 } f8. es16 d8 es
   }
   \figures {
     \bassFigureExtendersOn
@@ -1079,10 +1131,10 @@ a different figure location can cause the figure positions to invert.
 
 @lilypond[verbatim,ragged-right,fragment,quote,relative=1]
 <<
- { fis g g, e' }
+ { fis4 g g, e' }
   \figures {
     \bassFigureExtendersOn
-    <6 5> <5\! 4> < 5 _!> <6>
+    <6 5>4 <5\! 4> < 5 _!> <6>
   }
 >>
 @end lilypond
@@ -1092,11 +1144,11 @@ begins the extender line and turn them off at the end of the extender line.
 
 @lilypond[verbatim,ragged-right,fragment,quote,relative=1]
 <<
- { fis g g, e' }
+ { fis4 g g, e' }
   \figures {
-    <6 5> <5 4>
+    <6 5>4 <5 4>
     \bassFigureExtendersOn
-    < 5 _!> <6>
+    < 5 _!>4 <6>
     \bassFigureExtendersOff
   }
 >>