Add @cindex entries for variables and identifiers.

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

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

This chapter discusses general LilyPond concepts and how to
create @code{\score} blocks.


@menu
* Extending the templates::     
* How LilyPond files work::     
* Score is a single musical expression::  
@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.9.13"
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 ``Notes only'' example:

@example
\version "2.9.13"
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.9.13"
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.9.13"
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 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 @{ @}
  \midi @{ @}
  \header @{ @}
@}
@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.

@cindex variables
@cindex indentifiers

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
more details, see
@ref{Saving typing with identifiers and functions}.

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:

@quotation
@emph{A @code{\score} must begin with a single 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 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!