X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Ftemplates.itely;h=2f04fae957c171cb9532ccd36724d3a31f5252c2;hb=13798e90e8ae32bf341b21440f2687442274759f;hp=cc35e50da7c4c7827b407d35f1e5b621df466b71;hpb=82bc9ad690e201aaa55694f8b92261ae7338f56a;p=lilypond.git

diff --git a/Documentation/learning/templates.itely b/Documentation/learning/templates.itely
index cc35e50da7..2f04fae957 100644
--- a/Documentation/learning/templates.itely
+++ b/Documentation/learning/templates.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.19.2"
+@c \version "2.19.25"
 
 @node Templates
 @appendix Templates
@@ -32,19 +32,27 @@ beautiful printed scores!
 @node Built-in templates
 @appendixsec Built-in templates
 
-A template, suitable for a range of choral music, is built into
-LilyPond.  This may be used to create simple choral music, with or
-without piano accompaniment, in two or four staves.  Unlike other
-templates, this template is @q{built-in}, which means it does not
-need to be copied and edited:  instead it is simply 
-@code{\include}'d in the input file.
+Some templates, suitable for a range of choral music, are built into
+LilyPond.  These may be used to create simple choral music, with or
+without piano accompaniment, in two, four or eight staves.  Unlike
+other templates, these templates are @q{built-in}, which means they do
+not need to be copied and edited:  instead they are simply
+@code{@bs{}include}'d in the input file.
 
-@warning {Unlike most included files, this built-in template must be
-@code{\include}'d at the @emph{end} of the input file.}
+@warning {Unlike most included files, these built-in templates must be
+@code{@bs{}include}'d at the @emph{end} of the input file.}
 
 The required music expressions are entered by defining values for
-specific variables.  These definition must come before the
-@code{\include}'d file.
+specific variables.  These definitions must come before the
+@code{@bs{}include}'d file.
+
+@menu
+* SATB template::
+* SSAATTBB template::
+@end menu
+
+@node SATB template
+@appendixsubsec SATB template
 
 The music may be set out with one or two voices per staff by setting
 @code{TwoVoicesPerStaff} to @code{##f} or @code{##t} respectively.
@@ -106,11 +114,11 @@ parts:
 
 @lilypond[verbatim, quote]
   SopranoMusic = \relative { a'4 a a a }
-  SopranoLyricsOne = \lyricsto "Soprano" {
+  SopranoLyricsOne = \lyricmode {
     \set stanza = "1."
     Words to verse one
   }
-  SopranoLyricsTwo = \lyricsto "Soprano" {
+  SopranoLyricsTwo = \lyricmode {
     \set stanza = "2."
     Words to verse two
   }
@@ -174,30 +182,160 @@ changed:
   \include "satb.ly"
 @end lilypond
 
+although rather than do this it might be easier to use the
+@code{ssaattbb.ly} template, see @ref{SSAATTBB template}.
+
 A descant may be added by defining values for the variable
-@code{DescantMusic} and descant lyrics may be provided by
-defining values for @code{DescantLyrics}.
+@code{DescantMusic} and descant lyrics may be provided by defining
+values for @code{DescantLyrics}.  In a similar way a solo part may be
+added above the grouped choir staves by defining values for
+@code{SoloMusic} and @code{SoloLyrics}.
 
 @code{\header} and @code{\paper} blocks may be added as normal.
-A @code{\layout} block may be provided as the value of the
-@code{Layout} variable:
+A @code{\layout} block may be provided as usual at top level, and
+the contents will be combined with (but will not override) the default
+settings provided in the template.  Alternatively, all the default
+settings provided by the template can be discarded by defining a
+@code{Layout} variable containing @emph{all} the required settings:
 
 @example
 Layout = \layout @{ ... @}
 @end example
 
 The complete set of variables which may be changed can be seen by
-examining the file @file{ly/satb.ly}.
+examining the file @file{ly/satb.ly}, see
+@ref{Other sources of information}.
 
 @seealso
 Learning Manual:
 @ref{Organizing pieces with variables},
 @ref{Vocal ensembles templates},
-@ref{Extending the templates}.
+@ref{Extending the templates},
+@ref{Other sources of information}.
 
 @knownissues
+The setting of the @code{TwoVoicesPerStaff} variable applies for the
+entire duration of the score: it cannot be given different values at
+different times.
+
 More complex arrangements of SATB choral music are not possible with
-these simple built-in templates.
+this simple built-in template.
+
+
+@node SSAATTBB template
+@appendixsubsec SSAATTBB template
+
+All the variables defined for the SATB template, with the exception of
+the @code{VerseXxx} variables, are also available for the SSAATTBB
+template, see @ref{SATB template}.  In addition, music and lyrics for
+first and second voices in any or all of the four parts may be specified
+by providing values for @code{SopranoOneMusic}, @code{SopranoTwoMusic},
+etc, with lyrics in @code{SopranoOneLyrics} and @code{SopranoTwoLyrics},
+etc.  Up to four additional stanzas may be defined for all the voice
+parts by using the variables @code{SopranoOneLyricsOne}, with the others
+defined in an analogous way.
+
+Setting @code{TwoVoicesPerStaff} to @code{##t} will cause @emph{all}
+voice parts to be placed on single staves as divisi voices.  If
+@code{TwoVoicesPerStaff} is left to default or set to @code{##f} then
+individual voice parts may be set on one or two staves according to
+the setting of @code{SopranoTwoVoicesPerStaff},
+@code{MenTwoVoicesPerStaff}, etc.
+
+As an example, suppose we have a piece for soprano and alto which begins
+with all voices in unison, progresses to a section with two parts,
+soprano and alto, and ends with a four-part section.  This would be
+coded like this:
+
+@lilypond[verbatim,quote]
+Time = { s1 \break s1 \break }
+WomenMusic = \relative { a'4 a a a }
+WomenLyrics = \lyricmode { Wo -- men ly -- rics }
+SopranoMusic = \relative { s1 | c''4 c c c8 c }
+SopranoLyrics = \lyricmode{ So -- pra -- no ly -- rics }
+AltoMusic = \relative { s1 | g'4 g g g }
+AltoLyrics = \lyricmode { Al -- to ly -- rics }
+SopranoOneMusic = \relative { s1 | s1 |e''4 e e e }
+SopranoOneLyrics = \lyricmode { Sop One ly -- rics }
+SopranoTwoMusic = \relative { s1 | s1 | c''4 c c c }
+SopranoTwoLyrics = \lyricmode { Sop Two ly -- rics }
+AltoOneMusic = \relative { s1 | s1 | g'4 g g g8 g }
+AltoOneLyrics = \lyricmode { Al -- to One ly -- rics }
+AltoTwoMusic = \relative { s1 | s1 | e'4 e e e8 e }
+AltoTwoLyrics = \lyricmode { Al -- to Two ly -- rics }
+\layout { ragged-right = ##t }
+\include "ssaattbb.ly"
+@end lilypond
+
+Male voices may be added in an analogous way.
+
+To change the layout so that the divisi soprano voices use a shared
+staff, we simply set @code{SopranoTwoVoicesPerStaff} to ##t, leaving
+all other variables unchanged, like this:
+
+@lilypond[verbatim,quote]
+SopranoTwoVoicesPerStaff = ##t
+Time = { s1 \break s1 \break }
+WomenMusic = \relative { a'4 a a a }
+WomenLyrics = \lyricmode { Wo -- men ly -- rics }
+SopranoMusic = \relative { s1 | c''4 c c c8 c }
+SopranoLyrics = \lyricmode{ So -- pra -- no ly -- rics }
+AltoMusic = \relative { s1 | g'4 g g g }
+AltoLyrics = \lyricmode { Al -- to ly -- rics }
+SopranoOneMusic = \relative { s1 | s1 |e''4 e e e }
+SopranoOneLyrics = \lyricmode { Sop One ly -- rics }
+SopranoTwoMusic = \relative { s1 | s1 | c''4 c c c }
+SopranoTwoLyrics = \lyricmode { Sop Two ly -- rics }
+AltoOneMusic = \relative { s1 | s1 | g'4 g g g8 g }
+AltoOneLyrics = \lyricmode { Al -- to One ly -- rics }
+AltoTwoMusic = \relative { s1 | s1 | e'4 e e e8 e }
+AltoTwoLyrics = \lyricmode { Al -- to Two ly -- rics }
+\layout { ragged-right = ##t }
+\include "ssaattbb.ly"
+@end lilypond
+
+or, to make all paired voices share a single staff, set
+@code{TwoVoicesPerStaff} to ##t:
+
+@lilypond[verbatim,quote]
+TwoVoicesPerStaff = ##t
+Time = { s1 \break s1 \break }
+WomenMusic = \relative { a'4 a a a }
+WomenLyrics = \lyricmode { Wo -- men ly -- rics }
+SopranoMusic = \relative { s1 | c''4 c c c8 c }
+SopranoLyrics = \lyricmode{ So -- pra -- no ly -- rics }
+AltoMusic = \relative { s1 | g'4 g g g }
+AltoLyrics = \lyricmode { Al -- to ly -- rics }
+SopranoOneMusic = \relative { s1 | s1 |e''4 e e e }
+SopranoOneLyrics = \lyricmode { Sop One ly -- rics }
+SopranoTwoMusic = \relative { s1 | s1 | c''4 c c c }
+SopranoTwoLyrics = \lyricmode { Sop Two ly -- rics }
+AltoOneMusic = \relative { s1 | s1 | g'4 g g g8 g }
+AltoOneLyrics = \lyricmode { Al -- to One ly -- rics }
+AltoTwoMusic = \relative { s1 | s1 | e'4 e e e8 e }
+AltoTwoLyrics = \lyricmode { Al -- to Two ly -- rics }
+\layout { ragged-right = ##t }
+\include "ssaattbb.ly"
+@end lilypond
+
+The complete set of variables which may be changed can be seen by
+examining the file @file{ly/ssaattbb.ly}, see
+@ref{Other sources of information}.
+
+@seealso
+Learning Manual:
+@ref{Organizing pieces with variables},
+@ref{Vocal ensembles templates},
+@ref{Extending the templates},
+@ref{Other sources of information}.
+
+@knownissues
+The setting of the various @code{...TwoVoicesPerStaff} variables apply
+for the entire duration of the score: they cannot be given different
+values at different times.
+
+More complex arrangements of 8-part choral music are not possible with
+this simple built-in template.
 
 
 @node Single staff templates
@@ -213,13 +351,13 @@ these simple built-in templates.
 @node Notes only
 @appendixsubsec Notes only
 
-@lilypondfile[verbatim,quote,ragged-right,texidoc,addversion]
+@lilypondfile[verbatim,quote,ragged-right,texidoc]
 {single-staff-template-with-only-notes.ly}
 
 @node Notes and lyrics
 @appendixsubsec Notes and lyrics
 
-@lilypondfile[verbatim,quote,ragged-right,texidoc,addversion]
+@lilypondfile[verbatim,quote,ragged-right,texidoc]
 {single-staff-template-with-notes-and-lyrics.ly}
 
 @node Notes and chords
@@ -370,9 +508,8 @@ use the built-in templates, which can simply be @code{\include}'d, see
 @node Transcription of mensural music
 @appendixsubsec Transcription of mensural music
 
-@c Line-width below is because of Issue 766.  If that's fixed, it can be removed.
-@lilypondfile[verbatim,quote,ragged-right,texidoc,line-width=140]
-{ancient-notation-template----modern-transcription-of-mensural-music.ly}
+@lilypondfile[verbatim,quote,ragged-right,texidoc]
+{incipit.ly}
 
 @node Gregorian transcription template
 @appendixsubsec Gregorian transcription template
@@ -391,8 +528,7 @@ use the built-in templates, which can simply be @code{\include}'d, see
 @node Jazz combo
 @appendixsubsec Jazz combo
 
-@c Line-width below is because of Issue 766.  If that's fixed, it can be removed.
-@lilypondfile[verbatim,quote,ragged-right,texidoc,line-width=140]
+@lilypondfile[verbatim,quote,ragged-right,texidoc]
 {jazz-combo-template.ly}
 
 
@@ -417,7 +553,7 @@ violin concerto as TchaikovskyPI, whereas perhaps you wish to print
 
 @ The `line-width' is for \header.
 @li lypond[quote,verbatim,ragged-right,line-width]
-\version "2.19.2"
+\version "2.19.25"
 \header {
   dedication = "dedication"
   title = "Title"