@node Fundamental concepts
@chapter Fundamental concepts
+You've seen in the Tutorial how to produce beautifully printed
+music from a simple text file. This section introduces the
+concepts and techniques required to produce equally beautiful
+but more complex scores.
@menu
* How LilyPond files work::
@menu
* Introduction to the LilyPond file structure::
* Score is a (single) compound musical expression::
-* Nesting Music Expressions::
+* Nesting music expressions::
* On the un-nestedness of brackets and ties::
@end menu
There are many variations of this basic pattern, but this
example serves as a useful starting place.
-At this point, you may be confused, since you have never seen a
-@code{\score@{@}} before. This is because LilyPond automatically
-adds the extra commands when you give it simple input. LilyPond
-treats input like this:
+Up to this point none of the examples you have seen have used a
+@code{\score@{@}} command. This is because LilyPond automatically
+adds the extra commands which are needed when you give it simple
+input. LilyPond treats input like this:
@example
\relative c'' @{
as shorthand for this:
@example
-\score @{
- \relative c'' @{
- c4 a b c
+\book @{
+ \score @{
+ \new Staff @{
+ \new Voice @{
+ \relative c'' @{
+ c4 a b c
+ @}
+ @}
+ @}
+ \layout @{ @}
@}
- \layout @{ @}
@}
@end example
In other words, if the input contains a single music expression,
LilyPond will interpret the file as though the music expression
-was wrapped up inside a @code{\score@{@}}.
-
-@smallspace
+was wrapped up inside the commands shown above. For now, though,
+let us return to the first example and examine the @code{\score}
+command, leaving the others to default.
-A @code{\score} must begin with a compound music expression.
+A @code{\score} block must always contain just one music
+expression, and
+this must appear first within the @code{\score @{..@}} block.
Remember that a music expression could be anything from a single
-note to a huge
+note to a huge compound expression like
@example
@{
Some people put some of those commands outside the @code{\score}
block -- for example, @code{\header} is often placed above the
@code{\score}. That's just another shorthand that LilyPond
-accepts. Two more commands you have not previously seen are
+accepts.
+
+Two more commands you have not previously seen are
@code{\layout @{ @}} and @code{\midi @{@}}. If these appear as
shown they will cause LilyPond to produce a printed output and a
-MIDI out respectively. They are described fully in the
-Notation Reference - @ruser{Score layout} and
-@ruser{Creating MIDI files}.
+MIDI output respectively. They are described fully in the
+Notation Reference -- @ruser{Score layout} and
+@ruser{Creating MIDI files}.
-@smallspace
+The @code{\book} command allows
+several @code{\score} blocks to be combined into one output.
+If there are several @code{\book} blocks each one produces a
+separate output file. For details see @ruser{Multiple scores
+in a book}.
@cindex variables
When LilyPond looks at this file, it takes the value of
@code{melody} (everything after the equals sign) and inserts it
whenever it sees @code{\melody}. There's nothing special about
-the names -- it could be @code{melody}, @code{global},
-@code{pianorighthand}, or @code{foofoobarbaz}. You can use
-whatever variable names you want as along as they contain just
-alphabetic characters. For more details, see
-@ruser{Saving typing with variables and functions}.
+the names -- it could be @code{melody}, @code{global},
+@code{TimeKey},
+@code{pianorighthand}, or @code{foofoobarbaz}. For more details,
+see @ref{Saving typing with variables and functions}.
+Remember that you can use almost any name you like as long
+as it contains just alphabetic characters and is distinct from
+LilyPond command names. The exact
+limitations on variable names are detailed in
+@ruser{File structure}.
+
@seealso
@}
@end example
-@noindent
-Remember that you can use almost any name you like as long
-as it contains just alphabetic characters. The exact
-limitations on variable names are detailed in
-@ruser{File structure}.
-
Be careful about the difference between notes, which are introduced
with @code{\relative}, and lyrics, which are introduced with
@code{\lyricmode}. These are essential to tell LilyPond
on the same horizontal position in your text editor.
-@node Nesting Music Expressions
-@subsection Nesting Music Expressions
+@node Nesting music expressions
+@subsection Nesting music expressions
It is not essential to declare all staves at the beginning;
they may be introduced temporarily at any point. This is
}
@end lilypond
+@noindent
+Note that the size of the clef is the same as a clef printed
+following a clef change -- slightly smaller than the clef
+at the begining of the line. This is usual for clefs printed
+in the middle of a line.
+
The ossia section may be placed above the staff
as follows:
Ossia are often written without clef and without
time signature and are usually in a smaller font.
These require further commands which
-have not yet been introduced. See ...
-
-TODO Add ref to tweaks section where this example should
-be placed and explained.
+have not yet been introduced. See @ref{Size of objects}
@node On the un-nestedness of brackets and ties
@subsection On the un-nestedness of brackets and ties
which can be confusing at first. Before we explain the rules
let's first review the different types of bracket.
-@multitable @columnfractions .3 .7
+@c attempt to force this onto a new page
+@need 50
+@multitable @columnfractions .3 .7
@headitem Bracket Type
@tab Function
@item @code{@{ .. @}}
@item @code{< .. >}
@tab Encloses the notes of a chord
@item @code{<< .. >>}
- @tab Encloses concurrent or simultaneous sections
+ @tab Encloses concurrent or simultaneous sections
@item @code{( .. )}
@tab Marks the start and end of a slur
@item @code{\( .. \)}
tuplets written as @code{\times x/y @{..@}}, and grace notes
written as @code{\grace@{..@}}.
-Outside LilyPond, the conventional use of brackets requires
-the different types to be properly nested, like this,
+Outside LilyPond, the conventional use of brackets requires
+the different types to be properly nested, like this,
@code{<< [ @{ ( .. ) @} ] >>}, with the closing brackets being
-encountered in exactly the opposite order to the opening
-brackets. This @strong{is} a requirement for the three types of
-bracket described by the word @q{Encloses} in the table above -
+encountered in exactly the opposite order to the opening
+brackets. This @strong{is} a requirement for the three types of
+bracket described by the word @q{Encloses} in the table above --
they must nest properly.
-However, the remaining brackets, described with the word
+However, the remaining brackets, described with the word
@q{Marks} in the table above together with ties and tuplets,
do @strong{not} have to nest
-properly with any of the brackets. In fact, these are not
+properly with any of the brackets. In fact, these are not
brackets in the sense that
-they enclose something - they are simply markers to indicate
+they enclose something -- they are simply markers to indicate
where something starts and ends.
So, for example, a phrasing slur can start before a manually
-inserted beam and end before the end of the beam - not very
+inserted beam and end before the end of the beam -- not very
musical, perhaps, but possible:
@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
Singers need voices to sing, and so does LilyPond.
The actual music for all instruments in a score
-is contained in Voices - the most fundamental
+is contained in Voices -- the most fundamental
of all LilyPond's concepts.
@menu
In fact, a Voice layer or context is the only one which can
contain music. If a Voice context is not explicitly declared
-one is created automatically. Some instruments such as an
+one is created automatically, as we saw at the beginning of
+this chapter. Some instruments such as an
Oboe can play only one note at a time. Music written for
such instruments is monophonic and requires just a single
voice. Instruments which can play more than one note at a
as sequential notes, as they must start at the same time.
This section of the bar requires three voices, and the
normal practice would be to write the whole bar as three
-voices, as shown here, where we have used different noteheads
+voices, as shown here, where we have used different note heads
and colors for the three voices.
@c The following should appear as music without code
<< { a2. r4 } \\ { fis2. s4 } >>
@end lilypond
+It is not necessary to use a separate @code{<< \\ >>} construct
+for each bar. For music with few notes in each bar this layout
+can help the legibility of the code, but if there are many
+notes in each bar it may be better to split out each voice
+separately, like this:
+
+@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+\key d \minor
+<< {
+ % Voice "1"
+ r4 g g4. a8 |
+ bes4 bes c bes |
+ a2. r4 |
+} \\ {
+ % Voice "2"
+ d,2 d4 g |
+ g4 g g8( a) g4 |
+ fis2. s4 |
+} >>
+@end lilypond
+
+
This example has just two voices, but the same contruct may be
used to encode three or more voices by adding more back-slash
separators.
parallel voices from separate simultaneous constructs on the same
staff are the same voice. Other voice-related properties also
carry across simultaneous constructs. Here is the same example,
-with different colors and noteheads for each voice. Note that
+with different colors and note heads for each voice. Note that
changes in one Voice do not affect other voices, but they do
persist in the same Voice later. Note also that tied notes may be
split across the same voices in two constructs, shown here in the
@lilypond[quote,verbatim]
\new Staff \relative c' {
- \voiceOneStyle
+ % Main voice
c16 d e f
<< % Bar 1
- { g4 f e } \\
- { \voiceTwoStyle
- r8 e4 d c8 ~ }
- >> |
+ {
+ \voiceOneStyle
+ g4 f e
+ }
+ \\
+ {
+ \voiceTwoStyle
+ r8 e4 d c8 ~
+ }
+ >>
<< % Bar 2
- { d2 e2 } \\
- { c8 b16 a b8 g ~ g2 } \\
- { \voiceThreeStyle
- s4 b4 c2 }
+ { d2 e2 } % Voice 1 continues
+ \\
+ { c8 b16 a b8 g ~ g2 } % Voice 2 continues
+ \\
+ {
+ \voiceThreeStyle
+ s4 b4 c2
+ }
>>
}
@end lilypond
The commands @code{\voiceXXXStyle} are mainly intended for use in
educational documents such as this one. They modify the color
-of the notehead, the stem and the beams, and the style of the
-notehead, so that the voices may be easily distinguished.
+of the note head, the stem and the beams, and the style of the
+ note head, so that the voices may be easily distinguished.
Voice one is set to red diamonds, voice two to blue triangles,
voice three to green crossed circles, and voice four (not used
here) to magenta crosses. We shall see later how commands like
-these may be created by the user.
-TODO: add ref to appropriate section in Tweaks
+these may be created by the user.
+See @ref{Visibility and color of objects}
+TODO Add link to using variables for tweaks
Polyphony does not change the relationship of notes within a
@code{\relative @{ @}} block. Each note is still calculated
\key aes \major
<<
{ c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
- >> |
- <c ees aes c>1 |
+ >>
+ <c ees aes c>1
}
@end lilypond
by telling LilyPond that this third voice is really a fourth
voice, with stems going down, using the @code{\voiceFour}
command. There are also corresponding @code{\voiceOne},
-@code{\voiceTwo}, and @code{voiceThree}
+@code{\voiceTwo}, and @code{\voiceThree}
commands. This results in the following:
@lilypond[quote,verbatim,fragment,ragged-right]
@noindent
and exposes a problem commonly encountered with multiple
-voices: the stems of notes can collide with noteheads
+voices: the stems of notes can collide with note heads
in other voices. In laying out the notes, LilyPond allows the
notes or chords from two voices to occupy the same vertical
note column provided the stems are in opposite directions, but
notes of the third voice are clearly not well placed by default.
LilyPond provides several ways to adjust the horizontal placing
of notes. We are not quite ready yet to see how to correct this,
-so we shall leave this problem until a later section (see ... )
-
-TODO link.
+so we shall leave this problem until a later section
+(see @ref{Fixing overlapping notation} )
@node Explicitly instantiating voices
@subsection Explicitly instantiating voices
Voice contexts can also be created manually
inside a @code{<< >>} block to create polyphonic music, using
@code{\voiceOne} ... @code{\voiceFour} to indicate the required
-directions of stems, slurs, etc.
+directions of stems, slurs, etc. In longer scores this method
+is clearer, as it permits the voices to be separated and to be
+given more descriptive names.
Specifically, the construct @code{<< \\ >>} which we used in
the previous section:
@example
-<< \upper \\ \lower >>
+\new Staff @{
+ \relative c' @{
+ << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
+ @}
+@}
@end example
@noindent
-where @code{upper} and @code{lower} are user-defined variables
-containing the music for the two voices, is equivalent to
+is equivalent to
@example
-<<
- \new Voice = "1" @{ \voiceOne \upper @}
- \new Voice = "2" @{ \voiceTwo \lower @}
+\new Staff <<
+ \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
+ \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
>>
@end example
+Both of the above would produce
+
+@c The following example should not display the code
+FIXME: weird compiling bug! Leave for gp.
+@c @lilypond{ragged-right,quote]
+@c \relative c' {
+@c % << { e4 f g a } \\ { c,4 d e f } >>
+@c }
+@c @end lilypond
+
The @code{\voiceXXX} commands set the direction of stems, slurs,
ties, articulations, text annotations, augmentation dots of dotted
notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
markup, ties, slurs, and dynamics:
@lilypond[quote,ragged-right,verbatim]
-\relative c'{
- c-"default" d8 ~ d e4 ( f g a ) b-> c
+\relative c'{
+ % Default behaviour or behaviour after \oneVoice
+ c d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
@lilypond[quote,ragged-right,verbatim]
\relative c'{
\voiceOne
- c-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c
+ c d8 ~ d e4 ( f g a ) b-> c
\oneVoice
- c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
+ c, d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
@lilypond[quote,ragged-right,verbatim]
\relative c'{
\voiceTwo
- c-"\\voiceTwo" d8 ~ d e4 ( f g a ) b-> c
+ c d8 ~ d e4 ( f g a ) b-> c
\oneVoice
- c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
+ c, d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
An expression that appears directly inside a @code{<< >>} belongs
to the main voice (but, note, @strong{not} in a @code{<< \\ >>}
-contruct). This is useful when extra voices appear while the main
-voice is playing. Here is a more correct rendition of the example
-from the previous section. The red diamond-shaped notes
+construct). This is useful when extra voices appear while the
+main voice is playing. Here is a more correct rendition of the
+example from the previous section. The red diamond-shaped notes
demonstrate that the main melody is now in a single voice context,
permitting a phrasing slur to be drawn over them.
@lilypond[quote,ragged-right,verbatim]
\new Staff \relative c' {
\voiceOneStyle
- c16^( d e f % These notes are monophonic
- << % Start simultaneous section of three voices
- { g4 f e | d2 e2) } % Continue the main voice in parallel
- \new Voice { % Initiate second voice
- \voiceTwo % Set stems, etc, down
+ % The following notes are monophonic
+ c16^( d e f
+ % Start simultaneous section of three voices
+ <<
+ % Continue the main voice in parallel
+ { g4 f e | d2 e2) }
+ % Initiate second voice
+ \new Voice {
+ % Set stems, etc, down
+ \voiceTwo
r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
}
- \new Voice { % Initiate third voice
- \voiceThree % Set stems, etc, up
- s2. | s4 b4 c2
+ % Initiate third voice
+ \new Voice {
+ % Set stems, etc, up
+ \voiceThree
+ s2. | s4 b4 c2
}
>>
}
r8 e4 d c8 ~ |
<<
{c8 b16 a b8 g ~ g2}
- \new Voice {
+ \new Voice {
\voiceThree
s4 b4 c2
}
@end lilypond
-This method of nesting new voices briefly is useful
+This method of nesting new voices briefly is useful
when only small sections of the music
are polyphonic, but when the whole staff is largely polyphonic
-it can be clearer to use multiple voices throughout, using
-spacing notes to step over sections where the voice is silent,
+it can be clearer to use multiple voices throughout, using
+spacing notes to step over sections where the voice is silent,
as here:
@lilypond[quote,ragged-right,verbatim]
\new Staff \relative c' <<
- \new Voice { % Initiate first voice
+ % Initiate first voice
+ \new Voice {
\voiceOne
c16^( d e f g4 f e | d2 e2) |
}
- \new Voice { % Initiate second voice
- \voiceTwo % set stems, etc down
+ % Initiate second voice
+ \new Voice {
+ % set stems, etc down
+ \voiceTwo
s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
}
- \new Voice { % Initiate third voice
- \voiceThree % set stems, etc up
+ % Initiate third voice
+ \new Voice {
+ % set stems, etc up
+ \voiceThree
s1 | s4 b4 c2 |
}
>>
@end lilypond
+@cindex note column
+@cindex shift commands
+@funindex \shiftOff
+@funindex \shiftOn
+@funindex \shiftOnn
+@funindex \shiftOnnn
+
+Closely spaced notes in a chord, or notes occuring at the same
+time in different voices, are arranged in two, occasionally more,
+columns to prevent the note heads overlapping. These are called
+note columns. There are separate columns for each voice, and
+the currently specified voice-dependent shift is applied to the
+note column if there would otherwise be a collision. This can
+be seen in the example above. In bar 2 the C in voice two is
+shifted to the right relative to the D in voice one, and in the
+final chord the C in voice three is also shifted to the right
+relative to the other notes.
+
+The @code{\shiftOn}, @code{\shiftOnn}, @code{\shiftOnnn}, and
+@code{\shiftOff} commands specify the degree to which notes and
+chords of the voice should be shifted if a collision
+would otherwise occur. By default, the outer voices (normally
+voices one and two) have @code{\shiftOff} specified, while the
+inner voices (three and four) have @code{\shiftOn} specified.
+When a shift is applied, Voices one and three are shifted to
+the right and voices two and four to the left.
+
+@code{\shiftOnn} and @code{\shiftOnnn} define further shift
+levels which may be specified temporarily to resolve collisions
+in complex situations -- see @ref{Real music example}.
+
+A note column can contain just one note (or chord) from a voice
+with stems up and one note (or chord) from a voice with stems
+down. If notes from two voices which have their stems in the
+same direction are placed at the same position and both voices
+have no shift or the same shift specified, the error message
+@qq{Too many clashing note columns} will be produced.
@node Voices and vocals
@subsection Voices and vocals
Vocal music presents a special difficulty: we need to combine two
expressions -- notes and lyrics.
-You have already seen the @code{\addlyricsd@{@}} command, which
+You have already seen the @code{\addlyrics@{@}} command, which
handles simple scores well. However, this technique is
quite limited. For more complex music, you must introduce the
lyrics in a @code{Lyrics} context using @code{\new Lyrics} and
explicitly link
-the lyrics to the notes with @code{\lyricsto@{@}}, using the
+the lyrics to the notes with @code{\lyricsto@{@}}, using the
name assigned to the Voice.
@lilypond[quote,verbatim,fragment]
parts are the same.
@lilypond[quote,verbatim]
-global = { \time 4/4 \partial 4 \key c \major}
+TimeKey = { \time 4/4 \partial 4 \key c \major}
SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
\new ChoirStaff <<
\new Staff <<
\clef "treble"
- \new Voice = "Sop" { \voiceOne \global \SopMusic }
+ \new Voice = "Sop" { \voiceOne \TimeKey \SopMusic }
\new Voice = "Alto" { \voiceTwo \AltoMusic }
\new Lyrics \lyricsto "Sop" { \VerseOne }
\new Lyrics \lyricsto "Sop" { \VerseTwo }
@menu
* Contexts explained::
* Creating contexts::
-* Engravers::
-* Modifying contexts::
+* Engravers explained::
+* Modifying context properties::
+* Adding and removing engravers::
@end menu
@node Contexts explained
the entire score.
Within LilyPond, these rules and bits of information are grouped
-in @emph{Contexts}. We have already met the @context{Voice}
-context.
-Others are the @context{Staff} and @context{Score} contexts.
+in @emph{Contexts}. We have already met the
+@code{Voice} context.
+Others are the @code{Staff} and @code{Score} contexts.
Contexts are hierarchical to reflect the heirarchical nature of
a musical score.
-For example: a @context{Staff} context can contain many
-@context{Voice} contexts, and a @context{Score} context can
-contain many @context{Staff} contexts.
+For example: a @code{Staff} context can contain many
+@code{Voice} contexts, and a @code{Score} context can
+contain many @code{Staff} contexts.
@quotation
@image{context-example,5cm,,}
Each context has the responsibility for enforcing some notation rules,
creating some notation objects and maintaining the associated
-properties. For example, the @context{Voice} context may introduce an
-accidental and then the @context{Staff} context maintains the rule to
+properties. For example, the @code{Voice} context may introduce an
+accidental and then the @code{Staff} context maintains the rule to
show or suppress the accidental for the remainder of the measure.
As another example, the synchronization of bar lines is, by default,
-handled in the @context{Score} context.
+handled in the @code{Score} context.
However, in some music we may not want the bar lines to be
synchronized -- consider a polymetric score in 4/4 and 3/4 time.
In such cases, we must modify the default settings of the
-@context{Score} and @context{Staff} contexts.
+@code{Score} and @code{Staff} contexts.
For very simple scores, contexts are created implicitly, and you need
not be aware of them. For larger pieces, such as anything with more
with specialized notation, it is usual to modify existing, or
even to define totally new, contexts.
-In addition to the @context{Score,} @context{Staff} and
-@context{Voice} contexts there are contexts which fit between
+In addition to the @code{Score,} @code{Staff} and
+@code{Voice} contexts there are contexts which fit between
the score and staff levels to control staff groups, such as the
-@context{PianoStaff} and @context{ChoirStaff} contexts. There
+@code{PianoStaff} and @code{ChoirStaff} contexts. There
are also alternative staff and voice contexts, and contexts for
lyrics, percussion, fret boards, figured bass, etc. A complete
list is shown in the Notation Reference.
The names of all context types are formed from one or more
words, each word being capitalised and joined immediately to the
preceding word with no hyphen or underscore, e.g.,
-@context{GregorianTranscriptionStaff}.
+@code{GregorianTranscriptionStaff}.
@node Creating contexts
@subsection Creating contexts
-There can be only one top level context: the @context{Score}
+There can be only one top level context: the
+@code{Score}
context. This is created with the @code{\score} command,
or, in simple scores, it is created automatically.
For scores with only one voice and one staff, the
-@context{Voice} and @context{Staff} contexts may be left to be
+@code{Voice} and @code{Staff} contexts may be left to be
created automatically, but for more complex scores it is
necessary to create them by hand.
The simplest command that does this is @code{\new}.
@cindex Context, creating
@example
-\new @var{type} @var{music expression}
+\new @var{type} @var{music-expression}
@end example
@noindent
where @var{type} is a context name (like @code{Staff} or
@code{Voice}). This command creates a new context, and starts
-interpreting the @var{music expression} within that context.
+interpreting the @var{music-expression} within that context.
-Note that there is no @code{\new Score % Invalid!} command;
-the single top-level @context{Score} context is introduced
-with @code{\score}. This is because there can be only one
-@context{Score} context, whereas there may be multiple
-@context{Staff} and @context{Voice} contexts - each created
-by @code{\new}.
+Note that there is no @code{\new Score} command;
+the single top-level @code{Score} context is introduced
+with @code{\score}.
The @code{\new} command may also give a identifying name to the
context to distinguish it from other contexts of the same type,
@example
-\new @var{type} = @var{id} @var{music}
+\new @var{type} = @var{id} @var{music-expression}
@end example
Note the distinction between the name of the context type,
-@context{Staff}, @context{Voice}, etc, and
+@code{Staff}, @code{Voice}, etc, and
the identifying name of a particular instance of that type,
which can be any sequence of letters invented by the user.
The identifying name is used to refer back to that particular
lyrics in @ref{Voices and vocals}.
-@node Engravers
-@subsection Engravers
+@node Engravers explained
+@subsection Engravers explained
+
+@cindex engravers
Every mark on the printed output of a score produced by LilyPond
is produced by an @code{Engraver}. Thus there is an engraver
-to print staves, one to print noteheads, one for stems, one for
+to print staves, one to print note heads, one for stems, one for
beams, etc, etc. In total there are over 120 such engravers!
Fortunately, for most scores it is not necessary to know about
more than a few, and for simple scores you do not need to know
Engravers live and operate in Contexts.
Engravers such as the @code{Metronome_mark_engraver}, whose
action and output applies to the score as a whole, operate in
-the highest level context - the @context{Score} context.
+the highest level context -- the @code{Score} context.
The @code{Clef_engraver} and @code{Key_engraver} are to be
found in every Staff Context, as different staves may require
different clefs and keys.
The @code{Note_heads_engraver} and @code{Stem_engraver} live
-in each @context{Voice} context, the lowest level context of all.
+in every @code{Voice} context, the lowest level context of all.
Each engraver processes the particular objects associated
with its function, and maintains the properties that relate
@item Metronome_mark_engraver
@tab Engraves metronome marking
@item Note_heads_engraver
- @tab Engraves noteheads
+ @tab Engraves note heads
@item Rest_engraver
@tab Engraves rests
@item Staff_symbol_engraver
@tab Engraves the five (by default) lines of the staff
@item Stem_engraver
@tab Creates stems and single-stem tremulos
+@item Time_signature_engraver
+ @tab Creates time signatures
@end multitable
@smallspace
by modifying the action of Engravers.
-@node Modifying contexts
-@subsection Modifying contexts
-
-@menu
-* Changing context properties::
-@end menu
-
-@node Changing context properties
-@subsubsection Changing context properties
+@node Modifying context properties
+@subsection Modifying context properties
@cindex context properties
@funindex \set
@code{\set} command. This takes the form
@example
-\set @emph{ContextName}.@emph{propertyName} = @emph{value}
+\set @emph{ContextName}.@emph{propertyName} = #@emph{value}
@end example
-Where the @emph{ContextName} is usually @context{Score},
-@context{Staff} or @context{Voice}. It may be omitted,
-in which case @context{Voice} is assumed.
+Where the @emph{ContextName} is usually @code{Score},
+@code{Staff} or @code{Voice}. It may be omitted,
+in which case @code{Voice} is assumed.
The names of context properties consist of words joined
together with no hyphens or underscores, all except the
first having a capital letter. Here are a few examples
of some commonly used ones. There are many more.
-@multitable @columnfractions .3 .2 .5
+@c attempt to force this onto a new page
+@need 50
+@multitable @columnfractions .25 .15 .45 .15
@headitem propertyName
- @tab Value
+ @tab Type
@tab Function
+ @tab Example Value
@item extraNatural
- @tab ##t or ##f
- @tab If true (##t), set extra natural sign before accidentals
+ @tab Boolean
+ @tab If true, set extra natural signs before accidentals
+ @tab @code{#t}, @code{#f}
@item currentBarNumber
@tab Integer
@tab Set the current bar number
+ @tab @code{50}
@item doubleSlurs
- @tab ##t or ##f
- @tab If true (##t), print slurs both above and below notes
+ @tab Boolean
+ @tab If true, print slurs both above and below notes
+ @tab @code{#t}, @code{#f}
@item instrumentName
@tab Text
@tab Set the name to be placed at the start of the staff
+ @tab @code{"Cello I"}
@item fontSize
- @tab Number
+ @tab Real
@tab Increase or decrease the font size
+ @tab @code{2.4}
@item stanza
@tab Text
@tab Set the text to print before the start of a verse
+ @tab @code{"2"}
@end multitable
-
+
+@noindent
+where a Boolean is either True (@code{#t}) or False (@code{#f}),
+an Integer is a positive whole number, a Real is a positive
+or negative decimal number, and text is enclosed in double
+apostrophes. Note the occurrence of hash signs,
+(@code{#}), in two different places -- as part of the Boolean
+value before the @code{t} or @code{f}, and before @emph{value}
+in the @code{\set} statement. So when a Boolean is being
+entered you need to code two hash signs, e.g., @code{##t}.
+
Before we can set any of these properties we need to know
-which context they operate in. Sometimes this is obvious,
+in which context they operate. Sometimes this is obvious,
but occasionally it can be tricky. If the wrong context
is specified, no error message is produced, but the expected
-action will not be taken. For example, the
+action will not take place. For example, the
@code{instrumentName} clearly lives in the Staff context, since
-it is the staff that is named.
-In this example the first staff is labelled, but the second,
-Alto, staff is not, because we omitted the context name.
+it is the staff that is to be named.
+In this example the first staff is labelled, but not the second,
+because we omitted the context name.
@lilypond[quote,verbatim,ragged-right]
<<
c4 c
}
\new Staff \relative c' {
- \set instrumentName = "Alto"
+ \set instrumentName = "Alto" % Wrong!
d4 d
}
>>
@end lilypond
Remember the default context name is Voice, so the second
-@code{\set} command set the property @emph{instrumentName} in the
+@code{\set} command set the property @code{instrumentName} in the
Voice context to @qq{Alto}, but as LilyPond does not look
-for any such property in the @context{Voice} context, no
-further action took place. No error message is logged in
-the log file.
+for any such property in the @code{Voice} context, no
+further action took place. This is not an error, and no error
+message is logged in the log file.
Similarly, if the property name is mis-spelt no error message
-is produced, and the expected action clearly is not performed.
+is produced, and clearly the expected action cannot be performed.
If fact, you can set any (fictitious) @q{property} using any
name you like in any context that exists by using the
@code{\set} command. But if the name is not
known to LilyPond it will not cause any action to be taken.
+This is one of the reasons why it is highly recommended to
+use a context-sensitive editor with syntax highlighting for
+editing LilyPond files, such as Vim, Jedit, ConTEXT or Emacs,
+since unknown property names will be highlighted differently.
The @code{instrumentName} property will take effect only
-if it is set in the @context{Staff} context, but
+if it is set in the @code{Staff} context, but
some properties can be set in more than one context.
For example, the property @code{extraNatural} is by
default set to ##t (true) for all staves.
-If it is set to ##f (false) in the @context{Staff} context
+If it is set to ##f (false) in the @code{Staff} context
it applies just to the accidentals on that staff.
-If it is set to false in the @context{Score} context
+If it is set to false in the @code{Score} context
it applies to all staves.
-So this sets @code{extraNatural} in one staff:
+So this turns off extra naturals in one staff:
@lilypond[quote,verbatim,ragged-right]
<<
@end lilypond
@noindent
-and this sets it in all staves:
+and this turns them off in all staves:
@lilypond[quote,verbatim,ragged-right]
<<
@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
c4
-\set fontSize = #-4 % make noteheads smaller
+% make note heads smaller
+\set fontSize = #-4
d e
-\set fontSize = #2.5 % make noteheads larger
+% make note heads larger
+\set fontSize = #2.5
f g
-\unset fontSize % return to original size
+% return to original size
+\unset fontSize
a b
@end lilypond
@end lilypond
In effect this overrides the default value of the property. It
-may still be changed dynamically using @code{\set} and
-@code{\unset}.
+may still be changed dynamically using @code{\set} and returned
+to its (new) default value with @code{\unset}.
+@node Adding and removing engravers
+@subsection Adding and removing engravers
@cindex Engravers, adding
@cindex Engravers, removing
We have seen that contexts each contain several engravers, each
of which is responsible for producing a particular part of the
-output, like barlines, staves, note heads, stems, etc. If an
+output, like bar lines, staves, note heads, stems, etc. If an
engraver is removed from a context it can no longer produce its
output. This is a crude way of modifying the output, but it
can sometimes be useful.
}
\relative c' {
c4
- \set fontSize = #-4 % make noteheads smaller
+ \set fontSize = #-4 % make note heads smaller
d e
- \set fontSize = #2.5 % make noteheads larger
+ \set fontSize = #2.5 % make note heads larger
f g
\unset fontSize % return to original size
a b
staff to indicate the range of notes in that staff.
The ambitus is produced by the @code{Ambitus_engraver},
which is not normally included in any context. If
-we add it to the @context{Voice} context it calculates
+we add it to the @code{Voice} context it calculates
the range from that voice only:
@lilypond[quote,verbatim,ragged-right]
@noindent
but if we add the Ambitus engraver to the
-@context{Staff} context it calculates the range from all
+@code{Staff} context it calculates the range from all
the notes in all the voices on that staff:
@lilypond[quote,verbatim,ragged-right]
But what
if you want something that isn't covered there? Read on.
+TODO Add links to templates after they have been moved to LSR
+
@menu
* Soprano and cello::
* Four-part SATB vocal score::
None of the templates provides this layout exactly. The
nearest is @q{SATB vocal score and automatic piano reduction},
-but we shall need to change the layout and add a piano
+but we need to change the layout and add a piano
accompaniment which is not derived automatically from the
vocal parts. The variables holding the music and words for
the vocal parts are fine, but we shall need to add variables for
score shown above. We need to rearrange them so there are
four staves with the words written directly underneath the
notes for each part.
-All the voices should be @code{voiceOne}, which is
-the default, so the @code{\voiceXXX} commands can be removed.
+All the voices should be @code{\voiceOne}, which is
+the default, so the @code{\voiceXXX} commands should be removed.
We also need to specify the tenor clef for the tenors.
-The way in which lyrics are specified has also been simplified
-as we have not yet encountered the method used in the template.
-We've also added the names of each staff.
+The way in which lyrics are specified in the template has not yet
+been encountered so we need to use the method with which we are
+familiar. We should also add the names of each staff.
Doing this gives for our ChoirStaff:
We'll use the first two bars of Bach's prelude
based on @emph{Jesu, meine Freude} which is written for two
-manuals and pedal organ. The top manual part has two voices,
+manuals and pedal organ. You can see these two bars of music
+at the bottom of this section. The top manual part has two voices,
the lower and pedal organ one each. So we need four
music definitions and one to define the time signature
and key:
>>
@end example
-It is not strictly necessary to use the simultaneous contruct
+It is not strictly necessary to use the simultaneous construct
@code{<< >>} for the manual two staff and the pedal organ staff,
since they contain only one music expression, but it does no harm
and always using angle brackets after @code{\new Staff} is a good
@end lilypond
+
projects / lilypond.git / blobdiff