@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.
@node Pitches
@section Pitches
-This section discusses how to specify the pitch of notes.
-
-@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.
+
@menu
-* Writing pitches::
-* Changing multiple pitches::
-* Displaying pitches::
+* Writing pitches::
+* Changing multiple pitches::
+* Displaying pitches::
+* Note heads::
@end menu
@node Writing pitches
@subsection Writing pitches
-Into text.
+This section discusses how to input pitches.
@menu
-* Normal pitches::
-* Accidentals::
-* Note names in other languages::
+* Absolute octave entry::
+* Relative octave entry::
+* Accidentals::
+* Note names in other languages::
@end menu
-@node Normal pitches
-@unnumberedsubsubsec Normal pitches
+@node Absolute octave entry
+@unnumberedsubsubsec Absolute octave entry
-@cindex Pitch names
+@cindex pitch names
@cindex pitches
-A pitch name is specified using lowercase letters @code{a} through
-@code{g}. An ascending C-major scale is engraved with
+@c don't use @samp here because that might get confused with
+@c octave marks
+A pitch name is specified using lowercase letters@tie{}@code{a}
+through@tie{}@code{g}. An ascending C-major scale is engraved
+with
-@lilypond[quote,fragment,verbatim,ragged-right]
+@lilypond[verbatim,quote,ragged-right,fragment]
\clef bass
c d e f g a b c'
@end lilypond
-The note name @code{c} is engraved one octave below middle C.
+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
+
+In absolute mode, every note is placed explicitly in a specific
+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]
+@lilypond[verbatim,quote,ragged-right,fragment]
\clef treble
c1
\clef bass
@funindex '
@funindex ,
-The optional octave specification takes the form of a series of
-single quote (@samp{'}) characters or a series of comma (@samp{,})
-characters. Each @samp{'} raises the pitch by one octave; each
-@samp{,} lowers the pitch by an octave.
+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@tie{}(@code{'}) or comma@tie{}(@code{,}) characters.
+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
\clef bass
c, c,, e, g d,, d, d c
@end lilypond
-An alternate method may be used to declare which octave to engrave
-a pitch; this method does not require as many octave
-specifications (@code{'} and @code{,}). See @ref{Relative
-octaves}.
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
+Internals reference: @internalsref{LedgerLineSpanner},
+@internalsref{NoteHead}.
+
+
+@node Relative octave entry
+@unnumberedsubsubsec Relative octave entry
+
+@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.
+
+@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:
+
+@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.
+
+@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.
+
+@item
+The octave changing marks@tie{}@code{'} and@tie{}@code{,} can be
+added to raise or lower the pitch by an extra octave from the
+basic interval.
+
+@item
+Multiple octave changing marks can be used. @code{''}@tie{}will
+raise the pitch by two octaves.
+
+@end itemize
+
+Here is the relative mode shown in action:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\relative c'' {
+ b c d c b c bes a
+}
+@end lilypond
+
+Octave changing marks are used for intervals greater than a
+fourth:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\relative c'' {
+ c g c f, c' a, e''
+}
+@end lilypond
+
+A note sequence without a single octave mark can nevertheless span
+large intervals:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\relative c {
+ c f b e a d g
+}
+@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:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\relative c' {
+ c <c e g>
+ <c' e, g'>
+ <c, e' g> c
+}
+@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@tie{}@code{c} in various octave positions.
+
+When octaves are specified as above by adding@tie{}@code{'}
+and@tie{}@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.
+
+LilyPond examines pitches based on the note names -- in other
+words, an augmented fourth is @emph{not} treated the same as a
+diminished fifth. If we begin at a C, then an F-sharp will be
+placed higher than the C, while a G-flat will be placed lower than
+the C.
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c2 fis
+c2 ges
+@end lilypond
+
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
+
+@refbugs
+
+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
+@code{\relative} must be placed inside @code{\transpose}.
+
+@c 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
+@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@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
-@c following paragraph changed to match Tutorial and Accidental
-@c and Key Signature pages.
-
-A @rglos{sharp} pitch is made by adding @samp{is} to the name, and
-a @rglos{flat} pitch by adding @samp{es}. As you might expect,
-a @rglos{double sharp} or @rglos{double flat} is made by adding
-@samp{isis} or @samp{eses}. This syntax derived from note naming
-conventions in Nordic and Germanic languages, like German and
-Dutch. To use other names for accidentals, see @ruser{Note names
-in other languages}.
+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
+@ref{Note names in other languages}.
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,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
+both @code{es} and @code{ees} are accepted:
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a2 as e es
@end lilypond
A natural will cancel the effect of an accidental or key
signature. However, naturals are not encoded into the note name
syntax with a suffix; a natural pitch is shown as a simple note
-name
+name:
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a4 aes a2
@end lilypond
-The input @code{d e f} is interpreted as @q{print a D-natural,
-E-natural, and an F-natural,} regardless of the key signature.
-For more information about the distinction between musical content
-and the presentation of that content, see @rlearning{Accidentals
-and key signatures}.
-
-@lilypond[fragment,quote,ragged-right,verbatim,relative]
-\key d \major
-d e f g
-d e fis g
-@end lilypond
-
-
@cindex accidental, reminder
@cindex accidental, cautionary
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 @samp{?} after the pitch.
-These extra accidentals can be used to produce natural signs, too.
+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 be used to produce natural
+signs, too.
-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
cis cis cis! cis? c c? c! c
@end lilypond
@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
+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]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\set Staff.extraNatural = ##f
ceseh ceh cih cisih
@end lilypond
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 @code{\set
-Staff.extraNatural = ##f}
+be canceled. To change this behavior, use
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
ceses4 ces cis c
\set Staff.extraNatural = ##f
ceses4 ces cis c
@seealso
-The automatic production of accidentals can be tuned in many ways.
-For more information, see @ref{Automatic accidentals}.
+Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
+@rglos{double flat}.
-Program reference: @internalsref{LedgerLineSpanner},
-@internalsref{NoteHead}.
+Notation Reference: @ref{Automatic accidentals},
+@ref{Musica ficta accidentals}.
+
+Snippets: @lsrdir{pitches}.
@refbugs
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
+define are:
@cindex note names, other languages
-@c put the rest of the old table into this new format.
+
@example
@multitable @columnfractions .2 .6 .05 .05 .05 .05
@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
-@c new stuff here:
-
-
+@item english.ly
+ @tab c d e f g a bf b
+ @tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
+ @tab -ff/-flatflat
+@item deutsch.ly
+ @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 -iss/-is @tab -ess/-es @tab -ississ/-isis
+ @tab -essess/-eses
+@item svenska.ly
+ @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 -d @tab -b @tab -dd @tab -bb
+@item catalan.ly
+ @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 -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
-@c old table
-@ignore
-@example
- Note Names sharp flat double double
- sharp flat
-
-nederlands.ly c d e f g a bes b -is -es -isis -eses
-english.ly c d e f g a bf b -s/-sharp -f/-flat -ss/-x/ -ff/
- -sharpsharp -flatflat
-deutsch.ly c d e f g a b h -is -es -isis -eses
-norsk.ly c d e f g a b h -iss/-is -ess/-es -ississ/-isis -essess/-eses
-svenska.ly c d e f g a b h -iss -ess -ississ -essess
-italiano.ly do re mi fa sol la sib si -d -b -dd -bb
-catalan.ly do re mi fa sol la sib si -d/-s -b -dd/-ss -bb
-espanol.ly do re mi fa sol la sib si -s -b -ss -bb
-@end example
-@end ignore
-
@noindent
Note that in Dutch, German, Norwegian, and Swedish, the flat
-alterations of @samp{a} like for example @code{aes} and
+alterations of@tie{}@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
@noindent
Some music uses microtones whose alterations are fractions of a
-@q{regular} sharp or flat. The note names for quartertones defined
+@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.
+@q{one and a half}, respectively. For the other languages no
+special names have been defined yet.
+
@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
- Note Names semi- semi- sesqui- sesqui-
- sharp flat sharp flat
-
-nederlands.ly c d e f g a bes b -ih -eh -isih -eseh
-english.ly c d e f g a bf b -qs -qf -tqs -tqf
-deutsch.ly c d e f g a b h -ih -eh -isih -eseh
-norsk.ly c d e f g a b h
-svenska.ly c d e f g a b h
-italiano.ly do re mi fa sol la sib si -sd -sb -dsd -bsb
-catalan.ly do re mi fa sol la sib si
-espanol.ly do re mi fa sol la sib si
-@end example
-
-
-@node Changing multiple pitches
-@subsection Changing multiple pitches
-
-@menu
-* Relative octaves::
-* Octave check::
-* Transpose::
-@end menu
-
-@node Relative octaves
-@unnumberedsubsubsec Relative octaves
-
-@cindex Relative
-@cindex Relative octave specification
-@funindex \relative
-
-Octaves are specified by adding @code{'} and @code{,} to pitch
-names. When you copy existing music, it is easy to accidentally
-put a pitch in the wrong octave and hard to find such an error.
-The relative octave mode prevents these errors by making the
-mistakes much larger: a single error puts the rest of the piece
-off by one octave
+@c Note that the term "three-quarter-sharp/-flat" used in
+@c lilypond's source code is actually misleading since the
+@c alteration is in fact one and a half of a regular sharp/flat.
+@c Whence the naming "sesqui-sharp/-flat" used below.
@example
-\relative @var{startpitch} @var{musicexpr}
-@end example
-
-@noindent
-or
+@multitable @columnfractions .2 .6 .05 .05 .05 .05
+@headitem Language
+ @tab Note names
+ @tab semi- @tab semi- @tab sesqui- @tab sesqui-
-@example
-\relative @var{musicexpr}
+@item nederlands.ly
+ @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 -qs @tab -qf @tab -tqs @tab -tqf
+@item deutsch.ly
+ @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 -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
-@noindent
-@code{c'} is used as the default if no starting pitch is defined.
-
-The octave of notes that appear in @var{musicexpr} are calculated
-as follows:
-
-@itemize
-@item
-If no octave changing marks are used, the basic interval between
-this and the last note is always taken to be a fourth or less.
-
-@item
-This distance is determined without regarding alterations; 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.
-
-@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.
-
-@item
-Multiple octave changing marks can be used. @code{''} will raise
-the pitch by two octaves.
-
-@item
-The pitch of the first note is relative to @code{\relative
-@var{startpitch} }.
-
-@item
-If you do not specify @var{startpitch} then middle C is used.
-
-@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
-}
-@end lilypond
-
-Octave changing marks are used for intervals greater than a fourth
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\relative c'' {
- c g c f, c' a, e''
-}
-@end lilypond
+@seealso
-If the preceding item is a chord, the first note of the chord is
-used to determine the first note of the next chord
+Snippets: @lsrdir{pitches}.
-@lilypond[quote,ragged-right,fragment,verbatim]
-\relative c' {
- c <c e g>
- <c' e g>
- <c, e' g>
-}
-@end lilypond
-The pitch after @code{\relative} contains a note name.
+@node Changing multiple pitches
+@subsection Changing multiple pitches
-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
-@code{\relative} must be placed inside @code{\transpose}.
+This section discusses how to modify pitches.
+@menu
+* Octave check::
+* Transpose::
+@end menu
@node Octave check
@unnumberedsubsubsec Octave check
-@cindex Octave check
+@cindex octave check
-Octave checks make octave errors easier to correct: a note may be
-followed by @code{=}@var{quotes} which indicates what its absolute
+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='' b=' d,='' @}
+\relative c'' @{ c g d='' @}
@end example
@noindent
-the @code{d} will generate a warning, because a @code{d''} is
-expected (because @code{b'} to @code{d''} is only a third), but a
-@code{d'} is found. 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'}.
+the@tie{}@code{d} will generate a warning, because
+a@tie{}@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@tie{}@code{d''} and the next note is calculated relative
+to@tie{}@code{d''} instead of@tie{}@code{d'}.
There is also an octave check that produces no visible output.
-The syntax
+The syntax is:
@example
-\octave @var{pitch}
+@var{pitch} \octave @var{controlpitch}
@end example
-This checks that @var{pitch} (without quotes) yields @var{pitch}
-(with quotes) in @code{\relative} mode compared to the note given
-in the @code{\relative} command. If not, a warning is printed,
-and the octave is corrected. The @var{pitch} is not printed as a
-note.
+@noindent
+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 a fifth of
-@code{a'}. However, the second check produces a warning, since
-the @code{e} is not within a fifth 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.
+since the@tie{}@code{e} (in @code{relative} mode) is within the
+octave range of@tie{}@code{a'}. However, the second check
+produces a warning, since the@tie{}@code{e} is not within the
+octave range of@tie{}@code{b'}. The warning message is printed,
+and the octave is adjusted so that the following notes are in the
+correct octave once again.
@example
\relative c' @{
@end example
-The octave of a note following an octave check is determined with
-respect to the note preceding it. In the next fragment, the last
-note is an @code{a'}, above middle C. That means that the
-@code{\octave} check passes successfully, so the check could be
-deleted without changing the output of the piece.
+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@tie{}@code{e'}, lies within the octave of@tie{}@code{b},
+and the @code{\octave} check passes successfully. The second note
+is then calculated relative to (absolute)@tie{}@code{e'}, which
+yields an@tie{}@code{a'}, above middle@tie{}C. In this case, the
+check had no influence on the output of the piece.
-@lilypond[quote,ragged-right,verbatim,fragment]
+The second @code{\octave} check fails: @code{a'}@tie{}is not
+within the range of@tie{}@code{b}. A warning is issued, and the
+last note is calculated relative to@tie{}@code{a}, not
+to@tie{}@code{a'}, and we get a@tie{}@code{d'}. Without the last
+@code{\octave} check, the last note would have been
+a@tie{}@code{d''}.
+
+@lilypond[verbatim,quote,ragged-right,fragment]
\relative c' {
e
\octave b
a
+ \octave b
+ d
}
@end lilypond
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
@node Transpose
@unnumberedsubsubsec Transpose
-@cindex Transpose
-@cindex Transposition of pitches
+@cindex transpose
+@cindex transposition of pitches
@funindex \transpose
A music expression can be transposed with @code{\transpose}. The
This means that @var{musicexpr} is transposed by the interval
between the pitches @var{from} and @var{to}: any note with pitch
-@code{from} is changed to @code{to}.
+@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
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 which sounds a minor third lower than notated), the
-following transposition will produce the appropriate part
+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
-@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
-second version will print flats
+@code{\transpose} will also transpose key signatures:
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
mus = { \key d \major cis d fis g }
\new Staff {
\clef "F" \mus
}
@end lilypond
+@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
+will remain on the same scale step, the second version will print
+flats on the scale step above.
+
+@lilypond[verbatim,quote,ragged-right]
+mus = { c d e f }
+\new Staff {
+ \transpose c cis { \relative c' \mus }
+ \transpose c des { \relative c' \mus }
+}
+@end lilypond
+
@code{\transpose} may also be used to input written notes for a
-transposing instrument. Pitches are normally entered into
-LilyPond in C (or @q{concert pitch}), but they may be entered in
-another key. For example, when entering music for a B-flat
-trumpet which begins on concert D, one would write
+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:
@example
-\transpose c bes @{ e4 @dots{} @}
+musicInBflat = @{ e4 @dots{} @}
+\transpose c bes \musicInBflat
@end example
-To print this music in B-flat again (i.e., producing a trumpet
-part, instead of a concert pitch conductor's score) you would wrap
-the existing music with another @code{transpose}
+To print this music in F (e.g., rearranging to a french horn) you
+would wrap the existing music with another @code{\transpose}
@example
-\transpose bes c @{ \transpose c bes @{ e4 @dots{} @} @}
+musicInBflat = @{ e4 @dots{} @}
+\transpose f c @{ \transpose c bes \musicInBflat @}
@end example
-
@seealso
-Program reference: @internalsref{TransposedMusic}.
-
-Example:
-@lsr{scheme,transpose-pitches-with-minimum-accidentals.ly}.
+Snippets: @lsrdir{pitches}, @lsr{scheme,
+transpose-pitches-with-minimum-accidentals.ly}.
+Internals reference: @internalsref{TransposedMusic}.
@refbugs
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}.
+a @code{\transpose}. See the previous example.
@node Displaying pitches
@subsection Displaying pitches
+This section discusses how to alter the output of pitches.
+
@menu
-* Clef::
-* Key signature::
-* Ottava brackets::
-* Instrument transpositions::
+* Clef::
+* Key signature::
+* Ottava brackets::
+* Instrument transpositions::
+* Automatic accidentals::
+* Ambitus::
@end menu
@node Clef
@funindex \clef
-The clef indicates which lines of the staff correspond to which
-pitches. The clef is set with the @code{\clef} command
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-{ c''2 \clef alto g'2 }
-@end lilypond
-
+@cindex G clef
+@cindex C clef
+@cindex F clef
@cindex treble clef
@cindex violin clef
@cindex alto clef
@cindex varbaritone clef
@cindex subbass clef
+The clef is set with the @code{\clef} @var{clefname}
+command:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+<<
+ \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"
+ }
+>>
+@end lilypond
+
+The clef can also be changed inside the staff:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
+\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
+ }
+>>
+@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@tie{}@code{g'} (@code{c'}, @code{f}) note is printed.
+
Supported clefs include
-@multitable @columnfractions .33 .66
+@multitable @columnfractions .4 .6
@headitem Clef @tab Position
-@item @code{treble}, violin, G, G2 @tab
-G clef on 2nd line
+@item @code{treble, violin, G, G2} @tab
+G clef (g') on 2nd line
@item @code{alto, C} @tab
-C clef on 3rd line
+C clef (c') on 3rd line
@item @code{tenor} @tab
-C clef on 4th line.
+C clef (c') on 4th line
@item @code{bass, F} @tab
-F clef on 4th line
+F clef (f) on 4th line
@item @code{french} @tab
-G clef on 1st line, so-called French violin clef
+G clef (g') on 1st line, so-called French violin clef
@item @code{soprano} @tab
-C clef on 1st line
+C clef (c') on 1st line
@item @code{mezzosoprano} @tab
-C clef on 2nd line
+C clef (c') on 2nd line
@item @code{baritone} @tab
-C clef on 5th line
+C clef (c') on 5th line
@item @code{varbaritone} @tab
-F clef on 3rd line
+F clef (f) on 3rd line
@item @code{subbass} @tab
-F clef on 5th line
+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}.
+
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}
For example,
@cindex choral tenor clef
-@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
\clef "G_8" c4
@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 any of these
-properties are changed. The following example shows possibilities
-when setting properties manually.
+@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[verbatim,quote,ragged-right]
+{
+ % 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]
+@lilypond[verbatim,quote,ragged-right]
{
\set Staff.clefGlyph = #"clefs.F"
\set Staff.clefPosition = #2
\set Staff.clefOctavation = #0
\set Staff.clefPosition = #0
c'4
- \clef "bass"
- c'4
\set Staff.middleCPosition = #4
c'4
}
@end lilypond
-
@seealso
-Program reference: @internalsref{Clef}.
+Notation Reference: @ref{Ancient clefs}.
+
+Snippets: @lsrdir{pitches}.
-This manual: @ref{Ancient clefs}.
+Internals reference: @internalsref{Clef}.
@node Key signature
@unnumberedsubsubsec 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@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
+command:
@example
-@code{\key} @var{pitch} @var{type}
+\key @var{pitch} @var{type}
@end example
@funindex \minor
@code{\mixolydian}, @code{\lydian}, @code{\phrygian}, and
@code{\dorian}.
-This command sets the context property @code{Staff.keySignature}.
-Non-standard key signatures can be specified by setting this
-property directly.
-
-Accidentals and key signatures often confuse new users, because
-unaltered notes get natural signs depending on the key signature.
-For more information, see @ref{Accidentals}, or
-@rlearning{Accidentals and key signatures}.
-
-@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\key g \major
f1
fis
@commonprop
A natural sign is printed to cancel any previous accidentals.
-This can be suppressed by setting the
-@code{Staff.printKeyCancellation} property.
+This may be altered:
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\key d \major
a b cis d
\key g \minor
a bes c d
@end lilypond
+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:
+
+@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 @code{,SHARP} @code{,FLAT}
+@code{,DOUBLE-SHARP} etc. (Note the leading comma.) Here is an
+example of a possible key signature for generating a whole-tone
+scale:
+
+@lilypond[verbatim,quote,ragged-right]
+\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
-Program reference: @internalsref{KeyCancellation},
-@internalsref{KeySignature}.
+Music Glossary: @rglos{church mode}, @rglos{scordatura}.
+
+Snippets: @lsrdir{pitches},
+FIXME link to snippet 248,
+FIXME link to a snippet about scordatura.
+
+Internals reference: @internalsref{KeyCancellation},
+@internalsref{KeySignature}, @internalsref{Key_engraver}.
@node Ottava brackets
@unnumberedsubsubsec Ottava brackets
-@q{Ottava} brackets introduce an extra transposition of an octave
-for the staff. They are created by invoking the function
-@code{set-octavation}
-
@cindex ottava
@cindex 15ma
+@cindex 8va
+@cindex 8ve
@cindex octavation
-@lilypond[quote,ragged-right,verbatim,fragment]
+@notation{Ottava brackets} introduce an extra transposition of an
+octave for the staff:
+
+@lilypond[verbatim,quote,ragged-right,fragment]
\relative c''' {
a2 b
#(set-octavation 1)
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{centralCPosition}. For overriding the text of the bracket,
-set @code{ottavation} after invoking @code{set-octavation}, i.e.,
+@code{middleCPosition}. To override the text of the bracket, set
+@code{ottavation} after invoking @code{set-octavation}, i.e.,
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
{
#(set-octavation 1)
\set Staff.ottavation = #"8"
@seealso
-Program reference: @internalsref{OttavaBracket}.
+Snippets: @lsrdir{pitches}.
+
+Internals reference: @internalsref{OttavaBracket}.
@refbugs
@cindex transposition, MIDI
@cindex transposition, instrument
-The key of a transposing instrument can also 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 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 after the keyword
-@code{\transposition}
+The transposition is entered with the command
@example
-\transposition bes %% B-flat clarinet
+\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.
-It does not affect how notes are printed in the current staff. To
-change the printed output, see @ref{Transpose}.
+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. For example, when entering
-a score in concert pitch, typically all voices are entered in C,
-so they should be entered as
+the real sound heard when a@tie{}@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
+parts have been entered using the notes and key as they appear in
+each part or the conductor's score:
+
+@lilypond[verbatim,quote,ragged-right]
+\new GrandStaff <<
+ \new Staff = "Violin I" {
+ \set Staff.instrumentName = "Vln"
+ \set Staff.midiInstrument="violin"
+ \key c \major
+ \transposition c
+ g'4( c''8) r c'' r c''4
+ }
+ \new Staff = "Clarinet" {
+ \set Staff.instrumentName = "Cl"
+ \set Staff.midiInstrument="clarinet"
+ \key d \major
+ \transposition bes
+ a'4( d''8) r d'' r d''4
+ }
+>>
+@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'}:
@example
clarinet = @{
@}
@end example
-The command @code{\transposition} should be used when the music is
-entered from a (transposed) orchestral part. For example, in
-classical horn parts, the tuning of the instrument is often
-changed during a piece. When copying the notes from the part, use
-@code{\transposition}, e.g.,
+@noindent
+to serve as a reminder that these parts are written in C.
+
+
+@seealso
+
+Notation Reference: @ref{Quoting other voices}, @ref{Transpose}.
+
+Snippets: @lsrdir{pitches}.
+
+
+@node Automatic accidentals
+@unnumberedsubsubsec Automatic accidentals
+@cindex automatic accidentals
+
+Common rules for typesetting accidentals have been placed in a
+function. This function is called as follows
+
+@funindex set-accidental-style
+
+@example
+\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
+
+If no context name is supplied, the accidental style applies to
+the @code{Staff} by default. Optionally, the function can take
+the context for which the style should be changed as a second
+argument:
+
+@example
+#(set-accidental-style 'STYLE #('CONTEXT))
+@end example
+
+The following accidental styles are supported. To demonstrate
+each style, we use the following example:
+
+@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
+
+@c don't use verbatim in this table.
+@table @code
+@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
+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 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 @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
+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.
+
+
+@lilypond[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" {
+ #(set-accidental-style 'voice)
+ \musicA
+ }
+ \context Staff = "down" {
+ #(set-accidental-style 'voice)
+ \musicB
+ }
+ >>
+}
+@end lilypond
+
+@item modern
+@funindex modern style accidentals
+
+This rule corresponds to the common practice in the twentieth
+century. It prints the same accidentals as @code{default}, with
+two exceptions which 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 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 modern-cautionary
+@funindex modern-cautionary
+
+This rule is similar to @code{modern}, but the @q{extra}
+accidentals (the ones not typeset by @code{default}) are typeset
+as cautionary accidentals. They are by default printed with
+parentheses, but they can also be printed in reduced size by
+defining the @code{cautionary-style} property of
+@code{AccidentalSuggestion}.
+
+
+@lilypond[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" {
+ #(set-accidental-style 'modern-cautionary)
+ \musicA
+ }
+ \context Staff = "down" {
+ #(set-accidental-style 'modern-cautionary)
+ \musicB
+ }
+ >>
+}
+@end lilypond
+
+@item modern-voice
+@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 @internalsref{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 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
+
+@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,
+some of them are typeset as cautionaries.
+
+@lilypond[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" {
+ #(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 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 accidental style takes place in a GrandStaff context.
+However, you have to explicitly set it for @emph{each} individual
+Staff of the GrandStaff:
+
@example
-\transposition d'
-c'4^"in D"
-...
-\transposition g'
-c'4^"in G"
-...
+\new GrandStaff @{ <<
+ \new Staff = "up" @{ <<
+ #(set-accidental-style 'piano)
+ @{ @dots{} @}
+ >> @}
+ \new Staff = "down" @{ <<
+ #(set-accidental-style 'piano)
+ @{ @dots{} @}
+ >> @}
+>> @}
@end example
+@lilypond[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" {
+ #(set-accidental-style 'piano)
+ \musicA
+ }
+ \context Staff = "down" {
+ #(set-accidental-style 'piano)
+ \musicB
+ }
+ >>
+}
+@end lilypond
+
+@item piano-cautionary
+@funindex #(set-accidental-style 'piano-cautionary)
+
+Same as @code{#(set-accidental-style 'piano)} but with the extra
+accidentals typeset as cautionaries.
+
+@lilypond[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" {
+ #(set-accidental-style 'piano-cautionary)
+ \musicA
+ }
+ \context Staff = "down" {
+ #(set-accidental-style 'piano-cautionary)
+ \musicB
+ }
+ >>
+}
+@end lilypond
+
+@item no-reset
+@funindex no-reset accidental style
+
+This is the same as @code{default} but with accidentals lasting
+@q{forever} and not only within the same measure:
+
+@lilypond[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" {
+ #(set-accidental-style 'no-reset)
+ \musicA
+ }
+ \context Staff = "down" {
+ #(set-accidental-style 'no-reset)
+ \musicB
+ }
+ >>
+}
+@end lilypond
+
+@item forget
+@funindex forget accidental style
+
+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 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
+
+
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
+Internals reference: @internalsref{Accidental_engraver},
+@internalsref{Accidental}, @internalsref{AccidentalSuggestion},
+@internalsref{AccidentalPlacement}, @internalsref{GrandStaff} and
+@internalsref{PianoStaff}.
+
+
+@refbugs
+
+Simultaneous notes are considered to be entered in sequential
+mode. This means that in a chord the accidentals are typeset as
+if the notes in the chord happen one at a time, in the order in
+which they appear in the input file. This is a problem when
+accidentals in a chord depend on each other, which does not happen
+for the default accidental style. The problem can be solved by
+manually inserting@tie{}@code{!} and@tie{}@code{?} for the
+problematic notes.
+
+
+@node Ambitus
+@unnumberedsubsubsec Ambitus
+@cindex ambitus
+
+The term @notation{ambitus} or @notation{ambit} 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.
+Ambits are printed on vocal parts, so performers can easily
+determine if it meets their capabilities.
+
+Ambits are denoted at the beginning of a piece near the initial
+clef. The range is graphically specified by two note heads that
+represent the minimum and maximum pitch. To print such ambits,
+add the @code{Ambitus_engraver} to the @code{Voice} context, for
+example:
+
+@lilypond[verbatim,quote,ragged-right]
+\layout {
+ \context {
+ \Staff
+ \consists Ambitus_engraver
+ }
+}
+
+\relative \new Staff {
+ as'' c e2 cis,2
+}
+@end lilypond
+
+If you have multiple voices in a single staff and you want a
+single ambitus per staff rather than per voice, add the
+@code{Ambitus_engraver} to the @code{Staff} context rather than to
+the @code{Voice} context:
+
+@lilypond[verbatim,quote,ragged-right]
+\new Staff \with {
+ \consists "Ambitus_engraver"
+}
+<<
+ \new Voice \with {
+ \remove "Ambitus_engraver"
+ } \relative c'' {
+ \override Ambitus #'X-offset = #-1.0
+ \voiceOne
+ c4 a d e f2
+ }
+ \new Voice \with {
+ \remove "Ambitus_engraver"
+ } \relative c' {
+ \voiceTwo
+ es4 f g as b2
+ }
+>>
+@end lilypond
+
+@noindent
+This example uses one advanced feature,
+
+@example
+\override Ambitus #'X-offset = #-1.0
+@end example
+
+@noindent
+This code moves the ambitus to the left. The same effect could
+have been achieved with @code{extra-offset}, but then the
+formatting system would not reserve space for the moved object.
+
+@seealso
+
+Snippets: @lsrdir{pitches},
+@lsr{vocal,ambitus@/.ly}.
+
+Internals reference: @internalsref{Ambitus},
+@internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
+@internalsref{AmbitusAccidental}, @internalsref{Ambitus_engraver},
+@internalsref{Staff} and @internalsref{Voice}.
+
+
+@refbugs
+
+There is no collision handling in the case of multiple per-voice
+ambitus.
+
+
+@node Note heads
+@subsection Note heads
+
+@menu
+* Easy notation note heads::
+* Shape note heads::
+* Improvisation::
+* Special noteheads::
+@end menu
+
+@node Easy notation note heads
+@unnumberedsubsubsec Easy notation note heads
+
+@cindex note heads, practice
+@cindex note heads, easy notation
+@cindex easy notation
+@cindex Hal Leonard
+
+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,fragment,staffsize=26]
+\setEasyHeads
+c'2 e'4 f' |
+g'1
+@end lilypond
+
+The command @code{\setEasyHeads} overrides settings for the
+@code{NoteHead} object. 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}.
+
+@refcommands
+
+@funindex \setEasyHeads
+@code{\setEasyHeads}
+
+@seealso
+
+Snippets: @lsrdir{pitches},
+
+Internals reference: @internalsref{NoteHead}.
+
+
+@node Shape note heads
+@unnumberedsubsubsec Shape note heads
+
+@cindex note heads, shape
+
+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,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.
+
+@funindex \key
+@funindex shapeNoteStyles
+@funindex \aikenHeads
+@funindex \sacredHarpHeads
+
+Shape note heads are implemented through the
+@code{shapeNoteStyles} property. Its value is a vector of
+symbols. The k-th element indicates the style to use for the k-th
+step of the scale. Arbitrary combinations are possible, e.g.:
+
+@lilypond[verbatim,fragment,relative=1]
+\set shapeNoteStyles =
+ ##(cross triangle fa #f mensural xcircle diamond)
+c8 d4. e8 a2 g1
+@end lilypond
+
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
+
+@node Improvisation
+@unnumberedsubsubsec Improvisation
+
+Improvisation is sometimes denoted with slashed note heads. Such
+note heads can be created by adding a @code{Pitch_squash_engraver}
+to the @code{Voice} context. Then, the following command
+
+@example
+\set squashedPosition = #0
+\override NoteHead #'style = #'slash
+@end example
+
+@noindent
+switches on the slashes.
+
+There are shortcuts @code{\improvisationOn} (and an accompanying
+@code{\improvisationOff}) for this command sequence. They are
+used in the following example:
+
+@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
+
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
+Internals reference: @internalsref{Pitch_squash_engraver} and
+@internalsref{Voice}.
+
+@node Special noteheads
+@unnumberedsubsubsec Special noteheads
+
+@cindex note heads, special
+
+Different noteheads 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 notehead 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 notehead styles, please see @ref{Note head styles}.
+
+
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
+Internals reference: @internalsref{NoteHead}.