X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnl%2Flearning%2Ffundamental.itely;h=2bdbf8349c6925a110a61a7a740170908e7914c8;hb=1b832d794f1444033f10465971e97d33f76fe310;hp=fa011e9b5f6f3a8b61614ed14a62324fcf33bfba;hpb=3dd9b13331489a191d0e901245cc98476e5fcac1;p=lilypond.git

diff --git a/Documentation/nl/learning/fundamental.itely b/Documentation/nl/learning/fundamental.itely
index fa011e9b5f..2bdbf8349c 100644
--- a/Documentation/nl/learning/fundamental.itely
+++ b/Documentation/nl/learning/fundamental.itely
@@ -1,115 +1,578 @@
-\input texinfo @c -*- coding: utf-8; mode: texinfo; documentlanguage: nl -*-
-@c This file is part of learning.tely
+@c -*- coding: utf-8; mode: texinfo; fill-column: 60 -*-
+
 @ignore
-    Translation of GIT committish: 1b3da70d81938d19a2b107382bbe25a267cf130b
+    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 -*- coding: utf-8; mode: texinfo; -*-
-@c \version "2.12.0"
-@node Fundamental concepts
-@chapter Fundamental concepts
+@c \version "2.13.36"
 
-@untranslated
+@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
-* How LilyPond input files work::
+* Hoe LilyPond-invoerbestanden werken::
 * Voices contain music::
 * Contexts and engravers::
 * Extending the templates::
 @end menu
 
-@node How LilyPond input files work
-@section How LilyPond input files work
 
-@untranslated
+@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
-* Introduction to the LilyPond file structure::
+* 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 Introduction to the LilyPond file structure
-@subsection Introduction to the LilyPond file structure
-
-@untranslated
-
-
-@c index input format
-@c index file structure
-@c index book
-@c index score
-@c ode{\score@{@}} command.  This is because LilyPond automatically
-@c index implicit contexts
-@c index contexts, implicit
-@ref{Contexts and engravers}.
-@c ode{\score} command, leaving the others to default.
-@c index header
-@c index layout
-@c index midi
-@c ode{\midi} -- are special: unlike many other commands which begin
-@c ode{\header} is often placed above the @code{\score} command, as the
-@c ode{\layout @{ @}} and @code{\midi @{@}}.  If these appear as
-@c index scores, multiple
-@c index book block, implicit
-@c index implicit book block
-@c ode{\book} command should be used to separate the different
-@c ode{\book} block.
-@c index layout block, effect of location
-@c ode{\book} block in which it appears -- i.e., a @code{\layout}
-@c index variables
-@c ode{melody} (everything after the equals sign) and inserts it
-@c ode{TimeKey},
-@c ode{pianorighthand}, or @code{foofoobarbaz}.  For more details,
+@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
 
-@untranslated
+@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:
 
-@c index score
-@c index contents of a score block
-@c index score block, contents of
-@c index compound music expression
-@c index music expression, compound
 @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
-@c ode{StaffGroup} for this ensemble, which simply groups a number
-@c ode{\lyricmode}.  These are essential to tell LilyPond
+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
 
-@untranslated
+@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}.
 
 
-@c index staves, temporary
-@c index temporary staves
-@c index ossias
-@c index staff, positioning
 @node On the un-nestedness of brackets and ties
 @subsection On the un-nestedness of brackets and ties
 
-@untranslated
+@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 index brackets, nesting
-@c index bracket types
-@c index brackets, enclosing vs. marking
 @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
 
-@untranslated
-
+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::
@@ -120,94 +583,794 @@
 @node I'm hearing Voices
 @subsection I'm hearing Voices
 
-@untranslated
-
-
-@c index polyphony
-@c index layers
-@c index multiple voices
-@c index voices, multiple
-@c index Voice context
-@c index context, Voice
-@c index simultaneous music
-@c index music, simultaneous
-@c index concurrent music
-@c index music, concurrent
-@c index voices vs. chords
-@c index chords vs. voices
-@c ode{\\}, to place them in separate voices.  Without these, the
-@c index voices, naming
-@c index voices crossing brackets
-@c index slurs crossing brackets
-@c index ties crossing brackest
+@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}.
-@c index polyphony and relative note entry
-@c index relative note entry and polyphony
-@c ode{\relative @{ @}} block.  Each note is still calculated
-@c ode{noteB} is relative to @code{noteA}                      @*
-@c ode{noteC} is relative to @code{noteB}, not @code{noteA};   @*
-@c ode{noteD} is relative to @code{noteB}, not @code{noteA} or
-@c ode{noteC};                                                 @*
-@c ode{noteE} is relative to @code{noteD}, not @code{noteA}.
+
+@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
-@c index stem down
-@c index voices and stem directions
-@c index stem directions and voices
-@c index stem up
+@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
 
-@untranslated
+@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 index voice contexts, creating
-@c ode{\voiceOne} ... @code{\voiceFour} to indicate the required
 @c The following example should not display the code
-@c index voices, reverting to single
-@c index reverting to a single voice
-@c ode{\voiceFour} make them point downwards.  These commands also
-@c ode{\oneVoice}, @code{\voiceOne} and @code{voiceTwo} have on
-@c index nesting music expressions
-@c index nesting simultaneous constructs
-@c index nesting voices
-@c index voices, temporary
-@c index voices, nesting
-@c index spacing notes
+@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
-@c index note column
-@c index note collisions
-@c index collisions, notes
-@c index shift commands
-@c ode{\shiftOff} commands specify the degree to which notes and
-@c ode{\shiftOnn} and @code{\shiftOnnn} define further shift
+
+@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
 
-@untranslated
-
-
-@c index Lyrics context, creating
-@c index lyrics, linking to voice
-@c index lyrics and beaming
-@c index beaming and lyrics
-@c ode{\autoBeamOff} to turn off the automatic beaming.
-@c index vocal score structure
-@c index choir staff
-@c ode{\lyricmode} to ensure they are interpreted as lyrics
-@c index hymn structure
-@c index SATB structure
-@c index vocal scores with multiple verses
-@c index multiple vocal verses
-@c index verses, multiple vocal
-@c index verse and refrain
-@c index book, example of using
-@c ode{\score} blocks within an implicit @code{\book} block, as
+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
 
-@untranslated
+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
@@ -221,99 +1384,769 @@
 @node Contexts explained
 @subsection Contexts explained
 
-@untranslated
-
+@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.
 
-@c index contexts explained
 @quotation
+@sourceimage{context-example,5cm,,}
 @end quotation
-@c ode{Score} and @code{Staff} contexts.
-@c ode{Voice} contexts there are contexts which fit between
-@c ode{PianoStaff} and @code{ChoirStaff} contexts.  There
-@c ode{GregorianTranscriptionStaff}.
+
+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
 
-@untranslated
+@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}.
 
 
-@c index new contexts
-@c index creating contexts
-@c index contexts, creating
-@c ode{Staff} contexts may be left to be created automatically, but for
-@c ode{Voice}).  This command creates a new context, and starts
-@c ode{Staff} and @code{Voice} contexts in earlier sections, but
-@c index contexts, naming
-@c index naming contexts
-@c ode{Staff}, @code{Voice}, etc, and the identifying name of a
 @node Engravers explained
 @subsection Engravers explained
 
-@untranslated
+@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}.
 
 
-@c index engravers
-@c ode{Metronome_mark_engraver}, whose action and output apply to the
-@c ode{Score} context.
-@c The old Dynamic_engraver is deprecated. -jm
 @node Modifying context properties
 @subsection Modifying context properties
 
-@untranslated
-
+@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 index context properties
-@c index context properties, modifying
-@c index modifying context properties
-@c ode{\set} command.  This takes the form
-@c ode{Staff} or @code{Voice}.  It may be omitted,
 @c attempt to force this onto a new page
-@c index properties operating in contexts
-@c index setting properties within contexts
-@c ode{instrumentName} clearly lives in the @code{Staff} context, since
-@c ode{\set} command set the property @code{instrumentName} in the
-@c ode{Voice} context to @qq{Alto}, but as LilyPond does not look
-@c ode{\set} or @code{\unset} again.  Let's try changing the
-@c ode{##t} and @code{##f}, with two hash signs.  A text property
+@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}
-@c index context properties, setting with \with
-@c ode{\with @{ .. @}} block in which the property values are
-@c ode{\set} and returned to their default value with @code{\unset}.
-@c index fontSize, default and setting
-@c ode{\unset fontSize} command.
+
+@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}
-@c index context properties, setting with \context
-@c ode{\with} block, introduced above.  It is placed in a
-@c ode{\context} block within a @code{\layout} block.  Each
-@c ode{\context} block will affect all contexts of the type specified
-@c ode{\layout} block appears.  Here is a example to show the format:
-@c ode{\set} commands embedded in music statements.
-@c FIXME
-@c uncomment when backslash-node-name issue is resolved -pm
-@c @ruser{The set command}.
+
+@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
 
-@untranslated
+@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.
 
-@c index engravers, adding
-@c index adding engravers
-@c index engravers, removing
-@c index removing engravers
 @subsubheading Changing a single context
-@c ode{\with} command placed immediately after the context creation
-@c index ambitus engraver
-@c ode{\consists @var{Engraver_name}},
-@c ode{Ambitus_engraver}, which is not normally included in any
-@c ode{Staff} context, it calculates the range from all
+
+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
-@c ode{\set} command in a @code{\context} block in the
+
+@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
 
-@untranslated
-
+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::
@@ -326,61 +2159,1001 @@
 @node Soprano and cello
 @subsection Soprano and cello
 
-@untranslated
-
+@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 index template, modifying
-@c index modifying templates
-@c ode{melody} section.  We don't want two @code{\score} sections
-@c ode{text} to be @code{sopranoLyrics}.  Remember to rename both
-@c ode{melody = \relative c' @{ } part) and the name's use (in the
-@c ode{\score} section).
-@c ode{>>} around the music -- that tells LilyPond that there's
 @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
 
-@untranslated
+@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 index template, SATB
-@c index SATB template
 @c The following should appear as music without code
-@c ode{\voiceXXX} commands should be removed.  We also need to specify
+@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
 
-@untranslated
+@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
 
 
-@c index template, writing your own
-@c index example of writing a score
-@c index writing a score, example
-@c index score, example of writing
-@c ode{<< .. >>} for the manual two staff and the pedal organ staff,
-@c ode{@{ .. @}} in case your music is coded in several variables
-@c ode{\voiceOne} and @code{\voiceTwo}, and enter the time signature
 @node Saving typing with variables and functions
 @subsection Saving typing with variables and functions
 
-@untranslated
+@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 index variables
-@c index variables
 @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
-@c ode{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
 
-@untranslated
-
+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
 
-@c ode{\transpose f@tie{}c'} indicates that the argument, being
-@c ode{\hornNotes}, should be transposed by a fifth upwards.  Sounding
-@c ode{f} is denoted by notated @code{c'}, which corresponds with the
-@c ode{Score} context to true (@code{##t}).  Prepending the rest and
 
-@c -- SKELETON FILE --