Second round of reorg for the Learning manual.

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

@c -*- coding: utf-8; mode: texinfo; -*-
@node Putting it all together
@chapter Putting it all together

This chapter is an extention of the tutorial, dealing with FIXME.


@menu
* Extending the templates::     
* How LilyPond files work::     
* Score is a single musical expression::  
* Organizing larger pieces::    
* An orchestral part::          
@end menu


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

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 ``Notes and lyrics'' (for the
soprano part).

@example
\version "2.7.39"
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 @{ \tempo 4=60 @}
@}
@end example

Now we want to add a cello part.  Let's look at the ``Notes only'' example:

@example
\version "2.7.39"
melody = \relative c' @{
  \clef treble
  \key c \major
  \time 4/4

  a4 b c d
@}
     
\score @{
\new Staff \melody
\layout @{ @}
\midi @{ \tempo 4=60 @}
@}
@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 one
for the soprano @code{sopranoMusic}, and the one for the cello can be
called @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.7.39"
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 @{ \tempo 4=60 @}
@}
@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 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 @{ \tempo 4=60 @}
@}
@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.7.39"
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 { \tempo 4=60 }
}
@end lilypond



@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 @ref{File structure}.

Most examples in this manual are little snippets -- for example

@example
c4 a b c
@end example

As you are (hopefully) aware by now, this will not compile by
itself.  These examples are shorthand for complete
examples.  They all need at least curly braces to compile

@example
@{
  c4 a b c
@}
@end example

Most examples also make use of the @code{\relative c'}
(or @code{c''}) command.  This is not necessary to merely
compile the examples, but in most cases the output will
look very odd if you omit the @code{\relative c'}.

@lilypond[quote,fragment,ragged-right,verbatim]
\relative c'' {
  c4 a b c
}
@end lilypond

Now we get to the only real stumbling block: LilyPond
input in this form is actually @emph{another}
shorthand.  Although it compiles and displays the
correct output, it is shorthand for

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

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

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

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

The @code{\score} can contain other things, such as

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

@noindent
Most people put some of those commands outside the
@code{\score} block -- for example, @code{\header} is
almost always placed above the @code{\score}.  That's
just another shorthand.

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.

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


@node Score is a single musical expression
@section Score is a single musical expression

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

@example
A @code{\score} must begin with a single music expression.
@end example

@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 music expression
    \new GrandStaff <<
      insert the whole score of a Wagner opera in here
    >>
  @}   % this brace ends the overall music expression
  \layout @{ @}
@}
@end example

A whole Wagner opera would easily double the length of
this manual, so let's just do 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!

@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 identifiers (or
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.  The
limitations on identifier names are detailed in
@ref{File structure}.

When writing a @code{\score} section, or when reading
one, 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 Organizing larger pieces
@section Organizing larger pieces

When all of the elements discussed earlier are combined to produce
larger files, the @code{\score} blocks get a lot bigger, because the
music expressions are longer, and, in the case of polyphonic pieces,
more deeply nested.  Such large expressions can become unwieldy.

By using variables, also known as identifiers, it is possible to break
up complex music expressions.  An identifier is assigned as follows

@example
namedMusic = @{ @dots{} @}
@end example

@noindent
The contents of the music expression @code{namedMusic}, can be used
later by preceding the name with a backslash, i.e., @code{\namedMusic}.
In the next example, a two-note motive is repeated two times by using
variable substitution

@lilypond[quote,ragged-right,verbatim,nofragment]
seufzer = {
  e'4( dis'4)
}
{ \seufzer \seufzer }
@end lilypond

The name of an identifier should have alphabetic characters only; no
numbers, underscores or dashes.  The assignment should be outside of
running music.

It is possible to use variables for many other types of objects in the
input.  For example,

@example
width = 4.5\cm
name = "Wendy"
aFivePaper = \paper @{ paperheight = 21.0 \cm @}
@end example

Depending on its contents, the identifier can be used in different
places.  The following example uses the above variables

@example
\paper @{
  \aFivePaper
  line-width = \width
@}
@{ c4^\name @}
@end example

More information on the possible uses of identifiers is given in the
technical manual, in @ref{Input variables and Scheme}.
@c fixme: the ref is too technical.


@node An orchestral part
@section An orchestral part

In orchestral music, all notes are printed twice.  Once in a part for
the musicians, and once in a full score for the conductor.  Identifiers 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
@samp{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 @samp{R} followed by a duration
(1@tie{}for a whole note, 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

More in-depth information on preparing parts and scores can be found
in the notation manual; see @ref{Orchestral music}.

Setting run-time variables (`properties') is discussed in
@ref{Changing context properties on the fly}.