Issue 3720: Built-in templates for SATB vocal scores

Documentation/learning/templates.itely

 @c -*- coding: utf-8; mode: texinfo; -*-
 
 @ignore
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     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 \version "2.16.0"
 
 @node Templates
 @appendix Templates
 
 This section of the manual contains templates with the LilyPond score
 already set up for you.  Just add notes, run LilyPond, and enjoy
 beautiful printed scores!
 
 @menu
+* Built-in templates::
 * Single staff templates::
 * Piano templates::
 * String quartet templates::
 * Vocal ensembles templates::
 * Orchestral templates::
 * Ancient notation templates::
 * Other templates::
 @end menu
 
 
+@node Built-in templates
+@appendixsec Built-in templates
+
+Two 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 or four staves.  The templates
+are @q{built-in}, which means they do not need to be copied and
+edited:  instead they are simply @code{\include}'d in the input file.
+
+The templates are in pairs, one of the pair is @code{\include}'d at
+the top of the input file and the other is @code{\include}'d at the
+bottom.  Your music expressions are entered by defining values for
+specific variables between the two @code{\include}'d files.
+
+The template pair @code{S-A-T-B-init.ily} and @code{S-A-T-B.ily}
+are used to produce up to four separate SATB staves with individual
+lyrics and optional piano accompaniment.  The template pair
+@code{SA-TB-init.ily} and @code{SA-TB.ily} are used to produce two
+vocal staves, one for SA and one for TB, together with optional
+piano accompaniment.
+
+Any of the staves my be omitted.  Here, for example, is how the input

[Jean-Charles, 2013/12/14 16:15:14]

mAy be omitted

+file for a Soprano/Bass duet might be written:
+
+@lilypond[verbatim,quote]
+  \include "S-A-T-B-init.ily"
+
+  SopranoMusic = \relative { c'' c c c }
+  SopranoLyrics = \lyricsto "Soprano" \lyricmode {
+    High voice ly -- rics
+  }
+  BassMusic = \relative { a a a a }
+  BassLyrics = \lyricsto "Bass" \lyricmode {
+    Low voice ly -- rics
+  }
+  \include "S-A-T-B.ily"
+@end lilypond
+
+The same template pair can be used for a full four-part SATB
+arrangement with individual lyrics and piano accompaniment:
+
+@lilypond[verbatim, quote]
+  \include "S-A-T-B-init.ily"
+
+  SopranoMusic = \relative { a'4 a8 a a4\f a }
+  SopranoLyrics = \lyricsto "Soprano" \lyricmode {
+    Sop -- ra -- no ly -- rics
+  }
+  AltoMusic = \relative { d'4 d d\f d }
+  AltoLyrics = \lyricsto "Alto" \lyricmode {
+    Al -- to ly -- rics
+  }
+  TenorMusic = \relative { a4 a a\p a }
+  TenorLyrics = \lyricsto "Tenor" \lyricmode {
+    Te -- nor ly -- rics
+  }
+  BassMusic = \relative { c2 c4\mp c }
+  BassLyrics = \lyricsto "Bass" \lyricmode {
+    Bass ly -- rics
+  }
+  PianoRHMusic = \relative { c' e g c }
+  PianoDynamics = { s2 s4\f s4 }
+  PianoLHMusic = \relative { c e g c }
+
+  \include "S-A-T-B.ily"
+@end lilypond
+
+A second verse or alternative lyrics may be added to each of the parts:
+
+@lilypond[verbatim, quote]
+  \include "S-A-T-B-init.ily"
+
+  SopranoMusic = \relative {
+    a'4 a a a
+  }
+  SopranoLyrics = \lyricsto "Soprano" \lyricmode {
+    \set stanza = "1."
+    Words to verse one
+  }
+  SopranoLyricsTwo = \lyricsto "Soprano" \lyricmode {
+    \set stanza = "2."
+    Words to verse two
+  }
+  \include "S-A-T-B.ily"
+@end lilypond
+
+The @code{SA-TB.ily} template pair is intended for use when the
+lyrics are the same for each part, with the vocal music arranged
+on two staves with two voices in each.  Up to nine verses may be
+provided.  Here's an unaccompanied example with just three verses.
+
+@lilypond[verbatim, quote]
+  \include "SA-TB-init.ily"
+··
+  SopranoMusic = \relative { a' a a a }
+  AltoMusic = \relative { f' f f f }
+  VerseOne = \lyricsto "Soprano" \lyricmode {
+    \set stanza = "1."
+    Words to verse one
+  }
+  VerseTwo = \lyricsto "Soprano" \lyricmode {
+    \set stanza = "2."
+    Words to verse two
+  }
+  VerseThree = \lyricsto "Soprano" \lyricmode {
+    \set stanza = "3."
+    Words to verse three
+  }
+  TenorMusic = \relative { a a a a }
+  BassMusic = \relative { f f f f }
+··
+  \include "SA-TB.ily"
+@end lilypond
+
+Other variables may be given values.  The key signature and
+the time signature may be changed from the default in either of
+the two templates:
+
+@lilypond[verbatim, quote]
+  \include "SA-TB-init.ily"
+··
+  Key = \key a \major
+  Time = {
+    \time 5/4
+    \tempo "Allegro" 4 = 144
+  }
+  SopranoMusic = \relative { gis' gis gis gis gis }
+  AltoMusic = \relative { cis' cis cis cis cis }
+  VerseOne = \lyricsto "Soprano" \lyricmode {
+    Words to this du -- et
+  }
+  \include "SA-TB.ily"
+@end lilypond
+
+A descant may be added when using either pair of templates
+by defining the variables @code{DescantMusic} and, in the
+@code{S-A-T-B.ily} template pair, descant lyrics may be provided
+by defining @code{DescantLyrics} and @code{DescantLyricsTwo}.
+
+@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:
+
+@example
+Layout = \layout @{ ... @}
+@end example
+
+The complete set of variables which may be changed can be seen by
+examining the files @file{ly/S-A-T-B-init.ily} and
+@file{ly/SA-TB-init.ily}.  The context structures may be examined
+in the files @file{ly/S-A-T-B.ily} and @file{ly/SA-TB.ily}.  Pairs
+of these four files may be copied, edited and placed in your
+usual @code{\include} path to provide alternative SATB layouts
+if the ones provided here are unsuitable.
+
+@seealso
+Learning Manual:
+@ref{Organizing pieces with variables},
+@ref{Vocal ensembles templates},
+@ref{Extending the templates}.
+
+@knownissues
+More complex arrangements of SATB choral music are not possible with
+these simple built-in templates.
+
+
 @node Single staff templates
 @appendixsec Single staff templates
 
 @menu
 * Notes only::
 * Notes and lyrics::
 * Notes and chords::
 * Notes lyrics and chords::
 @end menu
 
@@ skipping 67 matching lines @@
 @node String quartet parts
 @appendixsubsec String quartet parts
 
 @lilypondfile[verbatim,quote,ragged-right,texidoc]
 {string-quartet-template-with-separate-parts.ly}
 
 
 @node Vocal ensembles templates
 @appendixsec Vocal ensembles templates
 
+The templates shown below should be copied into your score and edited
+there.  If you have a relatively simple SATB layout you may prefer to
+use the built-in templates, which can simply be @code{\include}'d, see
+@ref{Built-in templates}.
+
 @menu
 * SATB vocal score::
 * SATB vocal score and automatic piano reduction::
 * SATB with aligned contexts::
 * SATB on four staves::
 * Solo verse and two-part refrain::
 * Hymn tunes::
 * Psalms::
 @end menu
 
@@ skipping 155 matching lines @@
   \header {
     piece = "piece2"
     opus = "opus2"
   }
 }
 @end lilypond
 @end ignore