@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::
-* TODO new sec fundamental::
+* Contexts and engravers::
* Extending the templates::
-* Scores and parts::
@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) compound musical expression::
+* Nesting music expressions::
+* On the un-nestedness of brackets and ties::
@end menu
@node Introduction to the LilyPond file structure
A basic example of a lilypond input file is
@example
-\version "2.11.23"
+\version @w{"@version{}"}
\score @{
@var{...compound music expression...} % all the music goes here!
\header @{ @}
There are many variations of this basic pattern, but this
example serves as a useful starting place.
-At this point, you may be confused, since you have never seen a
-@code{\score@{@}} before. This is because LilyPond automatically
-adds the extra commands when you give it simple input. LilyPond
-treats input like this:
+Up to this point none of the examples you have seen 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'' @{
as shorthand for this:
@example
-\score @{
- \relative c'' @{
- c4 a b c
+\book @{
+ \score @{
+ \new Staff @{
+ \new Voice @{
+ \relative c'' @{
+ c4 a b c
+ @}
+ @}
+ @}
+ \layout @{ @}
@}
- \layout @{ @}
@}
@end example
In other words, if the input contains a single music expression,
LilyPond will interpret the file as though the music expression
-was wrapped up inside a @code{\score@{@}}.
-
-@smallspace
+was wrapped up inside the commands shown above. For now, though,
+let us return to the first example and examine the @code{\score}
+command, leaving the others to default.
-A @code{\score} must begin with a compound music expression.
+A @code{\score} block must always contain just one music
+expression, and
+this must appear immediately after the @code{\score} command.
Remember that a music expression could be anything from a single
-note to a huge
+note to a huge compound expression like
@example
@{
Since everything is inside @code{@{ ... @}}, it counts
as one music expression.
-As we saw previously, the @code{\score} can contain other things,
-such as
+As we saw previously, the @code{\score} block can contain other
+things, such as
@example
\score @{
@noindent
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
+@code{\score} command. That's just another shorthand that LilyPond
accepts.
-@smallspace
+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
@}
\score @{
- @{ \melody @}
+ \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{pianorighthand}, or @code{foofoobarbaz}. You can use
-whatever variable names you want. For more details, see
-@ruser{Saving typing with variables and functions}.
+the names -- it could be @code{melody}, @code{global},
+@code{TimeKey},
+@code{pianorighthand}, or @code{foofoobarbaz}. For more details,
+see @ref{Saving typing with variables and functions}.
+Remember that you can use almost any name you like as long
+as it contains just alphabetic characters and is distinct from
+LilyPond command names. The exact
+limitations on variable names are detailed in
+@ruser{File structure}.
-@seealso
-For a complete definition of the input format, see @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
there @emph{is} no mystery. This line explains it all:
@quotation
-@emph{A @code{\score} must begin with a compound music expression.}
+@emph{A @code{\score} block 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 @{
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 @{
- @{
- <<
- \new Staff = "singer" <<
- >>
- \new PianoStaff = piano <<
- >>
+ <<
+ \new Staff = "singer" <<
>>
- @}
+ \new PianoStaff = piano <<
+ >>
+ >>
\layout @{ @}
@}
@end example
-Remember that we use @code{<<} and @code{>>} to show simultaneous
+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!
-
-@example
-\score @{
- @{
- <<
- \new Staff = "singer" <<
- \new Voice = "vocal" @{ @}
- >>
- \new Lyrics \lyricsto vocal \new Lyrics @{ @}
- \new PianoStaff = "piano" <<
- \new Staff = "upper" @{ @}
- \new Staff = "lower" @{ @}
- >>
+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 }
>>
- @}
- \layout @{ @}
-@}
-@end example
+ \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
@example
\relative c'' @{
- a4 b c d
+ 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.
+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:
-@example
-melody = @{ @}
-text = @{ @}
-upper = @{ @}
-lower = @{ @}
-\score @{
- @{
- <<
- \new Staff = "singer" <<
- \new Voice = "vocal" @{ \melody @}
- >>
- \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
- \new PianoStaff = "piano" <<
- \new Staff = "upper" @{ \upper @}
- \new Staff = "lower" @{ \lower @}
- >>
+@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 }
>>
- @}
- \layout @{ @}
-@}
-@end example
+ \new PianoStaff = "piano" <<
+ \new Staff = "upper" { \upper }
+ \new Staff = "lower" {
+ \clef "bass"
+ \lower
+ }
+ >>
+ >>
+ \layout { }
+}
+@end lilypond
-@noindent
-Remember that you can use almost any name you like. The
-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
+
+@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
-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, 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
-TODO: add intro about voices vs. layers vs. whatever.
+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 \\
-TODO: sex this up with colors and stuff. -gp
+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
-TODO: actually, a general rewrite is needed. -gp
+Notice how the stems of the second voice now point down.
+Here's another simple example:
-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{\\}
+@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
-@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
+
+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
-@cindex layers
+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
-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
+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
-@lilypond[quote,verbatim,fragment]
-\new Staff \relative c' {
- \override NoteHead #'style = #'cross
- \override NoteHead #'color = #red
- c16 d e f
+@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
<<
- { g4 f e } \\
- { \override NoteHead #'style = #'triangle
- \override NoteHead #'color = #blue
- r8 e4 d c8 ~ }
+ { % 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
<<
- { d2 e2 } \\
- { c8 b16 a b8 g ~ g2 } \\
- { \override NoteHead #'style = #'slash
- \override NoteHead #'color = #green
- s4 b4 c2 }
+ { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { <ees c>2 des2 }
>>
+ <c ees aes c>1
}
@end lilypond
-Polyphony does not change the relationship of notes within a
-@code{\relative @{ @}} block. Each note is calculated relative to
-the note immediately preceding it.
+@cindex stem down
+@cindex stem up
-@example
-\relative @{ noteA << noteB \\ noteC >> noteD @}
-@end example
+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:
-@code{noteC} is relative to @code{noteB}, not @code{noteA};
-@code{noteD} is relative to @code{noteC}, not @code{noteB} or
-@code{noteA}.
+@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
-TODO: more colors and stuff.
+@funindex \voiceOne
+@funindex \voiceTwo
+@funindex \voiceThree
+@funindex \voiceFour
-@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. 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:
-Specifically,
@example
-<< \upper \\ \lower >>
+\new Staff @{
+ \relative c' @{
+ << @{ e4 f g a @} \\ @{ c,4 d e f @} >>
+ @}
+@}
@end example
@noindent
-is equivalent to
+is equivalent to
@example
-<<
- \new Voice = "1" @{ \voiceOne \upper @}
- \new Voice = "2" @{ \voiceTwo \lower @}
+\new Staff <<
+ \new Voice = "1" @{ \voiceOne \relative c' @{ e4 f g a @} @}
+ \new Voice = "2" @{ \voiceTwo \relative c' @{ c4 d e f @} @}
>>
@end example
+Both of the above would produce
+
+@c The following example should not display the code
+@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. 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'{
+ % 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
- <<
- { 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 d8 ~ d e4 ( f g a ) b-> c
\oneVoice
+ c, d8 ~ d e4 ( f g a ) b-> c
}
@end lilypond
-The correct definition of the voices allows the melody to be
-slurred.
+@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
- \voiceOne
+ % Start simultaneous section of three voices
<<
+ % Continue the main voice in parallel
{ g4 f e | d2 e2) }
- \context Voice="1" { \voiceTwo
+ % Initiate second voice
+ \new Voice {
+ % Set stems, etc, down
+ \voiceTwo
r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
- \oneVoice
}
- \new Voice { \voiceThree
- s2. s4 b4 c2
- \oneVoice
+ % Initiate third voice
+ \new Voice {
+ % Set stems, etc, up
+ \voiceThree
+ 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' <<
+ % 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{\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{\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]
<<
>>
@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" {
+ \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 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::
-* Up and down::
-* Distances and measurements MAYBE MOVE::
+* Contexts explained::
+* Creating contexts::
+* Engravers explained::
+* Modifying context properties::
+* Adding and removing engravers::
@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
+@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
-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 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
-@node Up and down
-@subsection Up and down
+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.
-TODO: everything
+@subsubheading Changing a single context
-By default, lilypnod does a pretty jazz'n job of picking
-directions. But in some cases, it may be desirable to force a
-direction.
+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.
-@verbatim
--
-^ _
-@end verbatim
+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:
-@node Distances and measurements MAYBE MOVE
-@subsection Distances and measurements MAYBE MOVE
+@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
-DISCUSS after working on other sections.
+@subsubheading Changing all contexts of the same type
-TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
+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. But how can you
-get the staves that you want? The templates are ok, but what if you
-want something that isn't covered?
+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::
-* TODO another example of extending templates::
+* Four-part SATB vocal score::
+* Building a score from scratch::
@end menu
@node Soprano and cello
soprano part).
@example
-\version "2.11.23"
+\version @w{"@version{}"}
melody = \relative c' @{
\clef treble
\key c \major
\time 4/4
-
a4 b c d
@}
Aaa Bee Cee Dee
@}
-\score@{
+\score @{
<<
\new Voice = "one" @{
\autoBeamOff
Now we want to add a cello part. Let's look at the @q{Notes only} example:
@example
-\version "2.11.23"
+\version @w{"@version{}"}
melody = \relative c' @{
\clef treble
\key c \major
\time 4/4
-
a4 b c d
@}
\score @{
-\new Staff \melody
-\layout @{ @}
-\midi @{ @}
+ \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
+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.
+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"
+\version @w{"@version{}"}
sopranoMusic = \relative c' @{
\clef treble
\key c \major
\time 4/4
-
a4 b c d
@}
\clef bass
\key c \major
\time 4/4
-
d4 g fis8 e d4
@}
-\score@{
+\score @{
<<
\new Voice = "one" @{
\autoBeamOff
@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
+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@{
+\score @{
<<
- <<
- \new Voice = "one" @{
- \autoBeamOff
- \sopranoMusic
- @}
- \new Lyrics \lyricsto "one" \sopranoLyrics
- >>
- \new Staff \celloMusic
+ <<
+ \new Voice = "one" @{
+ \autoBeamOff
+ \sopranoMusic
+ @}
+ \new Lyrics \lyricsto "one" \sopranoLyrics
+ >>
+ \new Staff \celloMusic
>>
\layout @{ @}
\midi @{ @}
easily fixed. Here's the complete soprano and cello template.
@lilypond[quote,verbatim,ragged-right]
-\version "2.11.23"
+\version "2.11.38"
sopranoMusic = \relative c' {
\clef treble
\key c \major
\time 4/4
-
a4 b c d
}
\clef bass
\key c \major
\time 4/4
-
d4 g fis8 e d4
}
-\score{
+\score {
<<
<<
\new Voice = "one" {
@end lilypond
-@node TODO another example of extending templates
-@subsection TODO another example of extending templates
+@node Four-part SATB vocal score
+@subsection Four-part SATB vocal score
-TODO: somebody else fill this in. You guys like vocal stuff,
-right? Get to it. :) -gp
+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
-@node Scores and parts
-@section Scores and parts
+ \new PianoStaff <<
+ \set PianoStaff.instrumentName = "Piano "
+ \new Staff = "upper" \upper
+ \new Staff = "lower" \lower
+ >>
+ >>
+}
+@end lilypond
-TODO: this is really old stuff from the really old tutorial.
-Rewrite, fix, etc. Or maybe delete entirely. -gp
+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:
-In orchestral music, all notes are printed twice. Once in a part for
-the musicians, and once in a full score for the conductor. Variables can
-be used to avoid double work. The music is entered once, and stored in
-a variable. The contents of that variable is then used to generate
-both the part and the full score.
+@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
-It is convenient to define the notes in a special file. For example,
-suppose that the file @file{horn-music.ly} contains the following part
-of a horn/@/bassoon duo
+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
-hornNotes = \relative c @{
- \time 2/4
- r4 f8 a cis4 f e d
-@}
+\new PianoStaff <<
+ \set PianoStaff.instrumentName = "Piano "
+ \new Staff = "upper" \upper
+ \new Staff = "lower" \lower
+>>
@end example
-@noindent
-Then, an individual part is made by putting the following in a file
+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
-\include "horn-music.ly"
-\header @{
- instrument = "Horn in F"
-@}
+<< % 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
-@{
- \transpose f c' \hornNotes
-@}
+ \new PianoStaff <<
+ \set PianoStaff.instrumentName = "Piano "
+ \new Staff = "upper" \upper
+ \new Staff = "lower" \lower
+ >>
+>>
@end example
-The line
+Combining all these together and adding the music
+for the three bars of the example above gives:
-@example
-\include "horn-music.ly"
-@end example
+@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 |
+}
-@noindent
-substitutes the contents of @file{horn-music.ly} at this position in
-the file, so @code{hornNotes} is defined afterwards. The command
-@code{\transpose f@tie{}c'} indicates that the argument, being
-@code{\hornNotes}, should be transposed by a fifth upwards. Sounding
-@samp{f} is denoted by notated @code{c'}, which corresponds with the
-tuning of a normal French Horn in@tie{}F. The transposition can be seen
-in the following output
+\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
-@lilypond[quote,ragged-right]
-\transpose f c' \relative c {
- \time 2/4
- r4 f8 a cis4 f e d
+ \new PianoStaff <<
+ \set PianoStaff.instrumentName = "Piano "
+ \new Staff = "upper" \upper
+ \new Staff = "lower" \lower
+ >>
+ >>
}
@end lilypond
-
-In ensemble pieces, one of the voices often does not play for many
-measures. This is denoted by a special rest, the multi-measure
-rest. It is entered with a capital @samp{R} followed by a duration
-(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
-etc.). By multiplying the
-duration, longer rests can be constructed. For example, this rest
-takes 3@tie{}measures in 2/4 time
+
+
+@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
-R2*3
+\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
-When printing the part, multi-rests
-must be condensed. This is done by setting a run-time variable
+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
-\set Score.skipBars = ##t
+ \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
-@noindent
-This command sets the property @code{skipBars} in the
-@code{Score} context to true (@code{##t}). Prepending the rest and
-this option to the music above, leads to the following result
+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.
-@lilypond[quote,ragged-right]
-\transpose f c' \relative c {
- \time 2/4
- \set Score.skipBars = ##t
- R2*3
- r4 f8 a cis4 f e d
-}
-@end lilypond
+@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.
-The score is made by combining all of the music together. Assuming
-that the other voice is in @code{bassoonNotes} in the file
-@file{bassoon-music.ly}, a score is made with
+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
-\include "bassoon-music.ly"
-\include "horn-music.ly"
-
-<<
- \new Staff \hornNotes
- \new Staff \bassoonNotes
->>
+\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
-@noindent
-leading to
+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,ragged-right]
-\relative c <<
- \new Staff {
- \time 2/4 R2*3
- r4 f8 a cis4 f e d
- }
- \new Staff {
- \clef bass
- r4 d,8 f | gis4 c | b bes |
- a8 e f4 | g d | gis f
+@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
+
+
+
+