@node Writing pitches
@subsection Writing pitches
-Into text.
+Intro text.
@menu
-* Normal pitches::
+* 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 pitches
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 certain
+octave. The note names @code{c} to @code{b} are engraved in the
+octave below middle C, as in the previous example.
@lilypond[quote,fragment,verbatim,ragged-right]
\clef treble
@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 (@samp{'}) or comma (@samp{,}) characters. Each
+@samp{'} raises the pitch by one octave; each @samp{,} lowers the
+pitch by an octave.
@lilypond[quote,ragged-right,fragment,verbatim]
\clef treble
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}.
+
+@node Relative octave entry
+@unnumberedsubsubsec Relative octaves 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 @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.
+
+@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
+
+A note sequence without a single octave mark can nevertheless span
+large intervals:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\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[quote,ragged-right,fragment,verbatim]
+\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 @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.
@seealso
Snippets: @lsrdir{pitch}
+@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
+@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
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
+Dutch. To use other names for accidentals, see @ref{Note names
in other languages}.
@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
@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]
a2 as e es
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]
a4 aes a2
@seealso
-The automatic production of accidentals can be tuned in many ways.
-For more information, see @ref{Automatic accidentals}.
+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}.
+
+For @emph{musica ficta}, editorial accidentals placed above the
+staff commonly used in editions of early music, see @ref{Musica
+ficta accidentals}.
Program reference: @internalsref{LedgerLineSpanner},
@internalsref{NoteHead}.
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
@item netherlands.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 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
@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
@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{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.
+
@c What about Turkish Maquam music and similar microtonal systems?
@c
@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
+@multitable @columnfractions .2 .6 .05 .05 .05 .05
+@headitem Language
+ @tab Note names
+ @tab semi- @tab semi- @tab sesqui- @tab sesqui-
+
+@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
+@end multitable
@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
-
-@example
-\relative @var{startpitch} @var{musicexpr}
-@end example
-
-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} }.
-
-@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
-
-If the preceding item is a chord, the first note of the chord is
-used to determine the first note of the next chord
-
-@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.
-
-@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
-@code{c'} is assumed. However, this is a deprecated option and
-may disappear in future versions, so its use is discouraged.
-
-
@node Octave check
@unnumberedsubsubsec Octave check
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}.
+@code{from} is changed to @code{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
+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]
mus = { \key d \major cis d fis g }
}
@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[quote,ragged-right,verbatim]
+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
+LilyPond in C (or @notation{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
@example
\transpose c bes @{ e4 @dots{} @}
@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[quote,ragged-right,fragment,verbatim]
+<<
+ \new Staff {
+ % treble clef by default
+ c'1^"middle C"
+ }
+ \new Staff {
+ \clef alto
+ c'1^"middle C"
+ }
+ \new Staff {
+ \clef bass
+ f1^"middle C"
+ }
+>>
+@end lilypond
+
+The clef can also be changed inside the staff:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new PianoStaff <<
+ \new Staff {
+ \time 2/4
+ \clef treble
+ r16
+ \clef bass
+ e g c' e' e g c'
+ }
+ \new Staff {
+ \clef bass
+ c,8 r \clef treble g''4
+ }
+>>
+@end lilypond
+
+These same clef symbols are used in different positions on
+the staff to change the range of notes shown by that staff.
+The treble (alto, bass) clef is always positioned to show
+the line on which a g' (c', f) note is printed.
+
Supported clefs include
-@multitable @columnfractions .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]
\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[quote,ragged-right,verbatim]
+{
+ % The default treble clef
+ c'4
+ % The standard bass clef
+ \set Staff.clefGlyph = #"clefs.F"
+ \set Staff.clefPosition = #2
+ \set Staff.middleCPosition = #6
+ c'4
+ % The baritone clef
+ \set Staff.clefGlyph = #"clefs.C"
+ \set Staff.clefPosition = #4
+ \set Staff.middleCPosition = #4
+ c'4
+ % The standard choral tenor clef
+ \set Staff.clefGlyph = #"clefs.G"
+ \set Staff.clefPosition = #-2
+ \set Staff.clefOctavation = #-7
+ \set Staff.middleCPosition = #1
+ c'4
+ % A non-standard clef
+ \set Staff.clefPosition = #0
+ \set Staff.clefOctavation = #0
+ \set Staff.middleCPosition = #-4
+ c'4
+}
+@end lilypond
+
+and some which do not:
@lilypond[quote,ragged-right,verbatim]
{
\set Staff.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}.
-
-This manual: @ref{Ancient clefs}.
+User manual: @ref{Ancient clefs}.
+Program reference: @internalsref{Clef}.
@node Key signature
@unnumberedsubsubsec Key signature
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}
also use the standard mode names (also called @q{church modes}):
@code{\ionian}, @code{\locrian}, @code{\aeolian},
@code{\mixolydian}, @code{\lydian}, @code{\phrygian}, and
-@code{\dorian}.
+@code{\dorian}. See @rglos{church mode}.
-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}.
+@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]
\key g \major
fis
@end lilypond
-
@commonprop
A natural sign is printed to cancel any previous accidentals.
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
+@code{\set Staff.keySignature} =
+#'((@var{octave} . @var{step}) . @var{alter})
+where @var{octave} specifies the octave (0 being the octave
+from middle C to the B above), @var{step} specifies the note
+within the octave (0 means C and 6 means B), and @var{alter}
+is ,SHARP ,FLAT ,DOUBLE-SHARP etc. (Note the leading comma.)
+Here is an example of a possible key
+signature for generating a whole-tone scale:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'
+ \new Staff {
+ \set Staff.keySignature =
+ #`(((0 . 3) . ,SHARP) ((0 . 5) . ,FLAT) ((0 . 6) . ,FLAT))
+ c d e fis aes bes c
+}
+@end lilypond
@seealso
+@c Link to snippet 248
+Another example of using @code{keySignature} can be found in
+@lsrdir{scordatura}
+
Program reference: @internalsref{KeyCancellation},
-@internalsref{KeySignature}.
+@internalsref{KeySignature}, @internalsref{Key_engraver}
@node Ottava brackets
@cindex ottava
@cindex 15ma
+@cindex 8va
+@cindex 8ve
@cindex octavation
@lilypond[quote,ragged-right,verbatim,fragment]
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]
{
@cindex transposition, MIDI
@cindex transposition, instrument
-The key of a transposing instrument can also be specified. This
+The key of a 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
+@code{\transposition} @var{pitch} where @var{pitch} specifies
+the key in which the instrument plays:
@example
\transposition bes %% B-flat clarinet
@noindent
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.
+See @ref{Quoting other voices}.
+The value does not affect how notes are printed in the
+current staff; to change the printed output, see @ref{Transpose}.
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
+played by the transposing instrument. The command
+@code{\transposition} @var{pitch} 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[quote,ragged-right,verbatim]
+\score {
+ \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
+ }
+ >>
+ \layout { }
+ \midi { }
+}
+@end lilypond
+
+Without the @code{\transposition} command the midi output of this
+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.
+
-@example
-\transposition d'
-c'4^"in D"
-...
-\transposition g'
-c'4^"in G"
-...
-@end example