X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpitches.itely;h=57369e59b01e7f1a319575ebf7c97a9b21f99012;hb=76c76ae6a8328b0ad69f183cc7c36e166f15bd05;hp=b1ec14c5d412de6b85cddd1b59430beba4a9eff3;hpb=555d8e498a31380d62be9f4853ab514b3786e986;p=lilypond.git

diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index b1ec14c5d4..05b71b88db 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -1,6 +1,6 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @ignore
-    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+   Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     version that you are working on.  See TRANSLATION for details.
@@ -10,23 +10,26 @@
 @node Pitches
 @section Pitches
 
-@lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
+@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
 {pitches-headword.ly}
 
 This section discusses how to specify the pitch of notes.  There
-are three steps to this process: input, modifying, and output.
+are three steps to this process: input, modification, and output.
 
 @menu
 * Writing pitches::             
 * Changing multiple pitches::   
 * Displaying pitches::          
+* Note heads::                  
 @end menu
 
 
 @node Writing pitches
 @subsection Writing pitches
 
-This section discusses how to input pitches.
+This section discusses how to input pitches.  There are two
+different ways to place notes in octaves: absolute and relative
+mode.  In most cases, relative mode will be more convenient.
 
 @menu
 * Absolute octave entry::       
@@ -37,219 +40,221 @@ This section discusses how to input pitches.
 
 
 @node Absolute octave entry
-@unnumberedsubsubsec Absolute octave entry
+@subsubsection Absolute octave entry
 
-@cindex Pitch names
+@cindex pitch names
 @cindex pitches
+@cindex absolute
+@cindex absolute octave specification
 
-@c don't use @samp here because that might get confused with
-@c octave marks
-A pitch name is specified using lowercase letters @code{a} through
-@code{g}.  An ascending C-major scale is engraved with
+A pitch name is specified using lowercase letters@tie{}@code{a}
+through@tie{}@code{g}.  The note names @code{c} to @code{b} are
+engraved in the octave below middle C.
 
-@lilypond[quote,fragment,verbatim,ragged-right]
+@c NOTE: don't use c' here.
+@lilypond[verbatim,quote,ragged-right,fragment]
 \clef bass
-c d e f g a b c'
-@end lilypond
-
-There are two different ways to enter these note names with regard
-to octave placement: absolute and relative.  The relative mode
-will in most cases be the most convenient, but the absolute mode
-is more fundamental and will be presented first.
-
-@cindex Absolute
-@cindex Absolute octave specification
-
-@c don't use @samp here because that might get confused with
-@c octave marks
-In absolute mode, every note is placed explicitly in a certain
-octave.  The note names @code{c} to @code{b} are engraved in the
-octave below middle C, as in the previous example.
-
-@lilypond[quote,fragment,verbatim,ragged-right]
-\clef treble
-c1
-\clef bass
-c1
+c d e f
+g a b c
+d e f g
 @end lilypond
 
 @funindex '
 @funindex ,
 
-If a note should be in another octave than this, an octave
-specification must be given.  It takes the form of a series of
-single quote (@code{'}) or comma (@code{,}) characters.  Each
-@code{'} raises the pitch by one octave; each @code{,} lowers the
-pitch by an octave.
+Other octaves may be specified with a single quote@tie{}(@code{'})
+or comma@tie{}(@code{,}) character.  Each@tie{}@code{'} raises the
+pitch by one octave; each@tie{}@code{,} lowers the pitch by an
+octave.
 
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment]
 \clef treble
-c' c'' e' g d'' d' d c
+c' c'' e' g
+d'' d' d c
 \clef bass
-c, c,, e, g d,, d, d c
+c, c,, e, g
+d,, d, d c
 @end lilypond
 
 @seealso
 
-Snippets: @lsrdir{pitch}
+Music Glossary: @rglos{Pitch names}.
 
-Program reference: @internalsref{LedgerLineSpanner},
-@internalsref{NoteHead}.
+Snippets: @lsrdir{Pitches,Pitches}.
 
 
 @node Relative octave entry
-@unnumberedsubsubsec Relative octaves entry
+@subsubsection Relative octave entry
 
-@cindex Relative
-@cindex Relative octave specification
+@cindex relative
+@cindex relative octave specification
 @funindex \relative
 
-The absolute mode requires a lot of octave specifications, which
-not only becomes tedious but also easily leads to errors.
-Therefore, it is usually more convenient to let notes be entered
-relative to the previous note.  This is done with the relative
-mode.  
+When octaves are specified in absolute mode it is easy to
+accidentally put a pitch in the wrong octave.  Relative octave
+mode reduces these errors since most of the time it is not
+necessary to indicate any octaves at all.  Furthermore, in
+absolute mode a single mistake may be difficult to spot, while in
+relative mode a single error puts the rest of the piece off by one
+octave.
 
 @example
 \relative @var{startpitch} @var{musicexpr}
 @end example
 
 In relative mode, each note is assumed to be as close to the
-previous note as possible.  This means that the octave of notes
-that appear in @var{musicexpr} are calculated as follows:
+previous note as possible.  This means that the octave of pitches
+in @var{musicexpr} is calculated as follows:
 
 @itemize
-@item 
-The pitch of the first note is relative to @code{\relative
-@var{startpitch} }.  
-
 @item
-If no octave changing marks are used, the basic interval between a
-note and the one that precedes it is always taken to be a fourth
-or less.
+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
-This distance is determined without regarding alterations or the
-actual sounding pitches; a @code{fisis} following a @code{ceses}
-will be put above the @code{ceses}.  In other words, a
-doubly-augmented fourth is considered a smaller interval than a
-diminished fifth, even though the doubly-augmented fourth spans
-seven semitones while the diminished fifth only spans six
-semitones.
+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
-The octave changing marks @code{'} and @code{,} can be added to
-raise or lower the pitch by an extra octave from the basic
-interval.
+Multiple octave changing marks can be used.  For example, @code{''}@tie{}and
+@code{,,}@tie{} will alter the pitch by two octaves.
 
 @item
-Multiple octave changing marks can be used.  @code{''} will raise
-the pitch by two octaves.
+The pitch of the first note is relative to
+@code{@var{startpitch}}.  @var{startpitch} is specified in
+absolute octave mode, and it is recommended that it be a octave of
+@code{c}.
 
-@end itemize 
+@end itemize
 
 Here is the relative mode shown in action:
 
-@lilypond[quote,fragment,ragged-right,verbatim]
-\relative c'' {
-  b c d c b c bes a
+@lilypond[verbatim,quote,ragged-right]
+\relative c {
+  \clef bass
+  c d e f
+  g a b c
+  d e f g
 }
 @end lilypond
 
 Octave changing marks are used for intervals greater than a
 fourth:
 
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \relative c'' {
-  c g c f, c' a, e''
+  c g c f,
+  c' a, e'' c
 }
 @end lilypond
 
 A note sequence without a single octave mark can nevertheless span
 large intervals:
 
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \relative c {
-  c f b e a d g
+  c f b e
+  a d g c
 }
 @end lilypond
 
 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:
+following note or chord.  Inside chords, the next note is always
+relative to the preceding one.
 
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \relative c' {
-  c <c e g>
-  <c' e g>
-  <c, e' g> c
+  c
+  <c e g>
+  % the C is now an octave higher
+  <c' e g'>
+  % the C returns to the original pitch
+  <c, e, g''>
 }
 @end lilypond
 
-The @var{startpitch} (after @code{\relative}) is a note name in
-absolute mode.  In principle it can be any note name, but common
-practice is to use @code{c} in various octave positions. 
+As explained above, the octave of pitches is calculated only with
+the note names, regardless of any alterations.  Therefore, an
+E-double-sharp following a B will be placed higher, while an
+F-double-flat will be placed lower.  In other words, a
+double-augmented fourth is considered a smaller interval than a
+double-diminished fifth, regardless of the number of semitones
+that each interval contains.
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+  c2 fis
+  c2 ges
+  b2 eisis
+  b2 feses
+}
+@end lilypond
 
-When octaves are specified as above by adding @code{'} and
-@code{,} to pitch names, it is easy to accidentally put a pitch in
-the wrong octave.  The relative octave mode prevents these errors
-since most of the time it is not necessary to indicate any octaves
-at all.  Furthermore, in absolute mode, a single mistake may be
-difficult to spot; in relative mode, a single error puts the rest
-of the piece off by one octave.
 
 @seealso
 
-Snippets: @lsrdir{pitch}
+Music Glossary: @rglos{fifth}, @rglos{interval}, @rglos{Pitch names}.
+
+Notation Reference: @ref{Octave checks}.
 
+Snippets: @lsrdir{Pitches,Pitches}.
 
-@refbugs
+
+@funindex \transpose
+@funindex \chordmode
+@funindex \relative
+
+@knownissues
 
 The relative conversion will not affect @code{\transpose},
 @code{\chordmode} or @code{\relative} sections in its argument.
-To use relative within transposed music, an additional
+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}, then
-@code{c'} is assumed.  However, this is a deprecated option and
-may disappear in future versions, so its use is discouraged.
+@c NOTE: DEPRECATED
+If no @var{startpitch} is specified for @code{\relative},
+then@tie{}@code{c'} is assumed.  However, this is a deprecated
+option and may disappear in future versions, so its use is
+discouraged.
 
 
 
 @node Accidentals
-@unnumberedsubsubsec Accidentals
+@subsubsection Accidentals
+
+@cindex accidental
+@cindex key signature
+@cindex clef
 
 @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.
-An unaltered note like @code{c} means @q{C natural}, regardless of
-the key signature or clef.  For more information, see
-@rlearning{Accidentals and key signatures}.}
+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}.}
 
 @cindex note names, Dutch
 @cindex note names, default
-
-A @notation{sharp} pitch is made by adding @code{is} to the 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 derived
-from note naming conventions in Nordic and Germanic languages,
-like German and Dutch.  To use other names for accidentals, see
+@cindex sharp
+@cindex flat
+@cindex double sharp
+@cindex sharp, double
+@cindex double flat
+@cindex flat, double
+@cindex natural sign
+
+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[quote,ragged-right,fragment,verbatim,relative=2]
-a2 ais a aes
-a2 aisis a aeses
-@end lilypond
-
-@noindent
-These are the Dutch note names.  In Dutch, @code{aes} is
-contracted to @code{as}, but both forms are accepted.  Similarly,
-both @code{es} and @code{ees} are accepted:
-
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-a2 as e es
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+ais1 aes aisis aeses
 @end lilypond
 
 A natural will cancel the effect of an accidental or key
@@ -257,10 +262,21 @@ 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[quote,ragged-right,fragment,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 a4 aes a2
 @end lilypond
 
+@cindex quarter tones
+@cindex semi-flats, semi-sharps
+
+Quarter tones may be added; the following is a series of Cs with
+increasing pitches
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+ceseh1 ces ceh c cih cis cisih
+@end lilypond
+
+
 
 @cindex accidental, reminder
 @cindex accidental, cautionary
@@ -273,164 +289,157 @@ a4 aes a2
 
 Normally accidentals are printed automatically, but you may also
 print them manually.  A reminder accidental can be forced by
-adding an exclamation mark @code{!} after the pitch.  A cautionary
-accidental (i.e., an accidental within parentheses) can be
-obtained by adding the question mark @code{?} after the pitch.
-These extra accidentals can be used to produce natural signs, too.
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
-cis cis cis! cis? c c? c! c
+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.
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+cis cis cis! cis? c c c! c?
 @end lilypond
 
+Accidentals on tied notes are only printed at the beginning of a
+new system:
 
-@cindex quarter tones
-@cindex semi-flats, semi-sharps
-
-Half-flats and half-sharps are formed by adding @code{eh} and
-@code{ih}; the following is a series of Cs with increasing
-pitches
-
-@lilypond[verbatim,ragged-right,quote,relative=2,fragment]
-\set Staff.extraNatural = ##f
-ceseh ceh cih cisih
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+cis1 ~ cis ~
+\break
+cis
 @end lilypond
 
-Micro tones are also exported to the MIDI file.
-
 
-@commonprop
-
-In accordance with standard typesetting rules, a natural sign is
-printed before a sharp or flat if a previous accidental needs to
-be cancelled.  To change this behavior, use
-
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-ceses4 ces cis c
-\set Staff.extraNatural = ##f
-ceses4 ces cis c
-@end lilypond
+@snippets
 
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{preventing-extra-naturals-from-being-automatically-added.ly}
 
 @seealso
 
-Music glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
-@rglos{double flat}.
+Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
+@rglos{double flat}, @rglos{Pitch names}, @rglos{quarter-tone}.
+
+Learning Manual: @rlearning{Accidentals and key signatures}.
 
-Notation reference: @ref{Automatic accidentals}, @ref{Musica ficta
-accidentals}.
+Notation Reference: @ref{Automatic accidentals},
+@ref{Musica ficta accidentals},
+@ref{Note names in other languages}.
 
-Snippets: @lsrdir{pitch}
+Snippets: @lsrdir{Pitches,Pitches}.
 
 
-@refbugs
+@knownissues
 
 There are no generally accepted standards for denoting
-three-quarter flats, so LilyPond's symbol does not conform to any
-standard.
+quarter-tone accidentals, so LilyPond's symbol does not conform to
+any standard.
 
 
 
 @node Note names in other languages
-@unnumberedsubsubsec Note names in other languages
+@subsubsection 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, add @code{\include "english.ly"} to the top of the
-input file.  The available language files and the note names they
-define are:
+languages.  To use them, include the language-specific init file.
+For example, to use English notes names, add @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
 
-@example
-@multitable @columnfractions .2 .6 .05 .05 .05 .05
+@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 netherlands.ly
+@item 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 c d e f g a bf b
   @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
     @tab -ff/-flatflat
 @item deutsch.ly
-  @tab c d e f g a b h 
+  @tab c d e f g a b h
   @tab -is @tab -es @tab -isis @tab -eses
 @item norsk.ly
-  @tab c d e f g a b h 
+  @tab c d e f g a b h
   @tab -iss/-is @tab -ess/-es @tab -ississ/-isis
     @tab -essess/-eses
 @item svenska.ly
-  @tab c d e f g a b h 
+  @tab c d e f g a b h
   @tab -iss @tab -ess @tab -ississ @tab -essess
+@item suomi.ly
+  @tab c d e f g a b h
+  @tab -is @tab -es @tab -isis @tab -eses
 @item italiano.ly
-  @tab do re mi fa sol la sib si 
+  @tab do re mi fa sol la sib si
   @tab -d @tab -b @tab -dd @tab -bb
 @item catalan.ly
-  @tab do re mi fa sol la sib si 
+  @tab do re mi fa sol la sib si
   @tab -d/-s @tab -b @tab -dd/-ss @tab -bb
 @item espanol.ly
-  @tab do re mi fa sol la sib si 
+  @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
   @tab -s @tab -b @tab -ss @tab -bb
+@item vlaams.ly
+  @tab do re mi fa sol la sib si
+  @tab -k @tab -b @tab -kk @tab -bb
 @end multitable
-@end example
+@end smallexample
 
-@noindent
-Note that in Dutch, German, Norwegian, and Swedish, the flat
-alterations of @code{a} like for example @code{aes} and
-@code{aeses} are usually contracted to @code{as} and @code{ases}
-(or more commonly @code{asas}).  Sometimes only these contracted
-names are defined in the corresponding language files (this also
-applies to the suffixes for quartertones below).
-
-@noindent
-Some music uses microtones whose alterations are fractions of a
-@q{normal} sharp or flat.  The note names for quartertones defined
-in the various language files are listed in the following table.
-Here the prefixes @q{semi-} and @q{sesqui-} mean @q{half} and
-@q{one and a half}, respectively.  For Norwegian, Swedish, Catalan
-and Spanish no special names have been defined yet.
+In Dutch, @code{aes} is contracted to @code{as}, but both forms
+are accepted in LilyPond.  Similarly, both @code{es} and
+@code{ees} are accepted.  This also applies to
+@code{aeses}@tie{}/@tie{}@code{ases} and
+@code{eeses}@tie{}/@tie{}@code{eses}.  Sometimes only these
+contracted names are defined in the corresponding language files.
 
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+a2 as e es a ases e eses
+@end lilypond
 
-@c What about Turkish Maquam music and similar microtonal systems?
-@c
-@c Note that the term "three-quarter-sharp/-flat" used in lilypond's source code 
-@c is actually misleading since the alteration is in fact one and a half
-@c of a regular sharp/flat.  Whence the naming "sesqui-sharp/-flat" used below.
 
-@example
-@multitable @columnfractions .2 .6 .05 .05 .05 .05
+Some music uses microtones whose alterations are fractions of a
+@q{normal} sharp or flat.  The note names for quarter-tones
+defined in the various language files are listed in the following
+table.  Here the prefixes @notation{semi-} and @notation{sesqui-}
+mean @q{half} and @q{one and a half}, respectively.  For the other
+languages, no special names have been defined yet.
+
+@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
-  @tab semi- @tab semi- @tab sesqui- @tab sesqui-
+  @tab semi-sharp @tab semi-flat @tab sesqui-sharp @tab sesqui-flat
 
 @item nederlands.ly
-  @tab c d e f g a bes b 
+  @tab c d e f g a bes b
   @tab -ih @tab -eh @tab -isih @tab -eseh
 @item english.ly
-  @tab c d e f g a bf b 
+  @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 
+  @tab c d e f g a b h
   @tab -ih @tab -eh @tab -isih @tab -eseh
-@c @item norsk.ly
-@c   @tab c d e f g a b h 
-@c @item svenska.ly
-@c   @tab c d e f g a b h 
 @item italiano.ly
-  @tab do re mi fa sol la sib si 
+  @tab do re mi fa sol la sib si
   @tab -sd @tab -sb @tab -dsd @tab -bsb
-@c @item catalan.ly 
-@c   @tab do re mi fa sol la sib si 
-@c @item  espanol.ly 
-@c   @tab do re mi fa sol la sib si 
+@item portugues.ly
+  @tab do re mi fa sol la sib si
+  @tab -sqt @tab -bqt @tab -stqt @tab -btqt
 @end multitable
-@end example
+@end smallexample
+
 
 @seealso
 
-Snippets: @lsrdir{pitch}
+Music Glossary: @rglos{Pitch names}.
 
+Snippets: @lsrdir{Pitches,Pitches}.
 
 
 @node Changing multiple pitches
@@ -439,189 +448,198 @@ Snippets: @lsrdir{pitch}
 This section discusses how to modify pitches.
 
 @menu
-* Octave check::                
+* Octave checks::               
 * Transpose::                   
 @end menu
 
-@node Octave check
-@unnumberedsubsubsec Octave check
+@node Octave checks
+@subsubsection Octave checks
 
-@cindex Octave check
+@cindex octave correction
+@cindex octave check
+@funindex =
+@funindex \octave
 
 In relative mode, it is easy to forget an octave changing mark.
-Octave checks make such errors easier to correct. A note may be
-followed by @code{=}@var{quotes} to indicate what its absolute
-octave should be.  In the following example,
-
-@example
-\relative c'' @{ c g d='' @}
-@end example
-
-@noindent
-the @code{d} will generate a warning, because a
-@code{d''} is expected, as indicated by the octave check
-@code{=''}, but a @code{d'} is found, since both @code{c}-@code{g}
-and @code{g}-@code{d} without octavation marks are descending
-fourths.  In the output, the octave is corrected to be a
-@code{d''} and the next note is calculated relative to @code{d''}
-instead of @code{d'}.
-
-There is also an octave check that produces no visible output.
-The syntax is:
+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.
 
-@example
-@var{pitch} \octave @var{controlpitch}
-@end example
-
-where @var{pitch} is a regular note within a music expression in
-relative mode and @var{controlpitch} is a pitch in absolute mode.
-This checks that @var{pitch} lies within the octave surrounding
-@var{controlpitch}, i.e. not more than a fourth above or below it.
-If this is not the case, a warning is printed and the octave is
-corrected.  The @var{controlpitch} is not printed as a note.
-
-In the example below, the first check passes without incident,
-since the @code{e} (in @code{relative} mode) is within the octave
-range of @code{a'}.  However, the second check produces a warning,
-since the @code{e} is not within the octave range of @code{b'}.
-The warning message is printed, and the octave is adjusted so that
-the following notes are in the correct octave once again.
+To check the octave of a specific 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.
 
-@example
-\relative c' @{
-  e
-  \octave a'
-  \octave b'
-@}
-@end example
+@lilypond[verbatim,quote,ragged-right,fragment]
+\relative c'' {
+  c2 d='4 d
+  e2 f
+}
+@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
+relative to the @var{controlpitch}.
 
-The octave of a note following an @code{\octave} check is
-determined with respect to the note preceding it, as modified by
-the outcome of the octave check.  In the next fragment, the first
-note, an @code{e'}, lies within the octave of @code{b}, and the
-@code{\octave} check passes successfully. The second note is then
-calculated relative to (absolute) @code{e'}, which yields an 
-@code{a'}, above middle C.  In this case, the check had no
-influence on the output of the piece.
+@lilypond[verbatim,quote,ragged-right,fragment]
+\relative c'' {
+  c2 d
+  \octave c'
+  e2 f
+}
+@end lilypond
 
-The second @code{\octave} check fails: @code{a'} is not within the
-range of @code{b}. A warning is issued, and the last note is
-calculated relative to @code{a}, not to @code{a'}, and we get a
-@code{d'}.  Without the last @code{\octave} check, the last note
-would have been a @code{d''}
+Compare the two bars below.  The first and third @code{\octave}
+check fail, but the second one does not fail.
 
-@lilypond[quote,ragged-right,verbatim,fragment]
-\relative c' {
-  e
-  \octave b
-  a
-  \octave b
-  d
+@lilypond[verbatim,quote,ragged-right,fragment]
+\relative c'' {
+  c4 f g f
+
+  c4
+  \octave c'
+  f
+  \octave c'
+  g
+  \octave c'
+  f
 }
 @end lilypond
 
+
 @seealso
 
-Snippets: @lsrdir{pitch}
+Snippets: @lsrdir{Pitches,Pitches}.
 
 
 @node Transpose
-@unnumberedsubsubsec Transpose
+@subsubsection Transpose
 
-@cindex Transpose
-@cindex Transposition of pitches
+@cindex transpose
+@cindex transposition
+@cindex transposition of pitches
 @funindex \transpose
 
 A music expression can be transposed with @code{\transpose}.  The
 syntax is
 
 @example
-\transpose @var{from} @var{to} @var{musicexpr}
+\transpose @var{frompitch} @var{topitch} @var{musicexpr}
 @end example
 
+@noindent
 This means that @var{musicexpr} is transposed by the interval
-between the pitches @var{from} and @var{to}: any note with pitch
-@var{from} is changed to @var{to} and any other note is transposed
-by the same interval.
-
-Consider a piece written in the key of D-major.  If this piece is
-a little too low for its performer, it can be transposed up to
-E-major with
-
-@example
-\transpose d e @dots{}
-@end example
-
-Consider a part written for violin (a C instrument).  If this part
-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
-following transposition will produce the appropriate part:
-
-@example
-\transpose a c @dots{}
-@end example
+between the pitches @var{frompitch} and @var{topitch}: any note
+with pitch @var{frompitch} is changed to @var{topitch} and any
+other note is transposed by the same interval.  Both pitches are
+entered in absolute mode.
+
+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.
+
+@lilypond[verbatim,quote,ragged-right]
+\transpose d e {
+  \relative c' {
+    \key d \major
+    d4 fis a d
+  }
+}
+@end lilypond
 
-@code{\transpose} will also transpose key signatures:
+If a part written in C (normal 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[quote,ragged-right,verbatim]
-mus = { \key d \major cis d fis g }
-\new Staff {
-  \clef "F" \mus
-  \clef "G"
-  \transpose c g' \mus
-  \transpose c f' \mus
+@lilypond[verbatim,quote,ragged-right]
+\transpose a c' {
+  \relative c' {
+    \key c \major
+    c4 d e g
+  }
 }
 @end lilypond
 
+@noindent
+Note that we specify @code{\key c \major} explicitly.  If we do
+not specify a key signature, the notes will be transposed but no
+key signature will be printed.
+
 @code{\transpose} distinguishes between enharmonic pitches: both
 @code{\transpose c cis} or @code{\transpose c des} will transpose
-up half a tone.  The first version will print sharps and the notes
+up a semitone.  The first version will print sharps and the notes
 will remain on the same scale step, the second version will print
 flats on the scale step above.
 
-@lilypond[quote,ragged-right,verbatim]
-mus = { c d e f }
+@lilypond[verbatim,quote,ragged-right]
+mus = \relative c' { c d e f }
 \new Staff {
-  \transpose c cis { \relative c' \mus }
-  \transpose c des { \relative c' \mus }
+  \transpose c cis { \mus }
+  \transpose c des { \mus }
 }
 @end lilypond
 
-@code{\transpose} may also be used to input written notes for a
-transposing instrument.  The previous examples show how to enter
-pitches in C (or @notation{concert pitch}) and typeset them for a
-transposing instrument, but the opposite is also possible if you
-for example have a set of instrumental parts and want to print a
-conductor's score. For example, when entering music for a B-flat
-trumpet which begins on a notated E (concert D), one would write:
+@cindex transposing instruments
+
+@code{\transpose} may also be used in a different way, to input
+written notes for a transposing instrument.  The previous examples
+show how to enter pitches in C (or @notation{concert pitch}) and
+typeset them for a transposing instrument, but the opposite is
+also possible if you for example have a set of instrumental parts
+and want to print a conductor's score.  For example, when entering
+music for a B-flat trumpet that begins on a notated E (concert D),
+one would write:
 
 @example
 musicInBflat = @{ e4 @dots{} @}
-\transpose c bes \musicInBflat
+\transpose c bes, \musicInBflat
 @end example
 
-To print this music in F (e.g., rearranging to a french horn) you
-would wrap the existing music with another @code{\transpose}
+@noindent
+To print this music in F (e.g., rearranging to a French horn) you
+could wrap the existing music with another @code{\transpose}:
 
 @example
 musicInBflat = @{ e4 @dots{} @}
-\transpose f c @{ \transpose c bes \musicInBflat @}
+\transpose f c' @{ \transpose c bes, \musicInBflat @}
 @end example
 
+@noindent
+For more information about transposing instruments,
+see @ref{Instrument transpositions}.
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
+
+
 @seealso
 
-Snippets: @lsrdir{pitch}, @lsr{scheme,
-transpose-pitches-with-minimum-accidentals.ly}.
+Notation Reference: @ref{Instrument transpositions}.
 
-Program reference: @internalsref{TransposedMusic}.
+Snippets: @lsrdir{Pitches,Pitches}.
 
-@refbugs
+Internals Reference: @internalsref{TransposedMusic}.
 
-If you want to use both @code{\transpose} and @code{\relative},
-you must put @code{\transpose} outside of @code{\relative}, since
-@code{\relative} will have no effect on music that appears inside
-a @code{\transpose}. See the previous example. 
+@funindex \transpose
+@funindex \chordmode
+@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
@@ -635,13 +653,14 @@ This section discusses how to alter the output of pitches.
 * Ottava brackets::             
 * Instrument transpositions::   
 * Automatic accidentals::       
+* Ambitus::                     
 @end menu
 
+
 @node Clef
-@unnumberedsubsubsec Clef
+@subsubsection Clef
 
 @funindex \clef
-
 @cindex G clef
 @cindex C clef
 @cindex F clef
@@ -656,207 +675,120 @@ This section discusses how to alter the output of pitches.
 @cindex baritone clef
 @cindex varbaritone clef
 @cindex subbass clef
-
-The clef is set with the @code{\clef} @var{clefname} 
-command:
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-<<
-  \new Staff {
-    % treble clef by default
-    c'1^"middle C"
-  }
-  \new Staff {
-    \clef alto
-    c'1^"middle C"
-  }
-  \new Staff {
-    \clef bass
-    c'1^"middle C"
-  }
->>
+@cindex clef
+@cindex ancient clef
+@cindex clef, ancient
+@cindex clef, G
+@cindex clef, C
+@cindex clef, F
+@cindex clef, treble
+@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 @code{\clef} @var{clefname} command.
+Middle C is shown in every example.
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+\clef treble
+c2 c
+\clef alto
+c2 c
+\clef tenor
+c2 c
+\clef bass
+c2 c
 @end lilypond
 
-The clef can also be changed inside the staff:
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\new PianoStaff <<
-  \new Staff {
-    \time 2/4
-    \clef treble
-    r16
-    \clef bass
-    e g c' e' e g c'
-  }
-  \new Staff {
-    \clef bass
-    c,8 r \clef treble g''4
-  }
->>
+Other clefs include:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+\clef french
+c2 c
+\clef soprano
+c2 c
+\clef mezzosoprano
+c2 c
+\clef baritone
+c2 c
+
+\break
+
+\clef varbaritone
+c2 c
+\clef subbass
+c2 c
+\clef percussion
+c2 c
+\clef tab
+c2 c
 @end lilypond
 
-These same clef symbols are used in different positions on
-the staff to change the range of notes shown by that staff.
-The treble (alto, bass) clef is always positioned to show
-the line on which a g' (c', f) note is printed.
- 
-Supported clefs include
-
-@multitable @columnfractions .4 .6
-@headitem Clef @tab Position
-@item @code{treble, violin, G, G2} @tab
-G clef (g') on 2nd line
-@item @code{alto, C} @tab
-C clef (c') on 3rd line
-@item @code{tenor} @tab
-C clef (c') on 4th line.
-@item @code{bass, F} @tab
-F clef (f) on 4th line
-@item @code{french} @tab
-G clef (g') on 1st line, so-called French violin clef
-@item @code{soprano} @tab
-C clef (c') on 1st line
-@item @code{mezzosoprano} @tab
-C clef (c') on 2nd line
-@item @code{baritone} @tab
-C clef (c') on 5th line
-@item @code{varbaritone} @tab
-F clef (f) on 3rd line
-@item @code{subbass} @tab
-F clef (f) on 5th line
-@item @code{percussion} @tab
-percussion clef
-@item @code{tab} @tab
-tablature clef
-@end multitable
-
 Further supported clefs are described under @ref{Ancient 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} transposes by two octaves.  The argument @var{clefname}
 must be enclosed in quotes when it contains underscores or digits.
-For example,
 
 @cindex choral tenor clef
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
-\clef "G_8" c4
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+\clef "treble_8"
+c2 c
+\clef "bass^15"
+c2 c
 @end lilypond
 
-@commonprop
-
-When a clef change takes place at a line break the new clef symbol
-is printed at both the end of the previous line and the beginning
-of the new line by default.  If the warning clef at the end of the
-previous line in not required it can be suppressed by setting the
-@code{explicitClefVisibility} Staff property to the value
-@var{end-of-line-invisible}:  @code{\set
-Staff.explicitClefVisibility = #end-of-line-invisible} The default
-behaviour can be recovered with @code{\unset
-Staff.explicitClefVisibility}
-
-The command @code{\clef "treble_8"} is equivalent to setting
-@code{clefGlyph}, @code{clefPosition} (which controls the Y
-position of the clef), @code{middleCPosition} and
-@code{clefOctavation}.  A clef is printed when either the
-@code{clefGlyph}, @code{clefPosition} or @code{clefOctavation}
-properties are changed.  Note that changing the glyph, the
-position of the clef, or the octavation, does not in itself change
-the position of subsequent notes on the staff: the position of
-middle C must also be specified to do this.  The positional
-parameters are relative to the staff centre line, positive numbers
-displacing upwards, counting 1 for each line and space.  The
-clefOctavation value would normally be set to 7, -7, 15 or -15,
-but other values are not invalid.
-
-The following examples show the possibilities when setting these
-properties manually.  First some manual changes which preserve the
-standard relative positioning of clefs and notes:
-
-@lilypond[quote,ragged-right,verbatim]
-{
-  % The default treble clef
-  c'4
-  % The standard bass clef
-  \set Staff.clefGlyph = #"clefs.F"
-  \set Staff.clefPosition = #2
-  \set Staff.middleCPosition = #6
-  c'4
-  % The baritone clef
-  \set Staff.clefGlyph = #"clefs.C"
-  \set Staff.clefPosition = #4
-  \set Staff.middleCPosition = #4
-  c'4
-  % The standard choral tenor clef
-  \set Staff.clefGlyph = #"clefs.G"
-  \set Staff.clefPosition = #-2
-  \set Staff.clefOctavation = #-7
-  \set Staff.middleCPosition = #1
-  c'4
-  % A non-standard clef
-  \set Staff.clefPosition = #0
-  \set Staff.clefOctavation = #0
-  \set Staff.middleCPosition = #-4
-  c'4
-}
-@end lilypond
 
-and some which do not:
-
-@lilypond[quote,ragged-right,verbatim]
-{
-  \set Staff.clefGlyph = #"clefs.F"
-  \set Staff.clefPosition = #2
-  c'4
-  \set Staff.clefGlyph = #"clefs.G"
-  c'4
-  \set Staff.clefGlyph = #"clefs.C"
-  c'4
-  \set Staff.clefOctavation = #7
-  c'4
-  \set Staff.clefOctavation = #0
-  \set Staff.clefPosition = #0
-  c'4
-  \set Staff.middleCPosition = #4
-  c'4
-}
-@end lilypond
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{clefs-commonly-tweaked-properties.ly}
+
 
 @seealso
 
-Notation reference: @ref{Ancient clefs}.
+Notation Reference: @ref{Ancient clefs}.
 
-Snippets: @lsrdir{pitch}
+Snippets: @lsrdir{Pitches,Pitches}.
 
-Program reference: @internalsref{Clef}.
+Internals Reference: @internalsref{Clef}.
 
 
 @node Key signature
-@unnumberedsubsubsec Key signature
+@subsubsection Key signature
 
-@cindex Key signature
+@cindex key signature
 @funindex \key
 
 @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.
-An unaltered note like @code{c} means @q{C natural}, regardless of
-the key signature or clef.  For more information, see
-@rlearning{Accidentals and key signatures}.}
+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}.}
 
 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.  Setting or changing the key signature
+is done with the @code{\key} command:
 
 @example
-\key @var{pitch} @var{type}
+\key @var{pitch} @var{mode}
 @end example
 
-@funindex \minor
 @funindex \major
 @funindex \minor
 @funindex \ionian
@@ -867,78 +799,46 @@ command:
 @funindex \phrygian
 @funindex \dorian
 @cindex church modes
+@cindex modes
 
-Here, @var{type} should be @code{\major} or @code{\minor} to get
-@var{pitch}-major or @var{pitch}-minor, respectively.  You may
-also use the standard mode names (also called @q{church modes}):
-@code{\ionian}, @code{\locrian}, @code{\aeolian},
-@code{\mixolydian}, @code{\lydian}, @code{\phrygian}, and
-@code{\dorian}.
+Here, @var{mode} should be @code{\major} or @code{\minor} to get a
+key signature of @var{pitch}-major or @var{pitch}-minor,
+respectively.  You may also use the standard mode names, also
+called @q{church modes}: @code{\ionian}, @code{\dorian},
+@code{\phrygian}, @code{\lydian}, @code{\mixolydian},
+@code{\aeolian}, and @code{\locrian}.
 
-@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \key g \major
-f1
+fis1
+f
 fis
 @end lilypond
 
 
-@commonprop
-
-A natural sign is printed to cancel any previous accidentals.
-This may be altered:
+@snippets
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\key d \major
-a b cis d
-\key g \minor
-a bes c d
-\set Staff.printKeyCancellation = ##f
-\key d \major
-a b cis d
-\key g \minor
-a bes c d
-@end lilypond
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
 
-The @code{\key} command sets the context property
-@code{Staff.keySignature}.  Non-standard key signatures can be
-specified by setting this property directly.  The format of this
-command is a list:
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{non-traditional-key-signatures.ly}
 
-@example
-\set Staff.keySignature = #'((@var{octave} .  @var{step}) . @var{alter})
-@end example
-
-@noindent
-where, for each element in the list, @var{octave} specifies the
-octave (0 being the octave from middle C to the B above),
-@var{step} specifies the note within the octave (0 means C and 6
-means B), and @var{alter} is ,SHARP ,FLAT ,DOUBLE-SHARP etc.
-(Note the leading comma.)  Here is an example of a possible key
-signature for generating a whole-tone scale:
-
-@lilypond[quote,ragged-right,verbatim]
-\relative c'
-  \new Staff {
-    \set Staff.keySignature = 
-      #`(((0 .  3) . ,SHARP) ((0 . 5) . ,FLAT) ((0 . 6) . ,FLAT))
-    c d e fis aes bes c
-}
-@end lilypond
 
 @seealso
 
-Music glossary: @rglos{Church mode}, @rglos{scordatura}.
+Music Glossary: @rglos{church mode}, @rglos{scordatura}.
+
+Learning Manual: @rlearning{Accidentals and key signatures}.
 
-Snippets: @lsrdir{pitch},
-FIXME link to snippet 248,
-FIXME link to a snippet about scordatura.
+Snippets: @lsrdir{Pitches,Pitches}.
 
-Program reference: @internalsref{KeyCancellation},
-@internalsref{KeySignature}, @internalsref{Key_engraver}
+Internals Reference: @internalsref{KeyCancellation},
+@internalsref{KeySignature}, @internalsref{Key_engraver}.
 
 
 @node Ottava brackets
-@unnumberedsubsubsec Ottava brackets
+@subsubsection Ottava brackets
 
 @cindex ottava
 @cindex 15ma
@@ -949,496 +849,1099 @@ Program reference: @internalsref{KeyCancellation},
 @notation{Ottava brackets} introduce an extra transposition of an
 octave for the staff:
 
-@lilypond[quote,ragged-right,verbatim,fragment]
-\relative c''' {
-  a2 b
-  #(set-octavation 1)
-  a b
-  #(set-octavation 0)
-  a b
-}
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+a'2 b
+#(set-octavation 1)
+a b
+#(set-octavation 0)
+a b
 @end lilypond
 
 The @code{set-octavation} function also takes -1 (for 8va bassa),
 2@tie{}(for 15ma), and -2 (for 15ma bassa) as arguments.
-Internally the function sets the properties @code{ottavation}
-(e.g., to @code{"8va"} or @code{"8vb"}) and
-@code{middleCPosition}.  To override the text of the bracket, set
-@code{ottavation} after invoking @code{set-octavation}, i.e.,
-
-@lilypond[quote,ragged-right,verbatim]
-{
-  #(set-octavation 1)
-  \set Staff.ottavation = #"8"
-  c'''
-}
-@end lilypond
 
 
-@seealso
+@snippets
 
-Snippets: @lsrdir{pitch}
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{ottava-text.ly}
+
+
+@seealso
 
-Program reference: @internalsref{OttavaBracket}.
+Music Glossary: @rglos{octavation}.
 
+Snippets: @lsrdir{Pitches,Pitches}.
 
-@refbugs
+Internals Reference: @internalsref{OttavaBracket}.
 
-@code{set-octavation} will get confused when clef changes happen
-during an octavation bracket.
 
 
 @node Instrument transpositions
-@unnumberedsubsubsec Instrument transpositions
+@subsubsection Instrument transpositions
 
 @cindex transposition, MIDI
 @cindex transposition, instrument
-
-The key of a @notation{transposing instrument} can be specified.
-This applies to many wind instruments, for example, clarinets
-(B-flat, A, and E-flat), horn (F) and trumpet (B-flat, C, D, and
-E-flat).
-
-The transposition is entered with the command
+@cindex transposing instrument
+@cindex MIDI
+@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}.
 
 @example
 \transposition @var{pitch}
 @end example
 
-@noindent
-where @var{pitch} specifies the key in which the instrument plays.
-For example, a part for B-flat clarinet would include
-
-@example
-\transposition bes
-@end example
-
-This command sets the property @code{instrumentTransposition}.
-The value of this property is used for MIDI output and quotations.
-MIDI output is transposed to play at concert pitch, and cue notes
-and quotations are automatically transposed to the key of the
-instrument in which they are quoted.  For more information about
-quotations, see @ref{Quoting other voices}.
-
 The pitch to use for @code{\transposition} should correspond to
-the real sound heard when a @code{c'} written on the staff is
-played by the transposing instrument.  @code{\transposition}
-should be used when the music is entered from an orchestral part
-written for the instrument.  For example, in classical horn parts,
-the tuning of the instrument is often changed during a piece.
-Here are a few notes for a violin and a B-flat clarinet where the
+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
+@emph{only} be used if the pitches are @emph{not} being entered in
+concert pitch.
+
+Here are a few notes for violin and B-flat clarinet where the
 parts have been entered using the notes and key as they appear in
-each part or the conductor's score:
+each part of the conductor's score.  The two instruments are
+playing in unison.
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \new GrandStaff <<
-    \new Staff = "Violin I" {
+  \new Staff = "Vln" {
+    \relative c'' {
       \set Staff.instrumentName = "Vln"
       \set Staff.midiInstrument="violin"
+      % strictly speaking not necessary, but a good reminder
+      \transposition c'
+
       \key c \major
-      \transposition c
-      g'4( c''8) r c'' r c''4
+      g4( c8) r c r c4
     }
-    \new Staff = "Clarinet" {
-      \set Staff.instrumentName = "Cl"
+  }
+  \new Staff = "clarinet" {
+    \relative c'' {
+      \set Staff.instrumentName = \markup {Cl (B\flat)}
       \set Staff.midiInstrument="clarinet"
-      \key d \major
       \transposition bes
-      a'4( d''8) r d'' r d''4
+
+      % not concert pitch
+      \key d \major
+      a4( d8) r d r d4
     }
+  }
 >>
 @end lilypond
 
-Without the @code{\transposition} command the midi output of this
-music would play the notes a tone apart; with it the notes are
-played correctly in unison.
-
-However, when entering the notes of a score in concert pitch, when
-all voices are entered in C, they may be prefaced by (the default)
-@code{\transposition c'}:
+The @code{\transposition} may be changed during a piece.  For
+example, a clarinetist may switch from an A clarinet to a B-flat
+clarinet.
 
-@example
-clarinet = @{
-  \transposition c'
-  ...
-@}
-saxophone = @{
-  \transposition c'
-  ...
-@}
-@end example
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+\set Staff.instrumentName = "Cl (A)"
+\key a \major
+\transposition a
+c d e f
+\textLengthOn
+r1^\markup{Switch to B\flat clarinet}
 
-@noindent
-to serve as a reminder that these parts are written in C.
+\key bes \major
+\transposition bes
+c2 g
+@end lilypond
 
 
 @seealso
 
-Notation reference: @ref{Quoting other voices}, @ref{Transpose}.
+Music Glossary: @rglos{concert pitch}, @rglos{transposing instrument}.
+
+Notation Reference: @ref{Quoting other voices}, @ref{Transpose}.
 
-Snippets: @lsrdir{pitch}
+Snippets: @lsrdir{Pitches,Pitches}.
 
 
 @node Automatic accidentals
-@unnumberedsubsubsec Automatic accidentals
-@cindex Automatic accidentals
+@subsubsection Automatic accidentals
+
+@cindex automatic accidentals
+@cindex accidentals, automatic
+@cindex accidentals
+@cindex accidental style
+@cindex default accidental style
+@cindex accidental style, default
+@funindex set-accidental-style
 
-Common rules for typesetting accidentals have been placed in a
-function.  This function is called as follows
+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
 
-@funindex set-accidental-style
 @example
-#(set-accidental-style 'STYLE)
+\new Staff <<
+  #(set-accidental-style 'voice)
+  @{ @dots{} @}
+>>
 @end example
 
-@c TODO: check the context stuff below
-@c -does it *really* work?
-@c -the default contexts as specified in
-@c  scm/music-function.scm seem to be different -vv
-
-Optionally, the function can take two arguments: the name of the
-accidental style, and an optional argument that denotes the context that
-should be changed:
+The accidental style applies to the current @code{Staff} by
+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
 
 @example
-#(set-accidental-style 'STYLE #('CONTEXT#))
+#(set-accidental-style 'voice 'StaffGroup)
 @end example
 
-If no context name is supplied, @code{Staff} is the default,
-but you may wish to apply the accidental style to a single @code{Voice}
-instead.
+The following accidental styles are supported.  To demonstrate
+each style, we use the following example:
 
-The following accidental styles are supported:
+@lilypond[verbatim,quote,ragged-right]
+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" {
+      %%% change the next line as desired:
+      #(set-accidental-style 'default)
+      \musicA
+    }
+    \context Staff = "down" {
+      %%% change the next line as desired:
+      #(set-accidental-style 'default)
+      \musicB
+    }
+  >>
+}
+@end lilypond
+
+Note that the last lines of this example can be replaced by the
+following, as long as the same accidental style should be used in
+both staves.
+@example
+\new PianoStaff @{
+  <<
+    \context Staff = "up" @{
+      %%% change the next line as desired:
+      #(set-accidental-style 'default 'Score)
+      \musicA
+    @}
+    \context Staff = "down" @{
+      \musicB
+    @}
+  >>
+@}
+@end example
+
+
+@c NOTE: don't use verbatim in this table.
 @table @code
 @item default
-This is the default typesetting behavior.  It corresponds
-to 18th century common practice: Accidentals are
-remembered to the end of the measure in which they occur and
-only on their own octave.
+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 on their own
+octave.  Thus, in the example below, no natural signs are printed
+before the@tie{}@code{b} in the second measure or the
+last@tie{}@code{c}:
 
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       %#(set-accidental-style 'default) 
-       \musicA }
-       \context Staff = "down"{
-	       %#(set-accidental-style 'default)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'default" }}}
+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 'default)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'default)
+      \musicB
+    }
+  >>
 }
 @end lilypond
 
 @item voice
-The normal behavior is to remember the accidentals on
-Staff-level.  This variable, however, typesets accidentals
-individually for each voice.  Apart from that, the rule is similar to
+The normal behavior is to remember the accidentals on Staff-level.
+In this style, however, accidentals are typeset individually for
+each voice.  Apart from that, the rule is similar to
 @code{default}.
 
-@example
- \new Staff <<
-        #(set-accidental-style 'voice)
-	@{ @dots{} @}
-	>>
-@end example
+As a result, accidentals from one voice do not get canceled in
+other voices, which is often an unwanted result: in the following
+example, it is hard to determine whether the second@tie{}@code{a}
+should be played natural or sharp.  The @code{voice} option should
+therefore be used only if the voices are to be read solely by
+individual musicians.  If the staff is to be used by one musician
+(e.g., a conductor or in a piano score) then @code{modern} or
+@code{modern-cautionary} should be used instead.
 
-As a result, accidentals from one voice do not get canceled in other
-voices, which is often an unwanted result: in the following example, it
-is hard to determine whether the second @samp{a} should be played
-natural or sharp.
 
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'voice) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'voice)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'voice" }}}
+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 |
+    }
+  }
 }
-@end lilypond
 
-The @code{voice} option should be used if the voices
-are to be read solely by individual musicians.  If the staff is to be
-used by one musician (e.g., a conductor) then
-@code{modern} or @code{modern-cautionary}
-should be used instead.
+\new PianoStaff {
+  <<
+    \context Staff = "up" {
+      #(set-accidental-style 'voice)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'voice)
+      \musicB
+    }
+  >>
+}
+@end lilypond
 
 @item modern
+@cindex accidentals, modern style
+@cindex modern style accidentals
 @funindex modern style accidentals
-This rule corresponds to the common practice in the 20th century.  This rule
-prints the same accidentals as @code{default}, but temporary
-accidentals also are canceled in other octaves.  Furthermore,
-in the same octave, they also get canceled in the following
-measure: in the following example, notice the two natural signs which appear
-in the second bar of the upper staff.
+
+This rule corresponds to the common practice in the twentieth
+century.  It prints the same accidentals as @code{default}, with
+two exceptions that serve to avoid ambiguity: after temporary
+accidentals, cancellation marks are printed also in the following
+measure (for notes in the same octave) and, in the same measure,
+for notes in other octaves.  Hence the naturals before
+the@tie{}@code{b} and the@tie{}@code{c} in the second measure of
+the upper staff:
 
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'modern) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'modern)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'modern" }}}
+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 'modern)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'modern)
+      \musicB
+    }
+  >>
 }
 @end lilypond
 
-@item @code{modern-cautionary}
+@item modern-cautionary
+@cindex accidentals, modern cautionary style
+@cindex modern style accidentals
+@cindex modern style cautionary accidentals
+@cindex modern accidental style
+@cindex modern cautionary accidental style
 @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 printed in reduced size or (by default)
-with parentheses -- this can be set by definig the @code{cautionary-style}
-property of the @internalsref{AccidentalSuggestion} object.
+
+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}.
+
 
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'modern-cautionary) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'modern-cautionary)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'modern-cautionary" }}}
+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 'modern-cautionary)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'modern-cautionary)
+      \musicB
+    }
+  >>
 }
 @end lilypond
 
-@funindex modern-voice
 @item modern-voice
-This rule is used for multivoice accidentals to be read both by musicians
-playing one voice and musicians playing all voices.  Accidentals are
-typeset for each voice, but they @emph{are} canceled across voices in
-the same @internalsref{Staff}.
+@cindex accidentals, multivoice
+@cindex accidentals, modern
+@cindex modern accidentals
+@cindex multivoice accidentals
+@cindex accidental style, modern
+@cindex modern accidental style
+@funindex modern-voice
+
+This rule is used for multivoice accidentals to be read both by
+musicians playing one voice and musicians playing all voices.
+Accidentals are typeset for each voice, but they @emph{are}
+canceled across voices in the same @code{Staff}.  Hence,
+the@tie{}@code{a} in the last measure is canceled because the
+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,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'modern-voice) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'modern-voice)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'modern-voice" }}}
+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 'modern-voice)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'modern-voice)
+      \musicB
+    }
+  >>
 }
 @end lilypond
 
+@cindex accidental style, modern voice cautionary
+@cindex accidental style, cautionary, modern voice
+@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 by this variable,
+@code{default} @emph{are} typeset with this rule,
 some of them are typeset as cautionaries.
 
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'modern-voice-cautionary) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'modern-voice-cautionary)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'modern-voice-cautionary" }}}
+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 'modern-voice-cautionary)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'modern-voice-cautionary)
+      \musicB
+    }
+  >>
 }
 @end lilypond
 
 @item piano
-@funindex piano accidentals
-This accidental style takes place in a GrandStaff context.  However, you have to 
-explicitly set it for @emph{each} individual Staff of the GrandStaff:
+@cindex piano accidentals
+@cindex piano accidentals
+@cindex accidentals, piano
+@cindex piano accidental style
+@cindex accidental style, piano
 
-@example
-\new GrandStaff @{ <<
-  \new Staff = "up" @{ <<
-    #(set-accidental-style 'piano)
-    @{ @dots{} @}
-  >> @}
-  \new Staff = "down"@{ <<
-    #(set-accidental-style 'piano)
-  @{ @dots{} @}
-  >> @}
->> @}
-@end example
+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
+GrandStaff or PianoStaff, hence all the cancellations of the final
+notes.
 
-This rule reflects 20th 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 @internalsref{GrandStaff} or
-@internalsref{PianoStaff}.
+This accidental style applies to the current @code{GrandStaff} or
+@code{PianoStaff} by default.
 
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'piano) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'piano)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'piano" }}}
+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 'piano)
+      \musicA
+    }
+    \context Staff = "down" {
+      \musicB
+    }
+  >>
 }
 @end lilypond
 
 @item piano-cautionary
 @funindex #(set-accidental-style 'piano-cautionary)
+@cindex accidentals, piano cautionary
+@cindex cautionary accidentals, piano
+@cindex piano cautionary accidentals
+@cindex accidental style, piano cautionary
+@cindex cautionary accidental style, piano
+@cindex piano cautionary accidental style
+
 Same as @code{#(set-accidental-style 'piano)} but with the extra
 accidentals typeset as cautionaries.
 
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'piano-cautionary) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'piano-cautionary)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'piano-cautionary" }}}
+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 'piano-cautionary)
+      \musicA
+    }
+    \context Staff = "down" {
+      \musicB
+    }
+  >>
 }
 @end lilypond
 
 @item no-reset
 @funindex no-reset accidental style
+@cindex accidental style, no reset
+@cindex no reset accidental style
+
 This is the same as @code{default} but with accidentals lasting
-@q{forever} and not only until the next measure:
+@q{forever} and not only within the same measure:
+
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'no-reset) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'no-reset)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'no-reset" }}}
+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 'no-reset)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'no-reset)
+      \musicB
+    }
+  >>
 }
 @end lilypond
 
 @item forget
-This is sort of 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 was
-before in the music
+@funindex forget accidental style
+@cindex forget accidental style
+@cindex accidental style, 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 was before in
+the music:
 
 @lilypond[quote,ragged-right]
-musicA = {  << \relative {  cis'8 fis, d'4 <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>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 |  } }}
-
-\score { 
-	\new PianoStaff {
-       << \context Staff = "up" {
-	       #(set-accidental-style 'forget) 
-       \musicA }
-       \context Staff = "down"{
-	       #(set-accidental-style 'forget)
-       \musicB } >> }
-       \header { piece = \markup {\fill-line { \fontsize #3  "'forget" }}}
+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 'forget)
+      \musicA
+    }
+    \context Staff = "down" {
+      #(set-accidental-style 'forget)
+      \musicB
+    }
+  >>
 }
 @end lilypond
 @end table
 
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
+
 
 @seealso
 
-Program reference: @internalsref{Accidental_engraver},
-@internalsref{Accidental}, @internalsref{AccidentalSuggestion} and @internalsref{AccidentalPlacement}.
+Snippets: @lsrdir{Pitches,Pitches}.
+
+Internals Reference: @internalsref{Accidental_engraver},
+@internalsref{Accidental}, @internalsref{AccidentalSuggestion},
+@internalsref{AccidentalPlacement}, @internalsref{GrandStaff} and
+@internalsref{PianoStaff}, @internalsref{Staff}.
 
 
-@refbugs
+@cindex accidentals and simultaneous notes
+@cindex simultaneous notes and accidentals
+@cindex accidentals in chords
+@cindex chords, accidentals in
+
+@knownissues
 
 Simultaneous notes are considered to be entered in sequential
-mode.  This means that in a chord the accidentals are typeset as if the
-notes in the chord happen one at a time, in the order in which
-they appear in the input file.  This is a problem when accidentals
-in a chord depend on each other,
-which does not happen for the default accidental style.  The problem
-can be solved by manually inserting @code{!} and @code{?} for the
+mode.  This means that in a chord the accidentals are typeset as
+if the notes in the chord happen one at a time, in the order in
+which they appear in the input file.  This is a problem when
+accidentals in a chord depend on each other, which does not happen
+for the default accidental style.  The problem can be solved by
+manually inserting@tie{}@code{!} and@tie{}@code{?} for the
 problematic notes.
 
 
+@node Ambitus
+@subsubsection Ambitus
+
+@cindex ambitus
+@cindex range of pitches
+@cindex pitch range
+
+The term @notation{ambitus} (pl. ambitus) denotes a range of
+pitches for a given voice in a part of music.  It may also denote
+the pitch range that a musical instrument is capable of playing.
+Ambitus are printed on vocal parts so that performers can easily
+determine if it matches their capabilities.
+
+Ambitus are denoted at the beginning of a piece near the initial
+clef.  The range is graphically specified by two note heads that
+represent the lowest and highest pitches.  Accidentals are only
+printed if they are not part of the key signature.
+
+@lilypond[verbatim,quote,ragged-right]
+\layout {
+  \context {
+    \Voice
+    \consists Ambitus_engraver
+  }
+}
+
+\relative c'' {
+  aes c e2 cis,2
+}
+@end lilypond
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{adding-ambiti-per-voice.ly}
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{ambiti-multiple-voices.ly}
+
+
+@seealso
+
+Music Glossary: @rglos{ambitus}.
+
+Snippets: @lsrdir{Pitches,Pitches}.
+
+Internals Reference: @internalsref{Ambitus},
+@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
+@internalsref{AmbitusAccidental}, @internalsref{Ambitus_engraver},
+@internalsref{Staff}, @internalsref{Voice}.
+
+
+@knownissues
+
+There is no collision handling in the case of multiple per-voice
+ambitus.
+
+
+@node Note heads
+@subsection Note heads
+
+This section suggests ways of altering note heads.
+
+@menu
+* Special note heads::          
+* Easy notation note heads::    
+* Shape note heads::            
+* Improvisation::               
+@end menu
+
+@node Special note heads
+@subsubsection Special note heads
+
+@cindex note heads, special
+@cindex note heads, cross
+@cindex note heads, diamond
+@cindex note heads, parlato
+@cindex note heads, harmonic
+@cindex note heads, guitar
+@cindex special note heads
+@cindex cross note heads
+@cindex diamond note heads
+@cindex parlato note heads
+@cindex harmonic note heads
+@cindex guitar note heads
+
+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:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+c4 d
+\override NoteHead #'style = #'cross
+e f
+\revert NoteHead #'style
+e d <c f\harmonic> <d a'\harmonic>
+@end lilypond
+
+@noindent
+To see all note head styles, see @ref{Note head styles}.
+
+
+@seealso
+
+Snippets: @lsrdir{Pitches,Pitches}.
+
+Notation Reference: @ref{Note head styles}.
+
+Internals Reference: @internalsref{NoteHead},
+@internalsref{LedgerLineSpanner}.
+
+
+@node Easy notation note heads
+@subsubsection Easy notation note heads
+
+@cindex note heads, practice
+@cindex note heads, easy notation
+@cindex easy notation
+@cindex Hal Leonard
+@cindex beginners' music
+@cindex music, beginners'
+@cindex easy play note heads
+@cindex note heads, easy play
+
+The @q{easy play} note head includes a note name inside the head.
+It is used in music for beginners.
+
+@lilypond[verbatim,quote,ragged-right]
+#(set-global-staff-size 26)
+\relative c' {
+  \easyHeadsOn
+  c2 e4 f
+  g1
+  \easyHeadsOff
+  c,1
+}
+@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
+
+@funindex \easyHeadsOn
+@funindex \easyHeadsOff
+@code{\easyHeadsOn}, @code{\easyHeadsOff}
+
+@seealso
+
+Notation Reference: @ref{Setting the staff size}.
+
+Snippets: @lsrdir{Pitches,Pitches},
+
+Internals Reference: @internalsref{NoteHead}.
+
+
+@node Shape note heads
+@subsubsection Shape note heads
+
+@cindex note heads, shape
+@cindex note heads, Aiken
+@cindex note heads, sacred harp
+@cindex shape notes
+@cindex Aiken shape note heads
+@cindex sacred harp note heads
+@funindex \key
+@funindex shapeNoteStyles
+@funindex \aikenHeads
+@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 by setting @code{\aikenHeads} or
+@code{\sacredHarpHeads}, depending on the style desired.
+
+@lilypond[verbatim,fragment,quote,ragged-right,relative=1]
+\aikenHeads
+c8 d4 e8 a2 g1
+\sacredHarpHeads
+c,8 d4 e8 a2 g1
+@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.
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+{applying-noteheads-styles-depending-on-the-step-of-the-scale.ly}
+
+@noindent
+To see all note head styles, see @ref{Note head styles}.
+
+@seealso
+
+Snippets: @lsrdir{Pitches,Pitches}.
+
+Notation Reference: @ref{Note head styles}.
+
+
+@node Improvisation
+@subsubsection Improvisation
+
+@cindex improvisation
+@cindex slashed note heads
+@cindex note heads, improvisation
+@cindex note heads, slashed
+
+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,ragged-right]
+\new Voice \with {
+  \consists Pitch_squash_engraver
+} \transpose c c' {
+  e8 e g a a16( bes) a8 g
+  \improvisationOn
+  e8
+  ~e2~e8 f4 fis8
+  ~fis2
+  \improvisationOff
+  a16(bes) a8 g e
+}
+@end lilypond
+
+
+@predefined
+
+@funindex \improvisationOn
+@funindex \improvisationOff
+
+@code{\improvisationOn}, @code{\improvisationOff}
+
+@seealso
+
+Snippets: @lsrdir{Pitches,Pitches}.
+
+Internals Reference: @internalsref{Pitch_squash_engraver},
+@internalsref{Voice}.
+