@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
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}.
-
-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
+@code{\dorian}. See @rglos{church mode}.
@warning{The relationship between accidentals and key signatures can
be confusing to new users who think of the note letters as scale
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
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]
@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