[lilypond.git] / 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.19.2"

@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

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.

@warning {Unlike most included files, this built-in template must be
@code{\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.

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

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{\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 file @file{ly/satb.ly}.

@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

@node Notes only
@appendixsubsec Notes only

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

@node Notes and lyrics
@appendixsubsec Notes and lyrics

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

@node Notes and chords
@appendixsubsec Notes and chords

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

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

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


@node Piano templates
@appendixsec Piano templates

@menu
* Solo piano::
* Piano and melody with lyrics::
* Piano centered lyrics::
@end menu

@node Solo piano
@appendixsubsec Solo piano

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

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

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

@node Piano centered lyrics
@appendixsubsec Piano centered lyrics

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


@node String quartet templates
@appendixsec String quartet templates

@menu
* String quartet::
* String quartet parts::
@end menu

@node String quartet
@appendixsubsec String quartet

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

@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

@node SATB vocal score
@appendixsubsec SATB vocal score

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{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]
{vocal-ensemble-template-with-automatic-piano-reduction.ly}

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

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{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]
{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]
{vocal-ensemble-template-with-verse-and-refrain.ly}

@node Hymn tunes
@appendixsubsec Hymn tunes

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

@node Psalms
@appendixsubsec Psalms

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


@node Orchestral templates
@appendixsec Orchestral templates

@menu
* Orchestra choir and piano::
@end menu

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

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


@node Ancient notation templates
@appendixsec Ancient notation templates

@menu
* Transcription of mensural music::
* Gregorian transcription template::
@end menu

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

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

@node Gregorian transcription template
@appendixsubsec Gregorian transcription template

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


@node Other templates
@appendixsec Other templates

@menu
* Jazz combo::
@end menu

@node Jazz combo
@appendixsubsec Jazz combo

@lilypondfile[verbatim,quote,ragged-right,texidoc]
{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.2"
\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 {
  { c'4 }
  \header {
    piece = "piece1"
    opus = "opus1"
  }
}

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