@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
-Intro text.
+This section discusses how to input pitches.
@menu
-* Absolute octave entry::
-* Relative octave entry::
-* Accidentals::
-* Note names in other languages::
+* Absolute octave entry::
+* Relative octave entry::
+* Accidentals::
+* Note names in other languages::
@end menu
@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
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
+@cindex absolute
+@cindex absolute octave specification
-In absolute mode, every note is placed explicitly in a certain
+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
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 (@samp{'}) or comma (@samp{,}) characters. Each
-@samp{'} raises the pitch by one octave; each @samp{,} lowers the
-pitch by an octave.
+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
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
+Internals reference: @internalsref{LedgerLineSpanner},
+@internalsref{NoteHead}.
+
@node Relative octave entry
-@unnumberedsubsubsec Relative octaves entry
+@unnumberedsubsubsec Relative octave entry
-@cindex Relative
-@cindex Relative octave specification
+@cindex relative
+@cindex relative octave specification
@funindex \relative
The absolute mode requires a lot of octave specifications, which
not only becomes tedious but also easily leads to errors.
Therefore, it is usually more convenient to let notes be entered
relative to the previous note. This is done with the relative
-mode.
+mode.
@example
\relative @var{startpitch} @var{musicexpr}
that appear in @var{musicexpr} are calculated as follows:
@itemize
-@item
+@item
The pitch of the first note is relative to @code{\relative
-@var{startpitch} }.
+@var{startpitch} }.
@item
If no octave changing marks are used, the basic interval between a
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.
+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{''} will raise
-the pitch by two octaves.
+Multiple octave changing marks can be used. @code{''}@tie{}will
+raise the pitch by two octaves.
-@end itemize
+@end itemize
Here is the relative mode shown in action:
-@lilypond[quote,fragment,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment]
\relative c'' {
b c d c b c bes a
}
Octave changing marks are used for intervals greater than a
fourth:
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment]
\relative c'' {
c g c f, c' a, e''
}
A note sequence without a single octave mark can nevertheless span
large intervals:
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment]
\relative c {
c f b e a d g
}
used as the reference point for the octave placement of a
following note or chord:
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment]
\relative c' {
c <c e g>
- <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 @code{c} in various octave positions.
-
-When octaves are specified as above by adding @code{'} and
-@code{,} to pitch names, it is easy to accidentally put a pitch in
-the wrong octave. The relative octave mode prevents these errors
-since most of the time it is not necessary to indicate any octaves
-at all. Furthermore, in absolute mode, a single mistake may be
-difficult to spot; in relative mode, a single error puts the rest
-of the piece off by one octave.
+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{pitch}
+Snippets: @lsrdir{pitches}.
@refbugs
@code{\relative} must be placed inside @code{\transpose}.
@c DEPRECATED
-If no @var{startpitch} is specified for @code{\relative}, then
-@code{c'} is assumed. However, this is a deprecated option and
-may disappear in future versions, so its use is discouraged.
-
+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 @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}.
-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 @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
contracted to @code{as}, but both forms are accepted. Similarly,
both @code{es} and @code{ees} are accepted:
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a2 as e es
@end lilypond
syntax with a suffix; a natural pitch is shown as a simple note
name:
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a4 aes a2
@end lilypond
-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
-concerning for how long an accidental is considered to last. For
-more information, see @ref{Automatic accidentals}.
+Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
+@rglos{double flat}.
-For @emph{musica ficta}, editorial accidentals placed above the
-staff commonly used in editions of early music, see @ref{Musica
-ficta accidentals}.
+Notation Reference: @ref{Automatic accidentals},
+@ref{Musica ficta accidentals}.
-Program reference: @internalsref{LedgerLineSpanner},
-@internalsref{NoteHead}.
+Snippets: @lsrdir{pitches}.
@refbugs
@headitem Language
@tab Note names
@tab sharp @tab flat @tab double sharp @tab double flat
-@item netherlands.ly
+@item nederlands.ly
@tab c d e f g a bes b
@tab -is @tab -es @tab -isis @tab -eses
@item english.ly
- @tab c d e f g a bf b
+ @tab c d e f g a bf b
@tab -s/-sharp @tab -f/-flat @tab -ss/-x/-sharpsharp
@tab -ff/-flatflat
@item deutsch.ly
- @tab c d e f g a b h
+ @tab c d e f g a b h
@tab -is @tab -es @tab -isis @tab -eses
@item norsk.ly
- @tab c d e f g a b h
+ @tab c d e f g a b h
@tab -iss/-is @tab -ess/-es @tab -ississ/-isis
@tab -essess/-eses
@item svenska.ly
- @tab c d e f g a b h
+ @tab c d e f g a b h
@tab -iss @tab -ess @tab -ississ @tab -essess
+@item suomi.ly
+ @tab c d e f g a b h
+ @tab -is @tab -es @tab -isis @tab -eses
@item italiano.ly
- @tab do re mi fa sol la sib si
+ @tab do re mi fa sol la sib si
@tab -d @tab -b @tab -dd @tab -bb
@item catalan.ly
- @tab do re mi fa sol la sib si
+ @tab do re mi fa sol la sib si
@tab -d/-s @tab -b @tab -dd/-ss @tab -bb
@item espanol.ly
- @tab do re mi fa sol la sib si
+ @tab do re mi fa sol la sib si
@tab -s @tab -b @tab -ss @tab -bb
+@item portugues.ly
+ @tab do re mi fa sol la sib si
+ @tab -s @tab -b @tab -ss @tab -bb
+@item vlaams.ly
+ @tab do re mi fa sol la sib si
+ @tab -k @tab -b @tab -kk @tab -bb
@end multitable
@end example
@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 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{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 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.
+@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
@multitable @columnfractions .2 .6 .05 .05 .05 .05
@tab semi- @tab semi- @tab sesqui- @tab sesqui-
@item nederlands.ly
- @tab c d e f g a bes b
+ @tab c d e f g a bes b
@tab -ih @tab -eh @tab -isih @tab -eseh
@item english.ly
- @tab c d e f g a bf b
+ @tab c d e f g a bf b
@tab -qs @tab -qf @tab -tqs @tab -tqf
@item deutsch.ly
- @tab c d e f g a b h
+ @tab c d e f g a b h
@tab -ih @tab -eh @tab -isih @tab -eseh
@c @item norsk.ly
-@c @tab c d e f g a b h
+@c @tab c d e f g a b h
@c @item svenska.ly
-@c @tab c d e f g a b h
+@c @tab c d e f g a b h
@item italiano.ly
- @tab do re mi fa sol la sib si
+ @tab do re mi fa sol la sib si
@tab -sd @tab -sb @tab -dsd @tab -bsb
-@c @item catalan.ly
-@c @tab do re mi fa sol la sib si
-@c @item espanol.ly
-@c @tab do re mi fa sol la sib si
+@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
+@seealso
+
+Snippets: @lsrdir{pitches}.
+
+
@node Changing multiple pitches
@subsection Changing multiple pitches
+This section discusses how to modify pitches.
+
@menu
-* Octave check::
-* Transpose::
+* 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} and any other note is
-transposed by the same interval.
+@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
+C, and thus sounds a minor third lower than notated), the
following transposition will produce the appropriate part:
@example
@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
will remain on the same scale step, the second version will print
flats on the scale step above.
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
mus = { c d e f }
\new Staff {
\transpose c cis { \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 is set with the @code{\clef} command
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-{ \clef treble g'1^G \clef alto c'1^C \clef bass f1^F }
-@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 same clef symbols are used in different positions on
-the staff to change the range of notes shown by that staff.
-The treble (alto, bass) clef is always positioned to show
-the line on which a G (C, F) note is shown.
-
+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 .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
-@lilypond[quote,ragged-right,verbatim]
+and some which do not:
+
+@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.
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. See @internalsref{Key_engraver}, and for an
-example TODO.
-@c TODO: LSR snippet 248. leave this here for now -gp
-
-@warning{The relationship between accidentals and key signatures can
-be confusing to new users who think of the note letters as scale
-steps and not as absolute pitches. The note names that are
-entered in a music expression are the raw material; key signatures
-and clefs decide how this raw material is displayed. Thus,
-unaltered notes may get natural signs depending on the key
-signature. For more information, see @ref{Accidentals} and
-@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}. To override the text of the bracket, set
+@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
+\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
-\transposition d'
-c'4^"in D"
-...
-\transposition g'
-c'4^"in G"
-...
+\override Ambitus #'X-offset = #-1.0
@end example
-TODO: also mention that it affects cue voices. Or make a link.
-Or something.
+@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}.
projects / lilypond.git / blobdiff