Merge branch 'master' of ssh://jomand@git.sv.gnu.org/srv/git/lilypond into dev/jmandereau

[lilypond.git] / Documentation / user / fundamental.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond-learning.tely

@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::     
* Voices contain music::        
* Contexts and engravers::      
* Extending the templates::     
@end menu


@node How LilyPond files work
@section How LilyPond files work

The LilyPond input format is quite free-form, giving experienced
users a lot of flexibility to structure their files however they
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) compound musical expression::  
* Nesting music expressions::   
* On the un-nestedness of brackets and ties::  
@end menu

@node Introduction to the LilyPond file structure
@subsection Introduction to the LilyPond file structure

A basic example of a lilypond input file is

@example
\version @w{"@version{}"}
\score @{
  @var{...compound music expression...}  % all the music goes here!
  \header @{ @}
  \layout @{ @}
  \midi @{ @}
@}
@end example

@noindent
There are many variations of this basic pattern, but this
example serves as a useful starting place.

Up to this point none of the examples you have seen has 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'' @{
  c4 a d c
@}
@end example

@noindent
as shorthand for this:

@example
\book @{
  \score @{
    \new Staff @{
      \new Voice @{
        \relative c'' @{
          c4 a b c
        @}
      @}
    @}
    \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 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} block must always contain just one music 
expression, and
this must appear immediately after the @code{\score} command.
Remember that a music expression could be anything from a single
note to a huge compound expression like

@example
@{
  \new GrandStaff <<
    @var{...insert the whole score of a Wagner opera in here...}
  >>
@}
@end example

@noindent
Since everything is inside @code{@{ ... @}}, it counts
as one music expression.

As we saw previously, the @code{\score} block can contain other 
things, such as

@example
\score @{
  @{ c'4 a b c' @}
  \header @{ @}
  \layout @{ @}
  \midi @{ @}
@}
@end example

@noindent
Some people put some of those commands outside the @code{\score}
block -- for example, @code{\header} is often placed above the
@code{\score} command.  That's just another shorthand that LilyPond
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 output respectively.  They are described fully in the
Notation Reference -- @ruser{Score layout} and
@ruser{Creating MIDI files}.

You may code multiple @code{\score} blocks.  Each will be
treated as a separate score, but they will be all combined into
a single output file.  A @code{\book} command is not necessary
-- one will be implicitly created.  However, if you would like
separate output files from one @code{.ly} file then the
@code{\book} command should be used to separate the different
sections: each @code{\book} block will produce a
separate output file.  For details see @ruser{Multiple scores
in a book}.

@cindex variables

Another great shorthand is the ability to define variables.  All
the templates use this

@example
melody = \relative c' @{
  c4 a b c
@}

\score @{
  \melody
@}
@end example

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{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

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

@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
skip over the most important part: how do we figure out what to
write after @code{\score}?

We didn't skip over it at all.  The big mystery is simply that
there @emph{is} no mystery.  This line explains it all:

@quotation
@emph{A @code{\score} block must begin with a compound music expression.}
@end quotation

@noindent
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 compound music expression
    \new GrandStaff <<
      @var{...insert the whole score of a Wagner opera in here...}
    >>
  @} % 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, 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 @{
  <<
    \new Staff = "singer" <<
    >>
    \new PianoStaff = piano <<
    >>
  >>
  \layout @{ @}
@}
@end example

Remember that we use @code{<< ... >>} instead of
@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!  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. We'll add some real
music later; for now let's just put in some dummy notes and lyrics.

@lilypond[verbatim,quote,ragged-right]
\score {
  <<
    \new Staff = "singer" <<
      \new Voice = "vocal" { c'1 }
      \addlyrics { And }
    >>
    \new PianoStaff = "piano" <<
      \new Staff = "upper" { c'1 }
      \new Staff = "lower" { c'1 }
    >>
  >>
  \layout { }
}
@end lilypond

Now we have a lot more details.  We have the singer's staff: it
contains a @code{Voice} (in LilyPond, this term refers to a set of
notes, not necessarily vocal notes -- for example, a violin
generally plays one voice) and some lyrics.  We also have a piano
staff: it contains an upper staff (right hand) and a lower staff
(left hand).

At this stage, we could start filling in notes.  Inside the curly
braces next to @code{\new Voice = vocal}, we could start writing

@example
\relative c'' @{
  r4 d8\noBeam g, c4 r
@}
@end example

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 variables instead.  These were introduced at the end
of the previous section, remember?  So, adding a few notes, we 
now have a piece of real music:

@lilypond[verbatim,quote,ragged-right]
melody = \relative c'' { r4 d8\noBeam g, c4 r }
text   = \lyricmode { And God said, }
upper  = \relative c'' { <g d g,>2~ <g d g,> }
lower  = \relative c { b2 e2 }

\score {
  <<
    \new Staff = "singer" <<
      \new Voice = "vocal" { \melody }
      \addlyrics { \text }
    >>
    \new PianoStaff = "piano" <<
      \new Staff = "upper" { \upper }
      \new Staff = "lower" {
        \clef "bass"
        \lower
      }
    >>
  >>
  \layout { }
}
@end lilypond


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
each smaller layer.  It also really helps to be strict with
indentation -- make sure that each item on the same layer starts
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

@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:

@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 single 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 @ref{Size of objects}

@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.

@c attempt to force this onto a new page
@need 50
@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

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 hearing Voices::          
* Explicitly instantiating voices::  
* Voices and vocals::           
@end menu

@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, 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
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?  Look first at
this example of four chords:

@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
\key g \major
<d g>4 <d fis> <d a'> <d g>
@end lilypond

This can be expressed using just the single angle bracket chord 
symbols, @code{< ... >}, and for this just a single voice is 
needed.  But suppose the F-sharp were actually an eighth-note
followed by an eighth-note G, a passing note on the way to the A?
Now we have two notes which start at the same time but have
different durations: the quarter-note D and the eighth-note
F-sharp.  How are these to be coded?  They cannot be written as
a chord because all the notes in a chord must have the same
duration.  And they cannot be written as two separate notes
as they need to start at the same time.  This is when two
voices are required.

Let us see how this is done in LilyPond input syntax.

@funindex << \\ >>
@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 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 how we split the chords above into two voices and add both
the passing note and a slur:

@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
\key g \major
%    Voice "1"                  Voice "2"
<< { g4 fis8( g) a4 g }    \\ { d4 d d d }  >> |
@end lilypond

Notice how the stems of the second voice now point down.

Here's another 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

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.

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
  %    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

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 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
blue triangle voice.

@lilypond[quote,verbatim]
\new Staff \relative c' {
  % Main voice
  c16 d e f
  << % Bar 1
    {
      \voiceOneStyle
      g4 f e
    }
  \\
    {
      \voiceTwoStyle
      r8 e4 d c8 ~
    }
  >>
  << % Bar 2
     % Voice 1 continues
    { d2 e2 }
  \\
     % Voice 2 continues
    { c8 b16 a b8 g ~ g2 }
  \\
    {
      \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 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.
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
relative to the note immediately preceding it, or to the first
note of the preceding chord.  So in

@example
\relative c' @{ noteA << < noteB noteC > \\ noteD >> noteE @}
@end example

@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}

An alternative way, which may be clearer if the notes in the
voices are widely separated, is to place a @code{\relative}
command at the start of each voice:

@example
\relative c' @{ noteA ... @}
<<
  \relative c'' @{ < noteB noteC > ... @}
\\
  \relative g' @{ noteD ... @}
>>
\relative c' @{ noteE ... @}
@end example

Let us finally analyse the voices in a more complex piece of 
music.  Here are
the notes from the first two bars of the second of Chopin's
Deux Nocturnes, Op 32.  This example will be used at later
stages in this and the next chapter to illustrate several
techniques for producing notation, so please ignore for now
anything in the underlying code which looks mysterious and
concentrate just on the music and the voices -- the
complications will all be explained in later sections.

@c The following should appear as music without code
@lilypond[quote,ragged-right]
\new Staff \relative c'' {
  \key aes \major
  << % Voice one
    { c2 aes4. bes8 }
  \\ % Voice two
    { aes2 f4 fes }
  \\ % No voice three
  \\ % Voice four
    {
      % Ignore these for now - they are explained in Ch 4
      \once \override NoteColumn #'force-hshift = #0
      <ees c>2
      \once \override NoteColumn #'force-hshift = #0.5
      des2
    }
  >> |
  <c ees aes c>1 |
}
@end lilypond

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 below, where we have used different note heads
and colors for the three voices.  Again, the code behind this
example will be explained later, so ignore anything you do
not understand.

@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
  <<
    { % Voice one
      \voiceOneStyle
      c2 aes4. bes8 
    }
  \\  % Voice two
    { \voiceTwoStyle
      aes2 f4 fes 
    }
  \\  % No Voice three (we want stems down)
  \\  % Voice four
    { \voiceThreeStyle
      % Ignore these for now - they are explained in Ch 4
      \once \override NoteColumn #'force-hshift = #0
      <ees c>2
      \once \override NoteColumn #'force-hshift = #0.5
      des2 
    }
  >> |
  <c ees aes c>1 |
}
@end lilypond


Let us try to encode this music from scratch.  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

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 simply by missing out voice three
and placing the music in voice four:

@lilypond[quote,verbatim,fragment,ragged-right]
\new Staff \relative c'' {
  \key aes \major
  << % Voice one
    { c2 aes4. bes8 }
  \\ % Voice two
    { aes2 f4 fes   }
  \\ % Omit Voice three
  \\ % Voice four
    { <ees c>2 des2 }
  >> |
  <c ees aes c>1 |
}
@end lilypond

@noindent
We see that this fixes the stem direction, but exposes a 
problem sometimes encountered with multiple voices -- the 
stems of the notes in one voice can collide with the 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
the notes from the third and fourth voices are displaced to if
necessary to avoid the note heads
colliding.  This usually works well, but in this example the
notes of the lowest 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 the force-hshift property in @ref{Fixing overlapping 
notation} )

@node Explicitly instantiating voices
@subsection Explicitly instantiating voices

@funindex \voiceOne
@funindex \voiceTwo
@funindex \voiceThree
@funindex \voiceFour

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.  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
\new Staff @{
  \relative c' @{
    << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
  @}
@}
@end example

@noindent
is equivalent to 

@example
\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
@lilypond[ragged-right,quote]
\new Staff <<
  \new Voice = "1" { \voiceOne \relative c' { e4 f g a } }
  \new Voice = "2" { \voiceTwo \relative c' { c4 d e f } }
>>
@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}
make these objects point upwards, while @code{\voiceTwo} and
@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.

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]
\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 d8 ~ d e4 ( f g a ) b-> c
  \oneVoice
  c, d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond

@lilypond[quote,ragged-right,verbatim]
\relative c'{
  \voiceTwo
  c d8 ~ d e4 ( f g a ) b-> c
  \oneVoice
  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{<< \\ >>}
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
  % 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
    }
    % Initiate third voice
    \new Voice {
      % Set stems, etc, up
      \voiceThree
      s2. | s4 b4 c2
    }
  >>
}
@end lilypond

@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
  <<
    { g4 f e | d2 e2) }
    \new Voice {
      \voiceTwo
      r8 e4 d c8 ~ |
      <<
        {c8 b16 a b8 g ~ g2}
        \new Voice {
          \voiceThree
          s4 b4 c2
        }
      >>
    }
  >>
}
@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' <<
  % Initiate first voice
  \new Voice {
    \voiceOne
    c16^( d e f g4 f e | d2 e2) |
  }
  % Initiate second voice
  \new Voice {
    % set stems, etc down
    \voiceTwo
    s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
  }
  % 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{\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
name assigned to the Voice.

@lilypond[quote,verbatim,fragment]
<<
  \new Voice = "one" \relative c'' {
    \autoBeamOff
    \time 2/4
    c4 b8. a16 g4. f8 e4 d c2
  }
  \new Lyrics \lyricsto "one" {
    No more let sins and sor -- rows grow.
  }
>>
@end lilypond

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" {
        \global
        \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]
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 }
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 \TimeKey \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 \TimeKey \TenorMusic }
      \new Voice = "Bass"  { \voiceTwo \BassMusic  }
    >>
  >>
}
@end lilypond

@node Contexts and engravers
@section Contexts and engravers

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
* Contexts explained::          
* Creating contexts::           
* Engravers explained::         
* Modifying context properties::  
* Adding and removing engravers::  
@end menu

@node Contexts explained
@subsection Contexts explained

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:

@lilypond[quote,verbatim,relative=2,fragment]
cis4 cis2. g4
@end lilypond

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 
@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 @code{Staff} context can contain many 
@code{Voice} contexts, and a @code{Score} context can 
contain many @code{Staff} contexts.

@quotation
@sourceimage{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 @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 @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 
@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
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 @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
@code{PianoStaff} and @code{ChoirStaff} contexts.  There
are also alternative staff and voice contexts, and contexts for
lyrics, percussion, fret boards, figured bass, etc.

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., 
@code{GregorianTranscriptionStaff}.

@node Creating contexts
@subsection Creating contexts

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 
@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}.  
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} 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-expression}
@end example

Note the distinction between the name of the context type,
@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
instance of a context.  We saw this in use in the section on 
lyrics in @ref{Voices and vocals}.


@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 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 
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 @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 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
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 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

We shall see later how the output of LilyPond can be changed
by modifying the action of Engravers.
  

@node Modifying context properties
@subsection Modifying 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 @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.

@c attempt to force this onto a new page
@need 50
@multitable @columnfractions .25 .15 .45 .15
@headitem propertyName
  @tab Type
  @tab Function
  @tab Example Value
@item extraNatural
  @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 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 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
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 take place.  For example, the
@code{instrumentName} clearly lives in the Staff context, since
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]
<<
  \new Staff \relative c'' {
    \set Staff.instrumentName = #"Soprano"
    c4 c
 }
  \new Staff \relative c' {
  \set instrumentName = #"Alto"  % Wrong!
  d4 d 
 }
>>
@end lilypond

Remember the default context name is Voice, so the second
@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 @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 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 @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 one particular @code{Staff} 
context it applies just to the accidentals on that staff.
If it is set to false in the @code{Score} context
it applies to all staves.

So this turns off extra naturals 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 turns them off 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.  The change is from the default
value, not the current value.

@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
c4 
% make note heads smaller
\set fontSize = #-4
d e
% make note heads larger
\set fontSize = #2.5
f g
% return to original size
\unset fontSize
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 followed immediately 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:

@example
\new Staff \with @{ extraNatural = ##f @}
@end example

@noindent
like this:

@lilypond[quote,verbatim,ragged-right]
<<
  \new Staff
  \relative c'' {
    gis ges aes ais
  }
  \new Staff \with { extraNatural = ##f }
  \relative c'' {
    gis ges aes ais
  }
>>
@end lilypond

In effect this overrides the default value of the property.  It
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

@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 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.

@subsubheading Changing a single context

To remove an engraver from a single context we 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 note heads smaller
  d e
  \set fontSize = #2.5  % make note heads larger
  f g
  \unset fontSize  % return to original size
  a b
}
@end lilypond

@cindex ambitus engraver

Engravers can also be added to individual 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 @code{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 
@code{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

@subsubheading Changing all contexts of the same type

The examples above show how to remove or add engravers to
individual contexts.  It is also possible to remove or add 
engravers to every context of a specific type by placing the
commands in the appropriate context in a @code{\layout}
block.  For example, If we wanted to show ambiti for every
staff in a four-staff score we could write

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new Staff <<
      \relative c'' { c a b g }
    >>
    \new Staff <<
      \relative c' { c a b g }
    >>
    \new Staff <<
      \clef "G_8"
      \relative c' { c a b g }
    >>
    \new Staff <<
      \clef "bass"
      \relative c { c a b g }
    >>
  >>
  \layout {
    \context {
      \Staff
      \consists Ambitus_engraver
    }
  }
}
@end lilypond

@noindent
The default values of context properties may also be set
for all contexts of a particular type by including the
@code{\set} command in a @code{\context} block in the
same way.

@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 (see @ref{Templates}) which may give you a start.  
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::  
* 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 @w{"@version{}"}
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 @w{"@version{}"}
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} definitions.  This would not generate
an error, but the second one would be used for both melodies.
So let's rename them to make them distinct.  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 @w{"@version{}"}
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, two @code{Staves}) 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.38"
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]
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 e2 |
}
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 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 should be removed.
We also need to specify the tenor clef for the tenors.
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:

@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.38"
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, then come any variable definitions, and
finally the score block.  Let's start with these in outline
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 written for two
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:

@example
\version @w{"@version{}"}
\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 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
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.38"
\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