]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/pitches.itely
NR: Replace \set Staff.instrumentName
[lilypond.git] / Documentation / notation / pitches.itely
index 5d246864207020a5f270a305aa6e496792619f4e..15af95d1405ba6ff626fd31ee912f7581f559274 100644 (file)
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.19.2"
+@c \version "2.19.53"
 
 
 @node Pitches
@@ -79,25 +79,37 @@ octave.
 @lilypond[verbatim,quote]
 {
   \clef treble
-  c'4 c'' e' g
-  d''4 d' d c
+  c'4 e' g' c''
+  c'4 g b c'
   \clef bass
-  c,4 c,, e, g
-  d,,4 d, d c
+  c,4 e, g, c
+  c,4 g,, b,, c,
 }
 @end lilypond
 
-@funindex absolute
-@funindex \absolute
-Music can be marked explicitly as being in absolute octave
-notation by preceding it with @code{\absolute}:
+@funindex \fixed
+Common octave marks can be entered just once on a reference pitch
+after @code{\fixed} placed before the music.  Pitches inside
+@code{\fixed} only need @code{'} or@tie{}@code{,} marks
+when they are above or below the octave of the reference pitch.
 
-@example
-\absolute @var{musicexpr}
-@end example
+@lilypond[verbatim,quote]
+{
+  \fixed c' {
+    \clef treble
+    c4 e g c'
+    c4 g, b, c
+  }
+  \clef bass
+  \fixed c, {
+    c4 e g c'
+    c4 g, b, c
+  }
+}
+@end lilypond
 
-will be interpreted in absolute octave entry mode regardless of
-the context it appears in.
+Pitches in the music expression following @code{\fixed} are
+unaffected by any enclosing @code{\relative}, discussed next.
 
 @seealso
 Music Glossary:
@@ -116,7 +128,6 @@ Snippets:
 @cindex relative octave specification
 @cindex octave specification, relative
 
-@funindex relative
 @funindex \relative
 
 Absolute octave entry requires specifying the octave for every
@@ -169,19 +180,19 @@ Writing @code{\relative gis''' @{ gis @dots{} @}} makes it easy to
 determine the absolute pitch of the first note inside.
 
 @item no explicit starting pitch
-This (namely writing @code{\relative @{ gis''' @dots{} @}}) can be
-viewed as a compact version of the previous option: the first note
-inside is written in absolute pitch itself.  This happens to be
-equivalent to choosing @code{f} as the reference pitch.
+The form @code{\relative @{ gis''' @dots{} @}} serves
+as a compact version of the previous option: the first note
+inside is written in absolute pitch itself.  (This happens to be
+equivalent to choosing @code{f} as the reference pitch.)
 @end table
 
-The documentation will usually employ the first option.
+The documentation will usually employ the last option.
 @end itemize
 
 Here is the relative mode shown in action:
 
 @lilypond[verbatim,quote]
-\relative {
+\relative {
   \clef bass
   c d e f
   g a b c
@@ -193,8 +204,8 @@ Octave changing marks are used for intervals greater than a
 fourth:
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  c g c f,
+\relative {
+  c'' g c f,
   c' a, e'' c
 }
 @end lilypond
@@ -203,20 +214,21 @@ A note sequence without a single octave mark can nevertheless span
 large intervals:
 
 @lilypond[verbatim,quote]
-\relative {
+\relative {
   c f b e
   a d g c
 }
 @end lilypond
 
 When @code{\relative} blocks are nested, the innermost
-@code{\relative} block applies.
+@code{\relative} block starts with its own reference pitch
+independently of the outer @code{\relative}.
 
 @lilypond[verbatim,quote]
-\relative c' {
-  c d e f
-  \relative c'' {
-    c d e f
+\relative {
+  c' d e f
+  \relative {
+    c'' d e f
   }
 }
 @end lilypond
@@ -238,12 +250,12 @@ Music inside a @code{\transpose} block is absolute unless a
 @code{\relative} is included.
 
 @lilypond[verbatim,quote]
-\relative c' {
-  d e
+\relative {
+  d' e
   \transpose f g {
     d e
-    \relative c' {
-      d e
+    \relative {
+      d' e
     }
   }
 }
@@ -260,8 +272,8 @@ relative to the preceding one.  Examine the next example
 carefully, paying attention to the @code{c} notes.
 
 @lilypond[verbatim,quote]
-\relative c' {
-  c
+\relative {
+  c'
   <c e g>
   <c' e g'>
   <c, e, g''>
@@ -277,17 +289,32 @@ double-diminished fifth, regardless of the number of semitones
 that each interval contains.
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  c2 fis
+\relative {
+  c''2 fis
   c2 ges
   b2 eisis
   b2 feses
 }
 @end lilypond
 
-One consequence of these rules is that the first note inside
-@code{@w{\relative f}} music is interpreted just the same as
-if it was written in absolute pitch mode.
+In complex situations, it is sometimes useful to get back to a
+certain pitch regardless of what happened before. This can be
+done using @code{\resetRelativeOctave}:
+
+@lilypond[verbatim,quote]
+\relative {
+  <<
+    { c''2 d }
+    \\
+    { e,,2 f }
+  >>
+  \resetRelativeOctave c''
+  c2
+}
+@end lilypond
+
+@funindex \resetRelativeOctave
+
 
 @seealso
 Music Glossary:
@@ -308,11 +335,8 @@ Internals Reference:
 @cindex transposition and relative octave entry
 
 @funindex \transpose
-@funindex transpose
 @funindex \chordmode
-@funindex chordmode
 @funindex \relative
-@funindex relative
 
 
 @node Accidentals
@@ -324,11 +348,11 @@ Internals Reference:
 
 @c duplicated in Key signature and Accidentals
 @warning{New users are sometimes confused about accidentals and
-key signatures.  In LilyPond, note names are the raw input; key
-signatures and clefs determine how this raw input is displayed.
+key signatures.  In LilyPond, note names specify pitches; key
+signatures and clefs determine how these pitches are displayed.
 An unaltered note like@tie{}@code{c} means @q{C natural},
 regardless of the key signature or clef.  For more information,
-see @rlearning{Accidentals and key signatures}.}
+see @rlearning{Pitches and key signatures}.}
 
 @cindex note names, Dutch
 @cindex note names, default
@@ -349,17 +373,16 @@ 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,relative=2]
-ais1 aes aisis aeses
+@lilypond[verbatim,quote,fragment]
+\relative c'' { ais1 aes aisis aeses }
 @end lilypond
 
-A natural will cancel the effect of an accidental or key
-signature.  However, naturals are not encoded into the note name
-syntax with a suffix; a natural pitch is shown as a simple note
-name:
+A natural pitch is entered as a simple note name; no suffix is
+required.  A natural sign will be printed when needed to cancel
+the effect of an earlier accidental or key signature.
 
-@lilypond[verbatim,quote,relative=2]
-a4 aes a2
+@lilypond[verbatim,quote,fragment]
+\relative c'' { a4 aes a2 }
 @end lilypond
 
 @cindex quarter tones
@@ -369,8 +392,8 @@ a4 aes a2
 Quarter tones may be added; the following is a series of Cs with
 increasing pitches:
 
-@lilypond[verbatim,quote,relative=2]
-ceseh1 ces ceh c cih cis cisih
+@lilypond[verbatim,quote,fragment]
+\relative c'' { ceseh1 ces ceh c cih cis cisih }
 @end lilypond
 
 
@@ -391,11 +414,10 @@ print them manually.  A reminder accidental can be forced by
 adding an exclamation mark@tie{}@code{!} after the pitch.  A
 cautionary accidental (i.e., an accidental within parentheses) can
 be obtained by adding the question mark@tie{}@code{?} after the
-pitch.  These extra accidentals can also be used to produce
-natural signs.
+pitch.
 
-@lilypond[verbatim,quote,relative=2]
-cis cis cis! cis? c c c! c?
+@lilypond[verbatim,quote,fragment]
+\relative c'' { cis cis cis! cis? c c c! c? }
 @end lilypond
 
 @cindex accidental on tied note
@@ -404,10 +426,12 @@ cis cis cis! cis? c c c! c?
 Accidentals on tied notes are only printed at the beginning of a
 new system:
 
-@lilypond[verbatim,quote,relative=2,ragged-right]
-cis1~ 1~
-\break
-cis
+@lilypond[verbatim,quote,fragment,ragged-right]
+\relative c'' {
+  cis1~ 1~
+  \break
+  cis
+}
 @end lilypond
 
 
@@ -429,7 +453,7 @@ Music Glossary:
 @rglos{quarter tone}.
 
 Learning Manual:
-@rlearning{Accidentals and key signatures}.
+@rlearning{Pitches and key signatures}.
 
 Notation Reference:
 @ref{Automatic accidentals},
@@ -450,7 +474,7 @@ Internals Reference:
 
 @knownissues
 There are no generally accepted standards for denoting
-quarter-tone accidentals, so LilyPond's symbol does not conform to
+quarter-tone accidentals, so LilyPond's symbols do not conform to
 any standard.
 
 
@@ -470,15 +494,15 @@ using Italian note names:
 @lilypond[quote,verbatim]
 \language "italiano"
 
-\relative do' {
-  do re mi sib
+\relative {
+  do' re mi sib
 }
 @end lilypond
 
 The available languages and the note names they define are:
 
 @quotation
-@multitable {@code{nederlands}} {do re mi fa sol la sib si}
+@multitable {@code{nederlands}} {do re/re mi fa sol la sib si}
 @headitem Language
   @tab Note Names
 @item @code{nederlands}
@@ -491,7 +515,9 @@ The available languages and the note names they define are:
   @tab c d e f g a bf b
 @item @code{espanol} or @code{español}
   @tab do re mi fa sol la sib si
-@item @code{italiano} or @code{français}
+@item @code{français}
+  @tab do ré/re mi fa sol la sib si
+@item @code{italiano}
   @tab do re mi fa sol la sib si
 @item @code{norsk}
   @tab c d e f g a b h
@@ -510,33 +536,35 @@ In addition to note names, accidental suffixes may
 also vary depending on the language:
 
 @quotation
-@multitable {@code{nederlands}} {-s/-sharp} {-ess/-es} {-ss/-x/-sharpsharp} {-essess/-eses}
+@multitable {@code{nederlands}} {-@code{s}/-@code{-sharp}} {-@code{f}/-@code{-flat}} {-@code{ss}/-@code{x}/-@code{-sharpsharp}} {-@code{ff}/-@code{-flatflat}}
 @headitem Language
   @tab sharp @tab flat @tab double sharp @tab double flat
 @item @code{nederlands}
-  @tab -is @tab -es @tab -isis @tab -eses
+  @tab -@code{is} @tab -@code{es} @tab -@code{isis} @tab -@code{eses}
 @item @code{catalan}
-  @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
+  @tab -@code{d}/-@code{s} @tab -@code{b} @tab -@code{dd}/-@code{ss} @tab -@code{bb}
 @item @code{deutsch}
-  @tab -is @tab -es @tab -isis @tab -eses
+  @tab -@code{is} @tab -@code{es} @tab -@code{isis} @tab -@code{eses}
 @item @code{english}
-  @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
-    @tab -ff/-flatflat
+  @tab -@code{s}/-@code{-sharp} @tab -@code{f}/-@code{-flat} @tab -@code{ss}/-@code{x}/-@code{-sharpsharp}
+    @tab -@code{ff}/-@code{-flatflat}
 @item @code{espanol} or @code{español}
-  @tab -s @tab -b @tab -ss/-x @tab -bb
-@item @code{italiano} or @code{français}
-  @tab -d @tab -b @tab -dd @tab -bb
+  @tab -@code{s} @tab -@code{b} @tab -@code{ss}/-@code{x} @tab -@code{bb}
+@item @code{français}
+  @tab -@code{d} @tab -@code{b} @tab -@code{dd}/-@code{x} @tab -@code{bb}
+@item @code{italiano}
+  @tab -@code{d} @tab -@code{b} @tab -@code{dd} @tab -@code{bb}
 @item @code{norsk}
-  @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
-    @tab -essess/-eses
+  @tab -@code{iss}/-@code{is} @tab -@code{ess}/-@code{es} @tab -@code{ississ}/-@code{isis}
+    @tab -@code{essess}/-@code{eses}
 @item @code{portugues}
-  @tab -s @tab -b @tab -ss @tab -bb
+  @tab -@code{s} @tab -@code{b} @tab -@code{ss} @tab -@code{bb}
 @item @code{suomi}
-  @tab -is @tab -es @tab -isis @tab -eses
+  @tab -@code{is} @tab -@code{es} @tab -@code{isis} @tab -@code{eses}
 @item @code{svenska}
-  @tab -iss @tab -ess @tab -ississ @tab -essess
+  @tab -@code{iss} @tab -@code{ess} @tab -@code{ississ} @tab -@code{essess}
 @item @code{vlaams}
-  @tab -k @tab -b @tab -kk @tab -bb
+  @tab -@code{k} @tab -@code{b} @tab -@code{kk} @tab -@code{bb}
 @end multitable
 @end quotation
 
@@ -547,8 +575,8 @@ 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,relative=2]
-a2 as e es a ases e eses
+@lilypond[verbatim,quote,fragment]
+\relative c'' { a2 as e es a ases e eses }
 @end lilypond
 
 
@@ -578,7 +606,9 @@ appear in this table do not provide special note names yet.
   @tab -qs @tab -qf @tab -tqs @tab -tqf
 @item @code{espanol} or @code{español}
   @tab -cs @tab -cb @tab -tcs @tab -tcb
-@item @code{italiano} or @code{français}
+@item @code{français}
+  @tab -sd @tab -sb @tab -dsd @tab -bsb
+@item @code{italiano}
   @tab -sd @tab -sb @tab -dsd @tab -bsb
 @item @code{portugues}
   @tab -sqt @tab -bqt @tab -stqt @tab -btqt
@@ -628,7 +658,6 @@ This section discusses how to modify pitches.
 
 @funindex =
 @funindex \octaveCheck
-@funindex octaveCheck
 @funindex controlpitch
 
 In relative mode, it is easy to forget an octave changing mark.
@@ -643,8 +672,8 @@ octave @code{d''} instead of @code{d'} as indicated by the octave
 correction.
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  c2 d='4 d
+\relative {
+  c''2 d='4 d
   e2 f
 }
 @end lilypond
@@ -655,12 +684,12 @@ The octave of notes may also be checked with the
 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 @code{@var{controlpitch}}.
+printed.  While the previous note itself is not changed, future
+notes are relative to the corrected value.
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  c2 d
+\relative {
+  c''2 d
   \octaveCheck c'
   e2 f
 }
@@ -670,8 +699,8 @@ Compare the two bars below.  The first and third @code{\octaveCheck}
 checks fail, but the second one does not fail.
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  c4 f g f
+\relative {
+  c''4 f g f
 
   c4
   \octaveCheck c'
@@ -703,7 +732,6 @@ Internals Reference:
 @cindex notes, transposition of
 
 @funindex \transpose
-@funindex transpose
 
 A music expression can be transposed with @code{\transpose}.  The
 syntax is
@@ -729,9 +757,9 @@ automatically transposed as well.
 
 @lilypond[verbatim,quote]
 \transpose d e {
-  \relative c' {
+  \relative {
     \key d \major
-    d4 fis a d
+    d'4 fis a d
   }
 }
 @end lilypond
@@ -746,9 +774,9 @@ part will be produced with:
 
 @lilypond[verbatim,quote]
 \transpose a c' {
-  \relative c' {
+  \relative {
     \key c \major
-    c4 d e g
+    c'4 d e g
   }
 }
 @end lilypond
@@ -765,7 +793,7 @@ the notes will remain on the same scale step, the second version
 will print flats on the scale step above.
 
 @lilypond[verbatim,quote]
-music = \relative c' { c d e f }
+music = \relative { c' d e f }
 \new Staff {
   \transpose c cis { \music }
   \transpose c des { \music }
@@ -821,11 +849,8 @@ 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},
@@ -834,7 +859,7 @@ relative mode within transposed music, an additional @code{\relative}
 must be placed inside @code{\transpose}.
 
 Triple accidentals will not be printed if using @code{\transpose}. An
-@q{enharmonically equivalent} pitch will be used instead (e.g. d-flat
+@q{enharmonically equivalent} pitch will be used instead (e.g., d-flat
 rather than e-triple-flat).
 
 
@@ -857,7 +882,7 @@ The @code{@var{musicexpr}} is inverted interval-by-interval around
 @code{@var{around-pitch}} is mapped to @code{@var{to-pitch}}.
 
 @lilypond[verbatim,quote]
-music = \relative c' { c d e f }
+music = \relative { c' d e f }
 \new Staff {
   \music
   \inversion d' d' \music
@@ -883,12 +908,11 @@ Notation Reference:
 @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 }
+music = \relative { c'8. ees16( fis8. a16 b8.) gis16 f8. d16 }
 
 \new Staff {
   \music
@@ -897,9 +921,14 @@ music = \relative c' { c8. ees16( fis8. a16 b8.) gis16 f8. d16 }
 @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}.
+@code{\retrograde} is a rather simple tool.  Since many events are
+@q{mirrored} rather than exchanged, tweaks and directional
+modifiers for opening spanners need to be added at the matching
+closing spanners: @code{^(} needs to be ended by @code{^)}, every
+@code{\<} or @code{\cresc} needs to be ended by @code{\!} or
+@code{\endcr}, every @code{\>} or @code{\decr} needs to be ended
+by @code{\enddecr}.  Property-changing commands/overrides with a
+lasting effect will likely cause surprises.
 
 @seealso
 Notation Reference:
@@ -931,7 +960,6 @@ left untransformed.}
 @cindex transposition, modal
 @cindex operation, transposition
 @funindex \modalTranspose
-@funindex modalTranspose
 
 A motif can be transposed within a given scale with:
 
@@ -944,8 +972,8 @@ 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 }
+diatonicScale = \relative { c' d e f g a b }
+motif = \relative { c'8 d e f g a b c }
 
 \new Staff {
   \motif
@@ -958,8 +986,8 @@ 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,> }
+pentatonicScale = \relative { ges aes bes des ees }
+motif = \relative { ees'8 des ges,4 <ges' bes,> <ges bes,> }
 
 \new Staff {
   \motif
@@ -972,8 +1000,8 @@ 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 }
+chromaticScale = \relative { c' cis d dis e f fis g gis a ais b }
+motif = \relative { c'8 d e f g a b c }
 
 \new Staff {
   \motif
@@ -988,7 +1016,6 @@ motif = \relative c' { c8 d e f g a b c }
 @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:
@@ -1007,8 +1034,8 @@ 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 }
+octatonicScale = \relative { ees' f fis gis a b c d }
+motif = \relative { c'8. ees16 fis8. a16 b8. gis16 f8. d16 }
 
 \new Staff {
   \motif
@@ -1021,8 +1048,8 @@ 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, }
+scale = \relative { c' g' }
+motive = \relative { c' c g' c, }
 
 \new Staff {
   \motive
@@ -1034,8 +1061,8 @@ 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 }
+octatonicScale = \relative { ees' f fis gis a b c d }
+motif = \relative { c'8. ees16 fis8. a16 b8. gis16 f8. d16 }
 
 \new Staff {
   \motif
@@ -1102,52 +1129,40 @@ This section discusses how to alter the output of pitches.
 
 
 @funindex \clef
-@funindex clef
 
-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.
+Without any explicit command, the default clef for LilyPond is the
+treble (or @emph{G}) clef.
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,fragment,ragged-right]
+c'2 c'
+@end lilypond
+
+However, the clef can be changed by using the @code{\clef} command and
+an appropriate clef name.  @emph{Middle C} is shown in each of the
+following examples.
+
+@lilypond[verbatim,quote,fragment]
 \clef treble
-c2 c
+c'2 c'
 \clef alto
-c2 c
+c'2 c'
 \clef tenor
-c2 c
+c'2 c'
 \clef bass
-c2 c
+c'2 c'
 @end lilypond
 
-Other clefs include:
-
-@lilypond[verbatim,quote,relative=1]
-\clef french
-c2 c
-\clef soprano
-c2 c
-\clef mezzosoprano
-c2 c
-\clef baritone
-c2 c
+For the full range of possible clef names see @ref{Clef styles}.
 
-\break
+Specialized clefs, such as those used in @emph{Ancient} music, are
+described in @ref{Mensural clefs} and @ref{Gregorian clefs}.  Music that
+requires tablature clefs is discussed in @ref{Default tablatures} and
+@ref{Custom tablatures}.
 
-\clef varbaritone
-c2 c
-\clef subbass
-c2 c
-\clef percussion
-c2 c
-
-\break
-
-\clef G   % synonym for treble
-c2 c
-\clef F   % synonym for bass
-c2 c
-\clef C   % synonym for alto
-c2 c
-@end lilypond
+@cindex Cue clefs
+@cindex Clefs with cue notes
+For mixing clefs when using cue notes, see the @code{\cueClef} and
+@code{\cueDuringWithClef} commands in @ref{Formatting cue notes}.
 
 @cindex transposing clef
 @cindex clef, transposing
@@ -1163,42 +1178,95 @@ and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
 Other integers can be used if required.  Clef names containing
 non-alphabetic characters must be enclosed in quotes
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,fragment]
 \clef treble
-c2 c
+c'2 c'
 \clef "treble_8"
-c2 c
+c'2 c'
 \clef "bass^15"
-c2 c
+c'2 c'
 \clef "alto_2"
-c2 c
+c'2 c'
 \clef "G_8"
-c2 c
+c'2 c'
 \clef "F^5"
-c2 c
+c'2 c'
 @end lilypond
 
 Optional octavation can be obtained by enclosing the numeric
 argument in parentheses or brackets:
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,fragment]
 \clef "treble_(8)"
-c2 c
+c'2 c'
 \clef "bass^[15]"
-c2 c
+c'2 c'
 @end lilypond
 
 The pitches are displayed as if the numeric argument were
 given without parentheses/brackets.
 
-Some special purpose clefs are described in @ref{Mensural clefs},
-@ref{Gregorian clefs}, @ref{Default tablatures}, and @ref{Custom
-tablatures}.  For mixing different clefs when using cue notes within a
-score, see the @code{\cueClef} and @code{\cueDuringWithClef} functions
-in @ref{Formatting cue notes}.
+By default, a clef change taking place at a line break will cause
+the new clef symbol to be printed at the end of the previous line,
+as a @emph{warning} clef, as well as the beginning of the next.
+This @emph{warning} clef can be suppressed.
 
-@snippets
+@lilypond[verbatim,quote,fragment]
+\clef treble { c'2 c' } \break
+\clef bass { c'2 c' } \break
+\clef alto
+  \set Staff.explicitClefVisibility = #end-of-line-invisible
+  { c'2 c' } \break
+  \unset Staff.explicitClefVisibility
+\clef bass { c'2 c' } \break
+@end lilypond
+
+By default, a clef that has previously been printed will not be
+re-printed if the same @code{\clef} command is issued again and
+will be ignored.  The command
+@code{\set Staff.forceClef = ##t} changes this behaviour.
 
+@lilypond[verbatim,quote,fragment]
+  \clef treble
+  c'1
+  \clef treble
+  c'1
+  \set Staff.forceClef = ##t
+  c'1
+  \clef treble
+  c'1
+@end lilypond
+
+@noindent
+To be more precise, it is not the @code{\clef} command itself that
+prints a clef.  Instead, it sets or changes a property of the
+@code{Clef_engraver}, which then decides by its own whether to
+display a clef or not in the current staff.  The @code{forceClef}
+property overrides this decision locally to re-print a clef once.
+
+When there is a manual clef change, the glyph of the changed clef
+will be smaller than normal.  This behaviour can be overridden.
+
+@lilypond[verbatim,quote,fragment]
+  \clef "treble"
+  c'1
+  \clef "bass"
+  c'1
+  \clef "treble"
+  c'1
+  \override Staff.Clef.full-size-change = ##t
+  \clef "bass"
+  c'1
+  \clef "treble"
+  c'1
+  \revert Staff.Clef.full-size-change
+  \clef "bass"
+  c'1
+  \clef "treble"
+  c'1
+@end lilypond
+
+@snippets
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {tweaking-clef-properties.ly}
 
@@ -1210,6 +1278,9 @@ Notation Reference:
 @ref{Custom tablatures},
 @ref{Formatting cue notes}.
 
+Installed Files:
+@file{scm/parser-clef.scm}.
+
 Snippets:
 @rlsr{Pitches}.
 
@@ -1220,18 +1291,18 @@ Internals Reference:
 @rinternals{clef-interface}.
 
 @knownissues
-Ottavation numbers attached to clefs are treated as separate grobs.  So
-any @code{\override} done to the @var{Clef} will also need to be
-applied, as a separate @code{\override}, to the @var{ClefModifier}
-grob.
+Ottavation numbers attached to clefs are treated as separate
+grobs.  So any @code{\override} done to the @var{Clef} will also
+need to be applied, as a separate @code{\override}, to the
+@var{ClefModifier} grob.
 
-@lilypond[fragment,quote,verbatim,relative=1]
+@lilypond[fragment,quote,verbatim]
 \new Staff \with {
   \override Clef.color = #blue
   \override ClefModifier.color = #red
 }
 
-\clef "treble_8" c4
+\clef "treble_8" c'4
 @end lilypond
 
 
@@ -1241,7 +1312,6 @@ grob.
 @cindex key signature
 
 @funindex \key
-@funindex key
 
 @c duplicated in Key signature and Accidentals
 @warning{New users are sometimes confused about accidentals and
@@ -1249,7 +1319,7 @@ key signatures.  In LilyPond, note names are the raw input; key
 signatures and clefs determine how this raw input is displayed.
 An unaltered note like@tie{}@code{c} means @q{C natural},
 regardless of the key signature or clef.  For more information,
-see @rlearning{Accidentals and key signatures}.}
+see @rlearning{Pitches 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)
@@ -1260,23 +1330,14 @@ at the start of the staff.  The key signature may be altered:
 @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
@@ -1298,11 +1359,13 @@ 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
-fis1
-f
-fis
+@lilypond[verbatim,quote,fragment]
+\relative {
+  \key g \major
+  fis''1
+  f
+  fis
+}
 @end lilypond
 
 Additional modes can be defined, by listing the alterations
@@ -1312,8 +1375,8 @@ for each scale step when the mode starts on C.
 freygish = #`((0 . ,NATURAL) (1 . ,FLAT) (2 . ,NATURAL)
     (3 . ,NATURAL) (4 . ,NATURAL) (5 . ,FLAT) (6 . ,FLAT))
 
-\relative c' {
-  \key c \freygish c4 des e f
+\relative {
+  \key c \freygish c'4 des e f
   \bar "||" \key d \freygish d es fis g
 }
 @end lilypond
@@ -1327,14 +1390,14 @@ printed.  If a single position is specified in an entry, the
 accidentals are placed within the octave ending at that staff
 position.
 
-@lilypond[verbatim, quote,relative=0]
+@lilypond[verbatim, quote,fragment]
 \override Staff.KeySignature.flat-positions = #'((-5 . 5))
 \override Staff.KeyCancellation.flat-positions = #'((-5 . 5))
-\clef bass \key es \major es g bes d
-\clef treble \bar "||" \key es \major es g bes d
+\clef bass \key es \major es g bes d'
+\clef treble \bar "||" \key es \major es' g' bes' d''
 
 \override Staff.KeySignature.sharp-positions = #'(2)
-\bar "||" \key b \major b fis b2
+\bar "||" \key b \major b' fis' b'2
 @end lilypond
 
 @snippets
@@ -1345,13 +1408,14 @@ position.
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {non-traditional-key-signatures.ly}
 
+
 @seealso
 Music Glossary:
 @rglos{church mode},
 @rglos{scordatura}.
 
 Learning Manual:
-@rlearning{Accidentals and key signatures}.
+@rlearning{Pitches and key signatures}.
 
 Snippets:
 @rlsr{Pitches}.
@@ -1376,23 +1440,24 @@ Internals Reference:
 
 @funindex set-octavation
 @funindex \ottava
-@funindex ottava
 
 @notation{Ottava brackets} introduce an extra transposition of an
 octave for the staff:
 
-@lilypond[verbatim,quote,relative=2]
-a2 b
-\ottava #-2
-a2 b
-\ottava #-1
-a2 b
-\ottava #0
-a2 b
-\ottava #1
-a2 b
-\ottava #2
-a2 b
+@lilypond[verbatim,quote]
+\relative a' {
+  a2 b
+  \ottava #-2
+  a2 b
+  \ottava #-1
+  a2 b
+  \ottava #0
+  a2 b
+  \ottava #1
+  a2 b
+  \ottava #2
+  a2 b
+}
 @end lilypond
 
 @snippets
@@ -1403,6 +1468,9 @@ a2 b
 @lilypondfile[verbatim,quote,texidoc,doctitle]
 {adding-an-ottava-marking-to-a-single-voice.ly}
 
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{modifying-the-ottava-spanner-slope.ly}
+
 @seealso
 Music Glossary:
 @rglos{octavation}.
@@ -1426,7 +1494,6 @@ Internals Reference:
 @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
@@ -1456,26 +1523,24 @@ playing in unison.
 
 @lilypond[verbatim,quote]
 \new GrandStaff <<
-  \new Staff = "violin" {
-    \relative c'' {
-      \set Staff.instrumentName = #"Vln"
-      \set Staff.midiInstrument = #"violin"
-      % not strictly necessary, but a good reminder
-      \transposition c'
-
-      \key c \major
-      g4( c8) r c r c4
-    }
+  \new Staff = "violin" \with {
+    instrumentName = #"Vln"
+    midiInstrument = #"violin"
   }
-  \new Staff = "clarinet" {
-    \relative c'' {
-      \set Staff.instrumentName = \markup { Cl (B\flat) }
-      \set Staff.midiInstrument = #"clarinet"
-      \transposition bes
-
-      \key d \major
-      a4( d8) r d r d4
-    }
+  \relative c'' {
+    % not strictly necessary, but a good reminder
+    \transposition c'
+    \key c \major
+    g4( c8) r c r c4
+  }
+  \new Staff = "clarinet" \with {
+    instrumentName = \markup { Cl (B\flat) }
+    midiInstrument = #"clarinet"
+  }
+  \relative c'' {
+    \transposition bes
+    \key d \major
+    a4( d8) r d r d4
   }
 >>
 @end lilypond
@@ -1567,12 +1632,12 @@ each style, we use the following example:
 @lilypond[verbatim,quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -1582,8 +1647,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -1650,12 +1715,12 @@ last@tie{}@code{c}:
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -1665,8 +1730,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -1723,12 +1788,12 @@ individual musicians.  If the staff is to be used by one musician
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -1738,8 +1803,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -1789,12 +1854,12 @@ the upper staff:
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -1804,8 +1869,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -1843,22 +1908,20 @@ musicB = {
 
 @funindex modern-cautionary
 
-This rule is similar to @code{modern}, but the @q{extra}
-accidentals (the ones not typeset by @code{default}) are typeset
-as cautionary accidentals.  They are by default printed with
-parentheses, but they can also be printed in reduced size by
-defining the @code{cautionary-style} property of
-@code{AccidentalSuggestion}.
+This rule is similar to @code{modern}, but the @q{extra} accidentals
+are printed as cautionary accidentals (with parentheses).  They can also
+be printed at a different size by overriding
+@code{AccidentalCautionary}'s @code{font-size} property.
 
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -1868,8 +1931,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -1920,12 +1983,12 @@ accidental in a different voice in the previous measure:
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -1935,8 +1998,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -1981,12 +2044,12 @@ typeset as cautionaries.
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -1996,8 +2059,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2046,12 +2109,12 @@ This accidental style applies to the current @code{GrandStaff} or
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2061,8 +2124,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2106,12 +2169,12 @@ typeset as cautionaries.
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2121,8 +2184,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2150,6 +2213,129 @@ musicB = {
 @end lilypond
 
 
+@item choral
+
+@cindex accidental style, choral
+@cindex accidentals, choral
+@cindex choral accidental style
+@cindex choral accidentals
+
+@funindex choral
+
+This rule is a combination of the @code{modern-voice} and the @code{piano}
+style. It shows all accidentals required for singers that only follow their
+own voice, as well as additional accidentals for readers that follow all
+voices of an entire @code{ChoirStaff} simultaneously.
+
+This accidental style applies to the current @code{ChoirStaff} by default.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
+      \change Staff = up
+      cis' cis
+      \change Staff = down
+      <fis, a> <fis a>]
+      \showStaffSwitch
+      \change Staff = up
+      dis'4 |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new ChoirStaff {
+  <<
+    \context Staff = "up" {
+      \accidentalStyle choral
+      \musicA
+    }
+    \context Staff = "down" {
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+@item choral-cautionary
+
+@cindex accidentals, choral cautionary
+@cindex cautionary accidentals, choral
+@cindex choral cautionary accidentals
+@cindex accidental style, choral cautionary
+@cindex cautionary accidental style, choral
+@cindex choral cautionary accidental style
+
+@funindex choral-cautionary
+
+This is the same as @code{choral} but with the extra accidentals
+typeset as cautionaries.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
+      \change Staff = up
+      cis' cis
+      \change Staff = down
+      <fis, a> <fis a>]
+      \showStaffSwitch
+      \change Staff = up
+      dis'4 |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new ChoirStaff {
+  <<
+    \context Staff = "up" {
+      \accidentalStyle choral-cautionary
+      \musicA
+    }
+    \context Staff = "down" {
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+
 @item neo-modern
 
 @cindex neo-modern accidental style
@@ -2165,12 +2351,12 @@ if the note is immediately repeated.
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2180,8 +2366,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2216,18 +2402,20 @@ musicB = {
 
 @funindex neo-modern-cautionary
 
-This rule is similar to @code{neo-modern}, but the extra
-accidentals are printed as cautionary accidentals.
+This rule is similar to @code{neo-modern}, but the @q{extra} accidentals
+are printed as cautionary accidentals (with parentheses).  They can also
+be printed at a different size by overriding
+@code{AccidentalCautionary}'s @code{font-size} property.
 
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2237,8 +2425,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2282,12 +2470,12 @@ but they are canceled across voices in the same @code{Staff}.
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2297,8 +2485,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2339,12 +2527,12 @@ accidentals are printed as cautionary accidentals.
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2354,8 +2542,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2399,12 +2587,12 @@ including natural signs.
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2414,8 +2602,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2452,17 +2640,17 @@ musicB = {
 
 Like with the dodecaphonic accidental style @emph{every} note
 gets an accidental sign by default, but accidentals are
-suppressed for pitches immediately repeated within one voice.
+suppressed for pitches immediately repeated within the same staff.
 
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2472,8 +2660,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2502,6 +2690,66 @@ musicB = {
 @end lilypond
 
 
+@item dodecaphonic-first
+
+@cindex dodecaphonic accidental style
+@cindex dodecaphonic style, neo-modern
+
+@funindex dodecaphonic-first
+
+Similar to the dodecaphonic accidental style @emph{every} pitch
+gets an accidental sign, but only the first time it is encountered
+in a measure.  Accidentals are only remembered for the actual octave
+but throughout voices.
+
+@lilypond[quote]
+musicA = {
+  <<
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
+      cis2. <c, g'>4 |
+    }
+    \\
+    \relative {
+      ais'2 cis, |
+      fis8 b a4 cis2 |
+    }
+  >>
+}
+
+musicB = {
+  \clef bass
+  \new Voice {
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
+      \change Staff = up
+      cis' cis
+      \change Staff = down
+      <fis, a> <fis a>]
+      \showStaffSwitch
+      \change Staff = up
+      dis'4 |
+      \change Staff = down
+      <fis, a cis>4 gis <f a d>2 |
+    }
+  }
+}
+
+\new PianoStaff {
+  <<
+    \context Staff = "up" {
+      \accidentalStyle dodecaphonic-first
+      \musicA
+    }
+    \context Staff = "down" {
+      \accidentalStyle dodecaphonic-first
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+
 @item teaching
 
 @cindex teaching accidental style
@@ -2518,12 +2766,12 @@ key signature, except if the note is immediately repeated.
 @lilypond[quote,staffsize=18]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2533,8 +2781,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2579,12 +2827,12 @@ This is the same as @code{default} but with accidentals lasting
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2594,8 +2842,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2638,12 +2886,12 @@ the music.
 @lilypond[quote]
 musicA = {
   <<
-    \relative c' {
-      cis'8 fis, bes4 <a cis>8 f bis4 |
+    \relative {
+      cis''8 fis, bes4 <a cis>8 f bis4 |
       cis2. <c, g'>4 |
     }
     \\
-    \relative c' {
+    \relative {
       ais'2 cis, |
       fis8 b a4 cis2 |
     }
@@ -2653,8 +2901,8 @@ musicA = {
 musicB = {
   \clef bass
   \new Voice {
-    \voiceTwo \relative c' {
-      <fis, a cis>8[ <fis a cis>
+    \voiceTwo \relative {
+      <fis a cis>8[ <fis a cis>
       \change Staff = up
       cis' cis
       \change Staff = down
@@ -2734,7 +2982,7 @@ The following work-around can be used: define a function that locally changes
 the accidental style to @code{forget}:
 
 @lilypond[verbatim,quote]
-forget = #(define-music-function (parser location music) (ly:music?) #{
+forget = #(define-music-function (music) (ly:music?) #{
   \accidentalStyle forget
   #music
   \accidentalStyle modern
@@ -2779,8 +3027,8 @@ printed if they are not part of the key signature.
   }
 }
 
-\relative c'' {
-  aes c e2
+\relative {
+  aes' c e2
   cis,1
 }
 @end lilypond
@@ -2853,16 +3101,18 @@ This section suggests ways of altering note heads.
 
 The appearance of note heads may be altered:
 
-@lilypond[verbatim,quote,relative=2]
-c4 b
-\override NoteHead.style = #'cross
-c4 b
-\revert NoteHead.style
-a b
-\override NoteHead.style = #'harmonic
-a b
-\revert NoteHead.style
-c4 d e f
+@lilypond[verbatim,quote]
+\relative c'' {
+  c4 b
+  \override NoteHead.style = #'cross
+  c4 b
+  \revert NoteHead.style
+  a b
+  \override NoteHead.style = #'harmonic
+  a b
+  \revert NoteHead.style
+  c4 d e f
+}
 @end lilypond
 
 To see all note head styles, see @ref{Note head styles}.
@@ -2872,22 +3122,26 @@ intentions.  The following generic predefined commands modify the
 note head in both staff and tablature contexts and can be used to
 represent any musical meaning:
 
-@lilypond[verbatim,quote,relative=2]
-c4 b
-\xNotesOn
- a b c4 b
-\xNotesOff
-c4 d
+@lilypond[verbatim,quote]
+\relative {
+  c''4 b
+  \xNotesOn
+   a b c4 b
+  \xNotesOff
+  c4 d
+}
 @end lilypond
 
 The music function form of this predefined command may be used
 inside and outside chords to generate crossed note heads in both
 staff and tablature contexts:
 
-@lilypond[verbatim,quote,relative=2]
-c4 b
-\xNote { e f }
-c b < g \xNote c f > b
+@lilypond[verbatim,quote]
+\relative {
+  c''4 b
+  \xNote { e f }
+  c b < g \xNote c f > b
+}
 @end lilypond
 
 As synonyms for @code{\xNote}, @code{\xNotesOn} and @code{\xNotesOff},
@@ -2896,8 +3150,10 @@ be used.  The term @notation{dead note} is commonly used by guitarists.
 
 There is also a similar shorthand for diamond shapes:
 
-@lilypond[verbatim,quote,relative=2]
-<c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic> f\harmonic
+@lilypond[verbatim,quote]
+\relative c'' {
+  <c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic> f\harmonic
+}
 @end lilypond
 
 @predefined
@@ -2939,9 +3195,7 @@ Internals Reference:
 @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.  To make the letters readable,
@@ -3006,15 +3260,10 @@ Internals Reference:
 @cindex note heads, Walker
 
 @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
@@ -3022,52 +3271,49 @@ notation was popular in nineteenth-century American song books.
 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 g2 a b1 c \break
-\sacredHarpHeads
-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
+@lilypond[verbatim,quote]
+\relative c'' {
+  \aikenHeads
+  c, d e f g2 a b1 c \break
+  \sacredHarpHeads
+  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
 
 @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
-
+@lilypond[verbatim,quote]
+\relative c'' {
+  \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
 
 
@@ -3115,19 +3361,17 @@ Internals Reference:
 @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,relative=2]
+@lilypond[verbatim,quote]
 \new Voice \with {
   \consists "Pitch_squash_engraver"
-} {
-  e8 e g a a16( bes) a8 g
+} \relative {
+  e''8 e g a a16( bes) a8 g
   \improvisationOn
   e8 ~
   2 ~ 8 f4 f8 ~