--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; fill-column: 60 -*-
+
+@ignore
+ Translation of GIT committish: 66dd932f6519b7913400a838c5efbc5407e06cd8
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
+@end ignore
+
+@c Translator: Jan Nieuwenhuizen
+@c Translation checker:
+@c Translation checker committish:
+
+@c \version "2.14.0"
+
+@node Fundamentele concepten
+@translationof Fundamental concepts
+@chapter Fundamentele concepten
+
+In het Leerboek hebben we gezien hoe je prachtig geprinte
+muziek maakt van een eenvoudig tekstbestand. Dit hoofdstuk
+introduceert de achterliggende concepten en benodigde
+technieken voor het maken van ingewikkeldere partituren die
+er net zo mooi uitzien.
+
+@menu
+* Hoe LilyPond-invoerbestanden werken::
+* Voices contain music::
+* Contexts and engravers::
+* Extending the templates::
+@end menu
+
+
+@node Hoe LilyPond-invoerbestanden werken
+@translationof How LilyPond input files work
+@section Hoe LilyPond-invoerbestanden werken
+
+Het LilyPond invoerformaat is tamelijk vrij, wat ervaren
+gebruikers veel flexibiliteit geeft hun bestanden te
+structureren zoals ze dat wensen. Deze flexibiliteit kan
+verwarrend zijn voor nieuwe gebruikers. Deze paragraaf legt
+het een en ander uit over deze structuur. Om het leesbaar
+te houden worden details weggelaten. Een complete
+beschrijving van het invoerformaat is te vinden in
+@ruser{File structure}.
+
+@menu
+* Inleiding in de LilyPond-bestandsstructuur::
+* Score is a (single) compound musical expression::
+* Nesting music expressions::
+* On the un-nestedness of brackets and ties::
+@end menu
+
+@node Inleiding in de LilyPond-bestandsstructuur
+@translationof Introduction to the LilyPond file structure
+@subsection Inleiding in de LilyPond-bestandsstructuur
+
+@cindex invoerformaat
+@cindex bestandsstructuur
+
+Een basisvoorbeeld van een LilyPond-invoerbestand is
+
+@example
+\version @w{"@version{}"}
+
+\header @{ @}
+
+\score @{
+ @var{...samengestelde muziekuitdrukking...} % alle muziek komt hier!
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+
+@noindent
+Er zijn veel variaties op dit basispatroon maar dit
+voorbeeld dient als een handig beginpunt.
+
+@funindex \book
+@funindex boek
+@funindex \score
+@funindex partituur
+@cindex boek
+@cindex partituur
+
+Tot nu toe heeft geen van de voorbeelden het
+@code{\score@{@}}-commando gebruikt. Dit kan omdat LilyPond
+automatisch de extra commando's toevoegt die benodigt zijn
+als je het eenvoudige invoer geeft. LilyPond behandelt invoer
+zoals dit:
+
+@example
+\relative c'' @{
+ c4 a d c
+@}
+@end example
+
+@noindent
+als een afkorting voor dit:
+
+@example
+\book @{
+ \score @{
+ \new Staff @{
+ \new Voice @{
+ \relative c'' @{
+ c4 a b c
+ @}
+ @}
+ @}
+ \layout @{ @}
+ @}
+@}
+@end example
+
+Anders gezegd, als de invoer een enkelvoudige
+muziekuitdrukking bevat, interpreteert LilyPond het bestand
+alsof die muziekuitdrukking ingepakt is in bovenstaande
+commando's.
+
+@cindex impliciete contexten
+@cindex contexten, impliciet
+
+@strong{Een kleine waarschuwing!} In veel van de voorbeelden
+in de LilyPond-documentatie worden de @code{\new Staff}- en
+@code{\new Voice}-commando's weggelaten en worden ze
+impliciet aangemaakt. Voor eenvoudige voorbeelden werkt dat
+goed, maar voor ingewikkelde voorbeelden, vooral wanneer
+additionele commando's worden gebruikt, kan het impliciete
+aanmaken van contexten verrassende resultaten opleveren,
+zoals extra ongewenste notebalken. Hoe je contexten
+expliciet specificeert, wordt uitgelegd in @ref{Contexts and
+engravers}.
+
+@warning{Voor het invoeren van meer dan enkele regels muziek
+wordt aangeraden altijd notenbalken en stemmen expliciet te
+specificeren.}
+
+Laten we terugkeren naar het eerste voorbeeld en het
+@code{\score}-commando beter bekijken.
+
+Een @code{\score}-blok moet altijd precies één
+muziekuitdrukking bevatten, en die moet direct na het
+@code{\score}-commando staan. Herrinner je dat een
+muziekuitdrukking alles kan zijn van een enkele noot
+tot een enorme samengestelde uitdrukking zoals
+
+@example
+@{
+ \new StaffGroup <<
+ @var{...vul de volledige partituur van een Wagner opera hier in...}
+ >>
+@}
+@end example
+
+@noindent
+Omdat alles tussen @code{@{ ... @}} staat, telt het als één
+muziekuitdrukking.
+
+Zoals we eerder al zagen, kan het @code{\score}-blok
+allerlei andere dingen bevatten, zoals
+
+@example
+\score @{
+ @{ c'4 a b c' @}
+ \header @{ @}
+ \layout @{ @}
+ \midi @{ @}
+@}
+@end example
+
+@funindex \header
+@funindex kop
+@funindex \layout
+@funindex layout
+@funindex \midi
+@funindex midi
+@cindex kop
+@cindex opmaak
+@cindex midi
+
+@noindent
+Merk op dat deze drie commando's -- @code{\header},
+@code{\layout} en @code{\midi} -- speciaal zijn: in
+tegenstelling tot veel andere commando's die met een
+backslash (@code{\}) beginnen zijn het @emph{geen}
+muziekuitdrukkingen en ze zijn ook geen onderdeel van een
+muziekuitdrukking. Ze kunnen zowel binnen als buiten het
+@code{\score}-blok worden geplaatst. Deze commando's worden
+gewoonlijk dan ook buiten het @code{\score}-blok gezet
+-- bijvoorbeeld, @code{\header} staat meestal boven het
+@code{\score}-commando, zoals het in eerste voorbeeld van
+deze paragraaf.
+
+De twee andere commando's die je niet eerder hebt gezien
+zijn @code{\layout @{ @}} en @code{\midi @{@}}. Als deze
+gebruikt worden als hierboven laten ze LilyPond
+respectievelijk geprinte- en MIDI-uitvoer genereren. Een
+volledige beschrijving van deze commando's is te vinden in
+de Notatiehandleiding -- @ruser{Score layout}, en
+@ruser{Creating MIDI files}.
+
+@cindex partituren, verscheidene
+@cindex boek blok, impliciet
+@cindex impliciet boek blok
+@funindex \book
+@funindex boek
+
+Je kunt meer dan een @code{\score}-blok gebruiken. Elk
+wordt behandeld als een afzonderlijke partituur en ze worden
+allemaal samengevoegd in een enkel uitvoerbestand. Een
+@code{\book}-commando is niet nodig -- die wordt impliciet
+aangemaakt. Echter, als je afzonderlijke uitvoerbestanden
+vanuit een @file{.ly}-bestand wil maken, dan moet het
+@code{\book}-commando worden gebruikt om de verschillende
+secties aan te geven: elk @code{\book}-blok produceert
+een apart uitvoerbestand.
+
+Samengevat:
+
+Elk @code{\book}-blok geeft een apart uitvoerbestand (bijv.,
+een PDF-bestand). Als je er geen expliciet toevoegt, stopt
+LilyPond je gehele invoercode impliciet in een
+@code{\book}-blok.
+
+Elk @code{\score}-blok is een apart brok muziek binnen een
+@code{\book}-blok.
+
+@cindex opmaakblok, effect van locatie
+
+Elk @code{\layout}-blok beïnvloedt het @code{\score}- of
+@code{\book}-blok waarin het voorkomt -- d.w.z., een
+@code{\layout}-blok binnen een @code{\score}-blok heeft
+uitsluitend invloed op dat @code{\score}-blok, maar een
+@code{\layout}-blok buiten een @code{\score}-blok (en dus
+binnen een @code{\book}-blok, expliciet danwel impliciet)
+beïnvloedt elke @code{\score} in dat @code{\book}.
+
+Voor details zie @ruser{Multiple scores in a book}.
+
+@cindex variabelen
+
+Een andere manier van afkorten is het gebruik van
+variabelen, zoals getoond in @ref{Stukken organiseren met
+variabelen}. Alle sjablonen gebruiken dat:
+
+@example
+melodie = \relative c' @{
+ c4 a b c
+@}
+
+\score @{
+ \melodie
+@}
+@end example
+
+Als LilyPond naar dit bestand kijkt, neemt het de waarde van
+@code{melodie} (alles na het isgelijkteken) en voegt die in
+zodra ergens @code{\melody} staat. De naam van de variable
+heeft verder geen speciale betekenis -- het kan net zo goed
+@code{melodie}, @code{globaal}, @code{TijdSleutel},
+@code{pianorechterhand}, of iets anders zijn. Bedenk dat je
+vrijwel elke naam kunt gebruiken die je wilt, zolang die
+maar bestaat uit letters en het niet de naam is van een
+LilyPond-commando. Voor meer details, zie @ref{Saving
+typing with variables and functions}. De precieze
+beperkingen van variabelenamen staan beschreven in
+@ruser{File structure}.
+
+
+@seealso
+Voor een volledige definitie van het invoerformaat, zie
+@ruser{File structure}.
+
+
+@node Score is a (single) compound musical expression
+@subsection Score is a (single) compound musical expression
+
+@funindex \score
+@funindex score
+@cindex score
+@cindex contents of a score block
+@cindex score block, contents of
+@cindex compound music expression
+@cindex music expression, compound
+
+We saw the general organization of LilyPond input files in the
+previous section, @ref{Introduction to the LilyPond file structure}.
+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
+To understand what is meant by a music expression and a compound
+music expression, you may find it useful to review the tutorial,
+@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. For simplicity, we'll use
+just a singer and piano in our example. We don't need a
+@code{StaffGroup} for this ensemble, which simply groups a number
+of staves together with a bracket at the left, but we do need
+staves for a singer and a piano, though.
+
+@example
+\score @{
+ <<
+ \new Staff = "singer" <<
+ >>
+ \new PianoStaff = "piano" <<
+ >>
+ >>
+ \layout @{ @}
+@}
+@end example
+
+Here we have given names to the staves -- @qq{singer} and
+@qq{piano}. This is not essential here, but it is a useful habit
+to cultivate so that you can see at a glance what each stave is
+for.
+
+Remember that we use @code{<< ... >>} instead of @code{@{ ... @}} to
+show simultaneous music. This causes the vocal part and piano part
+to appear one above the other in the score. The @code{<< ... >>}
+construct would not be necessary for the Singer staff in the example
+above if it were going to contain only one sequential music
+expression, but @code{<< ... >>} rather than braces is necessary if
+the music in the Staff is to contain two or more simultaneous
+expressions, e.g. two simultaneous Voices, or a Voice with lyrics.
+We're going to have a voice with lyrics, so angle brackets are
+required. We'll add some real music later; for now let's just put
+in some dummy notes and lyrics. If you've forgotten how to add lyrics
+you may wish to review @code{\addlyrics} in @ref{Setting simple songs}.
+
+@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), although the lower staff has yet to be given a bass
+clef.
+
+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? To ensure the contents of the
+@code{text} variable are interpreted as lyrics we preface them with
+@code{\lyricmode}. Like @code{\addlyrics}, this switches the input
+mode to lyrics. Without that, LilyPond would try to interpret the
+contents as notes, which would generate errors. (Several other
+input modes are available, see @ruser{Input modes}.)
+
+So, adding a few notes and a bass clef for the left hand, 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 e }
+
+\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
+
+When writing (or reading) a @code{\score} section, just take it
+slowly and carefully. Start with the outer level, then work on
+each smaller level. It also really helps to be strict with
+indentation -- make sure that each item on the same level starts
+on the same horizontal position in your text editor.
+
+
+@seealso
+Notation Reference: @ruser{Structure of a score}.
+
+
+@node Nesting music expressions
+@subsection Nesting music expressions
+
+@cindex staves, temporary
+@cindex temporary staves
+@cindex ossias
+
+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
+ <<
+ { f8 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 beginning of the line. This is usual for clefs printed
+in the middle of a line.
+
+@cindex staff, positioning
+
+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
+ <<
+ { f8 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 behavior
+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.
+
+
+@seealso
+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},
+and @ruser{Ossia staves}.
+
+
+@node On the un-nestedness of brackets and ties
+@subsection On the un-nestedness of brackets and ties
+
+@cindex brackets, nesting
+@cindex bracket types
+@cindex brackets, enclosing vs. marking
+
+You have already met a number of different types of bracket and
+bracket-like constructs in writing the input file to LilyPond.
+These obey different rules which can be confusing at first.
+Let's first review the different types of brackets and bracket-like
+constructs.
+
+@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 simultaneous music expressions
+@item @code{( .. )}
+ @tab Marks the start and end of a slur
+@item @code{\( .. \)}
+ @tab Marks the start and end of a phrasing slur
+@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 bracket-like constructs, 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 or
+bracket-like constructs. 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] g4 }
+@end lilypond
+
+In general, different kinds of brackets, bracket-like constructs,
+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[ g \times 2/3 { r16 e'8] }
+ g16( a \times 2/3 { b16 d) e' }
+ g8[( a \times 2/3 { b8 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 multiple voices
+@cindex voices, multiple
+@cindex Voice context
+@cindex context, Voice
+@cindex simultaneous music
+@cindex music, simultaneous
+@cindex concurrent music
+@cindex music, concurrent
+@cindex voices vs. chords
+@cindex chords vs. voices
+
+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 sequential 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
+
+
+@cindex voices, naming
+@cindex voices crossing brackets
+@cindex slurs crossing brackets
+@cindex ties crossing brackest
+
+This example has just two voices, but the same construct 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 e } \\ { c8 b16 a b8 g~ g2 } \\ { s4 b 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 e }
+ \\
+ % Voice 2 continues
+ { c8 b16 a b8 g~ g2 }
+ \\
+ {
+ \voiceThreeStyle
+ s4 b c2
+ }
+ >> |
+}
+@end lilypond
+
+@funindex \voiceOneStyle
+@funindex \voiceTwoStyle
+@funindex \voiceThreeStyle
+@funindex \voiceFourStyle
+@funindex \voiceNeutralStyle
+
+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; @code{\voiceNeutralStyle} (also not
+used here) reverts the style back to the default.
+We shall see later how commands like these may be created by the
+user.
+See @ref{Visibility and color of objects} and
+@ref{Using variables for tweaks}.
+
+@cindex polyphony and relative note entry
+@cindex relative note entry and polyphony
+
+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 analyze 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 des }
+ >> |
+ <c ees aes c>1 |
+}
+@end lilypond
+
+@cindex stem down
+@cindex voices and stem directions
+@cindex stem directions and voices
+@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 by skipping voice three
+and placing the music in voice four. This is done by simply
+adding another pair of @code{\\}.
+
+@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 des }
+ >> |
+ <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, 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 @code{force-hshift} property in @ref{Fixing
+overlapping notation}.
+
+
+@seealso
+Notation Reference: @ruser{Multiple voices}.
+
+
+@node Explicitly instantiating voices
+@subsection Explicitly instantiating voices
+
+@funindex \voiceOne
+@funindex voiceOne
+@funindex \voiceTwo
+@funindex voiceTwo
+@funindex \voiceThree
+@funindex voiceThree
+@funindex \voiceFour
+@funindex voiceFour
+@funindex \oneVoice
+@funindex oneVoice
+@funindex \new Voice
+@cindex voice contexts, creating
+
+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
+
+@cindex voices, reverting to single
+@cindex reverting to a single voice
+
+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 behavior or behavior after \oneVoice
+ c4 d8~ d e4( f | g4 a) b-> c |
+}
+@end lilypond
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ \voiceOne
+ c4 d8~ d e4( f | g4 a) b-> c |
+ \oneVoice
+ c,4 d8~ d e4( f | g4 a) b-> c |
+}
+@end lilypond
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ \voiceTwo
+ c4 d8~ d e4( f | g4 a) b-> c |
+ \oneVoice
+ c,4 d8~ d e4( f | g4 a) b-> c |
+}
+@end lilypond
+
+Now let's look at three different ways to notate the same passage
+of polyphonic music, each of which is advantageous in different
+circumstances, using the example from the previous section.
+
+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 our
+example. 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 e) | }
+ % 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 b c2 |
+ }
+ >>
+}
+@end lilypond
+
+@cindex nesting music expressions
+@cindex nesting simultaneous constructs
+@cindex nesting voices
+@cindex voices, temporary
+@cindex voices, nesting
+
+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 e) | }
+ \new Voice {
+ \voiceTwo
+ r8 e4 d c8~ |
+ <<
+ { c8 b16 a b8 g~ g2 | }
+ \new Voice {
+ \voiceThree
+ s4 b c2 |
+ }
+ >>
+ }
+ >>
+}
+@end lilypond
+
+@cindex spacing notes
+
+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 e) |
+ }
+ % 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 b c2 |
+ }
+>>
+@end lilypond
+
+@subsubheading Note columns
+
+@cindex note column
+@cindex note collisions
+@cindex collisions, notes
+@cindex shift commands
+@funindex \shiftOff
+@funindex shiftOff
+@funindex \shiftOn
+@funindex shiftOn
+@funindex \shiftOnn
+@funindex shiftOnn
+@funindex \shiftOnnn
+@funindex shiftOnnn
+
+Closely spaced notes in a chord, or notes occurring 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.
+
+
+@seealso
+Notation Reference: @ruser{Multiple voices}.
+
+
+@node Voices and vocals
+@subsection Voices and vocals
+
+Vocal music presents a special difficulty: we need to combine two
+expressions -- notes and lyrics.
+
+@funindex \new Lyrics
+@funindex \lyricsto
+@funindex lyricsto
+@funindex Lyrics
+@cindex Lyrics context, creating
+@cindex lyrics, linking to voice
+
+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
+
+Note that the lyrics must be linked to a @code{Voice} context,
+@emph{not} a @code{Staff} context. This is a case where it is
+necessary to create @code{Staff} and @code{Voice} contexts
+explicitly.
+
+@cindex lyrics and beaming
+@cindex beaming and lyrics
+@funindex \autoBeamOff
+@funindex autoBeamOff
+
+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.
+
+@funindex \new ChoirStaff
+@funindex ChoirStaff
+@funindex \lyricmode
+@funindex lyricmode
+@cindex vocal score structure
+@cindex choir staff
+
+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 = { \key f \major \time 6/8 \partial 8 }
+
+SopOneMusic = \relative c'' {
+ c8 | c8([ bes)] a a([ g)] f | f'4. b, | c4.~ c4
+}
+SopOneLyrics = \lyricmode {
+ Let | flee -- cy flocks the | hills a -- dorn, __
+}
+SopTwoMusic = \relative c' {
+ r8 | r4. r4 c8 | a'8([ g)] f f([ e)] d | e8([ d)] c bes'
+}
+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.
+
+@cindex hymn structure
+@cindex SATB structure
+@cindex vocal scores with multiple verses
+@cindex multiple vocal verses
+@cindex verses, multiple vocal
+
+Here is an 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. Note how we use variables to separate the
+music notation and words from the staff structure. See too
+how a variable, which we have chosen to call @q{keyTime}, is used
+to hold several commands for use within the two staves. In other
+examples this is often called @q{global}.
+
+@lilypond[quote,verbatim]
+keyTime = { \key c \major \time 4/4 \partial 4 }
+
+SopMusic = \relative c' { c4 | e4. e8 g4 g | a4 a g }
+AltoMusic = \relative c' { c4 | c4. c8 e4 e | f4 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 \keyTime \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 \keyTime \TenorMusic }
+ \new Voice = "Bass" { \voiceTwo \BassMusic }
+ >>
+ >>
+}
+@end lilypond
+
+
+@seealso
+Notation Reference: @ruser{Vocal music}.
+
+
+@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
+
+@cindex 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. | a4 a2. |
+@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 parsed from left to right, similar to the way a performer
+reads the score. 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, an accidental affects only 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 introduced the @code{Voice} context.
+Others are the @code{Staff} and @code{Score} contexts. Contexts are
+hierarchical to reflect the hierarchical 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 capitalized and joined immediately to the
+preceding word with no hyphen or underscore, e.g.,
+@code{GregorianTranscriptionStaff}.
+
+
+@seealso
+Notation Reference: @ruser{Contexts explained}.
+
+
+@node Creating contexts
+@subsection Creating contexts
+
+@funindex \new
+@funindex new
+@cindex new contexts
+@cindex creating contexts
+@cindex contexts, creating
+
+In an input file a score block, introduced with a @code{\score}
+command, contains a single music expression and an associated
+output definition (either a @code{\layout} or a @code{\midi} block).
+The @code{Score} context is usually left to be created automatically
+when the interpretation of that music expression starts.
+
+For scores with only one voice and one staff, the @code{Voice} and
+@code{Staff} contexts may also 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
+
+@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 a @code{\new Score} command is not normally required,
+as the essential top-level @code{Score} context is created
+automatically when the music expression within the @code{\score}
+block is interpreted. The only reason for creating a @code{Score}
+context explicitly using @code{\new Score} is to introduce a
+@code{\with} block in which one or more score-wide default values
+of context properties may be specified. Information on using
+@code{\with} blocks can be found under the heading
+@qq{Setting context properties with @code{\\with} } in
+@ref{Modifying context properties}.)
+
+You have seen many practical examples which created new
+@code{Staff} and @code{Voice} contexts in earlier sections, but
+to remind you how these commands are used in practice, here's an
+annotated real-music example:
+
+@lilypond[quote,verbatim,ragged-right]
+\score { % start of single compound music expression
+ << % start of simultaneous staves section
+ \time 2/4
+ \new Staff { % create RH staff
+ \clef "treble"
+ \key g \minor
+ \new Voice { % create voice for RH notes
+ \relative c'' { % start of RH notes
+ d4 ees16 c8. |
+ d4 ees16 c8. |
+ } % end of RH notes
+ } % end of RH voice
+ } % end of RH staff
+ \new Staff << % create LH staff; needs two simultaneous voices
+ \clef "bass"
+ \key g \minor
+ \new Voice { % create LH voice one
+ \voiceOne
+ \relative g { % start of LH voice one notes
+ g8 <bes d> ees, <g c> |
+ g8 <bes d> ees, <g c> |
+ } % end of LH voice one notes
+ } % end of LH voice one
+ \new Voice { % create LH voice two
+ \voiceTwo
+ \relative g { % start of LH voice two notes
+ g4 ees |
+ g4 ees |
+ } % end of LH voice two notes
+ } % end of LH voice two
+ >> % end of LH staff
+ >> % end of simultaneous staves section
+} % end of single compound music expression
+@end lilypond
+
+(Note how all the statements which open a block with either a
+curly bracket, @code{@{}, or double angle brackets, @code{<<},
+are indented by two further spaces, and the corresponding
+closing bracket is indented by exactly the same amount. While
+this is not required, following this practice will greatly
+reduce the number of @q{unmatched bracket} errors, and is
+strongly recommended. It enables the structure of the music to
+be seen at a glance, and any unmatched brackets will be obvious.
+Note too how the LH staff is created using double angle brackets
+because it requires two voices for its music, whereas the RH staff
+is created with a single music expression surrounded by curly
+brackets because it requires only one voice.)
+
+@cindex contexts, naming
+@cindex naming contexts
+
+The @code{\new} command may also give an 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. Digits and spaces can also be used in the
+identifying name, but then it has to be placed in quotes,
+i.e. @code{\new Staff = "MyStaff 1" @var{music-expression}}.
+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, see @ref{Voices and vocals}.
+
+
+@seealso
+Notation Reference: @ruser{Creating contexts}.
+
+
+@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 apply 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 @code{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 capitalized,
+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 usually 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 Completion_heads_engraver
+ @tab Splits notes which cross bar lines
+@c The old Dynamic_engraver is deprecated. -jm
+@item New_dynamic_engraver
+ @tab Creates hairpins and dynamic texts
+@item Forbid_line_break_engraver
+ @tab Prevents line breaks if a musical element is still active
+@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 tremolos
+@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.
+
+
+@seealso
+Internals reference: @rinternals{Engravers and Performers}.
+
+
+@node Modifying context properties
+@subsection Modifying context properties
+
+@cindex context properties
+@cindex context properties, modifying
+@cindex modifying context properties
+@funindex \set
+@funindex set
+@funindex \unset
+@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 the current context (typically @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}.
+
+@cindex properties operating in contexts
+@cindex setting properties within contexts
+
+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 @code{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"
+ c2 c
+ }
+ \new Staff \relative c' {
+ \set instrumentName = #"Alto" % Wrong!
+ d2 d
+ }
+>>
+@end lilypond
+
+Remember the default context name is @code{Voice}, so the second
+@code{\set} command set the property @code{instrumentName} in the
+@code{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. In
+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. Some text editors with special support for LilyPond input
+files document property names with bullets when you hover them with
+the mouse, like JEdit with LilyPondTool, or highlight unknown property
+names differently, like ConTEXT. If you do not use an editor with
+such features, it is recommended to check the property name in the
+Internals Reference: see @rinternals{Tunable context properties}, or
+@rinternals{Contexts}.
+
+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'' {
+ ais2 aes
+ }
+ \new Staff \relative c'' {
+ \set Staff.extraNatural = ##f
+ ais2 aes
+ }
+>>
+@end lilypond
+
+@noindent
+and this turns them off in all staves:
+
+@lilypond[quote,verbatim,ragged-right]
+<<
+ \new Staff \relative c'' {
+ ais2 aes
+ }
+ \new Staff \relative c'' {
+ \set Score.extraNatural = ##f
+ ais2 aes
+ }
+>>
+@end lilypond
+
+As another example, if @code{clefOctavation} is set in
+the @code{Score} context this immediately changes the value
+of the octavation in all current staves and sets a new default
+value which will be applied to all staves.
+
+The opposite command, @code{\unset}, effectively removes the
+property from the context, which causes most properties to
+revert to their default value. Usually @code{\unset} is not
+required as a new @code{\set} command will achieve what is
+wanted.
+
+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 most recently set value.
+
+@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
+c4 d
+% make note heads smaller
+\set fontSize = #-4
+e4 f |
+% make note heads larger
+\set fontSize = #2.5
+g4 a
+% return to default size
+\unset fontSize
+b4 c |
+@end lilypond
+
+We have now seen how to set the values of several different types of
+property. Note that integers and numbers are always preceded by a
+hash sign, @code{#}, while a true or false value is specified by
+@code{##t} and @code{##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.
+
+@subsubheading Setting context properties with @code{\with}
+
+@funindex \with
+@funindex with
+@cindex context properties, setting with \with
+
+The default value of context properties may be set at the time the
+context is created. Sometimes this is a clearer way of setting 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 default 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'' {
+ gis4 ges aes ais
+ }
+ }
+ \new Staff \with { extraNatural = ##f } {
+ \relative c'' {
+ gis4 ges aes ais
+ }
+ }
+>>
+@end lilypond
+
+Or, if the property override is to be applied to all staves
+within the score, it may be appended to an explicit
+@code{\new Score} command, like this:
+
+@lilypond[quote,verbatim,ragged-right]
+\score {
+ \new Score \with { extraNatural = ##f } <<
+ \new Staff {
+ \relative c'' {
+ gis4 ges aes ais
+ }
+ }
+ \new Staff {
+ \relative c'' {
+ gis4 ges aes ais
+ }
+ }
+ >>
+}
+@end lilypond
+
+Properties set in this way may still be changed dynamically using
+@code{\set} and returned to the default value set in the
+@code{\with} block with @code{\unset}.
+
+@cindex fontSize, default and setting
+
+So if the @code{fontSize} property is set in a @code{\with} clause
+it sets the default value of the font size. If it is later changed
+with @code{\set}, this new default value may be restored with the
+@code{\unset fontSize} command.
+
+@subsubheading Setting context properties with @code{\context}
+
+@cindex context properties, setting with \context
+@funindex \context
+@funindex context
+
+The values of context properties may be set in @emph{all} contexts
+of a particular type, such as all @code{Staff} contexts, with a single
+command. The context type is identified by using its
+type name, like @code{Staff}, prefixed by a back-slash: @code{\Staff}.
+The statement which sets the property value is the same as that in a
+@code{\with} block, introduced above. It is placed in a
+@code{\context} block within a @code{\layout} block. Each
+@code{\context} block will affect all contexts of the type specified
+throughout the @code{\score} or @code{\book} block in which the
+@code{\layout} block appears. Here is a example to show the format:
+
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ \relative c'' {
+ cis4 e d ces
+ }
+ }
+ \layout {
+ \context {
+ \Staff
+ extraNatural = ##t
+ }
+ }
+}
+@end lilypond
+
+@noindent
+Context properties set in this way may be overridden for particular
+instances of contexts by statements in a @code{\with} block, and by
+@code{\set} commands embedded in music statements.
+
+
+@seealso
+Notation Reference:
+@ruser{Changing context default settings}.
+@ruser{The set command}.
+
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{Tunable context properties}.
+
+
+@node Adding and removing engravers
+@subsection Adding and removing engravers
+
+@cindex engravers, adding
+@cindex adding engravers
+@cindex engravers, removing
+@cindex removing engravers
+
+@funindex \consists
+@funindex consists
+@funindex \remove
+@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 @code{Staff_symbol_engraver}.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Staff \with {
+ \remove Staff_symbol_engraver
+}
+\relative c' {
+ c4 d
+ \set fontSize = #-4 % make note heads smaller
+ e4 f |
+ \set fontSize = #2.5 % make note heads larger
+ g4 a
+ \unset fontSize % return to default size
+ b4 c |
+}
+@end lilypond
+
+@cindex ambitus engraver
+
+Engravers can also be added to individual contexts.
+The command to do this is
+
+@code{\consists @var{Engraver_name}},
+
+@noindent
+placed inside a @code{\with} block. Some vocal scores have an ambitus
+placed at the beginning of a staff to indicate the range of notes in
+that staff -- see @rglos{ambitus}. 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
+ c4 a b g
+ }
+ }
+ \new Voice {
+ \relative c' {
+ \voiceTwo
+ c4 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
+ c4 a b g
+ }
+ }
+ \new Voice {
+ \relative c' {
+ \voiceTwo
+ c4 e d f
+ }
+ }
+>>
+@end lilypond
+
+@subsubheading Changing all contexts of the same type
+
+@funindex \layout
+@funindex layout
+
+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 an ambitus for every
+staff in a four-staff score, we could write
+
+@lilypond[quote,verbatim,ragged-right]
+\score {
+ <<
+ \new Staff {
+ \relative c'' {
+ c4 a b g
+ }
+ }
+ \new Staff {
+ \relative c' {
+ c4 a b g
+ }
+ }
+ \new Staff {
+ \clef "G_8"
+ \relative c' {
+ c4 a b g
+ }
+ }
+ \new Staff {
+ \clef "bass"
+ \relative c {
+ c4 a b g
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Staff
+ \consists Ambitus_engraver
+ }
+ }
+}
+@end lilypond
+
+@noindent
+The 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.
+
+
+@seealso
+Notation Reference: @ruser{Modifying context plug-ins},
+@ruser{Changing context default settings}.
+
+
+@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.
+
+@menu
+* Soprano and cello::
+* Four-part SATB vocal score::
+* Building a score from scratch::
+* Saving typing with variables and functions::
+* Scores and parts::
+@end menu
+
+@node Soprano and cello
+@subsection Soprano and cello
+
+@cindex template, modifying
+@cindex modifying templates
+
+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 the
+@q{Notes and lyrics} template (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,addversion]
+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
+
+
+@seealso
+The starting templates can be found in the @q{Templates} appendix,
+see @ref{Single staff}.
+
+
+@node Four-part SATB vocal score
+@subsection Four-part SATB vocal score
+
+@cindex template, SATB
+@cindex SATB template
+
+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 }
+
+sopranoMusic = \relative c'' {
+ \clef "treble"
+ r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
+}
+sopranoWords = \lyricmode {
+ Wor -- thy | is the lamb | that was slain |
+}
+
+altoMusic = \relative a' {
+ \clef "treble"
+ r4 a2 a4 | fis4. fis8 a2 | g4 fis e2 |
+}
+altoWords = \sopranoWords
+
+tenorMusic = \relative c' {
+ \clef "G_8"
+ r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
+}
+tenorWords = \sopranoWords
+
+bassMusic = \relative c' {
+ \clef "bass"
+ r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
+}
+bassWords = \sopranoWords
+
+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
+ \sopranoMusic
+ }
+ >>
+ \new Lyrics \lyricsto "sopranos" {
+ \sopranoWords
+ }
+ \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} -- see @ref{Vocal
+ensembles} -- 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
+ \sopranoMusic
+ @}
+ >>
+ \new Lyrics \lyricsto "sopranos" @{
+ \sopranoWords
+ @}
+ \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
+ \sopranoMusic
+ @}
+ >>
+ \new Lyrics \lyricsto "sopranos" @{
+ \sopranoWords
+ @}
+ \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,addversion]
+global = { \key d \major \time 4/4 }
+sopranoMusic = \relative c'' {
+ \clef "treble"
+ r4 d2 a4 | d4. d8 a2 | cis4 d cis2 |
+}
+sopranoWords = \lyricmode {
+ Wor -- thy | is the lamb | that was slain |
+}
+altoMusic = \relative a' {
+ \clef "treble"
+ r4 a2 a4 | fis4. fis8 a2 | g4 fis fis2 |
+}
+altoWords = \sopranoWords
+tenorMusic = \relative c' {
+ \clef "G_8"
+ r4 fis2 e4 | d4. d8 d2 | e4 a, cis2 |
+}
+tenorWords = \sopranoWords
+bassMusic = \relative c' {
+ \clef "bass"
+ r4 d2 cis4 | b4. b8 fis2 | e4 d a'2 |
+}
+bassWords = \sopranoWords
+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
+ \sopranoMusic
+ }
+ >>
+ \new Lyrics \lyricsto "sopranos" {
+ \sopranoWords
+ }
+ \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
+
+@cindex template, writing your own
+@cindex example of writing a score
+@cindex writing a score, example
+@cindex score, example of writing
+
+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"
+@}
+keyTime = @{ \key c \minor \time 4/4 @}
+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
+around 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 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 opposite
+is true for Voices: these should habitually be followed by braces
+@code{@{ .. @}} in case your music is coded in several variables
+which need to run consecutively.
+
+Let's add this structure to the score block, and adjust the indenting.
+We also add the appropriate clefs, ensure stems, ties and slurs in
+each voice on the upper staff point to the right direction with
+@code{\voiceOne} and @code{\voiceTwo}, and enter the key and time
+signature to each staff using our predefined variable, @code{\keyTime}.
+
+@example
+\score @{
+ << % PianoStaff and Pedal Staff must be simultaneous
+ \new PianoStaff <<
+ \new Staff = "ManualOne" <<
+ \keyTime % set key and time signature
+ \clef "treble"
+ \new Voice @{
+ \voiceOne
+ \ManualOneVoiceOneMusic
+ @}
+ \new Voice @{
+ \voiceTwo
+ \ManualOneVoiceTwoMusic
+ @}
+ >> % end ManualOne Staff context
+ \new Staff = "ManualTwo" <<
+ \keyTime
+ \clef "bass"
+ \new Voice @{
+ \ManualTwoMusic
+ @}
+ >> % end ManualTwo Staff context
+ >> % end PianoStaff context
+ \new Staff = "PedalOrgan" <<
+ \keyTime
+ \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,addversion]
+\header {
+ title = "Jesu, meine Freude"
+ composer = "J S Bach"
+}
+keyTime = { \key c \minor \time 4/4 }
+ManualOneVoiceOneMusic = \relative g' {
+ g4 g f ees |
+ d2 c |
+}
+ManualOneVoiceTwoMusic = \relative c' {
+ ees16 d ees8~ ees16 f ees d c8 d~ d c~ |
+ c8 c4 b8 c8. g16 c b c d |
+}
+ManualTwoMusic = \relative c' {
+ c16 b c8~ c16 b c g a8 g~ g16 g aes ees |
+ f16 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" <<
+ \keyTime % set key and time signature
+ \clef "treble"
+ \new Voice {
+ \voiceOne
+ \ManualOneVoiceOneMusic
+ }
+ \new Voice {
+ \voiceTwo
+ \ManualOneVoiceTwoMusic
+ }
+ >> % end ManualOne Staff context
+ \new Staff = "ManualTwo" <<
+ \keyTime
+ \clef "bass"
+ \new Voice {
+ \ManualTwoMusic
+ }
+ >> % end ManualTwo Staff context
+ >> % end PianoStaff context
+ \new Staff = "PedalOrgan" <<
+ \keyTime
+ \clef "bass"
+ \new Voice {
+ \PedalOrganMusic
+ }
+ >> % end PedalOrgan Staff context
+ >>
+} % end Score context
+@end lilypond
+
+
+@node Saving typing with variables and functions
+@subsection Saving typing with variables and functions
+
+@cindex variables
+@cindex variables
+
+By this point, you've seen this kind of thing:
+
+@lilypond[quote,verbatim,ragged-right]
+hornNotes = \relative c'' { c4 b dis c }
+
+\score {
+ {
+ \hornNotes
+ }
+}
+@end lilypond
+
+You may even realize that this could be useful in minimalist music:
+
+@lilypond[quote,verbatim,ragged-right]
+fragmentA = \relative c'' { a4 a8. b16 }
+fragmentB = \relative c'' { a8. gis16 ees4 }
+
+violin = \new Staff {
+ \fragmentA \fragmentA |
+ \fragmentB \fragmentA |
+}
+
+\score {
+ {
+ \violin
+ }
+}
+@end lilypond
+
+However, you can also use these variables (also known as
+macros, or user-defined commands) for tweaks:
+
+@c TODO Avoid padtext - not needed with skylining
+@lilypond[quote,verbatim,ragged-right]
+dolce = \markup { \italic \bold dolce }
+
+padText = { \once \override TextScript #'padding = #5.0 }
+fthenp =_\markup {
+ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
+}
+
+violin = \relative c'' {
+ \repeat volta 2 {
+ c4._\dolce b8 a8 g a b |
+ \padText
+ c4.^"hi there!" d8 e' f g d |
+ c,4.\fthenp b8 c4 c-. |
+ }
+}
+
+\score {
+ {
+ \violin
+ }
+ \layout { ragged-right = ##t }
+}
+@end lilypond
+
+These variables are obviously useful for saving
+typing. But they're worth considering even if you
+only use them once -- they reduce complexity. Let's
+look at the previous example without any
+variables. It's a lot harder to read, especially
+the last line.
+
+@example
+violin = \relative c'' @{
+ \repeat volta 2 @{
+ c4._\markup @{ \italic \bold dolce @} b8 a8 g a b |
+ \once \override TextScript #'padding = #5.0
+ c4.^"hi there!" d8 e' f g d |
+ c,4.\markup @{
+ \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p
+ @}
+ b8 c4 c-. |
+ @}
+@}
+@end example
+
+@c TODO Replace the following with a better example -td
+@c Skylining handles this correctly without padText
+
+So far we've seen static substitution -- when LilyPond
+sees @code{\padText}, it replaces it with the stuff that
+we've defined it to be (ie the stuff to the right of
+@code{padtext=}).
+
+LilyPond can handle non-static substitution, too (you
+can think of these as functions).
+
+@lilypond[quote,verbatim,ragged-right]
+padText =
+#(define-music-function
+ (parser location padding)
+ (number?)
+ #{
+ \once \override TextScript #'padding = $padding
+ #})
+
+\relative c''' {
+ c4^"piu mosso" b a b |
+ \padText #1.8
+ c4^"piu mosso" d e f |
+ \padText #2.6
+ c4^"piu mosso" fis a g |
+}
+@end lilypond
+
+Using variables is also a good way to reduce work if the
+LilyPond input syntax changes (see
+@rprogram{Updating files with convert-ly}). If
+you have a single definition (such as @code{\dolce}) for all your
+input files (see @ref{Style sheets}), then if the syntax changes, you
+only need to update your single @code{\dolce} definition,
+instead of making changes throughout every @file{.ly} file.
+
+
+@node Scores and parts
+@subsection Scores and parts
+
+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.
+
+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
+
+@example
+hornNotes = \relative c @{
+ \time 2/4
+ r4 f8 a | cis4 f | e4 d |
+@}
+@end example
+
+@noindent
+Then, an individual part is made by putting the following in a file
+
+@example
+\include "horn-music.ly"
+
+\header @{
+ instrument = "Horn in F"
+@}
+
+@{
+ \transpose f c' \hornNotes
+@}
+@end example
+
+The line
+
+@example
+\include "horn-music.ly"
+@end example
+
+@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
+@code{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
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ r4 f8 a | cis4 f | e4 d |
+}
+@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 @code{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
+
+@example
+R2*3
+@end example
+
+When printing the part, multi-rests
+must be condensed. This is done by setting a run-time variable
+
+@example
+\set Score.skipBars = ##t
+@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
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ \set Score.skipBars = ##t
+ R2*3 |
+ r4 f8 a | cis4 f | e4 d |
+}
+@end lilypond
+
+
+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
+
+@example
+\include "bassoon-music.ly"
+\include "horn-music.ly"
+
+<<
+ \new Staff \hornNotes
+ \new Staff \bassoonNotes
+>>
+@end example
+
+@noindent
+leading to
+
+@lilypond[quote,ragged-right]
+\relative c <<
+ \new Staff {
+ \clef "treble"
+ \time 2/4
+ R2*3 |
+ r4 f8 a | cis4 f | e4 d |
+ }
+ \new Staff {
+ \clef "bass"
+ \time 2/4
+ r4 d,8 f | gis4 c | b4 bes |
+ a8 e f4 | g4 d | gis4 f |
+ }
+>>
+@end lilypond
+
+
projects / lilypond.git / blobdiff