@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::     
* Score is a single musical expression::  
@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}.

A basic example of a lilypond input file is

@example
\version "2.11.23"
\score @{
  @{@var{...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 single 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
@cindex identifiers

Another great shorthand is the ability to define identifiers.  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}.


@seealso

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

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 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 <<
      @var{...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 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 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 (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.