From: Graham Percival <graham@percival-music.ca>
Date: Sun, 18 May 2008 04:35:54 +0000 (-0700)
Subject: Update from Carl.
X-Git-Tag: release/2.11.47-1~5^2~34^2~1
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=fb08fd30b6e259758cba0527a490caa5a847bbc5;p=lilypond.git

Update from Carl.
---

diff --git a/Documentation/user/chords.itely b/Documentation/user/chords.itely
index 76a9b656f7..b881cb90a7 100644
--- a/Documentation/user/chords.itely
+++ b/Documentation/user/chords.itely
@@ -132,6 +132,9 @@ to create a major triad.
 
 @end table
 
+@c TODO -- perhaps add warning about c and c:maj being different, while
+@c   c:maj and c:maj7 are the same
+
 @seealso
 
 Snippets:
@@ -214,7 +217,7 @@ is allowed in a modifier string.
 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]
@@ -274,7 +277,6 @@ as notes on a staff.
 @menu
 * Printing chord names::        
 * Customizing chord names::     
-* Lead sheets::                 
 @end menu
 
 @node Printing chord names
@@ -284,21 +286,23 @@ as notes on a staff.
 @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 }
+\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}.
+Both chord names and the notes can be displayed:
 
 @lilypond[verbatim,quote,ragged-right]
-myChords = \chordmode { c2 f4. g8 }
+myChords = \relative c'{
+  \chordmode { c2 f4. g8 }
+}
 <<
-\new ChordNames \myChords
-\myChords
+  \new ChordNames { \myChords }
+  \myChords
 >>
 @end lilypond
 
@@ -308,16 +312,49 @@ of the mode of entry:
 
 @lilypond[quote,ragged-right,verbatim]
 twoWays = \relative c' {
-  \chordmode { c2 f:sus4 }
-  { <c e g>  <f bes c> }
+  \chordmode {
+     c2 f:sus4
+  }
+  {
+    <c e g>  <f bes c>
+  }
 }
 <<
-\new ChordNames \twoWays
-\new Voice \twoWays
+  \new ChordNames \twoWays
+  \new Voice \twoWays
+>>
+@end lilypond
+
+@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:
+
+@lilypond[verbatim,quote,ragged-right, relative=1]
+\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)
+  }
+  \addlyrics { One day this shall be free __ }
 >>
 @end lilypond
 
 
+
+@snippets
+
 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}
@@ -329,24 +366,16 @@ context, add @rinternals{Bar_engraver}.
   voltaOnThisStaff = ##t
   \consists "Bar_engraver"
 }
-\chordmode { \repeat volta 2 {
-  f1:maj7 f:7 bes:7
-  c:maj7
-} \alternative {
-  ees e
-}
+\chordmode {
+  \repeat volta 2 {
+    f1:maj7 f:7 bes:7 c:maj7
+  }
+  \alternative {
+    ees e
+  }
 }
 @end lilypond
 
-@code{\chords} is a shortcut method used to change the input mode to
-@code{\chordmode} and create a @code{ChordNames} context, with the
-following result:
-
-@lilypond[verbatim,quote,ragged-right, relative=1]
-\chords { c2 f4.:m g8:maj7 }
-@end lilypond
-
-
 @seealso
 
 Music Glossary:
@@ -358,7 +387,7 @@ Notation Reference:
 
 
 Snippets:
-@c @rlsr{Chords}.
+@rlsr{Chords}.
 
 Internals Reference:
 @rinternals{ChordNames},
@@ -381,6 +410,10 @@ 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
 other chord name schemes implemented: an alternate Jazz chord
@@ -410,99 +443,49 @@ If none of the default 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 dentify 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, e.g.,
 
 @lilypond[quote,ragged-right,fragment,verbatim]
-\new ChordNames \chordmode {
+\chords {
   c:7sus4
   \set chordNameSeparator
     = \markup { \typewriter "|" }
@@ -510,27 +493,17 @@ markup for a separator, e.g.,
 }
 @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 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.
 
-@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
@@ -540,12 +513,6 @@ and @q{m}.  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
@@ -572,91 +539,104 @@ and @q{m}.  The spacer is not used when the root is altered.
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {chord-name-major7.ly}
 
-@seealso
-@c Music Glossary:
-@c @rglos{}.
-
-@c Learning Manual:
-@c @rlearning{}.
-
-@c Notation Reference:
-@c @ruser{}.
+@c TODO -- see if the code below is in chord-name-exceptions.ly
+@c   if so, remove it.  If not, convert this to a snippet.
+@ignore
+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:
 
-@c Application Usage:
-@c @rprogram{}.
+@example
+FGGChordNames = @{
+  <c e g b d'>1-\markup @{ \super "maj9" @}
+  <c e g a d'>1-\markup @{ \super "6(add9)" @}
+@}
+@end example
 
-Installed Files:
-@file{scm/@/chords@/-ignatzek@/.scm},
-@file{scm/@/chord@/-entry@/.scm},
-@file{ly/@/chord@/-modifier@/-init@/.ly}.
+The second step is to convert the music from the first step to an
+exceptions list:
 
-@c Snippets: @c @rlsr{}.
+@example
+FGGExceptions = #(sequential-music-to-chord-exceptions
+FGGChordNames #t)
+@end example
 
-@c Internals Reference:
-@c @rinternals{}.
+The third step is to append the default exceptions list (in this
+case, the Ignatzek exceptions) to the newly-defined exceptions list:
 
-@knownissues
+@example
+chExceptions = #(append FGGExceptions ignatzekExceptions)
+@end example
 
-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
+The final step is to set @code{chordNameExceptions} to the
+newly-created exceptions list:
 
-@node Lead sheets
-@unnumberedsubsubsec Lead sheets
+@example
+\set chordNameExceptions = #chExceptions
+@end example
 
-@cindex lead sheet
+The entire process is illustrated below:
 
-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}.
+@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)
 
-When put together, chord names, a melody, and lyrics form a lead
-sheet:
+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]
-<<
-  \chords { c2 g:sus4 f e }
-  \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
-  }
-  \addlyrics { One day this shall be free __ }
->>
+\score
+{
+\new ChordNames \chordStuff
+}
 @end lilypond
+@end ignore
 
-@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{}.
+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:
+Internals Reference:
 @c @rinternals{}.
 
-@c @knownissues
-
+@knownissues
 
+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.
 
+@lilypond[quote,ragged-right,verbatim]
+myChords = \relative c' {
+  \chordmode{ c1 c/g c/f }
+  <c e g> <g c e> <f c' e g>
+}
+<<
+  \new ChordNames { \myChords }
+  \new Staff { \myChords }
+>>
+@end lilypond
 
 @node old Modern chords
 @subsection old Modern chords