@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.19.25"

@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!


@node Built-in templates
@appendixsec Built-in templates

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{\include}'d in 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 definitions must come before the
@code{\include}'d file.


@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.

Here's the complete input file for producing a full four-part SATB
arrangement with individual lyrics and piano accompaniment:

@lilypond[verbatim, quote]
SopranoMusic = \relative { a'4\f a8 a a4 a }
SopranoLyrics = \lyricmode { Sop -- ra -- no ly -- rics }
AltoMusic = \relative { d'4\f d d d }
AltoLyrics = \lyricmode { Al -- to ly -- rics }
TenorMusic = \relative { a4\p a a a }
TenorLyrics = \lyricmode { Te -- nor ly -- rics }
BassMusic = \relative { c2\p c4 c }
BassLyrics = \lyricmode { Bass ly -- rics }
PianoRHMusic = \relative { c' e g c }
PianoDynamics = { s2\mp s4 s4 }
PianoLHMusic = \relative { c e g c }
\include "satb.ly"
@end lilypond

The same input can be used to produce a score with two voices
per staff just by setting @code{TwoVoicesPerStaff} to @code{##t}.
Again, each voice has individual lyrics.

@lilypond[verbatim, quote]
SopranoMusic = \relative { a'4\f a8 a a4 a }
SopranoLyrics = \lyricmode { Sop -- ra -- no ly -- rics }
AltoMusic = \relative { d'4\f d d d }
AltoLyrics = \lyricmode { Al -- to ly -- rics }
TenorMusic = \relative { a4\p a a a }
TenorLyrics = \lyricmode { Te -- nor ly -- rics }
BassMusic = \relative { c2\p c4 c }
BassLyrics = \lyricmode { Bass ly -- rics }
PianoRHMusic = \relative { c' e g c }
PianoDynamics = { s2\mp s4 s4 }
PianoLHMusic = \relative { c e g c }
TwoVoicesPerStaff = ##t
\include "satb.ly"
@end lilypond

When @code{TwoVoicesPerStaff} is set to @code{#f} (false) or allowed to default,
any of the music variables may be omitted to produce arrangements
with fewer voices.  Here, for example, is how the input file for a
Soprano-Bass duet might be written:

@lilypond[verbatim,quote]
SopranoMusic = \relative { c'' c c c }
SopranoLyrics = \lyricmode { High voice ly -- rics }
BassMusic = \relative { a a a a }
BassLyrics = \lyricmode { Low voice ly -- rics }
\include "satb.ly"
@end lilypond

A second verse or alternative lyrics may be added to each of the
parts:

@lilypond[verbatim, quote]
SopranoMusic = \relative { a'4 a a a }
SopranoLyricsOne = \lyricmode {
  \set stanza = "1."
  Words to verse one
}
SopranoLyricsTwo = \lyricmode {
  \set stanza = "2."
  Words to verse two
}
\include "satb.ly"
@end lilypond

When the lyrics and rhythms are the same for every part, the vocal
music is best 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]
SopranoMusic = \relative { a' a a a }
AltoMusic = \relative { f' f f f }
VerseOne = \lyricmode {
  \set stanza = "1."
  Words to verse one
}
VerseTwo = \lyricmode {
  \set stanza = "2."
  Words to verse two
}
VerseThree = \lyricmode {
  \set stanza = "3."
  Words to verse three
}
TenorMusic = \relative { a a a a }
BassMusic = \relative { f f f f }
TwoVoicesPerStaff = ##t
\include "satb.ly"
@end lilypond

Other variables may be given values.  The key signature and
the time signature may be changed from the default:

@lilypond[verbatim, quote]
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 = \lyricmode { Words to this du -- et }
TwoVoicesPerStaff = ##t
\include "satb.ly"
@end lilypond

The instrument names and/or the short instrument names may be
changed:

@lilypond[verbatim,quote]
SopranoMusic = \relative { c'' c c c }
SopranoLyrics = \lyricmode { High voice ly -- rics }
SopranoInstrumentName = "Soprano 1"
SopranoShortInstrumentName = "S1"
AltoMusic = \relative { a' a a a }
AltoLyrics = \lyricmode { Low voice ly -- rics }
AltoInstrumentName = "Soprano 2"
AltoShortInstrumentName = "S2"
\include "satb.ly"
@end lilypond

@noindent
although rather than doing this it might be easier to use the
@code{ssaattbb.ly} template, @pxref{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}.  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 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},
@pxref{Other sources of information}.

@morerefs
Learning Manual:
@ref{Organizing pieces with variables},
@ref{Vocal ensembles templates},
@ref{Extending the templates},
@ref{Other sources of information}.
@endmorerefs

@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
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, @pxref{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 that 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 @code{##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

@noindent
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},
@pxref{Other sources of information}.

@morerefs
Learning Manual:
@ref{Organizing pieces with variables},
@ref{Vocal ensembles templates},
@ref{Extending the templates},
@ref{Other sources of information}.
@endmorerefs

@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.

@need 800
@node Single staff templates
@appendixsec Single staff templates


@node Notes only
@appendixsubsec Notes only

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/single-staff-template-with-only-notes.ly}

@node Notes and lyrics
@appendixsubsec Notes and lyrics

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/single-staff-template-with-notes-and-lyrics.ly}

@node Notes and chords
@appendixsubsec Notes and chords

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/single-staff-template-with-notes-and-chords.ly}

@node Notes lyrics and chords
@appendixsubsec Notes, lyrics, and chords

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/single-staff-template-with-notes,-lyrics,-and-chords.ly}


@need 800
@node Piano templates
@appendixsec Piano templates


@node Solo piano
@appendixsubsec Solo piano

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/piano-template-simple.ly}

@node Piano and melody with lyrics
@appendixsubsec Piano and melody with lyrics

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/piano-template-with-melody-and-lyrics.ly}

@node Piano-centered lyrics
@appendixsubsec Piano-centered lyrics

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/piano-template-with-centered-lyrics.ly}


@need 800
@node String quartet templates
@appendixsec String quartet templates


@node String quartet
@appendixsubsec String quartet

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/string-quartet-template-simple.ly}

@node String quartet parts
@appendixsubsec String quartet parts

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/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,
@pxref{Built-in templates}.


@node SATB vocal score
@appendixsubsec SATB vocal score

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/vocal-ensemble-template.ly}

@node SATB vocal score and automatic piano reduction
@appendixsubsec SATB vocal score and automatic piano reduction

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/vocal-ensemble-template-with-automatic-piano-reduction.ly}

@node SATB with aligned contexts
@appendixsubsec SATB with aligned contexts

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/vocal-ensemble-template-with-lyrics-aligned-below-and-above-the-staves.ly}

@node SATB on four staves
@appendixsubsec SATB on four staves

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/satb-choir-template---four-staves.ly}

@node Solo verse and two-part refrain
@appendixsubsec Solo verse and two-part refrain

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/vocal-ensemble-template-with-verse-and-refrain.ly}

@node Hymn tunes
@appendixsubsec Hymn tunes

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/hymn-template.ly}

@node Psalms
@appendixsubsec Psalms

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/anglican-psalm-template.ly}


@need 800
@node Orchestral templates
@appendixsec Orchestral templates


@node Orchestra choir and piano
@appendixsubsec Orchestra, choir and piano

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/orchestra,-choir-and-piano-template.ly}


@need 800
@node Ancient notation templates
@appendixsec Ancient notation templates


@node Transcription of mensural music
@appendixsubsec Transcription of mensural music

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/incipit.ly}

@node Gregorian transcription template
@appendixsubsec Gregorian transcription template

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/ancient-notation-template---modern-transcription-of-gregorian-music.ly}


@need 800
@node Other templates
@appendixsec Other templates


@node Jazz combo
@appendixsubsec Jazz combo

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{snippets/jazz-combo-template.ly}


@ignore
This isn't very useful, and only duplicates material in
"global issues".  And if this info changes, this section often
gets forgotten.

@no de Other templates
@se ction Other templates
@su bsection All headers

This template displays all available headers.  Some of them are only
used in the Mutopia project; they don't affect the printed output at
all.  They are used if you want the piece to be listed with different
information in the Mutopia database than you wish to have printed on the
music.  For example, Mutopia lists the composer of the famous D major
violin concerto as TchaikovskyPI, whereas perhaps you wish to print
"Petr Tchaikowski" on your music.

@ The `line-width` is for \header.
@li lypond[quote,verbatim,ragged-right,line-width]
\version "2.19.25"
\header {
  dedication = "dedication"
  title = "Title"
  subtitle = "Subtitle"
  subsubtitle = "Subsubtitle"
  composer = "Composer (xxxx-yyyy)"
  opus = "Opus 0"
  piece = "Piece I"
  meter = "meter"
  instrument = "Instrument"
  arranger = "Arranger"
  poet = "Poet"
  texttranslator = "Translator"
  copyright = "public domain"

  % These are headers used by the Mutopia Project
  % http://www.mutopiaproject.org/
  mutopiatitle = ""
  mutopiacomposer = ""
  mutopiapoet = ""
  mutopiainstrument = ""
  date = "composer's dates"
  source = "urtext "
  maintainer = "your name here"
  maintainerEmail = "your email here"
  maintainerWeb = "your home page"
  lastupdated = "2004/Aug/26"
}

\score {
  \header {
    piece = "piece1"
    opus = "opus1"
  }
  { c'4 }
}

\score {
  \header {
    piece = "piece2"
    opus = "opus2"
  }
  { c'4 }
}
@end lilypond
@end ignore
