X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpitches.itely;h=406ccd30cce23f2450753ad14cfc72621ca11738;hb=edf17353d89f4f6bd831466262402bb9151a26ca;hp=e4cf9aba953f05d01f5c045b51404fc1d5d79507;hpb=ee82b79ea25f8773097b52ee5932ee5f42794c04;p=lilypond.git

diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index e4cf9aba95..406ccd30cc 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -6,6 +6,8 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
+@c \version "2.11.51"
+
 
 @node Pitches
 @section Pitches
@@ -51,7 +53,7 @@ through@tie{}@code{g}.  The note names @code{c} to @code{b} are
 engraved in the octave below middle C.
 
 @c don't use c' here.
-@lilypond[verbatim,quote,ragged-right,fragment]
+@lilypond[verbatim,quote,fragment]
 \clef bass
 c d e f
 g a b c
@@ -66,7 +68,7 @@ or comma@tie{}(@code{,}) character.  Each@tie{}@code{'} raises the
 pitch by one octave; each@tie{}@code{,} lowers the pitch by an
 octave.
 
-@lilypond[verbatim,quote,ragged-right,fragment]
+@lilypond[verbatim,quote,fragment]
 \clef treble
 c' c'' e' g
 d'' d' d c
@@ -81,7 +83,7 @@ Music Glossary:
 @rglos{Pitch names}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 
 @node Relative octave entry
@@ -104,23 +106,25 @@ octave.
 @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 pitches
-in @var{musicexpr} is calculated as follows:
+previous note as possible.  This means that the octave of each
+pitch inside @var{musicexpr} is calculated as follows:
 
 @itemize
 @item
-If no octave changing mark is used on a pitch, its octave is calculated
-so that the interval with the previous note is less than a fifth.  This
-interval is determined without considering accidentals.
+If no octave changing mark is used on a pitch, its octave is
+calculated so that the interval with the previous note is less
+than a fifth.  This interval is determined without considering
+accidentals.
 
 @item
-An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be added to
-respectively raise or lower a pitch by an extra octave, relative to
-the pitch calculated without an octave mark.
+An octave changing mark@tie{}@code{'} or@tie{}@code{,} can be
+added to respectively raise or lower a pitch by an extra octave,
+relative to the pitch calculated without an octave mark.
 
 @item
-Multiple octave changing marks can be used.  For example, @code{''}@tie{}and
-@code{,,}@tie{} will alter the pitch by two octaves.
+Multiple octave changing marks can be used.  For example,
+@code{''}@tie{}and@tie{}@code{,,} will alter the pitch by two
+octaves.
 
 @item
 The pitch of the first note is relative to
@@ -132,7 +136,7 @@ absolute octave mode, and it is recommended that it be a octave of
 
 Here is the relative mode shown in action:
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \relative c {
   \clef bass
   c d e f
@@ -144,7 +148,7 @@ Here is the relative mode shown in action:
 Octave changing marks are used for intervals greater than a
 fourth:
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \relative c'' {
   c g c f,
   c' a, e'' c
@@ -154,7 +158,7 @@ fourth:
 A note sequence without a single octave mark can nevertheless span
 large intervals:
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \relative c {
   c f b e
   a d g c
@@ -164,15 +168,14 @@ large intervals:
 If the preceding item is a chord, the first note of the chord is
 used as the reference point for the octave placement of a
 following note or chord.  Inside chords, the next note is always
-relative to the preceding one.
+relative to the preceding one.  Examine the next example
+carefully, paying attention to the @code{c} notes.
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \relative 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
@@ -185,7 +188,7 @@ 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]
+@lilypond[verbatim,quote]
 \relative c'' {
   c2 fis
   c2 ges
@@ -206,7 +209,10 @@ Notation Reference:
 @ref{Octave checks}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
+
+Internals Reference:
+@rinternals{RelativeOctaveMusic}.
 
 
 @funindex \transpose
@@ -235,6 +241,7 @@ discouraged.
 @cindex key signature
 @cindex clef
 
+@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.
@@ -252,14 +259,14 @@ see @rlearning{Accidentals and key signatures}.}
 @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}.
+A @notation{sharp} pitch is made by adding @code{is} to the note
+name, and a @notation{flat} pitch by adding @code{es}.  As you
+might expect, a @notation{double sharp} or @notation{double flat}
+is made by adding @code{isis} or @code{eses}.  This syntax is
+derived from Dutch note naming conventions.  To use other names
+for accidentals, see @ref{Note names in other languages}.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 ais1 aes aisis aeses
 @end lilypond
 
@@ -268,7 +275,7 @@ signature.  However, naturals are not encoded into the note name
 syntax with a suffix; a natural pitch is shown as a simple note
 name:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 a4 aes a2
 @end lilypond
 
@@ -276,9 +283,9 @@ a4 aes a2
 @cindex semi-flats, semi-sharps
 
 Quarter tones may be added; the following is a series of Cs with
-increasing pitches
+increasing pitches:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 ceseh1 ces ceh c cih cis cisih
 @end lilypond
 
@@ -301,14 +308,14 @@ 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]
+@lilypond[verbatim,quote,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:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 cis1 ~ cis ~
 \break
 cis
@@ -317,7 +324,7 @@ cis
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {preventing-extra-naturals-from-being-automatically-added.ly}
 
 @seealso
@@ -328,18 +335,24 @@ Music Glossary:
 @rglos{double sharp},
 @rglos{double flat},
 @rglos{Pitch names},
-@rglos{quarter-tone}.
+@rglos{quarter tone}.
 
 Learning Manual:
 @rlearning{Accidentals and key signatures}.
 
 Notation Reference:
 @ref{Automatic accidentals},
-@ref{Musica ficta accidentals},
+@ref{Annotational accidentals},
 @ref{Note names in other languages}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
+
+Internals Reference:
+@rinternals{Accidental_engraver}, 
+@rinternals{Accidental},
+@rinternals{AccidentalCautionary},
+@rinternals{accidental-interface}.
 
 
 @knownissues
@@ -355,9 +368,9 @@ any standard.
 
 There are predefined sets of note names for various other
 languages.  To use them, include the language-specific init file.
-For example, to use English notes names, add @code{\include
-"english.ly"} to the top of the input file.  The available
-language files and the note names they define are:
+For example, to use English notes names, add
+@w{@code{\include "english.ly"}} to the top of the input file.
+The available language files and the note names they define are:
 
 @cindex note names, other languages
 @cindex pitch names, other languages
@@ -412,7 +425,7 @@ 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,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 a2 as e es a ases e eses
 @end lilypond
 
@@ -455,7 +468,7 @@ Music Glossary:
 @rglos{Pitch names}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 
 @node Changing multiple pitches
@@ -474,20 +487,20 @@ This section discusses how to modify pitches.
 @cindex octave correction
 @cindex octave check
 @funindex =
-@funindex \octave
+@funindex \octaveCheck
 
 In relative mode, it is easy to forget an octave changing mark.
 Octave checks make such errors easier to find by displaying a
 warning and correcting the octave if a note is found in an
 unexpected octave.
 
-To check the octave of a 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.
+To check the octave of a note, specify the absolute octave after
+the @code{=}@tie{}symbol.  This example will generate a warning
+(and change the pitch) because the second note is the absolute
+octave @code{d''} instead of @code{d'} as indicated by the octave
+correction.
 
-@lilypond[verbatim,quote,ragged-right,fragment]
+@lilypond[verbatim,quote]
 \relative c'' {
   c2 d='4 d
   e2 f
@@ -495,34 +508,35 @@ the octave correction.
 @end lilypond
 
 The octave of notes may also be checked with the
-@code{\octave}@tie{}@var{controlpitch} command.  @var{controlpitch} is
-specified in absolute mode.  This checks that the interval between the
-previous note and the @var{controlpitch} is within a fourth (i.e. the
-normal calculation of relative mode).  If this check fails, a warning
-is printed, but the previous note is not changed.  Future notes are
+@code{\octaveCheck}@tie{}@var{controlpitch} command.
+@var{controlpitch} is specified in absolute mode.  This checks
+that the interval between the previous note and the
+@var{controlpitch} is within a fourth (i.e., the normal
+calculation of relative mode).  If this check fails, a warning is
+printed, but the previous note is not changed.  Future notes are
 relative to the @var{controlpitch}.
 
-@lilypond[verbatim,quote,ragged-right,fragment]
+@lilypond[verbatim,quote]
 \relative c'' {
   c2 d
-  \octave c'
+  \octaveCheck c'
   e2 f
 }
 @end lilypond
 
-Compare the two bars below.  The first and third @code{\octave}
-check fail, but the second one does not fail.
+Compare the two bars below.  The first and third @code{\octaveCheck}
+checks fail, but the second one does not fail.
 
-@lilypond[verbatim,quote,ragged-right,fragment]
+@lilypond[verbatim,quote]
 \relative c'' {
   c4 f g f
 
   c4
-  \octave c'
+  \octaveCheck c'
   f
-  \octave c'
+  \octaveCheck c'
   g
-  \octave c'
+  \octaveCheck c'
   f
 }
 @end lilypond
@@ -531,7 +545,10 @@ check fail, but the second one does not fail.
 @seealso
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
+
+Internals Reference:
+@rinternals{RelativeOctaveCheck}.
 
 
 @node Transpose
@@ -560,7 +577,7 @@ 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]
+@lilypond[verbatim,quote]
 \transpose d e {
   \relative c' {
     \key d \major
@@ -569,12 +586,12 @@ automatically transposed as well.
 }
 @end lilypond
 
-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:
+If a part written in C (normal @notation{concert pitch}) is to be
+played on the A clarinet (for which an A is notated as a C and
+thus sounds a minor third lower than notated), the appropriate
+part will be produced with:
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \transpose a c' {
   \relative c' {
     \key c \major
@@ -584,17 +601,17 @@ produced with:
 @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.
+Note that we specify @w{@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 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.
+@w{@code{\transpose c cis}} or @w{@code{\transpose c des}} will
+transpose 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[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 mus = \relative c' { c d e f }
 \new Staff {
   \transpose c cis { \mus }
@@ -634,7 +651,7 @@ see @ref{Instrument transpositions}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {transposing-pitches-with-minimum-accidentals-smart-transpose.ly}
 
 
@@ -644,10 +661,10 @@ Notation Reference:
 @ref{Instrument transpositions}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Internals Reference:
-@internalsref{TransposedMusic}.
+@rinternals{TransposedMusic}.
 
 @funindex \transpose
 @funindex \chordmode
@@ -655,7 +672,6 @@ Internals Reference:
 
 @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
@@ -713,10 +729,9 @@ This section discusses how to alter the output of pitches.
 @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.
+The clef may be altered.  Middle C is shown in every example.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+@lilypond[verbatim,quote,relative=1]
 \clef treble
 c2 c
 \clef alto
@@ -729,7 +744,7 @@ c2 c
 
 Other clefs include:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+@lilypond[verbatim,quote,relative=1]
 \clef french
 c2 c
 \clef soprano
@@ -756,15 +771,17 @@ 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.
-
 @cindex choral tenor clef
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+By adding@tie{}@code{_8} or@tie{}@code{^8} to the clef name, the
+clef is transposed one octave down or up, respectively,
+and@tie{}@code{_15} and@tie{}@code{^15} transpose by two octaves.
+The clef name must be enclosed in quotes when it contains
+underscores or digits.
+
+@lilypond[verbatim,quote,relative=2]
+\clef treble
+c2 c
 \clef "treble_8"
 c2 c
 \clef "bass^15"
@@ -774,8 +791,8 @@ c2 c
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-{clefs-commonly-tweaked-properties.ly}
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{tweaking-clef-properties.ly}
 
 
 @seealso
@@ -784,10 +801,13 @@ Notation Reference:
 @ref{Ancient clefs}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Internals Reference:
-@internalsref{Clef}.
+@rinternals{Clef_engraver},
+@rinternals{Clef},
+@rinternals{OctavateEight},
+@rinternals{clef-interface}.
 
 
 @node Key signature
@@ -796,6 +816,7 @@ Internals Reference:
 @cindex key signature
 @funindex \key
 
+@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.
@@ -805,8 +826,7 @@ see @rlearning{Accidentals and key signatures}.}
 
 The key signature indicates the tonality in which a piece is
 played.  It is denoted by a set of alterations (flats or sharps)
-at the start of the staff.  Setting or changing the key signature
-is done with the @code{\key} command:
+at the start of the staff.  The key signature may be altered:
 
 @example
 \key @var{pitch} @var{mode}
@@ -831,7 +851,7 @@ called @notation{church modes}: @code{\ionian}, @code{\dorian},
 @code{\phrygian}, @code{\lydian}, @code{\mixolydian},
 @code{\aeolian}, and @code{\locrian}.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 \key g \major
 fis1
 f
@@ -841,10 +861,10 @@ fis
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {preventing-natural-signs-from-being-printed-when-the-key-signature-changes.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {non-traditional-key-signatures.ly}
 
 
@@ -858,11 +878,16 @@ Learning Manual:
 @rlearning{Accidentals and key signatures}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Internals Reference:
-@internalsref{KeyCancellation},
-@internalsref{KeySignature}, @internalsref{Key_engraver}.
+@rinternals{KeyChangeEvent},
+@rinternals{Key_engraver},
+@rinternals{Key_performer},
+@rinternals{KeyCancellation},
+@rinternals{KeySignature},
+@rinternals{key-cancellation-interface},
+@rinternals{key-signature-interface}.
 
 
 @node Ottava brackets
@@ -877,7 +902,7 @@ Internals Reference:
 @notation{Ottava brackets} introduce an extra transposition of an
 octave for the staff:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 a'2 b
 #(set-octavation 1)
 a b
@@ -891,7 +916,7 @@ The @code{set-octavation} function also takes -1 (for 8va bassa),
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {ottava-text.ly}
 
 
@@ -901,10 +926,12 @@ Music Glossary:
 @rglos{octavation}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Internals Reference:
-@internalsref{OttavaBracket}.
+@rinternals{Ottava_spanner_engraver},
+@rinternals{OttavaBracket},
+@rinternals{ottava-bracket-interface}.
 
 
 
@@ -922,8 +949,8 @@ parts can be typeset in a different pitch than the
 @notation{concert pitch}.  In these cases, the key of the
 @notation{transposing instrument} should be specified; otherwise
 the MIDI output and cues in other parts will produce incorrect
-pitches.  For more information about quotations, see @ref{Quoting
-other voices}.
+pitches.  For more information about quotations, see
+@ref{Quoting other voices}.
 
 @example
 \transposition @var{pitch}
@@ -934,7 +961,7 @@ the real sound heard when a@tie{}@code{c'} written on the staff is
 played by the transposing instrument.  This pitch is entered in
 absolute mode, so an instrument that produces a real sound which
 is one tone higher than the printed music should use
-@code{\transposition d'}.  @code{\transposition} should
+@w{@code{\transposition d'}}.  @code{\transposition} should
 @emph{only} be used if the pitches are @emph{not} being entered in
 concert pitch.
 
@@ -943,13 +970,13 @@ parts have been entered using the notes and key as they appear in
 each part of the conductor's score.  The two instruments are
 playing in unison.
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \new GrandStaff <<
-  \new Staff = "Vln" {
+  \new Staff = "violin" {
     \relative c'' {
       \set Staff.instrumentName = "Vln"
-      \set Staff.midiInstrument="violin"
-      % strictly speaking not necessary, but a good reminder
+      \set Staff.midiInstrument = "violin"
+      % not strictly necessary, but a good reminder
       \transposition c'
 
       \key c \major
@@ -958,11 +985,10 @@ playing in unison.
   }
   \new Staff = "clarinet" {
     \relative c'' {
-      \set Staff.instrumentName = \markup {Cl (B\flat)}
-      \set Staff.midiInstrument="clarinet"
+      \set Staff.instrumentName = \markup { Cl (B\flat) }
+      \set Staff.midiInstrument = "clarinet"
       \transposition bes
 
-      % not concert pitch
       \key d \major
       a4( d8) r d r d4
     }
@@ -974,13 +1000,14 @@ The @code{\transposition} may be changed during a piece.  For
 example, a clarinetist may switch from an A clarinet to a B-flat
 clarinet.
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
 \set Staff.instrumentName = "Cl (A)"
 \key a \major
 \transposition a
 c d e f
 \textLengthOn
-r1^\markup{Switch to B\flat clarinet}
+s1*0^\markup { Switch to B\flat clarinet }
+R1
 
 \key bes \major
 \transposition bes
@@ -998,23 +1025,23 @@ Notation Reference:
 @ref{Quoting other voices}, @ref{Transpose}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 
 @node Automatic accidentals
 @unnumberedsubsubsec Automatic accidentals
 
-@cindex automatic accidentals
-@cindex accidentals, automatic
-@cindex accidentals
 @cindex accidental style
-@cindex default accidental style
 @cindex accidental style, default
+@cindex accidentals
+@cindex accidentals, automatic
+@cindex automatic accidentals
+@cindex default accidental style
 @funindex set-accidental-style
 
 There are many different conventions on how to typeset
 accidentals.  LilyPond provides a function to specify which
-accidental style to use.  This function is called as follows
+accidental style to use.  This function is called as follows:
 
 @example
 \new Staff <<
@@ -1028,7 +1055,7 @@ default (with the exception of the styles @code{piano} and
 @code{piano-cautionary}, which are explained below).  Optionally,
 the function can take a second argument that determines in which
 scope the style should be changed.  For example, to use the same
-style in all staves of the current @code{StaffGroup}, use
+style in all staves of the current @code{StaffGroup}, use:
 
 @example
 #(set-accidental-style 'voice 'StaffGroup)
@@ -1037,7 +1064,7 @@ style in all staves of the current @code{StaffGroup}, use
 The following accidental styles are supported.  To demonstrate
 each style, we use the following example:
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 musicA = {
   <<
     \relative c' {
@@ -1072,12 +1099,10 @@ musicB = {
 \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
     }
@@ -1088,6 +1113,7 @@ musicB = {
 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 @{
   <<
@@ -1109,12 +1135,12 @@ both staves.
 @item default
 This is the default typesetting behavior.  It corresponds to
 eighteenth-century common practice: accidentals are remembered to
-the end of the measure in which they occur and only on their own
+the end of the measure in which they occur and only in 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]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1161,10 +1187,10 @@ musicB = {
 @end lilypond
 
 @item voice
-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}.
+The normal behavior is to remember the accidentals at
+@code{Staff}-level.  In this style, however, accidentals are
+typeset individually for each voice.  Apart from that, the rule is
+similar to @code{default}.
 
 As a result, accidentals from one voice do not get canceled in
 other voices, which is often an unwanted result: in the following
@@ -1176,7 +1202,7 @@ individual musicians.  If the staff is to be used by one musician
 @code{modern-cautionary} should be used instead.
 
 
-@lilypond[quote,ragged-right]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1236,7 +1262,7 @@ 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]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1284,10 +1310,10 @@ musicB = {
 
 @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
+@cindex modern style accidentals
+@cindex modern style cautionary accidentals
 @funindex modern-cautionary
 
 This rule is similar to @code{modern}, but the @q{extra}
@@ -1297,8 +1323,7 @@ parentheses, but they can also be printed in reduced size by
 defining the @code{cautionary-style} property of
 @code{AccidentalSuggestion}.
 
-
-@lilypond[quote,ragged-right]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1345,12 +1370,12 @@ musicB = {
 @end lilypond
 
 @item modern-voice
-@cindex accidentals, multivoice
+@cindex accidental style, modern
 @cindex accidentals, modern
+@cindex accidentals, multivoice
+@cindex modern accidental style
 @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
@@ -1362,8 +1387,7 @@ 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]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1409,19 +1433,19 @@ musicB = {
 }
 @end lilypond
 
-@cindex accidental style, modern voice cautionary
 @cindex accidental style, cautionary, modern voice
+@cindex accidental style, modern voice cautionary
 @cindex accidental style, voice, modern cautionary
 @funindex modern-voice-cautionary
 @item modern-voice-cautionary
 
 This rule is the same as @code{modern-voice}, but with the extra
-accidentals (the ones not typeset by @code{voice}) typeset
-as cautionaries.  Even though all accidentals typeset by
-@code{default} @emph{are} typeset with this rule,
-some of them are typeset as cautionaries.
+accidentals (the ones not typeset by @code{voice}) typeset as
+cautionaries.  Even though all accidentals typeset by
+@code{default} @emph{are} typeset with this rule, some of them are
+typeset as cautionaries.
 
-@lilypond[quote,ragged-right]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1468,22 +1492,21 @@ musicB = {
 @end lilypond
 
 @item piano
-@cindex piano accidentals
-@cindex piano accidentals
+@cindex accidental style, piano
 @cindex accidentals, piano
 @cindex piano accidental style
-@cindex accidental style, piano
+@cindex piano accidentals
 
 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.
+@code{GrandStaff} or @code{PianoStaff}, hence all the
+cancellations of the final notes.
 
 This accidental style applies to the current @code{GrandStaff} or
 @code{PianoStaff} by default.
 
-@lilypond[quote,ragged-right]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1537,10 +1560,10 @@ musicB = {
 @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.
+This is the same as @code{piano} but with the extra accidentals
+typeset as cautionaries.
 
-@lilypond[quote,ragged-right]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1593,7 +1616,7 @@ musicB = {
 This is the same as @code{default} but with accidentals lasting
 @q{forever} and not only within the same measure:
 
-@lilypond[quote,ragged-right]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1646,10 +1669,10 @@ musicB = {
 
 This is the opposite of @code{no-reset}: Accidentals are not
 remembered at all -- and hence all accidentals are typeset
-relative to the key signature, regardless of what was before in
+relative to the key signature, regardless of what came before in
 the music:
 
-@lilypond[quote,ragged-right]
+@lilypond[quote]
 musicA = {
   <<
     \relative c' {
@@ -1698,20 +1721,24 @@ musicB = {
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {dodecaphonic-style-accidentals-for-each-note-including-naturals.ly}
 
 
 @seealso
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Internals Reference:
-@internalsref{Accidental_engraver},
-@internalsref{Accidental}, @internalsref{AccidentalSuggestion},
-@internalsref{AccidentalPlacement}, @internalsref{GrandStaff} and
-@internalsref{PianoStaff}, @internalsref{Staff}.
+@rinternals{Accidental},
+@rinternals{Accidental_engraver},
+@rinternals{GrandStaff} and
+@rinternals{PianoStaff},
+@rinternals{Staff},
+@rinternals{AccidentalSuggestion},
+@rinternals{AccidentalPlacement},
+@rinternals{accidental-suggestion-interface}.
 
 
 @cindex accidentals and simultaneous notes
@@ -1749,27 +1776,28 @@ 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]
+@lilypond[verbatim,quote]
 \layout {
   \context {
     \Voice
-    \consists Ambitus_engraver
+    \consists "Ambitus_engraver"
   }
 }
 
 \relative c'' {
-  aes c e2 cis,2
+  aes c e2
+  cis,1
 }
 @end lilypond
 
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-{adding-ambiti-per-voice.ly}
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{adding-ambitus-per-voice.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-{ambiti-multiple-voices.ly}
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{ambitus-with-multiple-voices.ly}
 
 
 @seealso
@@ -1778,13 +1806,17 @@ Music Glossary:
 @rglos{ambitus}.
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Internals Reference:
-@internalsref{Ambitus},
-@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
-@internalsref{AmbitusAccidental}, @internalsref{Ambitus_engraver},
-@internalsref{Staff}, @internalsref{Voice}.
+@rinternals{Ambitus_engraver},
+@rinternals{Voice},
+@rinternals{Staff},
+@rinternals{Ambitus},
+@rinternals{AmbitusAccidental},
+@rinternals{AmbitusLine},
+@rinternals{AmbitusNoteHead},
+@rinternals{ambitus-interface}.
 
 
 @knownissues
@@ -1821,36 +1853,43 @@ This section suggests ways of altering 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:
+Note heads may be altered:
 
-@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
-c4 d
+@lilypond[verbatim,quote,relative=2]
+c4 b a b
 \override NoteHead #'style = #'cross
-e f
+c4 b a b
 \revert NoteHead #'style
-e d <c f\harmonic> <d a'\harmonic>
+c4 d e f
+@end lilypond
+
+There is a shorthand for diamond shapes which can only be used
+inside chords:
+
+@lilypond[verbatim,quote,relative=2]
+<c f\harmonic>2 <d a'\harmonic>4 <c g'\harmonic>
 @end lilypond
 
 @noindent
 To see all note head styles, see @ref{Note head styles}.
 
-
 @seealso
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Notation Reference:
-@ref{Note head styles}.
+@ref{Note head styles},
+@ref{Chorded notes}.
 
 Internals Reference:
-@internalsref{NoteHead},
-@internalsref{LedgerLineSpanner}.
+@rinternals{note-event},
+@rinternals{Note_heads_engraver},
+@rinternals{Ledger_line_engraver},
+@rinternals{NoteHead},
+@rinternals{LedgerLineSpanner},
+@rinternals{note-head-interface},
+@rinternals{ledger-line-spanner-interface}.
 
 
 @node Easy notation note heads
@@ -1866,9 +1905,11 @@ Internals Reference:
 @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.
+It is used in music for beginners.  To make the letters readable,
+it should be printed in a large font size.  To print with a larger
+font, see @ref{Setting the staff size}.
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 #(set-global-staff-size 26)
 \relative c' {
   \easyHeadsOn
@@ -1879,12 +1920,6 @@ It is used in music for beginners.
 }
 @end lilypond
 
-The command @code{\easyHeadsOn} overrides settings for the
-@code{NoteHead} object.  These settings can be reverted with the command
-@code{\easyHeadsOff}. To make the letters readable, it has to be printed
-in a large font size.  To print with a larger font, see @ref{Setting the
-staff size}.
-
 @predefined
 
 @funindex \easyHeadsOn
@@ -1897,10 +1932,13 @@ Notation Reference:
 @ref{Setting the staff size}.
 
 Snippets:
-@lsrdir{Pitches,Pitches},
+@rlsr{Pitches}.
 
 Internals Reference:
-@internalsref{NoteHead}.
+@rinternals{note-event},
+@rinternals{Note_heads_engraver},
+@rinternals{NoteHead},
+@rinternals{note-head-interface}.
 
 
 @node Shape note heads
@@ -1920,19 +1958,17 @@ Internals Reference:
 In shape note head notation, the shape of the note head
 corresponds to the harmonic function of a note in the scale.  This
 notation was popular in nineteenth-century American song books.
+Shape note heads can be produced:
 
-Shape note heads can be produced by setting @code{\aikenHeads} or
-@code{\sacredHarpHeads}, depending on the style desired.
-
-@lilypond[verbatim,fragment,quote,ragged-right,relative=1]
+@lilypond[verbatim,quote,relative=2]
 \aikenHeads
-c8 d4 e8 a2 g1
+c, d e f g a b c
 \sacredHarpHeads
-c,8 d4 e8 a2 g1
+c, d e f g a b c
 @end lilypond
 
-Shapes are typeset according to the step in the scale, where
-the base of the scale is determined by the @code{\key} command.
+Shapes are typeset according to the step in the scale, where the
+base of the scale is determined by the @code{\key} command.
 
 @predefined
 
@@ -1942,8 +1978,8 @@ the base of the scale is determined by the @code{\key} command.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
-{applying-notehead-styles-depending-on-the-step-of-the-scale.ly}
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{applying-note-head-styles-depending-on-the-step-of-the-scale.ly}
 
 @noindent
 To see all note head styles, see @ref{Note head styles}.
@@ -1951,11 +1987,17 @@ To see all note head styles, see @ref{Note head styles}.
 @seealso
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Notation Reference:
 @ref{Note head styles}.
 
+Internals Reference:
+@rinternals{note-event},
+@rinternals{Note_heads_engraver},
+@rinternals{NoteHead},
+@rinternals{note-head-interface}.
+
 
 @node Improvisation
 @unnumberedsubsubsec Improvisation
@@ -1969,17 +2011,17 @@ 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]
+@lilypond[verbatim,quote,relative=2]
 \new Voice \with {
-  \consists Pitch_squash_engraver
-} \transpose c c' {
+  \consists "Pitch_squash_engraver"
+} {
   e8 e g a a16( bes) a8 g
   \improvisationOn
-  e8
-  ~e2~e8 f4 fis8
-  ~fis2
+  e8 ~
+  e2 ~ e8 f4 f8 ~
+  f2
   \improvisationOff
-  a16(bes) a8 g e
+  a16( bes) a8 g e
 }
 @end lilypond
 
@@ -1994,10 +2036,11 @@ rhythm.  Such note heads can be created:
 @seealso
 
 Snippets:
-@lsrdir{Pitches,Pitches}.
+@rlsr{Pitches}.
 
 Internals Reference:
-@internalsref{Pitch_squash_engraver},
-@internalsref{Voice}.
+@rinternals{Pitch_squash_engraver},
+@rinternals{Voice},
+@rinternals{RhythmicStaff}.