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

@c -*- coding: utf-8; mode: texinfo; -*-

@node Fundamental concepts
@chapter Fundamental concepts

@menu
* File structure (introduction)::  
* How LilyPond files work::     
* Score is a single musical expression::  
@end menu


@node File structure (introduction)
@section File structure (introduction)

A basic example of a lilypond input file is

@example
\version "2.11.23"
\score @{
  @{ @}     % this is a single music expression;
            % all the music goes in here.
  \header @{ @}
  \layout @{ @}
  \midi @{ @}
@}
@end example

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

The major part of this manual is concerned with entering various
forms of music in LilyPond.  However, many music expressions are not
valid input on their own, for example, a @code{.ly} file containing
only a note
@example
c'4
@end example

@noindent
will result in a parsing error.  Instead, music should be inside other
expressions, which may be put in a file by themselves.  Such
expressions are called toplevel expressions; see @ruser{File structure}, for
a list of all such expressions.


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

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 identifiers

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
@ruser{Saving typing with identifiers and functions}.

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


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

In the previous section, @ruser{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
@ruser{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
@ruser{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!