]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/pitches.itely
Docs: run convert-ly for 2.14.0.
[lilypond.git] / Documentation / notation / pitches.itely
index 3cf931333b15a05065449dfb88f4aca5eb162666..f253d35a0df28c057dc07fd5e81635a829fcdaa9 100644 (file)
@@ -3,10 +3,11 @@
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
-    version that you are working on.  See TRANSLATION for details.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.14.0"
 
 
 @node Pitches
@@ -37,7 +38,6 @@ mode.  In most cases, relative mode will be more convenient.
 * Relative octave entry::
 * Accidentals::
 * Note names in other languages::
-* Non-Western note names and accidentals::
 @end menu
 
 
@@ -57,11 +57,13 @@ through@tie{}@code{g}.  The note names @code{c} to @code{b} are
 engraved in the octave below middle C.
 
 @c don't use c' here.
-@lilypond[verbatim,quote,fragment]
-\clef bass
-c d e f
-g a b c
-d e f g
+@lilypond[verbatim,quote]
+{
+  \clef bass
+  c4 d e f
+  g4 a b c
+  d4 e f g
+}
 @end lilypond
 
 @cindex octave changing mark
@@ -74,13 +76,15 @@ or comma@tie{}(@code{,}) character.  Each@tie{}@code{'} raises the
 pitch by one octave; each@tie{}@code{,} lowers the pitch by an
 octave.
 
-@lilypond[verbatim,quote,fragment]
-\clef treble
-c' c'' e' g
-d'' d' d c
-\clef bass
-c, c,, e, g
-d,, d, d c
+@lilypond[verbatim,quote]
+{
+  \clef treble
+  c'4 c'' e' g
+  d''4 d' d c
+  \clef bass
+  c,4 c,, e, g
+  d,,4 d, d c
+}
 @end lilypond
 
 
@@ -99,7 +103,7 @@ Snippets:
 @cindex relative octave entry
 @cindex octave entry, relative
 @cindex relative octave specification
-@cindex ocatve specification, relative
+@cindex octave specification, relative
 
 @funindex relative
 @funindex \relative
@@ -118,7 +122,7 @@ octave.
 
 In relative mode, each note is assumed to be as close to the
 previous note as possible.  This means that the octave of each
-pitch inside @var{musicexpr} is calculated as follows:
+pitch inside @code{@var{musicexpr}} is calculated as follows:
 
 @itemize
 @item
@@ -139,10 +143,9 @@ octaves.
 
 @item
 The pitch of the first note is relative to
-@code{@var{startpitch}}.  @var{startpitch} is specified in
+@code{@var{startpitch}}.  @code{@var{startpitch}} is specified in
 absolute octave mode, and it is recommended that it be a octave of
 @code{c}.
-
 @end itemize
 
 Here is the relative mode shown in action:
@@ -281,7 +284,7 @@ Internals Reference:
 
 
 @c DEPRECATED
-If no @var{startpitch} is specified for @code{\relative},
+If no @code{@var{startpitch}} is specified for @code{\relative},
 then@tie{}@code{c'} is assumed.  However, this is a deprecated
 option and may disappear in future versions, so its use is
 discouraged.
@@ -378,7 +381,7 @@ Accidentals on tied notes are only printed at the beginning of a
 new system:
 
 @lilypond[verbatim,quote,relative=2]
-cis1 ~ cis ~
+cis1~ cis~
 \break
 cis
 @end lilypond
@@ -386,10 +389,12 @@ cis
 
 @snippets
 
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle,ragged-right]
+{hiding-accidentals-on-tied-notes-at-the-start-of-a-new-system.ly}
+
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {preventing-extra-naturals-from-being-automatically-added.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{sharp},
@@ -437,80 +442,79 @@ any standard.
 @cindex language, pitch names in other
 
 There are predefined sets of note and accidental names for various
-other languages.  To use them, include the language-specific init
-file listed below.  For example, to use English note names, add
-@code{@w{\include "english.ly"}} to the input file.
+other languages.  Selecting the note name language is usually done
+at the beginning of the file; the following example is written
+using Italian note names:
 
-@warning{Because some other include files (such as @code{@w{predefined-fretboards.ly}})
-use default (Nederlands) note names, the @code{@bs{}include}
-command for the language file should be placed after all other
-LilyPond distribution files.}
+@lilypond[quote,verbatim]
+\language "italiano"
+
+\relative do' {
+  do re mi sib
+}
+@end lilypond
 
-The available language files and the note names they define are:
+The available languages and the note names they define are:
 
 @quotation
-@multitable {@file{nederlands.ly}} {do re mi fa sol la sib si}
-@headitem Language File
+@multitable {@code{nederlands}} {do re mi fa sol la sib si}
+@headitem Language
   @tab Note Names
-@item @file{nederlands.ly}
+@item @code{nederlands}
   @tab c d e f g a bes b
-@item @file{arabic.ly}
+@item @code{catalan}
   @tab do re mi fa sol la sib si
-@item @file{catalan.ly}
-  @tab do re mi fa sol la sib si
-@item @file{deutsch.ly}
+@item @code{deutsch}
   @tab c d e f g a b h
-@item @file{english.ly}
+@item @code{english}
   @tab c d e f g a bf b
-@item @file{espanol.ly}
+@item @code{espanol}
   @tab do re mi fa sol la sib si
-@item @file{italiano.ly}
+@item @code{italiano}
   @tab do re mi fa sol la sib si
-@item @file{norsk.ly}
+@item @code{norsk}
   @tab c d e f g a b h
-@item @file{portugues.ly}
+@item @code{portugues}
   @tab do re mi fa sol la sib si
-@item @file{suomi.ly}
+@item @code{suomi}
   @tab c d e f g a b h
-@item @file{svenska.ly}
+@item @code{svenska}
   @tab c d e f g a b h
-@item @file{vlaams.ly}
+@item @code{vlaams}
   @tab do re mi fa sol la sib si
 @end multitable
 @end quotation
 
-@noindent
-and the accidental suffixes they define are:
+In addition to note names, accidental suffixes may
+also vary depending on the language:
 
 @quotation
-@multitable {@file{nederlands.ly}} {-s/-sharp} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
-@headitem Language File
+@multitable {@code{nederlands}} {-s/-sharp} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
+@headitem Language
   @tab sharp @tab flat @tab double sharp @tab double flat
-@item @file{nederlands.ly}
+@item @code{nederlands}
   @tab -is @tab -es @tab -isis @tab -eses
-@item @file{arabic.ly}
-  @tab -d @tab -b @tab -dd @tab -bb
-@item @file{catalan.ly}
+@item @code{catalan}
   @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
-@item @file{deutsch.ly}
+@item @code{deutsch}
   @tab -is @tab -es @tab -isis @tab -eses
-@item @file{english.ly}
+@item @code{english}
   @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
     @tab -ff/-flatflat
-@item @file{espanol.ly}
+@item @code{espanol}
   @tab -s @tab -b @tab -ss/-x @tab -bb
-@item @file{italiano.ly}
+@item @code{italiano}
   @tab -d @tab -b @tab -dd @tab -bb
-@item @file{norsk.ly}
+@item @code{norsk}
   @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
     @tab -essess/-eses
-@item @file{portugues.ly}
+@item @code{portugues}
   @tab -s @tab -b @tab -ss @tab -bb
-@item @file{suomi.ly}
+@item @code{suomi}
   @tab -is @tab -es @tab -isis @tab -eses
-@item @file{svenska.ly}
+@item @code{svenska}
   @tab -iss @tab -ess @tab -ississ @tab -essess
-@item @file{vlaams.ly}
+@item @code{vlaams}
   @tab -k @tab -b @tab -kk @tab -bb
 @end multitable
 @end quotation
@@ -534,105 +538,52 @@ a2 as e es a ases e eses
 @cindex sesqui-flat
 
 Some music uses microtones whose alterations are fractions of a
-@q{normal} sharp or flat.  The note names for quarter-tones
-defined in the various language files are listed in the following
-table.  Here the prefixes @notation{semi-} and @notation{sesqui-}
-mean @q{half} and @q{one and a half}, respectively.  For the other
-languages, no special names have been defined yet.
+@q{normal} sharp or flat.  The following table lists note names
+for quarter-tone accidentals in various languages; here the prefixes
+@notation{semi-} and @notation{sesqui-} respectively
+mean @q{half} and @q{one and a half}.  Languages that do not
+appear in this table do not provide special note names yet.
 
 @quotation
-@multitable {@file{nederlands.ly}} {@b{semi-sharp}} {@b{semi-flat}} {@b{sesqui-sharp}} {@b{sesqui-flat}}
-@headitem Language File
+@multitable {@code{nederlands}} {@b{semi-sharp}} {@b{semi-flat}} {@b{sesqui-sharp}} {@b{sesqui-flat}}
+@headitem Language
   @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 
-@item @file{nederlands.ly}
+@item @code{nederlands}
   @tab -ih @tab -eh @tab -isih @tab -eseh
-@item @file{arabic.ly}
-  @tab -sd @tab -sb @tab -dsd @tab -bsb
-@item @file{deutsch.ly}
+@item @code{deutsch}
   @tab -ih @tab -eh @tab -isih @tab -eseh
-@item @file{english.ly}
+@item @code{english}
   @tab -qs @tab -qf @tab -tqs @tab -tqf
-@item @file{espanol.ly}
+@item @code{espanol}
   @tab -cs @tab -cb @tab -tcs @tab -tcb
-@item @file{italiano.ly}
+@item @code{italiano}
   @tab -sd @tab -sb @tab -dsd @tab -bsb
-@item @file{portugues.ly}
+@item @code{portugues}
   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
 @end multitable
 @end quotation
 
+Most languages presented here are commonly associated with
+Western classical music, also referred to as
+@notation{Common Practice Period}.  However, alternate
+pitches and tuning systems are also supported: see
+@ref{Common notation for non-Western music}.
+
 
 @seealso
 Music Glossary:
-@rglos{Pitch names}.
-
-Snippets:
-@rlsr{Pitches}.
-
-
-@node Non-Western note names and accidentals
-@unnumberedsubsubsec Non-Western note names and accidentals
-
-Many non-Western musics (and some Western folk and
-traditional musics) employ alternative or extended tuning
-systems that do not fit readily into standard classical
-notation.
-
-In some cases standard notation is still used, with the
-pitch differences being implicit.  For example, Arabic
-music is notated with standard semitone and quarter-tone
-accidentals, with the precise pitch alterations being
-determined by context.  Others require extended or unique
-notations.
-
-@notation{Turkish classical music}, or Ottoman music,
-employs melodic forms known as @notation{makamlar}, whose
-intervals are based on 1/9 divisions of the whole tone.
-From a modern notational point of view, it is convenient
-to use the standard Western staff notes (c, d, e, ...)
-with special accidentals unique to Turkish music.  These
-accidentals are defined in @file{makam.ly} (to locate this
-file on your system, see
-@rlearning{Other sources of information}).  The following
-table gives their names, the accidental suffix that must
-be added to notes, and their pitch alteration as a
-fraction of one whole tone.
-
-@c TODO: can we include the actual accidentals in this table?
-@quotation
-@multitable {@b{büyük mücenneb (sharp)}} {@b{suffix}} {@b{pitch alteration}}
-@headitem Accidental name
-  @tab suffix @tab pitch alteration
-
-@item büyük mücenneb (sharp)
-  @tab -bm @tab +8/9
-@item kücük mücenneb (sharp)
-  @tab -k @tab +5/9
-@item bakiye (sharp)
-  @tab -b @tab +4/9
-@item koma (sharp)
-  @tab -c @tab +1/9
-
-@item koma (flat)
-  @tab -fc @tab -1/9
-@item bakiye (flat)
-  @tab -fb @tab -4/9
-@item kücük mücenneb (flat)
-  @tab -fk @tab -5/9
-@item büyük mücenneb (flat)
-  @tab -fbm @tab -8/9
-@end multitable
-@end quotation
-
-For further information on Turkish classical music and
-makamlar, see @ref{Turkish classical music}.
+@rglos{Pitch names},
+@rglos{Common Practice Period}.
 
+Notation Reference:
+@ref{Common notation for non-Western music}.
 
-@snippets
+Installed Files:
+@file{scm/define-note-names.scm}.
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{makam-example.ly}
+Snippets:
+@rlsr{Pitches}.
 
 
 @node Changing multiple pitches
@@ -643,6 +594,9 @@ This section discusses how to modify pitches.
 @menu
 * Octave checks::
 * Transpose::
+* Inversion::
+* Retrograde::
+* Modal transformations::
 @end menu
 
 @node Octave checks
@@ -676,13 +630,13 @@ correction.
 @end lilypond
 
 The octave of notes may also be checked with the
-@code{\octaveCheck}@tie{}@var{controlpitch} command.
-@var{controlpitch} is specified in absolute mode.  This checks
-that the interval between the previous note and the
-@var{controlpitch} is within a fourth (i.e., the normal
+@code{\octaveCheck@tie{}@var{controlpitch}} command.
+@code{@var{controlpitch}} is specified in absolute mode.  This
+checks that the interval between the previous note and the
+@code{@var{controlpitch}} is within a fourth (i.e., the normal
 calculation of relative mode).  If this check fails, a warning is
 printed, but the previous note is not changed.  Future notes are
-relative to the @var{controlpitch}.
+relative to the @code{@var{controlpitch}}.
 
 @lilypond[verbatim,quote]
 \relative c'' {
@@ -740,11 +694,12 @@ syntax is
 @end example
 
 @noindent
-This means that @var{musicexpr} is transposed by the interval
-between the pitches @var{frompitch} and @var{topitch}: any note
-with pitch @var{frompitch} is changed to @var{topitch} and any
-other note is transposed by the same interval.  Both pitches are
-entered in absolute mode.
+This means that @code{@var{musicexpr}} is transposed by the
+interval between the pitches @code{@var{frompitch}} and
+@code{@var{topitch}}: any note with pitch @code{@var{frompitch}}
+is changed to @code{@var{topitch}} and any other note is
+transposed by the same interval.  Both pitches are entered in
+absolute mode.
 
 @warning{Music inside a @code{@bs{}transpose} block is absolute
 unless a @code{@bs{}relative} is included in the block.}
@@ -835,8 +790,11 @@ see @ref{Instrument transpositions}.
 
 @seealso
 Notation Reference:
+@ref{Instrument transpositions},
+@ref{Inversion},
+@ref{Modal transformations},
 @ref{Relative octave entry},
-@ref{Instrument transpositions}.
+@ref{Retrograde}.
 
 Snippets:
 @rlsr{Pitches}.
@@ -859,6 +817,213 @@ The relative conversion will not affect @code{\transpose},
 To use relative mode within transposed music, an additional
 @code{\relative} must be placed inside @code{\transpose}.
 
+@node Inversion
+@unnumberedsubsubsec Inversion
+
+@cindex inversion
+@cindex operation, inversion
+@funindex \inversion
+
+A music expression can be inverted with:
+
+@example
+\inversion @var{from-pitch} @var{to-pitch} @var{musicexpr}
+@end example
+
+The @code{@var{musicexpr}} is inverted interval-by-interval,
+and then transposed so that @code{@var{from-pitch}} is mapped
+to @code{@var{to-pitch}}.
+
+@lilypond[verbatim,quote]
+music = \relative c' { c d e f }
+\new Staff {
+  \music
+  \inversion d' d' \music
+  \inversion d' ees' \music
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Modal transformations},
+@ref{Retrograde},
+@ref{Transpose}.
+
+
+@node Retrograde
+@unnumberedsubsubsec Retrograde
+
+@cindex retrograde transformation
+@cindex transformation, retrograde
+@cindex operation, retrograde
+@funindex \retrograde
+@funindex retrograde
+
+A music expression can be reversed to produce its retrograde:
+
+@lilypond[verbatim,quote]
+music = \relative c' { c8. ees16( fis8. a16 b8.) gis16 f8. d16 }
+
+\new Staff {
+  \music
+  \retrograde \music
+}
+@end lilypond
+
+@knownissues
+Manual ties inside @code{\retrograde} will be broken and
+generate warnings.  Some ties can be generated automatically
+by enabling @ref{Automatic note splitting}.
+
+@seealso
+Notation Reference:
+@ref{Inversion},
+@ref{Modal transformations},
+@ref{Transpose}.
+
+
+@node Modal transformations
+@unnumberedsubsubsec Modal transformations
+
+@cindex modal transformations
+@cindex transformations, modal
+@cindex operations, modal
+
+In a musical composition that is based on a scale, a motif is
+frequently transformed in various ways.  It may be
+@notation{transposed} to start at different places in the scale or
+it may be @notation{inverted} around a pivot point in the scale.
+It may also be reversed to produce its @notation{retrograde}, see
+@ref{Retrograde}.
+
+@warning{Any note that does not lie within the given scale will be
+left untransformed.}
+
+@subsubheading Modal transposition
+
+@cindex modal transposition
+@cindex transposition, modal
+@cindex operation, transposition
+@funindex \modalTranspose
+@funindex modalTranspose
+
+A motif can be transposed within a given scale with:
+
+@example
+\modalTranspose @var{from-pitch} @var{to-pitch} @var{scale} @var{motif}
+@end example
+
+The notes of @var{motif} are shifted within the @var{scale} by the
+number of scale degrees given by the interval between @var{to-pitch}
+and @var{from-pitch}:
+
+@lilypond[verbatim,quote]
+diatonicScale = \relative c' { c d e f g a b }
+motif = \relative c' { c8 d e f g a b c }
+
+\new Staff {
+  \motif
+  \modalTranspose c f \diatonicScale \motif
+  \modalTranspose c b, \diatonicScale \motif
+}
+@end lilypond
+
+An ascending scale of any length and with any intervals may be
+specified:
+
+@lilypond[verbatim,quote]
+pentatonicScale = \relative c' { ges aes bes des ees }
+motif = \relative c' { ees8 des ges,4 <ges' bes,> <ges bes,> }
+
+\new Staff {
+  \motif
+  \modalTranspose ges ees' \pentatonicScale \motif
+}
+@end lilypond
+
+When used with a chromatic scale @code{\modalTranspose} has a
+similar effect to @code{\transpose}, but with the ability to
+specify the names of the notes to be used:
+
+@lilypond[verbatim,quote]
+chromaticScale = \relative c' { c cis d dis e f fis g gis a ais b }
+motif = \relative c' { c8 d e f g a b c }
+
+\new Staff {
+  \motif
+  \transpose c f \motif
+  \modalTranspose c f \chromaticScale \motif
+}
+@end lilypond
+
+@subsubheading Modal inversion
+
+@cindex modal inversion
+@cindex inversion, modal
+@cindex operation, modal inversion
+@funindex \modalInversion
+@funindex modalInversion
+
+A motif can be inverted within a given scale around a given pivot
+note and transposed in a single operation with:
+
+@example
+\modalInversion @var{around-pitch} @var{to-pitch} @var{scale} @var{motif}
+@end example
+
+The notes of @var{motif} are placed the same number of scale degrees
+from the @var{around-pitch} note within the @var{scale}, but in the
+opposite direction, and the result is then shifted within the
+@var{scale} by the number of scale degrees given by the interval between
+@var{to-pitch} and @var{around-pitch}.
+
+So to simply invert around a note in the scale use the same value for
+@var{around-pitch} and @var{to-pitch}:
+
+@lilypond[verbatim,quote]
+octatonicScale = \relative c' { ees f fis gis a b c d }
+motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }
+
+\new Staff {
+  \motif
+  \modalInversion fis' fis' \octatonicScale \motif
+}
+@end lilypond
+
+To invert around a pivot between two notes in the scale, invert around
+one of the notes and then transpose by one scale degree.  The two notes
+specified can be interpreted as bracketing the pivot point:
+
+@lilypond[verbatim,quote]
+scale = \relative c' { c g' }
+motive = \relative c' { c c g' c, }
+
+\new Staff {
+  \motive
+  \modalInversion c' g' \scale \motive
+}
+@end lilypond
+
+The combined operation of inversion and retrograde produce the
+retrograde-inversion:
+
+@lilypond[verbatim,quote]
+octatonicScale = \relative c' { ees f fis gis a b c d }
+motif = \relative c' { c8. ees16 fis8. a16 b8. gis16 f8. d16 }
+
+\new Staff {
+  \motif
+  \retrograde \modalInversion c' c' \octatonicScale \motif
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Inversion},
+@ref{Retrograde},
+@ref{Transpose}.
+
+
 @node Displaying pitches
 @subsection Displaying pitches
 
@@ -907,12 +1072,14 @@ This section discusses how to alter the output of pitches.
 @cindex clef, mezzosoprano
 @cindex clef, baritone
 @cindex clef, varbaritone
-@cindex subbass clef, subbass
+@cindex clef, subbass
+
 
 @funindex \clef
 @funindex clef
 
-The clef may be altered.  Middle C is shown in every example.
+The clef may be altered.  Middle C is shown in every example.  The
+following clef names can (but do not need to) be enclosed in quotes.
 
 @lilypond[verbatim,quote,relative=1]
 \clef treble
@@ -945,44 +1112,47 @@ c2 c
 c2 c
 \clef percussion
 c2 c
-\clef tab
-c2 c
 
 \break
 
-\clef G
+\clef G   % synonym for treble
 c2 c
-\clef F
+\clef F   % synonym for bass
 c2 c
-\clef C
+\clef C   % synonym for alto
 c2 c
-
 @end lilypond
 
-Further supported clefs are described under @ref{Mensural clefs}
-and @ref{Gregorian clefs}.
-
-@cindex transposing clefs
+@cindex transposing clef
 @cindex clef, transposing
 @cindex octave transposition
 @cindex choral tenor clef
 @cindex tenor clef, choral
 
 By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
-clef is transposed one octave down or up, respectively,
+clef is transposed one octave down or up respectively,
 and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
-The clef name must be enclosed in quotes when it contains
-underscores or digits.
+Other integers can be used if required.  Clef names containing
+non-alphabetic characters must be enclosed in quotes
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote,relative=1]
 \clef treble
 c2 c
 \clef "treble_8"
 c2 c
 \clef "bass^15"
 c2 c
+\clef "alto_2"
+c2 c
+\clef "G_8"
+c2 c
+\clef "F^5"
+c2 c
 @end lilypond
 
+Some special purpose clefs are described in @ref{Mensural clefs},
+@ref{Gregorian clefs}, @ref{Default tablatures}, and @ref{Custom
+tablatures}.
 
 @snippets
 
@@ -993,7 +1163,9 @@ c2 c
 @seealso
 Notation Reference:
 @ref{Mensural clefs},
-@ref{Gregorian clefs}.
+@ref{Gregorian clefs},
+@ref{Default tablatures},
+@ref{Custom tablatures}.
 
 Snippets:
 @rlsr{Pitches}.
@@ -1061,12 +1233,12 @@ at the start of the staff.  The key signature may be altered:
 @cindex dorian
 
 @noindent
-Here, @var{mode} should be @code{\major} or @code{\minor} to get a
-key signature of @var{pitch}-major or @var{pitch}-minor,
-respectively.  You may also use the standard mode names, also
-called @notation{church modes}: @code{\ionian}, @code{\dorian},
-@code{\phrygian}, @code{\lydian}, @code{\mixolydian},
-@code{\aeolian}, and @code{\locrian}.
+Here, @code{@var{mode}} should be @code{\major} or @code{\minor}
+to get a key signature of @code{@var{pitch}}-major or
+@code{@var{pitch}}-minor, respectively.  You may also use the
+standard mode names, also called @notation{church modes}:
+@code{\ionian}, @code{\dorian}, @code{\phrygian}, @code{\lydian},
+@code{\mixolydian}, @code{\aeolian}, and @code{\locrian}.
 
 @lilypond[verbatim,quote,relative=2]
 \key g \major
@@ -1123,17 +1295,19 @@ Internals Reference:
 octave for the staff:
 
 @lilypond[verbatim,quote,relative=2]
-a'2 b
-\ottava #1
-a b
+a2 b
+\ottava #-2
+a2 b
+\ottava #-1
+a2 b
 \ottava #0
-a b
+a2 b
+\ottava #1
+a2 b
+\ottava #2
+a2 b
 @end lilypond
 
-The @code{ottava} function also takes -1 (for 8va bassa),
-2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
-
-
 @snippets
 
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
@@ -1293,7 +1467,7 @@ each style, we use the following example:
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1376,7 +1550,7 @@ last@tie{}@code{c}:
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1449,7 +1623,7 @@ individual musicians.  If the staff is to be used by one musician
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1500,7 +1674,10 @@ musicB = {
 @funindex modern
 
 This rule corresponds to the common practice in the twentieth
-century.  It prints the same accidentals as @code{default}, with
+century.  It omits some extra natural signs, which were
+traditionally prefixed to accidentals that reduce or reverse
+the direction of a previous alteration.  The @code{modern} rule
+prints the same accidentals as @code{default}, with
 two exceptions that serve to avoid ambiguity: after temporary
 accidentals, cancellation marks are printed also in the following
 measure (for notes in the same octave) and, in the same measure,
@@ -1512,7 +1689,7 @@ the upper staff:
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1576,7 +1753,7 @@ defining the @code{cautionary-style} property of
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1643,7 +1820,7 @@ accidental in a different voice in the previous measure:
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1704,7 +1881,7 @@ typeset as cautionaries.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1769,7 +1946,7 @@ This accidental style applies to the current @code{GrandStaff} or
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1829,7 +2006,7 @@ typeset as cautionaries.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1888,7 +2065,7 @@ if the note is immediately repeated.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -1945,7 +2122,7 @@ accidentals are printed as cautionary accidentals.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2005,7 +2182,7 @@ but they are canceled across voices in the same @code{Staff}.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2062,7 +2239,7 @@ accidentals are printed as cautionary accidentals.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2122,7 +2299,7 @@ including natural signs.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2174,7 +2351,7 @@ musicB = {
 @funindex teaching
 
 This rule is intended for students, and makes it easy to create
-scale sheets with automagically created cautionary accidentals.
+scale sheets with automatically created cautionary accidentals.
 Accidentals are printed like with @code{modern}, but cautionary
 accidentals are added for all sharp or flat tones specified by the
 key signature, except if the note is immediately repeated.
@@ -2183,7 +2360,7 @@ key signature, except if the note is immediately repeated.
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2244,7 +2421,7 @@ This is the same as @code{default} but with accidentals lasting
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2297,14 +2474,13 @@ musicB = {
 This is the opposite of @code{no-reset}: Accidentals are not
 remembered at all -- and hence all accidentals are typeset
 relative to the key signature, regardless of what came before in
-the music.  Unlike @code{dodecaphonic}, this rule never prints
-any naturals.
+the music.
 
 @lilypond[quote]
 musicA = {
   <<
     \relative c' {
-      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis'8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
@@ -2348,12 +2524,6 @@ musicB = {
 @end lilypond
 @end table
 
-@snippets
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
-
-
 @seealso
 Snippets:
 @rlsr{Pitches}.
@@ -2376,15 +2546,11 @@ Internals Reference:
 
 @knownissues
 
-Simultaneous notes are considered to be entered in sequential
-mode.  This means that in a chord the accidentals are typeset as
-if the notes in the chord happen one at a time, in the order in
-which they appear in the input file.  This is a problem when
-accidentals in a chord depend on each other, which does not happen
-for the default accidental style.  The problem can be solved by
-manually inserting@tie{}@code{!} and@tie{}@code{?} for the
-problematic notes.
-
+Simultaneous notes are not considered in the automatic
+determination of accidentals; only previous notes and the key
+signature are considered.  Forcing accidentals with@tie{}@code{!}
+or@tie{}@code{?} may be required when the same note name occurs
+simultaneously with different alterations, as in @samp{<f! fis!>}.
 
 Cautionary cancellation of accidentals is done by looking at previous measure.
 However, in the @code{\alternative} block following a @code{\repeat volta N}
@@ -2404,7 +2570,6 @@ not need a natural sign:
      cis'
      c'
   }
-  \bar "|."
 }
 @end lilypond
 
@@ -2427,7 +2592,6 @@ forget = #(define-music-function (parser location music) (ly:music?) #{
      cis'
      \forget c'
   }
-  \bar "|."
 }
 @end lilypond
 
@@ -2472,6 +2636,9 @@ printed if they are not part of the key signature.
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {ambitus-with-multiple-voices.ly}
 
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{changing-the-ambitus-gap.ly}
+
 
 @seealso
 Music Glossary:
@@ -2568,6 +2735,10 @@ c4 b
 c b < g \xNote c f > b
 @end lilypond
 
+As synonyms for @code{\xNote}, @code{\xNotesOn} and @code{\xNotesOff},
+@code{\deadNote}, @code{\deadNotesOn} and @code{\deadNotesOff} can
+be used.  The term @notation{dead note} is commonly used by guitarists.
+
 There is also a shorthand for diamond shapes which can be used
 only inside chords:
 
@@ -2588,7 +2759,8 @@ Snippets:
 
 Notation Reference:
 @ref{Note head styles},
-@ref{Chorded notes}.
+@ref{Chorded notes},
+@ref{Indicating harmonics and dampened notes}.
 
 Internals Reference:
 @rinternals{note-event},
@@ -2607,7 +2779,6 @@ Internals Reference:
 @cindex practice note heads
 @cindex note heads, easy notation
 @cindex easy notation
-@cindex Hal Leonard
 @cindex beginners' music
 @cindex music, beginners'
 @cindex easy play note heads
@@ -2641,6 +2812,12 @@ font, see @ref{Setting the staff size}.
 @endpredefined
 
 
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{numbers-as-easy-note-heads.ly}
+
+
 @seealso
 Notation Reference:
 @ref{Setting the staff size}.
@@ -2664,33 +2841,94 @@ Internals Reference:
 @cindex shape notes
 @cindex Aiken shape note heads
 @cindex sacred harp note heads
+@cindex note heads, Southern Harmony
+@cindex Southern Harmony note heads
+@cindex Funk shape note heads
+@cindex note heads, Funk
+@cindex note heads, Harmonica Sacra
+@cindex Harmonica Sacra note heads
+@cindex Christian Harmony note heads
+@cindex note heads, Christian Harmony
+@cindex Walker shape note heads
+@cindex note heads, Walker
 
-@funindex \key
-@funindex key
 @funindex \aikenHeads
 @funindex aikenHeads
 @funindex \sacredHarpHeads
 @funindex sacredHarpHeads
+@funindex \southernHarmonyHeads
+@funindex southernHarmonyHeads
+@funindex \funkHeads
+@funindex funkHeads
+@funindex \walkerHeads
+@funindex walkerHeads
 
 In shape note head notation, the shape of the note head
 corresponds to the harmonic function of a note in the scale.  This
 notation was popular in nineteenth-century American song books.
-Shape note heads can be produced:
+Shape note heads can be produced in Sacred Harp, Southern Harmony,
+Funk (Harmonica Sacra), Walker, and Aiken (Christian Harmony) styles:
 
 @lilypond[verbatim,quote,relative=2]
 \aikenHeads
-c, d e f g a b c
+c, d e f g2 a b1 c \break
 \sacredHarpHeads
-c, d e f g a b c
+c,4 d e f g2 a b1 c \break
+\southernHarmonyHeads
+c,4 d e f g2 a b1 c \break
+\funkHeads
+c,4 d e f g2 a b1 c \break
+\walkerHeads
+c,4 d e f g2 a b1 c \break
 @end lilypond
 
-Shapes are typeset according to the step in the scale, where the
-base of the scale is determined by the @code{\key} command.
+@funindex \key
+@funindex key
+@funindex \aikenHeadsMinor
+@funindex aikenHeadsMinor
+@funindex \sacredHarpHeadsMinor
+@funindex sacredHarpHeadsMinor
+@funindex \southernHarmonyHeadsMinor
+@funindex southernHarmonyHeadsMinor
+@funindex \funkHeadsMinor
+@funindex funkHeadsMinor
+@funindex \walkerHeadsMinor
+@funindex walkerHeadsMinor
+
+Shapes are typeset according to the step in the scale, where the base
+of the scale is determined by the @code{\key} command.  When writing
+in a minor key, the scale step can be determined from the relative
+major:
+
+@lilypond[verbatim,quote,relative=2]
+\key a \minor
+\aikenHeads
+a b c d e2 f g1 a \break
+\aikenHeadsMinor
+a,4 b c d e2 f g1 a \break
+\sacredHarpHeadsMinor
+a,2 b c d \break
+\southernHarmonyHeadsMinor
+a2 b c d \break
+\funkHeadsMinor
+a2 b c d \break
+\walkerHeadsMinor
+a2 b c d \break
+
+@end lilypond
 
 
 @predefined
 @code{\aikenHeads},
-@code{\sacredHarpHeads}.
+@code{\aikenHeadsMinor},
+@code{\funkHeads},
+@code{\funkHeadsMinor},
+@code{\sacredHarpHeads},
+@code{\sacredHarpHeadsMinor},
+@code{\southernHarmonyHeads},
+@code{\southernHarmonyHeadsMinor},
+@code{\walkerHeads},
+@code{\walkerHeadsMinor}.
 @endpredefined
 
 
@@ -2762,5 +3000,3 @@ Internals Reference:
 @rinternals{Pitch_squash_engraver},
 @rinternals{Voice},
 @rinternals{RhythmicStaff}.
-
-