@node Fundamental concepts
@chapter Fundamental concepts
+
@menu
* How LilyPond files work::
* Voices contain music::
-* TODO new sec fundamental::
+* Contexts and engravers::
+* Extending the templates::
@end menu
The LilyPond input format is quite free-form, giving experienced
users a lot of flexibility to structure their files however they
-wish. However, this flexibility can make things confusing for new
+wish. But this flexibility can make things confusing for new
users. This section will explain some of this structure, but may
gloss over some details in favor of simplicity. For a complete
description of the input format, see @ruser{File structure}.
@menu
* Introduction to the LilyPond file structure::
-* Score is a single musical expression::
+* Score is a (single) compound musical expression::
+* Nesting Music Expressions::
+* On the un-nestedness of brackets and ties::
@end menu
@node Introduction to the LilyPond file structure
@example
\version "2.11.23"
\score @{
- @{@var{...music expression...}@} % all the music goes here!
+ @var{...compound music expression...} % all the music goes here!
\header @{ @}
\layout @{ @}
\midi @{ @}
@smallspace
-A @code{\score} must begin with a single music
-expression. Remember that a music expression could
-be anything from a single note to a huge
+A @code{\score} must begin with a compound music expression.
+Remember that a music expression could be anything from a single
+note to a huge
@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.
+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}.
@smallspace
@cindex variables
-@cindex identifiers
-Another great shorthand is the ability to define identifiers. All
+Another great shorthand is the ability to define variables. All
the templates use this
@example
@}
\score @{
- @{ \melody @}
+ \melody
@}
@end example
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. For more details, see
-@ruser{Saving typing with identifiers and functions}.
+whatever variable names you want as along as they contain just
+alphabetic characters. For more details, see
+@ruser{Saving typing with variables and functions}.
@seealso
-For a complete definition of the input format, see @ruser{File
-structure}.
+For a complete definition of the input format, see
+@ruser{File structure}.
+@node Score is a (single) compound musical expression
+@subsection Score is a (single) compound musical expression
-@node Score is a single musical expression
-@subsection Score is a single musical expression
+@cindex Compound music expression
+@cindex Music expression, compound
We saw the general organization of LilyPond input files in the
previous section, @ref{How LilyPond files work}. But we seemed to
there @emph{is} no mystery. This line explains it all:
@quotation
-@emph{A @code{\score} must begin with a single music expression.}
+@emph{A @code{\score} must begin with a compound music expression.}
@end quotation
@noindent
-You may find it useful to review @ruser{Music expressions
-explained}. In that section, we saw how to build big music
-expressions from small pieces -- we started from notes, then
-chords, etc. Now we're going to start from a big music expression
-and work our way down.
+You may find it useful to review
+@ref{Music expressions explained}. In that section, we saw how to
+build big music expressions from small pieces -- we started from
+notes, then chords, etc. Now we're going to start from a big
+music expression and work our way down.
@example
\score @{
- @{ % this brace begins the overall music expression
+ @{ % this brace begins the overall compound music expression
\new GrandStaff <<
@var{...insert the whole score of a Wagner opera in here...}
>>
- @} % this brace ends the overall music expression
+ @} % this brace ends the overall compound music expression
\layout @{ @}
@}
@end example
A whole Wagner opera would easily double the length of this
manual, so let's just add a singer and piano. We don't need a
-@code{GrandStaff} for this ensemble, so we shall remove it. We
-@emph{do} need a singer and a piano, though.
+@code{GrandStaff} for this ensemble, which simply groups a number
+of staves together with a brace at the left, so we shall remove
+it. We @emph{do} need a singer and a piano, though.
@example
\score @{
Remember that we use @code{<<} and @code{>>} to show simultaneous
music. And we definitely want to show the vocal part and piano
-part at the same time, not one after the other!
+part at the same time, not one after the other! However, the
+@code{<< .. >>} construct is not really necessary for the Singer
+staff, as it contains only one music expression, but Staves often
+do require simultaneous Voices within them, so using @code{<< .. >>}
+rather than braces is a good habit to adopt.
@example
\score @{
<<
\new Staff = "singer" <<
\new Voice = "vocal" @{ @}
+ \addlyrics @{ @}
>>
- \new Lyrics \lyricsto vocal \new Lyrics @{ @}
\new PianoStaff = "piano" <<
\new Staff = "upper" @{ @}
\new Staff = "lower" @{ @}
But if we did that, the @code{\score} section would get pretty
long, and it would be harder to understand what was happening. So
-let's use identifiers (or variables) instead.
+let's use variables instead.
@example
-melody = @{ @}
-text = @{ @}
-upper = @{ @}
-lower = @{ @}
+melody = \relative c'' @{ @}
+text = \lyricmode @{ @}
+upper = \relative c'' @{ @}
+lower = \relative c @{ @}
\score @{
@{
<<
\new Staff = "singer" <<
\new Voice = "vocal" @{ \melody @}
+ \addlyrics @{ \text @}
>>
- \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
\new PianoStaff = "piano" <<
\new Staff = "upper" @{ \upper @}
\new Staff = "lower" @{ \lower @}
@end example
@noindent
-Remember that you can use almost any name you like. The
-limitations on identifier names are detailed in @ruser{File
-structure}.
+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
+to interpret the following content as music and text
+respectively.
When writing (or reading) a @code{\score} section, just take it
slowly and carefully. Start with the outer layer, then work on
on the same horizontal position in your text editor.
+@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
+particularly useful for creating ossia sections
+(see @rglos{ossia}). Here is a simple example showing how
+to introduce a new staff temporarily for the duration of
+three notes:
+
+@lilypond[verbatim,quote,ragged-right]
+\new Staff {
+ \relative g' {
+ r4 g8 g c4 c8 d |
+ e4 r8
+ <<
+ { f c c }
+ \new Staff {
+ f8 f c
+ }
+ >>
+ r4 |
+ }
+}
+@end lilypond
+
+The ossia section may be placed above the staff
+as follows:
+
+@lilypond[verbatim,quote,ragged-right]
+\new Staff ="main" {
+ \relative g' {
+ r4 g8 g c4 c8 d |
+ e4 r8
+ <<
+ { f c c }
+ \new Staff \with {
+ alignAboveContext = "main" }
+ { f8 f c }
+ >>
+ r4 |
+ }
+}
+@end lilypond
+
+This example uses @code{\with}, which will be explained more
+fully later. It is a means of modifying the default behaviour
+of a Staff. Here it says that the new staff should be placed
+above the staff called @qq{main} instead of the default position
+which is below.
+
+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.
+
+@node On the un-nestedness of brackets and ties
+@subsection On the un-nestedness of brackets and ties
+
+You have already met a number of different types of bracket in
+writing the input file to LilyPond. These obey different rules
+which can be confusing at first. Before we explain the rules
+let's first review the different types of bracket.
+
+@multitable @columnfractions .3 .7
+@headitem Bracket Type
+ @tab Function
+@item @code{@{ .. @}}
+ @tab Encloses a sequential segment of music
+@item @code{< .. >}
+ @tab Encloses the notes of a chord
+@item @code{<< .. >>}
+ @tab Encloses concurrent or simultaneous sections
+@item @code{( .. )}
+ @tab Marks the start and end of a slur
+@item @code{\( .. \)}
+ @tab Marks the start and end of a phrase mark
+@item @code{[ .. ]}
+ @tab Marks the start and end of a manual beam
+@end multitable
+
+To these we should add other constructs which generate lines
+between or across notes: ties (marked by a tilde, @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,
+@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 -
+they must nest properly.
+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
+brackets in the sense that
+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
+musical, perhaps, but possible:
+
+@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+ { g8\( a b[ c b\) a] }
+@end lilypond
+
+In general, different kinds of brackets, and those implied by
+tuplets, ties and grace notes, may be mixed freely.
+This example shows a beam extending into a tuplet (line 1),
+a slur extending into a tuplet (line 2),
+a beam and a slur extending into a tuplet, a tie crossing
+two tuplets, and a phrasing slur extending out of a tuplet
+(lines 3 and 4).
+
+@lilypond[quote,verbatim,fragment,ragged-right]
+{
+ r16[ g16 \times 2/3 {r16 e'8] }
+ g16( a \times 2/3 {b d) e' }
+ g8[( a \times 2/3 {b d') e'~]}
+ \times 4/5 {e'32\( a b d' e'} a'4.\)
+}
+@end lilypond
+
+
@node Voices contain music
@section Voices contain music
-TODO: something cheesy and vaguely witty about voices being the
-fundamental thing that includes music in lilypond.
+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
+of all LilyPond's concepts.
@menu
-* I'm seeing Voices::
+* I'm hearing Voices::
* Explicitly instantiating voices::
* Voices and vocals::
@end menu
-@c too cheesy? I'm not certain. -gp
-@node I'm seeing Voices
-@subsection I'm seeing Voices
+@node I'm hearing Voices
+@subsection I'm hearing Voices
@cindex polyphony
+@cindex layers
+@cindex Voice context
+
+The lowest, most fundamental or innermost layers in a LilyPond
+score are called @q{Voice contexts} or just @q{Voices} for short.
+Voices are sometimes called @q{layers} in other notation
+packages.
+
+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
+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
+time like the piano will often require multiple voices to
+encode the different concurrent notes and rhythms they are
+capable of playing.
+
+A single voice can contain many notes in a chord, of course,
+so when exactly are multiple voices needed?
+Let us analyse a short piece of music to see how many voices
+are required. Here are the notes from the first two bars
+of the second of Chopin's Deux Nocturnes, Op 32.
+
+@c The following should appear as music without code
+@lilypond[quote,ragged-right]
+\new Staff \relative c'' {
+ \key aes \major
+ <<
+ { \voiceOne
+ c2 aes4. bes8 } \\
+ { \voiceTwo
+ aes2 f4 fes } \\
+ { \voiceFour
+ \once \override NoteColumn #'force-hshift = #0 <ees c>2
+ \once \override NoteColumn #'force-hshift = #0.5 des2 }
+ >> |
+ <c ees aes c>1 |
+}
+@end lilypond
-TODO: add intro about voices vs. layers vs. whatever.
-
-TODO: sex this up with colors and stuff. -gp
+The direction of the stems is often used to indicate the
+continuity of two simultaneous melodic lines. Here the
+stems of the highest notes are all pointing up and the
+stems of the lower notes are all pointing down.
+This is the first indication that more than one voice
+is required.
+
+But the real need for multiple voices arises when notes
+which start at the same time have different durations.
+Look at the notes which start at beat three in the first
+bar. The a-flat is a dotted quarter note, the f is a
+quarter note and the d-flat is a half note. These
+cannot be written as a chord as all the notes in a chord
+must have the same duration. Neither can they be written
+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
+and colors for the three voices.
+
+@c The following should appear as music without code
+@c The three voice styles should be defined in -init
+@lilypond[quote,ragged-right]
+\new Staff \relative c'' {
+ \key aes \major
+ <<
+ { \voiceOne
+ \voiceOneStyle
+ c2 aes4. bes8 } \\
+ { \voiceTwo
+ \voiceTwoStyle
+ aes2 f4 fes } \\
+ { \voiceFour
+ \voiceThreeStyle
+ \once \override NoteColumn #'force-hshift = #0 <ees c>2
+ \once \override NoteColumn #'force-hshift = #0.5 des2 }
+ >> |
+ <c ees aes c>1 |
+}
+@end lilypond
-TODO: actually, a general rewrite is needed. -gp
+Let us see how this is done.
+@funindex \\
The easiest way to enter fragments with more than one voice on a
staff is to enter each voice as a sequence (with @code{@{...@}}),
-and combine them simultaneously, separating the voices with
-@code{\\}
+and combine them simultaneously with angle brackets, @code{<<...>>}.
+The fragments must also be separated with double backward slashes,
+@code{\\}, to place them in separate voices. Without these, the
+notes would be entered into a single voice, which would usually
+cause errors. This technique is particularly suited to pieces of
+music which are largely monophonic with occasional short sections
+of polyphony. Here's a simple example:
+
+@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+\key d \minor
+% Voice "1" Voice "2"
+<< { r4 g g4. a8 } \\ { d,2 d4 g } >> |
+<< { bes4 bes c bes } \\ { g4 g g8( a) g4 } >> |
+<< { a2. r4 } \\ { fis2. s4 } >>
+@end lilypond
-@funindex \\
+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.
+
+The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
+In each of these contexts, the vertical direction of slurs,
+stems, ties, dynamics etc., is set appropriately.
@lilypond[quote,verbatim,fragment]
\new Staff \relative c' {
+ % Main voice
c16 d e f
- <<
- { g4 f e | d2 e2 } \\
- { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
- { s2. | s4 b4 c2 }
- >>
+ % Voice "1" Voice "2" Voice "3"
+ << { g4 f e } \\ { r8 e4 d c8 ~ } >> |
+ << { d2 e2 } \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 c2 } >> |
}
@end lilypond
-@cindex layers
-
-The separator causes @internalsref{Voice}
-contexts@footnote{Polyphonic voices are sometimes
-called @q{layers} in other notation packages} to be instantiated.
-They bear the names @code{"1"}, @code{"2"}, etc. In each of these
-contexts, vertical direction of slurs, stems, etc., is set
-appropriately.
-
-These voices are all separate from the voice that contains the
-notes just outside the @code{<< \\ >>} construct. This should be
-noted when making changes at the voice level. This also means
-that slurs and ties cannot go into or out of a @code{<< \\ >>}
-construct. Conversely, parallel voices from separate @code{<< \\
->>} constructs on the same staff are the same voice. Here is the
-same example, with different noteheads and colors for each voice.
-Note that the change to the note-head style in the main voice does
-not affect the inside of the @code{<< \\ >>} constructs. Also,
-the change to the second voice in the first @code{<< \\ >>}
-construct is effective in the second @code{<< \\ >>}, and the
-voice is tied across the two constructs.
-
-@cindex note heads, styles
-
-@lilypond[quote,verbatim,fragment]
+These voices are all separate from the main voice that contains
+the notes just outside the @code{<< .. >>} construct. Let's call
+this the @emph{simultaneous construct}. Slurs and ties may only
+connect notes within the same voice, so slurs and ties cannot go
+into or out of a simultaneous construct. Conversely,
+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
+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
+blue triangle voice.
+
+@lilypond[quote,verbatim]
\new Staff \relative c' {
- \override NoteHead #'style = #'cross
- \override NoteHead #'color = #red
+ \voiceOneStyle
c16 d e f
- <<
+ << % Bar 1
{ g4 f e } \\
- { \override NoteHead #'style = #'triangle
- \override NoteHead #'color = #blue
- r8 e4 d c8 ~ }
+ { \voiceTwoStyle
+ r8 e4 d c8 ~ }
>> |
- <<
+ << % Bar 2
{ d2 e2 } \\
{ c8 b16 a b8 g ~ g2 } \\
- { \override NoteHead #'style = #'slash
- \override NoteHead #'color = #green
+ { \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.
+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
+
Polyphony does not change the relationship of notes within a
-@code{\relative @{ @}} block. Each note is calculated relative to
-the note immediately preceding it.
+@code{\relative @{ @}} block. Each note is still calculated
+relative to the note immediately preceding it, or to the first
+note of the preceding chord. So in
@example
-\relative @{ noteA << noteB \\ noteC >> noteD @}
+\relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
@end example
-@code{noteC} is relative to @code{noteB}, not @code{noteA};
-@code{noteD} is relative to @code{noteC}, not @code{noteB} or
-@code{noteA}.
+@noindent
+@code{noteB} is relative to @code{noteA} @*
+@code{noteC} is relative to @code{noteB}, not @code{noteA}; @*
+@code{noteD} is relative to @code{noteB}, not @code{noteA} or
+@code{noteC}. @*
+@code{noteE} is relative to @code{noteD}, not @code{noteA}
+
+We are now in a position to return to the first example from
+the Chopin Nocturne to see how this might be encoded. As we
+shall see, this encounters some difficulties. We begin as
+we have learnt, using the @code{<< \\ >>} construct to
+enter the music of the first bar in three voices:
+@lilypond[quote,verbatim,fragment,ragged-right]
+\new Staff \relative c'' {
+ \key aes \major
+ <<
+ { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
+ >> |
+ <c ees aes c>1 |
+}
+@end lilypond
+
+@cindex stem down
+@cindex stem up
+@funindex \voiceOne
+@funindex \voiceTwo
+@funindex \voiceThree
+@funindex \voiceFour
+
+The stem directions are automatically assigned with the
+odd-numbered voices taking upward stems and the even-numbered
+voices downward ones. The stems for voices 1 and 2 are right,
+but the stems in voice 3 should go down in this particular piece
+of music. We can correct this
+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}
+commands. This results in the following:
+
+@lilypond[quote,verbatim,fragment,ragged-right]
+\new Staff \relative c'' {
+ \key aes \major
+ <<
+ { c2 aes4. bes8 } \\
+ { aes2 f4 fes } \\
+ { \voiceFour <ees c>2 des2 }
+ >> |
+ <c ees aes c>1 |
+}
+@end lilypond
+
+@noindent
+and exposes a problem commonly encountered with multiple
+voices: the stems of notes can collide with noteheads
+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
+the notes from a third voice are displaced to avoid the stems
+colliding. This often works well, but in this example the
+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.
@node Explicitly instantiating voices
@subsection Explicitly instantiating voices
-TODO: more colors and stuff.
-
-@internalsref{Voice} contexts can also be instantiated manually
+Voice contexts can also be created manually
inside a @code{<< >>} block to create polyphonic music, using
-@code{\voiceOne}, up to @code{\voiceFour} to assign stem
-directions and a horizontal shift for each part.
+@code{\voiceOne} ... @code{\voiceFour} to indicate the required
+directions of stems, slurs, etc.
+
+Specifically, the construct @code{<< \\ >>} which we used in
+the previous section:
-Specifically,
@example
<< \upper \\ \lower >>
@end example
@noindent
-is equivalent to
+where @code{upper} and @code{lower} are user-defined variables
+containing the music for the two voices, is equivalent to
@example
<<
ties, articulations, text annotations, augmentation dots of dotted
notes, and fingerings. @code{\voiceOne} and @code{\voiceThree}
make these objects point upwards, while @code{\voiceTwo} and
-@code{\voiceFour} make them point downwards. The command
-@code{\oneVoice} will revert back to the normal setting.
+@code{\voiceFour} make them point downwards. These commands also
+generate a horizontal shift for each voice when this is required
+to avoid clashes of note heads. The command @code{\oneVoice}
+reverts the settings back to the normal values for a single voice.
-An expression that appears directly inside a @code{<< >>} belongs
-to the main voice. 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 crossed colored
-noteheads demonstrate that the main melody is now in a single
-voice context.
+Let us see in some simple examples exactly what effect
+@code{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
+markup, ties, slurs, and dynamics:
@lilypond[quote,ragged-right,verbatim]
-\new Staff \relative c' {
- \override NoteHead #'style = #'cross
- \override NoteHead #'color = #red
- c16 d e f
+\relative c'{
+ c-"default" d8 ~ d e4 ( f g a ) b-> c
+}
+@end lilypond
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'{
\voiceOne
- <<
- { g4 f e | d2 e2 }
- \new Voice="1" { \voiceTwo
- r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
- \oneVoice
- }
- \new Voice { \voiceThree
- s2. | s4 b4 c2
- \oneVoice
- }
- >>
+ c-"\\voiceOne" d8 ~ d e4 ( f g a ) b-> c
+ \oneVoice
+ c,-"\\oneVoice" 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
\oneVoice
+ c,-"\\oneVoice" d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
-The correct definition of the voices allows the melody to be
-slurred.
+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
+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' {
- c16^( d e f
- \voiceOne
- <<
- { g4 f e | d2 e2) }
- \context Voice="1" { \voiceTwo
+ \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
r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
- \oneVoice
}
- \new Voice { \voiceThree
- s2. s4 b4 c2
- \oneVoice
+ \new Voice { % Initiate third voice
+ \voiceThree % Set stems, etc, up
+ s2. | s4 b4 c2
}
>>
- \oneVoice
}
@end lilypond
-Avoiding the @code{\\} separator also allows nesting polyphony
-constructs, which in some case might be a more natural way to
+@cindex nesting music expressions
+@cindex nesting simultaneous constructs
+
+More deeply nested polyphony constructs are possible, and if a
+voice appears only briefly this might be a more natural way to
typeset the music.
@lilypond[quote,ragged-right,verbatim]
\new Staff \relative c' {
c16^( d e f
- \voiceOne
<<
{ g4 f e | d2 e2) }
- \context Voice="1" { \voiceTwo
+ \new Voice {
+ \voiceTwo
r8 e4 d c8 ~ |
<<
{c8 b16 a b8 g ~ g2}
- \new Voice { \voiceThree
+ \new Voice {
+ \voiceThree
s4 b4 c2
- \oneVoice
}
>>
- \oneVoice
}
>>
- \oneVoice
}
@end lilypond
+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,
+as here:
+
+@lilypond[quote,ragged-right,verbatim]
+\new Staff \relative c' <<
+ \new Voice { % Initiate first voice
+ \voiceOne
+ c16^( d e f g4 f e | d2 e2) |
+ }
+ \new Voice { % Initiate second voice
+ \voiceTwo % set stems, etc down
+ s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
+ }
+ \new Voice { % Initiate third voice
+ \voiceThree % set stems, etc up
+ s1 | s4 b4 c2 |
+ }
+>>
+@end lilypond
+
+
@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{\lyricsAdd@{@}} command, which
-handles simple cases for you. However, @code{\lyricsAdd@{@}} is
-very limited. For most music, you must explicitly link the lyrics
-to the notes with @code{\lyricsTo@{@}}
+You have already seen the @code{\addlyricsd@{@}} 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
+name assigned to the Voice.
@lilypond[quote,verbatim,fragment]
<<
>>
@end lilypond
-TODO: get some vocal person to write more.
+The automatic beaming which LilyPond uses by default works well
+for instrumental music, but not so well for music with lyrics,
+where beaming is either not required at all or is used to indicate
+melismata in the lyrics. In the example above we use the command
+@code{\autoBeamOff} to turn off the automatic beaming.
+
+Let us reuse the earlier example from Judas Maccabæus to
+illustrate this more flexible technique. We first recast
+it to use variables so the music and lyrics can be separated
+from the staff structure. We also introduce a ChoirStaff
+bracket. The lyrics themselves must be introduced with
+@code{\lyricmode} to ensure they are interpreted as lyrics
+rather than music.
+
+@lilypond[quote,verbatim]
+global = { \time 6/8 \partial 8 \key f \major}
+SopOneMusic = \relative c'' {
+ c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
+SopTwoMusic = \relative c' {
+ r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
+SopOneLyrics = \lyricmode {
+ Let | flee -- cy flocks the | hills a -- dorn, __ }
+SopTwoLyrics = \lyricmode {
+ Let | flee -- cy flocks the | hills a -- dorn, }
+
+\score {
+ \new ChoirStaff <<
+ \new Staff <<
+ \new Voice = "SopOne" {
+ \global
+ \SopOneMusic
+ }
+ \new Lyrics \lyricsto "SopOne" {
+ \SopOneLyrics
+ }
+ >>
+ \new Staff <<
+ \new Voice = "SopTwo" {
+ \SopTwoMusic
+ }
+ \new Lyrics \lyricsto "SopTwo" {
+ \SopTwoLyrics
+ }
+ >>
+ >>
+}
+@end lilypond
+This is the basic structure of all vocal scores. More staves may
+be added as required, more voices may be added to the staves,
+more verses may be added to the lyrics,
+and the variables containing the music can easily be placed
+in separate files should they become too long.
+
+Here is a final example of the first line of a hymn with four
+verses, set for SATB. In this case the words for all four
+parts are the same.
+
+@lilypond[quote,verbatim]
+global = { \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 }
+BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
+VerseOne = \lyricmode {
+ E -- | ter -- nal fa -- ther, | strong to save, }
+VerseTwo = \lyricmode {
+ O | Christ, whose voice the | wa -- ters heard, }
+VerseThree = \lyricmode {
+ O | Ho -- ly Spi -- rit, | who didst brood }
+VerseFour = \lyricmode {
+ O | Tri -- ni -- ty of | love and pow'r }
+
+\score {
+ \new ChoirStaff <<
+ \new Staff <<
+ \clef "treble"
+ \new Voice = "Sop" { \voiceOne \global \SopMusic }
+ \new Voice = "Alto" { \voiceTwo \AltoMusic }
+ \new Lyrics \lyricsto "Sop" { \VerseOne }
+ \new Lyrics \lyricsto "Sop" { \VerseTwo }
+ \new Lyrics \lyricsto "Sop" { \VerseThree }
+ \new Lyrics \lyricsto "Sop" { \VerseFour }
+ >>
+ \new Staff <<
+ \clef "bass"
+ \new Voice = "Tenor" { \voiceOne \TenorMusic }
+ \new Voice = "Bass" { \voiceTwo \BassMusic }
+ >>
+ >>
+}
+@end lilypond
-@node TODO new sec fundamental
-@section TODO new sec fundamental
+@node Contexts and engravers
+@section Contexts and engravers
-blh blah
+Contexts and engravers have been mentioned informally
+in earlier sections; we now must look at
+these concepts in more detail, as they are important
+in the fine-tuning of LilyPond output.
@menu
-* On the un-nestedness of brackets and ties::
+* Contexts explained::
+* Creating contexts::
+* Engravers::
+* Modifying contexts::
@end menu
-@c my name start sucking the more docs I write. -gp
-@node On the un-nestedness of brackets and ties
-@subsection On the un-nestedness of brackets and ties
+@node Contexts explained
+@subsection Contexts explained
-Different kinds of brackets and ties may be mixed freely,
+When music is printed, many notational elements which do not
+appear explicitly in the input file must be added to the
+output. For example, compare the input and output of the
+following example:
-TODO: improve this example
+@lilypond[quote,verbatim,relative=2,fragment]
+cis4 cis2. g4
+@end lilypond
-@lilypond[quote,verbatim,fragment,ragged-right]
-{
- r16[ g16 \times 2/3 {r16 e'8] }
- g16( a \times 2/3 {b d e') }
- g8[( a \times 2/3 {b d') e'~]}
- \times 4/5 {e'32\( a b d' e'} a'4.\)
+The input is rather sparse, but in the output, bar lines,
+accidentals, clef, and time signature have been added. When
+LilyPond @emph{interprets} the input the musical information
+is inspected in time order, similar to reading a score from left
+to right. While reading the input, the program remembers where
+measure boundaries are, and which pitches require explicit
+accidentals. This information must be held on several levels.
+For example, the effect of an accidental is limited
+to a single staff, while a bar line must be synchronized across
+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.
+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.
+
+@quotation
+@image{context-example,5cm,,}
+@end quotation
+
+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
+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.
+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.
+
+For very simple scores, contexts are created implicitly, and you need
+not be aware of them. For larger pieces, such as anything with more
+than one staff, they must be
+created explicitly to make sure that you get as many staves as you
+need, and that they are in the correct order. For typesetting pieces
+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
+the score and staff levels to control staff groups, such as the
+@context{PianoStaff} and @context{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.
+TODO: Add link
+
+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}.
+
+@node Creating contexts
+@subsection Creating contexts
+
+There can be only one top level context: the @context{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
+created automatically, but for more complex scores it is
+necessary to create them by hand.
+The simplest command that does this is @code{\new}.
+It is prepended to a music expression, for example
+
+@funindex \new
+@cindex new contexts
+@cindex Context, creating
+
+@example
+\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.
+
+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}.
+
+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}
+@end example
+
+Note the distinction between the name of the context type,
+@context{Staff}, @context{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
+instance of a context. We saw this in use in the section on
+lyrics in @ref{Voices and vocals}.
+
+
+@node Engravers
+@subsection 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
+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
+about any.
+
+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 @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.
+
+Each engraver processes the particular objects associated
+with its function, and maintains the properties that relate
+to that function. These properties, like the properties
+associated with contexts, may be modified to change the
+operation of the engraver or the appearance of those elements
+in the printed score.
+
+Engravers all have compound names formed from words which
+describe their function. Just the first word is capitalised,
+and the remainder are joined to it with underscores. Thus
+the @code{Staff_symbol_engraver} is responsible for creating the
+lines of the staff, the @code{Clef_engraver} determines and sets
+the pitch reference point on the staff by drawing a clef symbol.
+
+Here are some of the most common engravers together with their
+function. You will see it is easy to guess the function from
+the name, or vice versa.
+
+@multitable @columnfractions .3 .7
+@headitem Engraver
+ @tab Function
+@item Accidental_engraver
+ @tab Makes accidentals, cautionary and suggested accidentals
+@item Beam_engraver
+ @tab Engraves beams
+@item Clef_engraver
+ @tab Engraves clefs
+@item Dynamic_engraver
+ @tab Creates hairpins and dynamic texts
+@item Key_engraver
+ @tab Creates the key signature
+@item Metronome_mark_engraver
+ @tab Engraves metronome marking
+@item Note_heads_engraver
+ @tab Engraves noteheads
+@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
+@end multitable
+
+@smallspace
+
+We shall see later how the output of LilyPond can be changed
+by modifying the action of Engravers.
+
+
+@node Modifying contexts
+@subsection Modifying contexts
+
+@menu
+* Changing context properties::
+* Adding and removing engravers::
+@end menu
+
+@node Changing context properties
+@subsubsection Changing context properties
+
+@cindex context properties
+@funindex \set
+@funindex \unset
+
+Contexts are responsible for holding the values of a number of
+context @emph{properties}. Many of them can be changed to
+influence the interpretation of the input and so change the
+appearance of the output. They are changed by the
+@code{\set} command. This takes the form
+
+@example
+\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.
+
+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
+@headitem propertyName
+ @tab Value
+ @tab Function
+@item extraNatural
+ @tab ##t or ##f
+ @tab If true (##t), set extra natural sign before accidentals
+@item currentBarNumber
+ @tab Integer
+ @tab Set the current bar number
+@item doubleSlurs
+ @tab ##t or ##f
+ @tab If true (##t), print slurs both above and below notes
+@item instrumentName
+ @tab Text
+ @tab Set the name to be placed at the start of the staff
+@item fontSize
+ @tab Number
+ @tab Increase or decrease the font size
+@item stanza
+ @tab Text
+ @tab Set the text to print before the start of a verse
+@end multitable
+
+Before we can set any of these properties we need to know
+which context they operate in. 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
+@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.
+
+@lilypond[quote,verbatim,ragged-right]
+<<
+ \new Staff \relative c'' {
+ \set Staff.instrumentName = "Soprano"
+ c4 c
+ }
+ \new Staff \relative c' {
+ \set instrumentName = "Alto"
+ d4 d
+ }
+>>
+@end lilypond
+
+Remember the default context name is Voice, so the second
+@code{\set} command set the property @emph{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.
+
+Similarly, if the property name is mis-spelt no error message
+is produced, and the expected action clearly is not 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.
+
+The @code{instrumentName} property will take effect only
+if it is set in the @context{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
+it applies just to the accidentals on that staff.
+If it is set to false in the @context{Score} context
+it applies to all staves.
+
+So this sets @code{extraNatural} in one staff:
+
+@lilypond[quote,verbatim,ragged-right]
+<<
+ \new Staff \relative c'' {
+ ais4 aes
+ }
+ \new Staff \relative c'' {
+ \set Staff.extraNatural = ##f
+ ais4 aes
+ }
+>>
+@end lilypond
+
+@noindent
+and this sets it in all staves:
+
+@lilypond[quote,verbatim,ragged-right]
+<<
+ \new Staff \relative c'' {
+ ais4 aes
+ }
+ \new Staff \relative c'' {
+ \set Score.extraNatural = ##f
+ ais4 aes
+ }
+>>
+@end lilypond
+
+The value of every property set in this way can be reset
+to its original value with the @code{\unset} command
+
+The @code{\set} and @code{\unset} commands can appear anywhere
+in the input file and will take effect from the time they are
+encountered until the end of the score or until the property is
+@code{\set} or @code{\unset} again. Let's try changing the
+font size, which affects the size of the note heads (among
+other things) several times.
+
+@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
+c4
+\set fontSize = #-4 % make noteheads smaller
+d e
+\set fontSize = #2.5 % make noteheads larger
+f g
+\unset fontSize % return to original size
+a b
+@end lilypond
+
+We have now seen how to set the values of several different
+types of property. Note that integers and numbers are alway
+preceded by a hash sign, @code{#}, while a true or false value
+is specified by ##t and ##f, with two hash signs. A text
+property should be enclosed in double quotation signs, as above,
+although we shall see later that text can actually be specified
+in a much more general way by using the very powerful
+@code{markup} command.
+
+
+@funindex \with
+
+Context properties may also be set at the time the context is
+created. Sometimes this is a clearer way of specifying a
+property value if it is to remain fixed for the duration of
+the context. When a context is created with a @code{\new}
+command it may be immediately followed by a
+@code{\with @{ .. @}} block in which the property values are
+set. For example, if we wish to suppress the printing of
+extra naturals for the duration of a staff we would write:
+
+@lilypond[quote,verbatim,ragged-right]
+\new Staff \with {
+ extraNatural = ##f
+}
+\relative c' {
+ gis ges aes ais
}
@end lilypond
-TODO... add more info? Fluff up the first sentence?
+In effect this overrides the default value of the property. It
+may still be changed dynamically using @code{\set} and
+@code{\unset}.
+
+@node Adding and removing engravers
+@subsubsection Adding and removing engravers
+
+@cindex Engravers, adding
+@cindex Engravers, removing
+
+@funindex \consists
+@funindex \remove
+
+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
+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.
+
+To remove an engraver we can use the @code{\with} command placed
+immediately after the context creation command, as in the
+previous section.
+
+As an
+illustration let's repeat an example from the previous
+section with the staff lines removed. Remember that the
+staff lines are produced by the Staff_symbol_engraver.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Staff \with {
+ \remove Staff_symbol_engraver
+}
+\relative c' {
+ c4
+ \set fontSize = #-4 % make noteheads smaller
+ d e
+ \set fontSize = #2.5 % make noteheads larger
+ f g
+ \unset fontSize % return to original size
+ a b
+}
+@end lilypond
+
+@cindex ambitus engraver
+
+Engravers can also be added to contexts. The command
+to do this is @code{\consists @emph{Engraver_name}},
+placed inside a @code{\with} block. Some vocal scores
+have an @rglos{ambitus} placed at the beginning of a
+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
+the range from that voice only:
+
+@lilypond[quote,verbatim,ragged-right]
+\new Staff <<
+ \new Voice \with {
+ \consists Ambitus_engraver
+ }
+ \relative c'' {
+ \voiceOne
+ c a b g
+ }
+ \new Voice
+ \relative c' {
+ \voiceTwo
+ c e d f
+ }
+>>
+@end lilypond
+
+@noindent
+but if we add the Ambitus engraver to the
+@context{Staff} context it calculates the range from all
+the notes in all the voices on that staff:
+
+@lilypond[quote,verbatim,ragged-right]
+\new Staff \with {
+ \consists Ambitus_engraver
+ }
+ <<
+ \new Voice
+ \relative c'' {
+ \voiceOne
+ c a b g
+ }
+ \new Voice
+ \relative c' {
+ \voiceTwo
+ c e d f
+ }
+>>
+@end lilypond
+@node Extending the templates
+@section Extending the templates
+
+You've read the tutorial, you know how to write music, you
+understand the fundamental concepts. But how can you
+get the staves that you want? Well, you can find lots of
+templates in Appendix A which may give you a start. But what
+if you want something that isn't covered there? Read on.
+
+@menu
+* Soprano and cello::
+* Four-part SATB vocal score::
+* Building a score from scratch::
+@end menu
+
+@node Soprano and cello
+@subsection Soprano and cello
+
+Start off with the template that seems closest to what you want to end
+up with. Let's say that you want to write something for soprano and
+cello. In this case, we would start with @q{Notes and lyrics} (for the
+soprano part).
+
+@example
+\version "2.11.23"
+melody = \relative c' @{
+ \clef treble
+ \key c \major
+ \time 4/4
+
+ a4 b c d
+@}
+
+text = \lyricmode @{
+ Aaa Bee Cee Dee
+@}
+
+\score @{
+ <<
+ \new Voice = "one" @{
+ \autoBeamOff
+ \melody
+ @}
+ \new Lyrics \lyricsto "one" \text
+ >>
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+
+Now we want to add a cello part. Let's look at the @q{Notes only} example:
+
+@example
+\version "2.11.23"
+melody = \relative c' @{
+ \clef treble
+ \key c \major
+ \time 4/4
+
+ a4 b c d
+@}
+
+\score @{
+ \new Staff \melody
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+
+We don't need two @code{\version} commands. We'll need the @code{melody}
+section. We don't want two @code{\score} sections -- if we had two
+@code{\score}s, we'd get the two parts separately. We want them together,
+as a duet. Within the @code{\score} section, we don't need two
+@code{\layout} or @code{\midi}.
+
+If we simply cut and paste the @code{melody} section, we would end up with
+two @code{melody} sections. So let's rename them. We'll call the section
+for the soprano @code{sopranoMusic} and the section for the cello
+@code{celloMusic}. While we're doing this, let's rename @code{text}
+to be @code{sopranoLyrics}. Remember to rename both instances of all
+these names -- both the initial definition (the
+@code{melody = relative c' @{ } part) and the name's use (in the
+@code{\score} section).
+
+While we're doing this, let's change the cello part's staff -- celli
+normally use bass clef. We'll also give the cello some different
+notes.
+
+@example
+\version "2.11.23"
+sopranoMusic = \relative c' @{
+ \clef treble
+ \key c \major
+ \time 4/4
+
+ a4 b c d
+@}
+
+sopranoLyrics = \lyricmode @{
+ Aaa Bee Cee Dee
+@}
+
+celloMusic = \relative c @{
+ \clef bass
+ \key c \major
+ \time 4/4
+
+ d4 g fis8 e d4
+@}
+
+\score @{
+ <<
+ \new Voice = "one" @{
+ \autoBeamOff
+ \sopranoMusic
+ @}
+ \new Lyrics \lyricsto "one" \sopranoLyrics
+ >>
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+
+This is looking promising, but the cello part won't appear in the
+score -- we haven't used it in the @code{\score} section. If we
+want the cello part to appear under the soprano part, we need to add
+
+@example
+\new Staff \celloMusic
+@end example
+
+@noindent
+underneath the soprano stuff. We also need to add @code{<<} and
+@code{>>} around the music -- that tells LilyPond that there's
+more than one thing (in this case, @code{Staff}) happening at once. The
+@code{\score} looks like this now
+
+@c Indentation in this example is deliberately poor
+@example
+\score @{
+ <<
+ <<
+ \new Voice = "one" @{
+ \autoBeamOff
+ \sopranoMusic
+ @}
+ \new Lyrics \lyricsto "one" \sopranoLyrics
+ >>
+ \new Staff \celloMusic
+ >>
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+
+@noindent
+This looks a bit messy; the indentation is messed up now. That is
+easily fixed. Here's the complete soprano and cello template.
+
+@lilypond[quote,verbatim,ragged-right]
+\version "2.11.23"
+sopranoMusic = \relative c' {
+ \clef treble
+ \key c \major
+ \time 4/4
+
+ a4 b c d
+}
+
+sopranoLyrics = \lyricmode {
+ Aaa Bee Cee Dee
+}
+
+celloMusic = \relative c {
+ \clef bass
+ \key c \major
+ \time 4/4
+
+ d4 g fis8 e d4
+}
+
+\score {
+ <<
+ <<
+ \new Voice = "one" {
+ \autoBeamOff
+ \sopranoMusic
+ }
+ \new Lyrics \lyricsto "one" \sopranoLyrics
+ >>
+ \new Staff \celloMusic
+ >>
+ \layout { }
+ \midi { }
+}
+@end lilypond
+
+
+@node Four-part SATB vocal score
+@subsection Four-part SATB vocal score
+
+Most vocal scores of music written for four-part mixed choir
+with orchestral accompaniment such as Mendelssohn's Elijah or
+Handel's Messiah have the choral music and words on four
+staves, one for each of SATB, with a piano reduction of the
+orchestral accompaniment underneath. Here's an example
+from Handel's Messiah:
+
+@c The following should appear as music without code
+@lilypond[quote,ragged-right]
+\version "2.11.23"
+global = { \key d \major \time 4/4 }
+sopMusic = \relative c'' {
+ \clef "treble"
+ r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
+}
+sopWords = \lyricmode {
+ Wor -- thy is the lamb that was slain
+}
+altoMusic = \relative a' {
+ \clef "treble"
+ r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
+}
+altoWords = \sopWords
+tenorMusic = \relative c' {
+ \clef "G_8"
+ r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
+}
+tenorWords = \sopWords
+bassMusic = \relative c' {
+ \clef "bass"
+ r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
+}
+bassWords = \sopWords
+upper = \relative a' {
+ \clef "treble"
+ \global
+ r4 <a d fis>2 <a e' a>4 |
+ <d fis d'>4. <d fis d'>8 <a d a'>2 |
+ <g cis g'>4 <a d fis> <a cis e>2 |
+}
+lower = \relative c, {
+ \clef "bass"
+ \global
+ <d d'>4 <d d'>2 <cis cis'>4 |
+ <b b'>4. <b' b'>8 <fis fis'>2 |
+ <e e'>4 <d d'> <a' a'>2 |
+}
+
+\score {
+ << % combine ChoirStaff and PianoStaff in parallel
+ \new ChoirStaff <<
+ \new Staff = "sopranos" <<
+ \set Staff.instrumentName = "Soprano"
+ \new Voice = "sopranos" { \global \sopMusic }
+ >>
+ \new Lyrics \lyricsto "sopranos" { \sopWords }
+ \new Staff = "altos" <<
+ \set Staff.instrumentName = "Alto"
+ \new Voice = "altos" { \global \altoMusic }
+ >>
+ \new Lyrics \lyricsto "altos" { \altoWords }
+ \new Staff = "tenors" <<
+ \set Staff.instrumentName = "Tenor"
+ \new Voice = "tenors" { \global \tenorMusic }
+ >>
+ \new Lyrics \lyricsto "tenors" { \tenorWords }
+ \new Staff = "basses" <<
+ \set Staff.instrumentName = "Bass"
+ \new Voice = "basses" { \global \bassMusic }
+ >>
+ \new Lyrics \lyricsto "basses" { \bassWords }
+ >> % end ChoirStaff
+
+ \new PianoStaff <<
+ \set PianoStaff.instrumentName = "Piano "
+ \new Staff = "upper" \upper
+ \new Staff = "lower" \lower
+ >>
+ >>
+}
+@end lilypond
+
+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
+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
+the piano reduction.
+
+The order in which the contexts appear in the ChoirStaff of
+the template do not correspond with the order in the vocal
+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.
+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.
+
+Doing this gives for our ChoirStaff:
+
+@example
+ \new ChoirStaff <<
+ \new Staff = "sopranos" <<
+ \set Staff.instrumentName = "Soprano"
+ \new Voice = "sopranos" @{ \global \sopMusic @}
+ >>
+ \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
+ \new Staff = "altos" <<
+ \set Staff.instrumentName = "Alto"
+ \new Voice = "altos" @{ \global \altoMusic @}
+ >>
+ \new Lyrics \lyricsto "altos" @{ \altoWords @}
+ \new Staff = "tenors" <<
+ \set Staff.instrumentName = "Tenor"
+ \new Voice = "tenors" @{ \global \tenorMusic @}
+ >>
+ \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
+ \new Staff = "basses" <<
+ \set Staff.instrumentName = "Bass"
+ \new Voice = "basses" @{ \global \bassMusic @}
+ >>
+ \new Lyrics \lyricsto "basses" @{ \bassWords @}
+ >> % end ChoirStaff
+@end example
+
+Next we must work out the piano part. This is
+easy - we just pull out the piano part from the
+@q{Solo piano} template:
+
+@example
+\new PianoStaff <<
+ \set PianoStaff.instrumentName = "Piano "
+ \new Staff = "upper" \upper
+ \new Staff = "lower" \lower
+>>
+@end example
+
+and add the variable definitions for @code{upper}
+and @code{lower}.
+
+The ChoirStaff and PianoStaff must be combined
+using angle brackets as we want them to be
+stacked one above the other:
+
+@example
+<< % combine ChoirStaff and PianoStaff one above the other
+ \new ChoirStaff <<
+ \new Staff = "sopranos" <<
+ \new Voice = "sopranos" @{ \global \sopMusic @}
+ >>
+ \new Lyrics \lyricsto "sopranos" @{ \sopWords @}
+ \new Staff = "altos" <<
+ \new Voice = "altos" @{ \global \altoMusic @}
+ >>
+ \new Lyrics \lyricsto "altos" @{ \altoWords @}
+ \new Staff = "tenors" <<
+ \clef "G_8" % tenor clef
+ \new Voice = "tenors" @{ \global \tenorMusic @}
+ >>
+ \new Lyrics \lyricsto "tenors" @{ \tenorWords @}
+ \new Staff = "basses" <<
+ \clef "bass"
+ \new Voice = "basses" @{ \global \bassMusic @}
+ >>
+ \new Lyrics \lyricsto "basses" @{ bassWords @}
+ >> % end ChoirStaff
+
+ \new PianoStaff <<
+ \set PianoStaff.instrumentName = "Piano "
+ \new Staff = "upper" \upper
+ \new Staff = "lower" \lower
+ >>
+>>
+@end example
+
+Combining all these together and adding the music
+for the three bars of the example above gives:
+
+@lilypond[quote,verbatim,ragged-right]
+\version "2.11.23"
+global = { \key d \major \time 4/4 }
+sopMusic = \relative c'' {
+ \clef "treble"
+ r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
+}
+sopWords = \lyricmode {
+ Wor -- thy is the lamb that was slain
+}
+altoMusic = \relative a' {
+ \clef "treble"
+ r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
+}
+altoWords = \sopWords
+tenorMusic = \relative c' {
+ \clef "G_8"
+ r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
+}
+tenorWords = \sopWords
+bassMusic = \relative c' {
+ \clef "bass"
+ r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
+}
+bassWords = \sopWords
+upper = \relative a' {
+ \clef "treble"
+ \global
+ r4 <a d fis>2 <a e' a>4 |
+ <d fis d'>4. <d fis d'>8 <a d a'>2 |
+ <g cis g'>4 <a d fis> <a cis e>2 |
+}
+lower = \relative c, {
+ \clef "bass"
+ \global
+ <d d'>4 <d d'>2 <cis cis'>4 |
+ <b b'>4. <b' b'>8 <fis fis'>2 |
+ <e e'>4 <d d'> <a' a'>2 |
+}
+
+\score {
+ << % combine ChoirStaff and PianoStaff in parallel
+ \new ChoirStaff <<
+ \new Staff = "sopranos" <<
+ \set Staff.instrumentName = "Soprano"
+ \new Voice = "sopranos" { \global \sopMusic }
+ >>
+ \new Lyrics \lyricsto "sopranos" { \sopWords }
+ \new Staff = "altos" <<
+ \set Staff.instrumentName = "Alto"
+ \new Voice = "altos" { \global \altoMusic }
+ >>
+ \new Lyrics \lyricsto "altos" { \altoWords }
+ \new Staff = "tenors" <<
+ \set Staff.instrumentName = "Tenor"
+ \new Voice = "tenors" { \global \tenorMusic }
+ >>
+ \new Lyrics \lyricsto "tenors" { \tenorWords }
+ \new Staff = "basses" <<
+ \set Staff.instrumentName = "Bass"
+ \new Voice = "basses" { \global \bassMusic }
+ >>
+ \new Lyrics \lyricsto "basses" { \bassWords }
+ >> % end ChoirStaff
+
+ \new PianoStaff <<
+ \set PianoStaff.instrumentName = "Piano "
+ \new Staff = "upper" \upper
+ \new Staff = "lower" \lower
+ >>
+ >>
+}
+@end lilypond
+
+
+@node Building a score from scratch
+@subsection Building a score from scratch
+
+After gaining some facility with writing LilyPond code you
+may find that it is easier to build a score from scratch
+rather than modifying one of the templates. You can also
+develop your own style this way to suit the sort of music you
+like. Let's see how to put together the score for an organ
+prelude as an example.
+
+We begin with a header section. Here go the title, name
+of composer, etc followed by the variable definitions
+and ending with the score block. Let's start with these and
+fill in the details later.
+
+We'll use the first two bars of Bach's prelude
+based on @emph{Jesu, meine Freude} which is set in two
+manuals and pedal organ. The top manual 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:
+
+@example
+\version "2.11.23"
+\header @{
+ title = "Jesu, meine Freude"
+ composer = "J S Bach"
+@}
+TimeKey = @{ \time 4/4 \key c \minor @}
+ManualOneVoiceOneMusic = @{s1@}
+ManualOneVoiceTwoMusic = @{s1@}
+ManualTwoMusic = @{s1@}
+PedalOrganMusic = @{s1@}
+
+\score @{
+@}
+@end example
+
+For now we've just used a spacer note, @code{s1},
+instead of the real music. We'll add that later.
+
+Next let's see what should go in the score block.
+We simply mirror the staff structure we want.
+Organ music is usually written on three staves,
+one for each manual and one for the pedals. The
+manual staves should be bracketed together so we
+need to use a PianoStaff for them. The first
+manual part needs two voices and the second manual
+part just one.
+
+@example
+ \new PianoStaff <<
+ \new Staff = "ManualOne" <<
+ \new Voice @{ \ManualOneVoiceOneMusic @}
+ \new Voice @{ \ManualOneVoiceTwoMusic @}
+ >> % end ManualOne Staff context
+ \new Staff = "ManualTwo" <<
+ \new Voice @{ \ManualTwoMusic @}
+ >> % end ManualTwo Staff context
+ >> % end PianoStaff context
+@end example
+
+Next we need to add a staff for the pedal organ.
+This goes underneath the PianoStaff, but it must
+be simultaneous with it, so we need angle brackets
+round the two. Missing these out would generate
+an error in the log file. It's a common mistake
+which you'll make sooner or later! Try copying
+the final example at the end of this section,
+remove these angle brackets, and compile it to
+see what errors it generates.
+
+@example
+<< % PianoStaff and Pedal Staff must be simultaneous
+ \new PianoStaff <<
+ \new Staff = "ManualOne" <<
+ \new Voice @{ \ManualOneVoiceOneMusic @}
+ \new Voice @{ \ManualOneVoiceTwoMusic @}
+ >> % end ManualOne Staff context
+ \new Staff = "ManualTwo" <<
+ \new Voice @{ \ManualTwoMusic @}
+ >> % end ManualTwo Staff context
+ >> % end PianoStaff context
+ \new Staff = "PedalOrgan" <<
+ \new Voice @{ \PedalOrganMusic @}
+ >>
+>>
+@end example
+
+It is not strictly necessary to use the simultaneous contruct
+@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
+habit to cultivate in case there are multiple voices.
+
+Let's add this structure to the score block, and adjust the
+indenting. We also add the appropriate clefs, ensure the
+second voice stems point down with @code{\voiceTwo} and
+enter the time signature and key to each staff using our
+predefined variable, @code{\TimeKey}.
+
+@example
+\score @{
+ << % PianoStaff and Pedal Staff must be simultaneous
+ \new PianoStaff <<
+ \new Staff = "ManualOne" <<
+ \TimeKey % set time signature and key
+ \clef "treble"
+ \new Voice @{ \ManualOneVoiceOneMusic @}
+ \new Voice @{ \voiceTwo \ManualOneVoiceTwoMusic @}
+ >> % end ManualOne Staff context
+ \new Staff = "ManualTwo" <<
+ \TimeKey
+ \clef "bass"
+ \new Voice @{ \ManualTwoMusic @}
+ >> % end ManualTwo Staff context
+ >> % end PianoStaff context
+ \new Staff = "PedalOrgan" <<
+ \TimeKey
+ \clef "bass"
+ \new Voice @{ \PedalOrganMusic @}
+ >> % end PedalOrgan Staff
+ >>
+@} % end Score context
+@end example
+
+That completes the structure. Any three-staff organ music
+will have a similar structure, although the number of voices
+may vary. All that remains now
+is to add the music, and combine all the parts together.
+
+@lilypond[quote,verbatim,ragged-right]
+\version "2.11.23"
+\header {
+ title = "Jesu, meine Freude"
+ composer = "J S Bach"
+}
+TimeKey = { \time 4/4 \key c \minor }
+ManualOneVoiceOneMusic = \relative g' {
+ g4 g f ees | d2 c2 |
+}
+ManualOneVoiceTwoMusic = \relative c' {
+ ees16 d ees8~ ees16 f ees s c8 d~ d c~ |
+ c c4 b8 c8. g16 c b c d |
+}
+ManualTwoMusic = \relative c' {
+ c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
+ f ees f d g aes g f ees d e8~ ees16 f ees d |
+}
+PedalOrganMusic = \relative c {
+ r8 c16 d ees d ees8~ ees16 a, b g c b c8 |
+ r16 g ees f g f g8 c,2 |
+ }
+
+\score {
+ << % PianoStaff and Pedal Staff must be simultaneous
+ \new PianoStaff <<
+ \new Staff = "ManualOne" <<
+ \TimeKey % set time signature and key
+ \clef "treble"
+ \new Voice { \ManualOneVoiceOneMusic }
+ \new Voice { \voiceTwo \ManualOneVoiceTwoMusic }
+ >> % end ManualOne Staff context
+ \new Staff = "ManualTwo" <<
+ \TimeKey
+ \clef "bass"
+ \new Voice { \ManualTwoMusic }
+ >> % end ManualTwo Staff context
+ >> % end PianoStaff context
+ \new Staff = "PedalOrgan" <<
+ \TimeKey
+ \clef "bass"
+ \new Voice { \PedalOrganMusic }
+ >> % end PedalOrgan Staff
+ >>
+} % end Score context
+@end lilypond