Merge branch 'master' of ssh://kainhofer@git.sv.gnu.org/srv/git/lilypond into kainhofer

[lilypond.git] / Documentation / user / fundamental.itely

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond-learning.tely

@node Fundamental concepts
@chapter Fundamental concepts

@menu
* How LilyPond files work::     
* Voices contain music::        
* TODO new sec fundamental::    
* Extending the templates::     
* Scores and parts::            
@end menu


@node How LilyPond files work
@section How LilyPond files work

The LilyPond input format is quite free-form, giving experienced
users a lot of flexibility to structure their files however they
wish.  However, this flexibility can make things confusing for new
users.  This section will explain some of this structure, but may
gloss over some details in favor of simplicity.  For a complete
description of the input format, see @ruser{File structure}.

@menu
* Introduction to the LilyPond file structure::  
* Score is a (single) compound musical expression::  
* Nesting Music Expressions::   
@end menu

@node Introduction to the LilyPond file structure
@subsection Introduction to the LilyPond file structure

A basic example of a lilypond input file is

@example
\version "2.11.23"
\score @{
  @var{...compound music expression...}  % all the music goes here!
  \header @{ @}
  \layout @{ @}
  \midi @{ @}
@}
@end example

@noindent
There are many variations of this basic pattern, but this
example serves as a useful starting place.

At this point, you may be confused, since you have never seen a
@code{\score@{@}} before.  This is because LilyPond automatically
adds the extra commands when you give it simple input.  LilyPond
treats input like this:

@example
\relative c'' @{
  c4 a d c
@}
@end example

@noindent
as shorthand for this:

@example
\score @{
  \relative c'' @{
    c4 a b c
  @}
  \layout @{ @}
@}
@end example

In other words, if the input contains a single music expression,
LilyPond will interpret the file as though the music expression
was wrapped up inside a @code{\score@{@}}.

@smallspace

A @code{\score} must begin with a compound music expression.
Remember that a music expression could be anything from a single
note to a huge

@example
@{
  \new GrandStaff <<
    @var{...insert the whole score of a Wagner opera in here...}
  >>
@}
@end example

@noindent
Since everything is inside @code{@{ ... @}}, it counts
as one music expression.

As we saw previously, the @code{\score} can contain other things,
such as

@example
\score @{
  @{ c'4 a b c' @}
  \header @{ @}
  \layout @{ @}
  \midi @{ @}
@}
@end example

@noindent
Some people put some of those commands outside the @code{\score}
block -- for example, @code{\header} is often placed above the
@code{\score}.  That's just another shorthand that LilyPond
accepts.

@smallspace

@cindex variables

Another great shorthand is the ability to define variables.  All
the templates use this

@example
melody = \relative c' @{
  c4 a b c
@}

\score @{
  @{ \melody @}
@}
@end example

When LilyPond looks at this file, it takes the value of
@code{melody} (everything after the equals sign) and inserts it
whenever it sees @code{\melody}.  There's nothing special about
the names -- it could be @code{melody}, @code{global},
@code{pianorighthand}, or @code{foofoobarbaz}.  You can use
whatever variable names you want as along as they contain just
alphabetic characters.  For more details, see
@ruser{Saving typing with variables and functions}.


@seealso

For a complete definition of the input format, see @ruser{File
structure}.


@node Score is a (single) compound musical expression
@subsection Score is a (single) compound musical expression

@cindex Compound music expression
@cindex Music expression, compound

We saw the general organization of LilyPond input files in the
previous section, @ref{How LilyPond files work}.  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:

@quotation
@emph{A @code{\score} must begin with a compound music expression.}
@end quotation

@noindent
You may find it useful to review @ref{Music expressions
explained}.  In that section, we saw how to 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.

@example
\score @{
  @{ % this brace begins the overall compound music expression
    \new GrandStaff <<
      @var{...insert the whole score of a Wagner opera in here...}
    >>
  @} % this brace ends the overall compound music expression
  \layout @{ @}
@}
@end example

A whole Wagner opera would easily double the length of this
manual, so let's just add a singer and piano.  We don't need a
@code{GrandStaff} for this ensemble, so we shall remove it.  We
@emph{do} need a singer and a piano, though.

@example
\score @{
  @{
    <<
      \new Staff = "singer" <<
      >>
      \new PianoStaff = piano <<
      >>
    >>
  @}
  \layout @{ @}
@}
@end example

Remember that we use @code{<<} and @code{>>} to show simultaneous
music.  And we definitely want to show the vocal part and piano
part at the same time, not one after the other!

@example
\score @{
  @{
    <<
      \new Staff = "singer" <<
        \new Voice = "vocal" @{ @}
      >>
      \new Lyrics \lyricsto vocal \new Lyrics @{ @}
      \new PianoStaff = "piano" <<
        \new Staff = "upper" @{ @}
        \new Staff = "lower" @{ @}
      >>
    >>
  @}
  \layout @{ @}
@}
@end example

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

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'' @{
  a4 b c d
@}
@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.

@example
melody = @{ @}
text   = @{ @}
upper  = @{ @}
lower  = @{ @}
\score @{
  @{
    <<
      \new Staff = "singer" <<
        \new Voice = "vocal" @{ \melody @}
      >>
      \new Lyrics \lyricsto vocal \new Lyrics @{ \text @}
      \new PianoStaff = "piano" <<
        \new Staff = "upper" @{ \upper @}
        \new Staff = "lower" @{ \lower @}
      >>
    >>
  @}
  \layout @{ @}
@}
@end example

@noindent
Remember that you can use almost any name you like as long
as it contains just alphabetic characters.  The exact
limitations on variable names are detailed in @ruser{File
structure}.

When writing (or reading) a @code{\score} section, just take it
slowly and carefully.  Start with the outer layer, then work on
each smaller layer.  It also really helps to be strict with
indentation -- make sure that each item on the same layer starts
on the same horizontal position in your text editor.


@node Nesting Music Expressions
@subsection Nesting Music Expressions

New staves do not have to all be declared at the beginning; 
they may be introduced temporarily at any point.  This is
particularly useful for creating ossia sections 
(see @rglos{ossia}).  Here's 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 
    <<
      { f c c }
      \new Staff {
        f8 f c
      }
    >>
    r4 |
  }
}
@end lilypond

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
    <<
      { f c c }
      \new Staff \with {
        alignAboveContext = "main" }
      { f8 f c }
    >>
    r4 |
  }
}
@end lilypond

Ossia are often written without clef and without
time signature and are usually in a smaller font.
These require commands which
have not yet been introduced.  See ...
TODO Add ref to tweaks section where this example should
be placed and explained.

@lilypond[verbatim,quote,ragged-right]
\new Staff = "main" {
  \relative g' {
    r4 g8 g c4 c8 d |
    e4
    <<  % Start main and ossia in parallel
      { r8 f c c }  % Main music
      \new Staff \with {  % Start ossia staff
        \remove "Clef_engraver"
        \remove "Time_signature_engraver"
        % Reduce size of notes and staff
        fontSize = #-2
        \override StaffSymbol #'staff-space = #(magstep -2)
        alignAboveContext = "main"  % Place above main staff
      }
      { s8 f f c }  % Ossia music
    >>  % End parallel music
    r4 |
  }
}
@end lilypond




@node Voices contain music
@section Voices contain music

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::          
* Explicitly instantiating voices::  
* Voices and vocals::           
@end menu

@node I'm hearing Voices
@subsection I'm hearing Voices

@cindex polyphony
@cindex layers
@cindex Voice context

The lowest, most fundamental or innermost layers in a LilyPond 
score are called Voices.  Voices are sometimes
called @q{layers} in other notation packages.  In LilyPond they
are called @q{Voice contexts}.

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.  Some instruments such as an 
Oboe can play only one note at a time and 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 concurent 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? 
Let us analyse a short piece of music to see how many voices
are required.  Here are the notes from the first two bars
of the second of Chopin's Deux Nocturnes, Op 32.

@c The following should appear as music without code
@lilypond[quote,ragged-right]
\new Staff \relative c'' {
  \key aes \major
  <<
    { \voiceOne
      c2 aes4. bes8 } \\
    { \voiceTwo
      aes2 f4 fes } \\
    { \voiceFour
      \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 here, where we have coloured the three
voices differently.

@c The following should appear as music without code
@lilypond[quote,ragged-right]
\new Staff \relative c'' {
  \key aes \major
  <<
    { \voiceOne
      \override NoteHead #'color = #red
      \override Stem #'color = #red
      c2 aes4. bes8 } \\
    { \voiceTwo
      \override NoteHead #'color = #blue
      \override Stem #'color = #blue
      aes2 f4 fes } \\
    { \voiceFour
      \override NoteHead #'color = #green
      \override Stem #'color = #green
      \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 see how this is done.

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

This example has just two voices, but the same contruct 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, 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 e2 }  \\ { c8 b16 a b8 g ~ g2 } \\ { s4 b4 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.  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 noteheads 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' {
  \voiceOneStyle
  c16 d e f
  << % Bar 1
    { g4 f e } \\
    { \voiceTwoStyle
      r8 e4 d c8 ~ }
  >> |
  << % Bar 2
    { d2 e2 } \\
    { c8 b16 a b8 g ~ g2 } \\
    { \voiceThreeStyle
      s4 b4 c2 }
  >>
}
@end lilypond

Polyphony does not change the relationship of notes within a
@code{\relative @{ @}} block.  Each note is calculated relative to
the note immediately preceding it, or to the first note of the
preceding chord.

@example
\relative @{ noteA << <noteB noteC> \\ noteD >> noteE @}
@end example

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

We are now in a position to return to the first example from
the Chopin Nocturne to see how this might be encoded.  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 des2 }
  >> |
  <c ees aes c>1 |
}
@end lilypond

@cindex stem down
@cindex stem up
@funindex \stemDown
@funindex \stemUp

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 telling LilyPond that this third voice is really a fourth
voice, with stems going down, using the @code{\voiceFour} 
command.  There are also corresponding @code{\voiceOne},
@code{\voiceTwo} and @code{voiceThree} commands.
This result in the following:

@lilypond[quote,verbatim,fragment,ragged-right]
\new Staff \relative c'' {
  \key aes \major
  << 
    { c2 aes4. bes8 } \\ 
    { aes2 f4 fes   } \\ 
    { \voiceFour <ees c>2 des2 }
  >> |
  <c ees aes c>1 |
}
@end lilypond

@noindent
and exposes a problem commonly encountered with multiple
voices: the stems of notes can collide with noteheads
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 a third voice are displaced to avoid the stems
colliding.  This often works well, but in this example the
notes of the third 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 ... )

FIXME: Move the following words and example into Tweaks or
somewhere more suitable, leaving just a ref here. -td

Ways or correcting horizontal placings are described fully 
in the Notation Reference.  
We introduce just one here, the @code{force-hshift} property of 
@code{NoteColumn}.  The lower two notes of the first chord (i.e,
those in the third voice) should not be shifted away from the
note column of the higher two notes.  To correct this we set
@code{force-hshift} of these notes to zero.  
The lower note of the second chord is best placed just to the 
right of the higher notes.  We achieve this by setting
@code{force-hshift} of this note to 0.5, ie half a notehead's 
width to the right of the note column of the higher notes.

Here's the final result:
    
@lilypond[quote,verbatim,fragment,ragged-right]
\new Staff \relative c'' {
  \key aes \major
  << 
    { c2 aes4. bes8 } \\ 
    { aes2 f4 fes   } \\ 
    { \stemDown
      \once \override NoteColumn #'force-hshift = #0 <ees c>2
      \once \override NoteColumn #'force-hshift = #0.5 des2 
    }
  >> |
  <c ees aes c>1 |
}
@end lilypond

@node Explicitly instantiating voices
@subsection Explicitly instantiating voices

Voice contexts can also be created manually
inside a @code{<< >>} block to create polyphonic music, using
@code{\voiceOne}, up to @code{\voiceFour} to automatically assign
the directions of stems, slurs, etc.

Specifically, the construct @code{<< \\  >>} which we used in
the previous section:

@example
<< \upper \\ \lower >>
@end example

@noindent
where @code{upper} and @code{lower} are user-defined variables 
containing the music for the two voices, is equivalent to 

@example
<<
  \new Voice = "1" @{ \voiceOne \upper @}
  \new Voice = "2" @{ \voiceTwo \lower @}
>>
@end example

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.

An expression that appears directly inside a @code{<< >>} belongs
to the main voice.  This is useful when extra voices appear while
the main voice is playing.  Here is a more correct rendition of
the example from the previous section.  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
  c16^( d e f  % These notes are monophonic
  <<           % Start simultaneous section of three voices
    { g4 f e | d2 e2) }  % Continue the main voice in parallel
    \new Voice {         % Initiate second voice
      \voiceTwo          % Set stems, etc, down
      r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
    }
    \new Voice {         % Initiate third voice
      \voiceThree        % Set stems, etc, up
      s2. | s4 b4 c2 
    }
  >>
}
@end lilypond

@cindex nesting music expressions
@cindex nesting simultaneous constructs

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 e2) }
    \new Voice {
      \voiceTwo
      r8 e4 d c8 ~ |
      <<
        {c8 b16 a b8 g ~ g2}
        \new Voice { 
          \voiceThree
          s4 b4 c2
        }
      >>
    }
  >>
}
@end lilypond


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' <<
  \new Voice {   % Initiate first voice
    \voiceOne
    c16^( d e f g4 f e | d2 e2) |
  }
  \new Voice {   % Initiate second voice
    \voiceTwo    % set stems, etc down
    s4 r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2 |
  }
  \new Voice {   % Initiate third voice
    \voiceThree  % set stems, etc up
    s1 | s4 b4 c2 |
  }
>>
@end lilypond



@node Voices and vocals
@subsection Voices and vocals

Vocal music presents a special difficulty: we need to combine two
expressions -- notes and lyrics.

You have already seen the @code{\lyricsAdd@{@}} command, which
handles simple cases for you.  However, this technique is
very limited.  For most music, you must 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

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 = { \time 6/8 \partial 8 \key f \major}
SopOneMusic = \relative c'' {
  c8 | c([ bes)] a a([ g)] f | f'4. b, | c4.~ c4 }
SopTwoMusic = \relative c' {
  r8 | r4. r4 c8 | a'([ g)] f f([ e)] d | e([ d)] c bes' }
SopOneLyrics = \lyricmode {
  Let | flee -- cy flocks the | hills a -- dorn, __ }
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" {
        \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.

Here is a final 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.

@lilypond[quote,verbatim]
global = { \time 4/4 \partial 4 \key c \major}
SopMusic   = \relative c' { c4 | e4. e8 g4  g  | a a g }
AltoMusic  = \relative c' { c4 | c4. c8 e4  e  | f 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 \global \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 \TenorMusic }
      \new Voice = "Bass"  { \voiceTwo \BassMusic  }
    >>
  >>
}
@end lilypond

@node TODO new sec fundamental
@section TODO new sec fundamental

blh blah


@menu
* On the un-nestedness of brackets and ties::  
@end menu

@c my name start sucking the more docs I write. -gp
@node On the un-nestedness of brackets and ties
@subsection On the un-nestedness of brackets and ties

Different kinds of brackets and ties may be mixed freely,

TODO: improve this example

@lilypond[quote,verbatim,fragment,ragged-right]
{
  r16[ g16 \times 2/3 {r16 e'8] }
  g16( a \times 2/3 {b d e') }
  g8[( a \times 2/3 {b d') e'~]}
  \times 4/5 {e'32\( a b d' e'} a'4.\)
}
@end lilypond

TODO... add more info?  Fluff up the first sentence?


@node Extending the templates
@section Extending the templates

You've read the tutorial, you know how to write music.  But how can you
get the staves that you want?  The templates are ok, but what if you
want something that isn't covered?

@menu
* Soprano and cello::           
* TODO another example of extending templates::  
@end menu

@node Soprano and cello
@subsection Soprano and cello

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 @q{Notes and lyrics} (for the
soprano part).

@example
\version "2.11.23"
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 "2.11.23"
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} sections.  So let's rename them.  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 "2.11.23"
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, @code{Staff}) happening at once.  The
@code{\score} looks like this now

@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]
\version "2.11.23"
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


@node TODO another example of extending templates
@subsection TODO another example of extending templates

TODO: somebody else fill this in.  You guys like vocal stuff,
right?  Get to it.  :)  -gp



@node Scores and parts
@section Scores and parts

TODO: this is really old stuff from the really old tutorial.
Rewrite, fix, etc.  Or maybe delete entirely.  -gp

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 e 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 e 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 e 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 {
    \time 2/4 R2*3
    r4 f8 a cis4 f e d
  }
  \new Staff {
    \clef bass
    r4 d,8 f | gis4 c | b bes |
    a8 e f4 | g d | gis f
  }
>>
@end lilypond