X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpitches.itely;h=fce608a7c86883bcf1d8f37f66851cbf7af1f45c;hb=1423508c355989fa26a8cfe5985b0d6e1ab0a538;hp=fcee02d3763cef38755e9b5fe81c42c149e67132;hpb=21db6803d7dfb80f52f8cde2294f46a04cffde01;p=lilypond.git

diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index fcee02d376..fce608a7c8 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -6,7 +6,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.38"
+@c \version "2.12.0"
 
 
 @node Pitches
@@ -18,10 +18,10 @@ This section discusses how to specify the pitch of notes.  There
 are three steps to this process: input, modification, and output.
 
 @menu
-* Writing pitches::             
-* Changing multiple pitches::   
-* Displaying pitches::          
-* Note heads::                  
+* Writing pitches::
+* Changing multiple pitches::
+* Displaying pitches::
+* Note heads::
 @end menu
 
 
@@ -33,10 +33,10 @@ different ways to place notes in octaves: absolute and relative
 mode.  In most cases, relative mode will be more convenient.
 
 @menu
-* Absolute octave entry::       
-* Relative octave entry::       
-* Accidentals::                 
-* Note names in other languages::  
+* Absolute octave entry::
+* Relative octave entry::
+* Accidentals::
+* Note names in other languages::
 @end menu
 
 
@@ -47,6 +47,9 @@ mode.  In most cases, relative mode will be more convenient.
 @cindex pitches
 @cindex absolute
 @cindex absolute octave specification
+@cindex octave specification, absolute
+@cindex absolute octave entry
+@cindex octave entry, absolute
 
 A pitch name is specified using lowercase letters@tie{}@code{a}
 through@tie{}@code{g}.  The note names @code{c} to @code{b} are
@@ -60,6 +63,8 @@ g a b c
 d e f g
 @end lilypond
 
+@cindex octave changing mark
+
 @funindex '
 @funindex ,
 
@@ -77,8 +82,8 @@ c, c,, e, g
 d,, d, d c
 @end lilypond
 
-@seealso
 
+@seealso
 Music Glossary:
 @rglos{Pitch names}.
 
@@ -90,7 +95,12 @@ Snippets:
 @unnumberedsubsubsec Relative octave entry
 
 @cindex relative
+@cindex relative octave entry
+@cindex octave entry, relative
 @cindex relative octave specification
+@cindex ocatve specification, relative
+
+@funindex relative
 @funindex \relative
 
 When octaves are specified in absolute mode it is easy to
@@ -111,18 +121,20 @@ pitch inside @var{musicexpr} is calculated as follows:
 
 @itemize
 @item
-If no octave changing mark is used on a pitch, its octave is calculated
-so that the interval with the previous note is less than a fifth.  This
-interval is determined without considering accidentals.
+If no octave changing mark is used on a pitch, its octave is
+calculated so that the interval with the previous note is less
+than a fifth.  This interval is determined without considering
+accidentals.
 
 @item
-An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be added to
-respectively raise or lower a pitch by an extra octave, relative to
-the pitch calculated without an octave mark.
+An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be
+added to respectively raise or lower a pitch by an extra octave,
+relative to the pitch calculated without an octave mark.
 
 @item
-Multiple octave changing marks can be used.  For example, @code{''}@tie{}and
-@code{,,}@tie{} will alter the pitch by two octaves.
+Multiple octave changing marks can be used.  For example,
+@code{''}@tie{}and@tie{}@code{,,} will alter the pitch by two
+octaves.
 
 @item
 The pitch of the first note is relative to
@@ -163,6 +175,50 @@ large intervals:
 }
 @end lilypond
 
+When @code{\relative} blocks are nested, the innermost
+@code{\relative} block applies.
+
+@lilypond[verbatim,quote]
+\relative c' {
+  c d e f
+  \relative c'' {
+    c d e f
+  }
+}
+@end lilypond
+
+@code{\relative} has no effect on @code{\chordmode} blocks.
+
+@lilypond[verbatim,quote]
+\new Staff {
+  \relative c''' {
+    \chordmode { c1 }
+  }
+  \chordmode { c1 }
+}
+@end lilypond
+
+@code{\relative} is not allowed inside of @code{\chordmode} blocks.
+
+Music inside a @code{\transpose} block is absolute unless a
+@code{\relative} is included.
+
+@lilypond[verbatim,quote]
+\relative c' {
+  d e
+  \transpose f g {
+    d e
+    \relative c' {
+      d e
+    }
+  }
+}
+@end lilypond
+
+
+@cindex chords and relative octave entry
+@cindex relative octave entry and chords
+
 If the preceding item is a chord, the first note of the chord is
 used as the reference point for the octave placement of a
 following note or chord.  Inside chords, the next note is always
@@ -197,7 +253,6 @@ that each interval contains.
 
 
 @seealso
-
 Music Glossary:
 @rglos{fifth},
 @rglos{interval},
@@ -213,16 +268,16 @@ Internals Reference:
 @rinternals{RelativeOctaveMusic}.
 
 
+@cindex relative octave entry and transposition
+@cindex transposition and relative octave entry
+
 @funindex \transpose
+@funindex transpose
 @funindex \chordmode
+@funindex chordmode
 @funindex \relative
+@funindex relative
 
-@knownissues
-
-The relative conversion will not affect @code{\transpose},
-@code{\chordmode} or @code{\relative} sections in its argument.
-To use relative mode within transposed music, an additional
-@code{\relative} must be placed inside @code{\transpose}.
 
 @c DEPRECATED
 If no @var{startpitch} is specified for @code{\relative},
@@ -249,6 +304,7 @@ see @rlearning{Accidentals and key signatures}.}
 
 @cindex note names, Dutch
 @cindex note names, default
+@cindex default note names
 @cindex sharp
 @cindex flat
 @cindex double sharp
@@ -256,15 +312,16 @@ see @rlearning{Accidentals and key signatures}.}
 @cindex double flat
 @cindex flat, double
 @cindex natural sign
+@cindex natural pitch
 
-A @notation{sharp} pitch is made by adding @code{is} to the note name,
-and a @notation{flat} pitch by adding @code{es}.  As you might expect,
-a @notation{double sharp} or @notation{double flat} is made by adding
-@code{isis} or @code{eses}.  This syntax is derived from Dutch note
-naming conventions.  To use other names for accidentals, see
-@ref{Note names in other languages}.
+A @notation{sharp} pitch is made by adding @code{is} to the note
+name, and a @notation{flat} pitch by adding @code{es}.  As you
+might expect, a @notation{double sharp} or @notation{double flat}
+is made by adding @code{isis} or @code{eses}.  This syntax is
+derived from Dutch note naming conventions.  To use other names
+for accidentals, see @ref{Note names in other languages}.
 
-@lilypond[verbatim,quote,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 ais1 aes aisis aeses
 @end lilypond
 
@@ -273,17 +330,18 @@ signature.  However, naturals are not encoded into the note name
 syntax with a suffix; a natural pitch is shown as a simple note
 name:
 
-@lilypond[verbatim,quote,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 a4 aes a2
 @end lilypond
 
 @cindex quarter tones
-@cindex semi-flats, semi-sharps
+@cindex semi-flats
+@cindex semi-sharps
 
 Quarter tones may be added; the following is a series of Cs with
 increasing pitches:
 
-@lilypond[verbatim,quote,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 ceseh1 ces ceh c cih cis cisih
 @end lilypond
 
@@ -293,11 +351,13 @@ ceseh1 ces ceh c cih cis cisih
 @cindex accidental, cautionary
 @cindex accidental, parenthesized
 @cindex reminder accidental
-@funindex ?
 @cindex cautionary accidental
 @cindex parenthesized accidental
+
+@funindex ?
 @funindex !
 
+
 Normally accidentals are printed automatically, but you may also
 print them manually.  A reminder accidental can be forced by
 adding an exclamation mark@tie{}@code{!} after the pitch.  A
@@ -306,14 +366,17 @@ be obtained by adding the question mark@tie{}@code{?} after the
 pitch.  These extra accidentals can also be used to produce
 natural signs.
 
-@lilypond[verbatim,quote,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 cis cis cis! cis? c c c! c?
 @end lilypond
 
+@cindex accidental on tied note
+@cindex tied note, accidental
+
 Accidentals on tied notes are only printed at the beginning of a
 new system:
 
-@lilypond[verbatim,quote,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 cis1 ~ cis ~
 \break
 cis
@@ -325,8 +388,11 @@ cis
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {preventing-extra-naturals-from-being-automatically-added.ly}
 
-@seealso
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{makam-example.ly}
+
 
+@seealso
 Music Glossary:
 @rglos{sharp},
 @rglos{flat},
@@ -340,19 +406,22 @@ Learning Manual:
 
 Notation Reference:
 @ref{Automatic accidentals},
-@ref{Annotational accidentals},
+@ref{Annotational accidentals (musica ficta)},
 @ref{Note names in other languages}.
 
 Snippets:
 @rlsr{Pitches}.
 
 Internals Reference:
-@rinternals{Accidental_engraver}, 
+@rinternals{Accidental_engraver},
 @rinternals{Accidental},
 @rinternals{AccidentalCautionary},
 @rinternals{accidental-interface}.
 
 
+@cindex accidental, quarter-tone
+@cindex quarter-tone accidental
+
 @knownissues
 
 There are no generally accepted standards for denoting
@@ -364,57 +433,89 @@ any standard.
 @node Note names in other languages
 @unnumberedsubsubsec Note names in other languages
 
-There are predefined sets of note names for various other
-languages.  To use them, include the language-specific init file.
-For example, to use English notes names, add
-@w{@code{\include "english.ly"}} to the top of the input file.
-The available language files and the note names they define are:
-
 @cindex note names, other languages
 @cindex pitch names, other languages
+@cindex language, note names in other
+@cindex language, pitch names in other
 
-@smallexample
-@multitable {nederlands.ly} {do re mi fa sol la sib si} {-iss/-is} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
-@headitem Language
-  @tab Note names
-  @tab sharp @tab flat @tab double sharp @tab double flat
-@item nederlands.ly
+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.
+
+@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.}
+
+The available language files and the note names they define are:
+
+@quotation
+@multitable {@file{nederlands.ly}} {do re mi fa sol la sib si}
+@headitem Language File
+  @tab Note Names
+@item @file{nederlands.ly}
   @tab c d e f g a bes b
-  @tab -is @tab -es @tab -isis @tab -eses
-@item english.ly
-  @tab c d e f g a bf b
-  @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
-    @tab -ff/-flatflat
-@item deutsch.ly
+@item @file{arabic.ly}
+  @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}
   @tab c d e f g a b h
-  @tab -is @tab -es @tab -isis @tab -eses
-@item norsk.ly
+@item @file{english.ly}
+  @tab c d e f g a bf b
+@item @file{espanol.ly}
+  @tab do re mi fa sol la sib si
+@item @file{italiano.ly}
+  @tab do re mi fa sol la sib si
+@item @file{norsk.ly}
   @tab c d e f g a b h
-  @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
-    @tab -essess/-eses
-@item svenska.ly
+@item @file{portugues.ly}
+  @tab do re mi fa sol la sib si
+@item @file{suomi.ly}
   @tab c d e f g a b h
-  @tab -iss @tab -ess @tab -ississ @tab -essess
-@item suomi.ly
+@item @file{svenska.ly}
   @tab c d e f g a b h
-  @tab -is @tab -es @tab -isis @tab -eses
-@item italiano.ly
+@item @file{vlaams.ly}
   @tab do re mi fa sol la sib si
+@end multitable
+@end quotation
+
+@noindent
+and the accidental suffixes they define are:
+
+@quotation
+@multitable {@file{nederlands.ly}} {-s/-sharp} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
+@headitem Language File
+  @tab sharp @tab flat @tab double sharp @tab double flat
+@item @file{nederlands.ly}
+  @tab -is @tab -es @tab -isis @tab -eses
+@item @file{arabic.ly}
   @tab -d @tab -b @tab -dd @tab -bb
-@item catalan.ly
-  @tab do re mi fa sol la sib si
+@item @file{catalan.ly}
   @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
-@item espanol.ly
-  @tab do re mi fa sol la sib si
-  @tab -s @tab -b @tab -ss @tab -bb
-@item portugues.ly
-  @tab do re mi fa sol la sib si
+@item @file{deutsch.ly}
+  @tab -is @tab -es @tab -isis @tab -eses
+@item @file{english.ly}
+  @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
+    @tab -ff/-flatflat
+@item @file{espanol.ly}
+  @tab -s @tab -b @tab -ss/-x @tab -bb
+@item @file{italiano.ly}
+  @tab -d @tab -b @tab -dd @tab -bb
+@item @file{norsk.ly}
+  @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
+    @tab -essess/-eses
+@item @file{portugues.ly}
   @tab -s @tab -b @tab -ss @tab -bb
-@item vlaams.ly
-  @tab do re mi fa sol la sib si
+@item @file{suomi.ly}
+  @tab -is @tab -es @tab -isis @tab -eses
+@item @file{svenska.ly}
+  @tab -iss @tab -ess @tab -ississ @tab -essess
+@item @file{vlaams.ly}
   @tab -k @tab -b @tab -kk @tab -bb
 @end multitable
-@end smallexample
+@end quotation
 
 In Dutch, @code{aes} is contracted to @code{as}, but both forms
 are accepted in LilyPond.  Similarly, both @code{es} and
@@ -423,11 +524,17 @@ are accepted in LilyPond.  Similarly, both @code{es} and
 @code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
 contracted names are defined in the corresponding language files.
 
-@lilypond[verbatim,quote,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 a2 as e es a ases e eses
 @end lilypond
 
 
+@cindex microtones
+@cindex semi-sharp
+@cindex semi-flat
+@cindex sesqui-sharp
+@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
@@ -435,33 +542,30 @@ 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.
 
-@smallexample
-@multitable {nederlands.ly} {do re mi fa sol la sib si} {-iss/-is} {-ess/-es} {-ississ/-isis} {-ississ/-isis}
-@headitem Language
-  @tab Note names
+@quotation
+@multitable {@file{nederlands.ly}} {@b{semi-sharp}} {@b{semi-flat}} {@b{sesqui-sharp}} {@b{sesqui-flat}}
+@headitem Language File
   @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 
-@item nederlands.ly
-  @tab c d e f g a bes b
+@item @file{nederlands.ly}
   @tab -ih @tab -eh @tab -isih @tab -eseh
-@item english.ly
-  @tab c d e f g a bf b
-  @tab -qs @tab -qf @tab -tqs @tab -tqf
-@item deutsch.ly
-  @tab c d e f g a b h
+@item @file{arabic.ly}
+  @tab -sd @tab -sb @tab -dsd @tab -bsb
+@item @file{deutsch.ly}
   @tab -ih @tab -eh @tab -isih @tab -eseh
-@item italiano.ly
-  @tab do re mi fa sol la sib si
+@item @file{english.ly}
+  @tab -qs @tab -qf @tab -tqs @tab -tqf
+@item @file{espanol.ly}
+  @tab -cs @tab -cb @tab -tcs @tab -tcb
+@item @file{italiano.ly}
   @tab -sd @tab -sb @tab -dsd @tab -bsb
-@item portugues.ly
-  @tab do re mi fa sol la sib si
+@item @file{portugues.ly}
   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
 @end multitable
-@end smallexample
+@end quotation
 
 
 @seealso
-
 Music Glossary:
 @rglos{Pitch names}.
 
@@ -475,8 +579,8 @@ Snippets:
 This section discusses how to modify pitches.
 
 @menu
-* Octave checks::               
-* Transpose::                   
+* Octave checks::
+* Transpose::
 @end menu
 
 @node Octave checks
@@ -484,21 +588,25 @@ This section discusses how to modify pitches.
 
 @cindex octave correction
 @cindex octave check
+@cindex control pitch
+
 @funindex =
-@funindex \octave
+@funindex \octaveCheck
+@funindex octaveCheck
+@funindex controlpitch
 
 In relative mode, it is easy to forget an octave changing mark.
 Octave checks make such errors easier to find by displaying a
 warning and correcting the octave if a note is found in an
 unexpected octave.
 
-To check the octave of a note, specify the absolute
-octave after the @code{=}@tie{}symbol.  This example will generate
-a warning (and change the pitch) because the second note is the
-absolute octave @code{d''} instead of @code{d'} as indicated by
-the octave correction.
+To check the octave of a note, specify the absolute octave after
+the @code{=}@tie{}symbol.  This example will generate a warning
+(and change the pitch) because the second note is the absolute
+octave @code{d''} instead of @code{d'} as indicated by the octave
+correction.
 
-@lilypond[verbatim,quote,fragment]
+@lilypond[verbatim,quote]
 \relative c'' {
   c2 d='4 d
   e2 f
@@ -506,41 +614,41 @@ the octave correction.
 @end lilypond
 
 The octave of notes may also be checked with the
-@code{\octave}@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 calculation of relative mode).  If this check fails, a warning
-is printed, but the previous note is not changed.  Future notes are
+@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
+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}.
 
-@lilypond[verbatim,quote,fragment]
+@lilypond[verbatim,quote]
 \relative c'' {
   c2 d
-  \octave c'
+  \octaveCheck c'
   e2 f
 }
 @end lilypond
 
-Compare the two bars below.  The first and third @code{\octave}
+Compare the two bars below.  The first and third @code{\octaveCheck}
 checks fail, but the second one does not fail.
 
-@lilypond[verbatim,quote,fragment]
+@lilypond[verbatim,quote]
 \relative c'' {
   c4 f g f
 
   c4
-  \octave c'
+  \octaveCheck c'
   f
-  \octave c'
+  \octaveCheck c'
   g
-  \octave c'
+  \octaveCheck c'
   f
 }
 @end lilypond
 
 
 @seealso
-
 Snippets:
 @rlsr{Pitches}.
 
@@ -552,9 +660,15 @@ Internals Reference:
 @unnumberedsubsubsec Transpose
 
 @cindex transpose
+@cindex transposing
 @cindex transposition
 @cindex transposition of pitches
+@cindex transposition of notes
+@cindex pitches, transposition of
+@cindex notes, transposition of
+
 @funindex \transpose
+@funindex transpose
 
 A music expression can be transposed with @code{\transpose}.  The
 syntax is
@@ -570,6 +684,9 @@ 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.
 
+@warning{Music inside a @code{@bs{}transpose} block is absolute
+unless a @code{@bs{}relative} is included in the block.}
+
 Consider a piece written in the key of D-major.  It can be
 transposed up to E-major; note that the key signature is
 automatically transposed as well.
@@ -583,10 +700,13 @@ automatically transposed as well.
 }
 @end lilypond
 
-If a part written in C (normal @notation{concert pitch}) is to be played on
-the A clarinet (for which an A is notated as a C and thus sounds a
-minor third lower than notated), the appropriate part will be
-produced with:
+@cindex transposing instruments
+@cindex instruments, transposing
+
+If a part written in C (normal @notation{concert pitch}) is to be
+played on the A clarinet (for which an A is notated as a C and
+thus sounds a minor third lower than notated), the appropriate
+part will be produced with:
 
 @lilypond[verbatim,quote]
 \transpose a c' {
@@ -609,14 +729,13 @@ the notes will remain on the same scale step, the second version
 will print flats on the scale step above.
 
 @lilypond[verbatim,quote]
-mus = \relative c' { c d e f }
+music = \relative c' { c d e f }
 \new Staff {
-  \transpose c cis { \mus }
-  \transpose c des { \mus }
+  \transpose c cis { \music }
+  \transpose c des { \music }
 }
 @end lilypond
 
-@cindex transposing instruments
 
 @code{\transpose} may also be used in a different way, to input
 written notes for a transposing instrument.  The previous examples
@@ -653,8 +772,8 @@ see @ref{Instrument transpositions}.
 
 
 @seealso
-
 Notation Reference:
+@ref{Relative octave entry},
 @ref{Instrument transpositions}.
 
 Snippets:
@@ -663,38 +782,39 @@ Snippets:
 Internals Reference:
 @rinternals{TransposedMusic}.
 
+
 @funindex \transpose
+@funindex transpose
 @funindex \chordmode
+@funindex chordmode
 @funindex \relative
+@funindex relative
 
 @knownissues
 
-
 The relative conversion will not affect @code{\transpose},
 @code{\chordmode} or @code{\relative} sections in its argument.
 To use relative mode within transposed music, an additional
 @code{\relative} must be placed inside @code{\transpose}.
 
-
 @node Displaying pitches
 @subsection Displaying pitches
 
 This section discusses how to alter the output of pitches.
 
 @menu
-* Clef::                        
-* Key signature::               
-* Ottava brackets::             
-* Instrument transpositions::   
-* Automatic accidentals::       
-* Ambitus::                     
+* Clef::
+* Key signature::
+* Ottava brackets::
+* Instrument transpositions::
+* Automatic accidentals::
+* Ambitus::
 @end menu
 
 
 @node Clef
 @unnumberedsubsubsec Clef
 
-@funindex \clef
 @cindex G clef
 @cindex C clef
 @cindex F clef
@@ -716,21 +836,23 @@ This section discusses how to alter the output of pitches.
 @cindex clef, C
 @cindex clef, F
 @cindex clef, treble
-@cindex clef, violin 
-@cindex clef, alto 
+@cindex clef, violin
+@cindex clef, alto
 @cindex clef, tenor
-@cindex clef, bass 
-@cindex clef, french 
-@cindex clef, soprano 
-@cindex clef, mezzosoprano 
-@cindex clef, baritone 
-@cindex clef, varbaritone 
-@cindex subbass clef, subbass 
-
-The clef is set with the @w{@code{\clef @var{clefname}}} command.
-Middle C is shown in every example.
-
-@lilypond[verbatim,quote,fragment,relative=1]
+@cindex clef, bass
+@cindex clef, french
+@cindex clef, soprano
+@cindex clef, mezzosoprano
+@cindex clef, baritone
+@cindex clef, varbaritone
+@cindex subbass clef, subbass
+
+@funindex \clef
+@funindex clef
+
+The clef may be altered.  Middle C is shown in every example.
+
+@lilypond[verbatim,quote,relative=1]
 \clef treble
 c2 c
 \clef alto
@@ -743,7 +865,7 @@ c2 c
 
 Other clefs include:
 
-@lilypond[verbatim,quote,fragment,relative=1]
+@lilypond[verbatim,quote,relative=1]
 \clef french
 c2 c
 \clef soprano
@@ -763,22 +885,36 @@ c2 c
 c2 c
 \clef tab
 c2 c
+
+\break
+
+\clef G
+c2 c
+\clef F
+c2 c
+\clef C
+c2 c
+
 @end lilypond
 
-Further supported clefs are described under @ref{Ancient clefs}.
+Further supported clefs are described under @ref{Mensural clefs}
+and @ref{Gregorian clefs}.
 
 @cindex transposing clefs
 @cindex clef, transposing
 @cindex octave transposition
-
-By adding @code{_8} or @code{^8} to the clef name, the clef is
-transposed one octave down or up, respectively, and @code{_15} and
-@code{^15} transpose by two octaves.  The argument @var{clefname}
-must be enclosed in quotes when it contains underscores or digits.
-
 @cindex choral tenor clef
+@cindex tenor clef, choral
 
-@lilypond[verbatim,quote,fragment,relative=1]
+By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
+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.
+
+@lilypond[verbatim,quote,relative=2]
+\clef treble
+c2 c
 \clef "treble_8"
 c2 c
 \clef "bass^15"
@@ -793,9 +929,8 @@ c2 c
 
 
 @seealso
-
 Notation Reference:
-@ref{Ancient clefs}.
+@ref{Mensural clefs}, @ref{Gregorian clefs}.
 
 Snippets:
 @rlsr{Pitches}.
@@ -811,7 +946,9 @@ Internals Reference:
 @unnumberedsubsubsec Key signature
 
 @cindex key signature
+
 @funindex \key
+@funindex key
 
 @c duplicated in Key signature and Accidentals
 @warning{New users are sometimes confused about accidentals and
@@ -823,24 +960,42 @@ see @rlearning{Accidentals and key signatures}.}
 
 The key signature indicates the tonality in which a piece is
 played.  It is denoted by a set of alterations (flats or sharps)
-at the start of the staff.  Setting or changing the key signature
-is done with the @code{\key} command:
+at the start of the staff.  The key signature may be altered:
 
 @example
 \key @var{pitch} @var{mode}
 @end example
 
 @funindex \major
+@funindex major
 @funindex \minor
+@funindex minor
 @funindex \ionian
+@funindex ionian
 @funindex \locrian
+@funindex locrian
 @funindex \aeolian
+@funindex aeolian
 @funindex \mixolydian
+@funindex mixolydian
 @funindex \lydian
+@funindex lydian
 @funindex \phrygian
+@funindex phrygian
 @funindex \dorian
+@funindex dorian
+
 @cindex church modes
 @cindex modes
+@cindex major
+@cindex minor
+@cindex ionian
+@cindex locrian
+@cindex aeolian
+@cindex mixolydian
+@cindex lydian
+@cindex phrygian
+@cindex dorian
 
 Here, @var{mode} should be @code{\major} or @code{\minor} to get a
 key signature of @var{pitch}-major or @var{pitch}-minor,
@@ -849,7 +1004,7 @@ called @notation{church modes}: @code{\ionian}, @code{\dorian},
 @code{\phrygian}, @code{\lydian}, @code{\mixolydian},
 @code{\aeolian}, and @code{\locrian}.
 
-@lilypond[verbatim,quote,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 \key g \major
 fis1
 f
@@ -867,7 +1022,6 @@ fis
 
 
 @seealso
-
 Music Glossary:
 @rglos{church mode},
 @rglos{scordatura}.
@@ -897,18 +1051,22 @@ Internals Reference:
 @cindex 8ve
 @cindex octavation
 
+@funindex set-octavation
+@funindex \ottava
+@funindex ottava
+
 @notation{Ottava brackets} introduce an extra transposition of an
 octave for the staff:
 
-@lilypond[verbatim,quote,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 a'2 b
-#(set-octavation 1)
+\ottava #1
 a b
-#(set-octavation 0)
+\ottava #0
 a b
 @end lilypond
 
-The @code{set-octavation} function also takes -1 (for 8va bassa),
+The @code{ottava} function also takes -1 (for 8va bassa),
 2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
 
 
@@ -919,7 +1077,6 @@ The @code{set-octavation} function also takes -1 (for 8va bassa),
 
 
 @seealso
-
 Music Glossary:
 @rglos{octavation}.
 
@@ -932,7 +1089,6 @@ Internals Reference:
 @rinternals{ottava-bracket-interface}.
 
 
-
 @node Instrument transpositions
 @unnumberedsubsubsec Instrument transpositions
 
@@ -940,15 +1096,18 @@ Internals Reference:
 @cindex transposition, instrument
 @cindex transposing instrument
 @cindex MIDI
+@cindex MIDI transposition
+
 @funindex \transposition
+@funindex transposition
 
 When typesetting scores that involve transposing instruments, some
 parts can be typeset in a different pitch than the
 @notation{concert pitch}.  In these cases, the key of the
 @notation{transposing instrument} should be specified; otherwise
 the MIDI output and cues in other parts will produce incorrect
-pitches.  For more information about quotations, see @ref{Quoting
-other voices}.
+pitches.  For more information about quotations, see
+@ref{Quoting other voices}.
 
 @example
 \transposition @var{pitch}
@@ -959,7 +1118,7 @@ the real sound heard when a@tie{}@code{c'} written on the staff is
 played by the transposing instrument.  This pitch is entered in
 absolute mode, so an instrument that produces a real sound which
 is one tone higher than the printed music should use
-@code{\transposition d'}.  @code{\transposition} should
+@w{@code{\transposition d'}}.  @code{\transposition} should
 @emph{only} be used if the pitches are @emph{not} being entered in
 concert pitch.
 
@@ -970,10 +1129,10 @@ playing in unison.
 
 @lilypond[verbatim,quote]
 \new GrandStaff <<
-  \new Staff = "Vln" {
+  \new Staff = "violin" {
     \relative c'' {
-      \set Staff.instrumentName = "Vln"
-      \set Staff.midiInstrument = "violin"
+      \set Staff.instrumentName = #"Vln"
+      \set Staff.midiInstrument = #"violin"
       % not strictly necessary, but a good reminder
       \transposition c'
 
@@ -984,7 +1143,7 @@ playing in unison.
   \new Staff = "clarinet" {
     \relative c'' {
       \set Staff.instrumentName = \markup { Cl (B\flat) }
-      \set Staff.midiInstrument = "clarinet"
+      \set Staff.midiInstrument = #"clarinet"
       \transposition bes
 
       \key d \major
@@ -998,8 +1157,8 @@ The @code{\transposition} may be changed during a piece.  For
 example, a clarinetist may switch from an A clarinet to a B-flat
 clarinet.
 
-@lilypond[verbatim,quote,fragment,relative=2]
-\set Staff.instrumentName = "Cl (A)"
+@lilypond[verbatim,quote,relative=2]
+\set Staff.instrumentName = #"Cl (A)"
 \key a \major
 \transposition a
 c d e f
@@ -1014,7 +1173,6 @@ c2 g
 
 
 @seealso
-
 Music Glossary:
 @rglos{concert pitch},
 @rglos{transposing instrument}.
@@ -1035,11 +1193,14 @@ Snippets:
 @cindex accidentals, automatic
 @cindex automatic accidentals
 @cindex default accidental style
+
 @funindex set-accidental-style
+@funindex voice
+@funindex default
 
 There are many different conventions on how to typeset
 accidentals.  LilyPond provides a function to specify which
-accidental style to use.  This function is called as follows
+accidental style to use.  This function is called as follows:
 
 @example
 \new Staff <<
@@ -1053,7 +1214,7 @@ default (with the exception of the styles @code{piano} and
 @code{piano-cautionary}, which are explained below).  Optionally,
 the function can take a second argument that determines in which
 scope the style should be changed.  For example, to use the same
-style in all staves of the current @code{StaffGroup}, use
+style in all staves of the current @code{StaffGroup}, use:
 
 @example
 #(set-accidental-style 'voice 'StaffGroup)
@@ -1062,6 +1223,7 @@ style in all staves of the current @code{StaffGroup}, use
 The following accidental styles are supported.  To demonstrate
 each style, we use the following example:
 
+
 @lilypond[verbatim,quote]
 musicA = {
   <<
@@ -1131,6 +1293,12 @@ both staves.
 @c don't use verbatim in this table.
 @table @code
 @item default
+
+@cindex default accidental style
+@cindex accidental style, default
+
+@funindex default
+
 This is the default typesetting behavior.  It corresponds to
 eighteenth-century common practice: accidentals are remembered to
 the end of the measure in which they occur and only in their own
@@ -1185,10 +1353,20 @@ musicB = {
 @end lilypond
 
 @item voice
-The normal behavior is to remember the accidentals at @code{Staff}-level.
-In this style, however, accidentals are typeset individually for
-each voice.  Apart from that, the rule is similar to
-@code{default}.
+
+@cindex accidental style, voice
+@cindex voice accidental style
+@cindex accidental style, modern
+@cindex modern accidental style
+@cindex accidental style, modern-cautionary
+@cindex modern-cautionary accidental style
+
+@funindex voice
+
+The normal behavior is to remember the accidentals at
+@code{Staff}-level.  In this style, however, accidentals are
+typeset individually for each voice.  Apart from that, the rule is
+similar to @code{default}.
 
 As a result, accidentals from one voice do not get canceled in
 other voices, which is often an unwanted result: in the following
@@ -1247,9 +1425,11 @@ musicB = {
 @end lilypond
 
 @item modern
+
 @cindex accidentals, modern style
 @cindex modern style accidentals
-@funindex modern style accidentals
+
+@funindex modern
 
 This rule corresponds to the common practice in the twentieth
 century.  It prints the same accidentals as @code{default}, with
@@ -1307,11 +1487,13 @@ musicB = {
 @end lilypond
 
 @item modern-cautionary
+
 @cindex accidentals, modern cautionary style
 @cindex modern accidental style
 @cindex modern cautionary accidental style
 @cindex modern style accidentals
 @cindex modern style cautionary accidentals
+
 @funindex modern-cautionary
 
 This rule is similar to @code{modern}, but the @q{extra}
@@ -1321,7 +1503,6 @@ parentheses, but they can also be printed in reduced size by
 defining the @code{cautionary-style} property of
 @code{AccidentalSuggestion}.
 
-
 @lilypond[quote]
 musicA = {
   <<
@@ -1369,12 +1550,14 @@ musicB = {
 @end lilypond
 
 @item modern-voice
+
 @cindex accidental style, modern
 @cindex accidentals, modern
 @cindex accidentals, multivoice
 @cindex modern accidental style
 @cindex modern accidentals
 @cindex multivoice accidentals
+
 @funindex modern-voice
 
 This rule is used for multivoice accidentals to be read both by
@@ -1386,7 +1569,6 @@ previous cancellation was in a different voice, and
 the@tie{}@code{d} in the lower staff is canceled because of the
 accidental in a different voice in the previous measure:
 
-
 @lilypond[quote]
 musicA = {
   <<
@@ -1436,14 +1618,16 @@ musicB = {
 @cindex accidental style, cautionary, modern voice
 @cindex accidental style, modern voice cautionary
 @cindex accidental style, voice, modern cautionary
+
 @funindex modern-voice-cautionary
+
 @item modern-voice-cautionary
 
 This rule is the same as @code{modern-voice}, but with the extra
-accidentals (the ones not typeset by @code{voice}) typeset
-as cautionaries.  Even though all accidentals typeset by
-@code{default} @emph{are} typeset with this rule,
-some of them are typeset as cautionaries.
+accidentals (the ones not typeset by @code{voice}) typeset as
+cautionaries.  Even though all accidentals typeset by
+@code{default} @emph{are} typeset with this rule, some of them are
+typeset as cautionaries.
 
 @lilypond[quote]
 musicA = {
@@ -1492,16 +1676,19 @@ musicB = {
 @end lilypond
 
 @item piano
+
 @cindex accidental style, piano
 @cindex accidentals, piano
 @cindex piano accidental style
 @cindex piano accidentals
 
+@funindex piano
+
 This rule reflects twentieth-century practice for piano notation.
 Its behavior is very similar to @code{modern} style, but here
 accidentals also get canceled across the staves in the same
-@code{GrandStaff} or @code{PianoStaff}, hence all the cancellations
-of the final notes.
+@code{GrandStaff} or @code{PianoStaff}, hence all the
+cancellations of the final notes.
 
 This accidental style applies to the current @code{GrandStaff} or
 @code{PianoStaff} by default.
@@ -1552,7 +1739,7 @@ musicB = {
 @end lilypond
 
 @item piano-cautionary
-@funindex #(set-accidental-style 'piano-cautionary)
+
 @cindex accidentals, piano cautionary
 @cindex cautionary accidentals, piano
 @cindex piano cautionary accidentals
@@ -1560,8 +1747,10 @@ musicB = {
 @cindex cautionary accidental style, piano
 @cindex piano cautionary accidental style
 
-Same as @w{@code{#(set-accidental-style 'piano)}} but with the
-extra accidentals typeset as cautionaries.
+@funindex piano-cautionary
+
+This is the same as @code{piano} but with the extra accidentals
+typeset as cautionaries.
 
 @lilypond[quote]
 musicA = {
@@ -1608,11 +1797,252 @@ musicB = {
 }
 @end lilypond
 
+
+@item neo-modern
+
+@cindex neo-modern accidental style
+@cindex accidental style, neo-modern
+
+@funindex neo-modern
+
+This rule reproduces a common practice in contemporary music:
+accidentals are printed like with @code{modern}, but they are printed
+again if the same note appears later in the same measure -- except
+if the note is immediately repeated.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative c' {
+      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative c' {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative c' {
+      <fis, a cis>4
+      \change Staff = up
+      cis'
+      \change Staff = down
+      <fis, a>
+      \change Staff = up
+      dis' |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new PianoStaff {
+  <<
+    \context Staff = "up" {
+      #(set-accidental-style 'neo-modern)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'neo-modern)
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+@item neo-modern-cautionary
+
+@cindex neo-modern-cautionary accidental style
+@cindex accidental style, neo-modern-cautionary
+
+@funindex neo-modern-cautionary
+
+This rule is similar to @code{neo-modern}, but the extra
+accidentals are printed as cautionary accidentals.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative c' {
+      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative c' {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative c' {
+      <fis, a cis>4
+      \change Staff = up
+      cis'
+      \change Staff = down
+      <fis, a>
+      \change Staff = up
+      dis' |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new PianoStaff {
+  <<
+    \context Staff = "up" {
+      #(set-accidental-style 'neo-modern-cautionary)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'neo-modern-cautionary)
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+
+@item dodecaphonic
+
+@cindex dodecaphonic accidental style
+@cindex dodecaphonic style, neo-modern
+
+@funindex dodecaphonic
+
+This rule reflects a practice introduced by composers at
+the beginning of the 20th century, in an attempt to
+abolish the hierarchy between natural and non-natural notes.
+With this style, @emph{every} note gets an accidental sign,
+including natural signs.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative c' {
+      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative c' {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative c' {
+      <fis, a cis>4
+      \change Staff = up
+      cis'
+      \change Staff = down
+      <fis, a>
+      \change Staff = up
+      dis' |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new PianoStaff {
+  <<
+    \context Staff = "up" {
+      #(set-accidental-style 'dodecaphonic)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'dodecaphonic)
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+
+@item teaching
+
+@cindex teaching accidental style
+@cindex accidental style, teaching
+
+@funindex teaching
+
+This rule is intended for students, and makes it easy to create
+scale sheets with automagically 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.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative c' {
+      cis'8 fis, d'4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative c' {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative c' {
+      <fis, a cis>4
+      \change Staff = up
+      cis'
+      \change Staff = down
+      <fis, a>
+      \change Staff = up
+      dis' |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new PianoStaff {
+  <<
+    \context Staff = "up" {
+      \key fis \minor
+      #(set-accidental-style 'teaching)
+      \musicA
+    }
+    \context Staff = "down" {
+      \key fis \minor
+      #(set-accidental-style 'teaching)
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+
+
 @item no-reset
-@funindex no-reset accidental style
+
 @cindex accidental style, no reset
 @cindex no reset accidental style
 
+@funindex no-reset
+
 This is the same as @code{default} but with accidentals lasting
 @q{forever} and not only within the same measure:
 
@@ -1663,14 +2093,17 @@ musicB = {
 @end lilypond
 
 @item forget
-@funindex forget accidental style
+
 @cindex forget accidental style
 @cindex accidental style, forget
 
+@funindex forget
+
 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:
+the music.  Unlike @code{dodecaphonic}, this rule never prints
+any naturals.
 
 @lilypond[quote]
 musicA = {
@@ -1726,7 +2159,6 @@ musicB = {
 
 
 @seealso
-
 Snippets:
 @rlsr{Pitches}.
 
@@ -1801,7 +2233,6 @@ printed if they are not part of the key signature.
 
 
 @seealso
-
 Music Glossary:
 @rglos{ambitus}.
 
@@ -1831,10 +2262,10 @@ ambitus.
 This section suggests ways of altering note heads.
 
 @menu
-* Special note heads::          
-* Easy notation note heads::    
-* Shape note heads::            
-* Improvisation::               
+* Special note heads::
+* Easy notation note heads::
+* Shape note heads::
+* Improvisation::
 @end menu
 
 @node Special note heads
@@ -1852,20 +2283,26 @@ This section suggests ways of altering note heads.
 @cindex parlato note heads
 @cindex harmonic note heads
 @cindex guitar note heads
+@cindex note head styles
+@cindex styles, note heads
+
+@funindex cross
 
-Different note heads are used by various instruments for various
-meanings -- crosses are used for @q{parlato} with vocalists,
-stopped notes on guitar; diamonds are used for harmonics on string
-instruments, etc.  There is a shorthand (@code{\harmonic}) for
-diamond shapes; the other note head styles are produced by
-tweaking the property:
+Note heads may be altered:
 
-@lilypond[verbatim,quote,fragment,relative=1]
-c4 d
+@lilypond[verbatim,quote,relative=2]
+c4 b a b
 \override NoteHead #'style = #'cross
-e f
+c4 b a b
 \revert NoteHead #'style
-e d <c f\harmonic> <d a'\harmonic>
+c4 d e f
+@end lilypond
+
+There is a shorthand for diamond shapes which can only be used
+inside chords:
+
+@lilypond[verbatim,quote,relative=2]
+<c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>
 @end lilypond
 
 @noindent
@@ -1873,12 +2310,12 @@ To see all note head styles, see @ref{Note head styles}.
 
 
 @seealso
-
 Snippets:
 @rlsr{Pitches}.
 
 Notation Reference:
-@ref{Note head styles}.
+@ref{Note head styles},
+@ref{Chorded notes}.
 
 Internals Reference:
 @rinternals{note-event},
@@ -1894,6 +2331,7 @@ Internals Reference:
 @unnumberedsubsubsec Easy notation note heads
 
 @cindex note heads, practice
+@cindex practice note heads
 @cindex note heads, easy notation
 @cindex easy notation
 @cindex Hal Leonard
@@ -1902,8 +2340,15 @@ Internals Reference:
 @cindex easy play note heads
 @cindex note heads, easy play
 
+@funindex \easyHeadsOn
+@funindex easyHeadsOn
+@funindex \easyHeadsOff
+@funindex easyHeadsOff
+
 The @q{easy play} note head includes a note name inside the head.
-It is used in music for beginners.
+It is used in music for beginners.  To make the letters readable,
+it should be printed in a large font size.  To print with a larger
+font, see @ref{Setting the staff size}.
 
 @lilypond[verbatim,quote]
 #(set-global-staff-size 26)
@@ -1916,20 +2361,14 @@ It is used in music for beginners.
 }
 @end lilypond
 
-The command @code{\easyHeadsOn} overrides settings for the
-@code{NoteHead} object.  These settings can be reverted with the command
-@code{\easyHeadsOff}. To make the letters readable, it has to be printed
-in a large font size.  To print with a larger font, see @ref{Setting the
-staff size}.
 
 @predefined
+@code{\easyHeadsOn},
+@code{\easyHeadsOff}.
+@endpredefined
 
-@funindex \easyHeadsOn
-@funindex \easyHeadsOff
-@code{\easyHeadsOn}, @code{\easyHeadsOff}
 
 @seealso
-
 Notation Reference:
 @ref{Setting the staff size}.
 
@@ -1952,33 +2391,35 @@ Internals Reference:
 @cindex shape notes
 @cindex Aiken shape note heads
 @cindex sacred harp note heads
+
 @funindex \key
-@funindex shapeNoteStyles
+@funindex key
 @funindex \aikenHeads
+@funindex aikenHeads
 @funindex \sacredHarpHeads
+@funindex sacredHarpHeads
 
 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 by setting @code{\aikenHeads} or
-@code{\sacredHarpHeads}, depending on the style desired.
-
-@lilypond[verbatim,fragment,quote,relative=2]
+@lilypond[verbatim,quote,relative=2]
 \aikenHeads
 c, d e f g a b c
 \sacredHarpHeads
 c, d e f g a b c
 @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.
+Shapes are typeset according to the step in the scale, where the
+base of the scale is determined by the @code{\key} command.
+
 
 @predefined
+@code{\aikenHeads},
+@code{\sacredHarpHeads}.
+@endpredefined
 
-@funindex \aikenHeads
-@funindex \sacredHarpHeads
-@code{\aikenHeads}, @code{\sacredHarpHeads}
 
 @snippets
 
@@ -1988,8 +2429,8 @@ the base of the scale is determined by the @code{\key} command.
 @noindent
 To see all note head styles, see @ref{Note head styles}.
 
-@seealso
 
+@seealso
 Snippets:
 @rlsr{Pitches}.
 
@@ -2011,14 +2452,19 @@ Internals Reference:
 @cindex note heads, improvisation
 @cindex note heads, slashed
 
+@funindex \improvisationOn
+@funindex improvisationOn
+@funindex \improvisationOff
+@funindex improvisationOff
+
 Improvisation is sometimes denoted with slashed note heads, where
 the performer may choose any pitch but should play the specified
 rhythm.  Such note heads can be created:
 
-@lilypond[verbatim,quote]
+@lilypond[verbatim,quote,relative=2]
 \new Voice \with {
   \consists "Pitch_squash_engraver"
-} \transpose c c' {
+} {
   e8 e g a a16( bes) a8 g
   \improvisationOn
   e8 ~
@@ -2031,14 +2477,12 @@ rhythm.  Such note heads can be created:
 
 
 @predefined
+@code{\improvisationOn},
+@code{\improvisationOff}.
+@endpredefined
 
-@funindex \improvisationOn
-@funindex \improvisationOff
-
-@code{\improvisationOn}, @code{\improvisationOff}
 
 @seealso
-
 Snippets:
 @rlsr{Pitches}.