Add info about compound music expressions, clarify file structure.

[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::    
@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::  
@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
@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) 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 @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 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 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.


@node Voices contain music
@section Voices contain music

TODO: something cheesy and vaguely witty about voices being the
fundamental thing that includes music in lilypond.

@menu
* I'm seeing Voices::           
* Explicitly instantiating voices::  
* Voices and vocals::           
@end menu

@c too cheesy?  I'm not certain.  -gp
@node I'm seeing Voices
@subsection I'm seeing Voices

@cindex polyphony

TODO: add intro about voices vs. layers vs. whatever.

TODO: sex this up with colors and stuff.  -gp 

TODO: actually, a general rewrite is needed.  -gp


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, separating the voices with
@code{\\}

@funindex \\

@lilypond[quote,verbatim,fragment]
\new Staff \relative c' {
  c16 d e f
  <<
    { g4 f e | d2 e2 } \\
    { r8 e4 d c8 ~ | c b16 a b8 g ~ g2 } \\
    { s2. | s4 b4 c2 }
  >>
}
@end lilypond

@cindex layers

The separator causes @internalsref{Voice}
contexts@footnote{Polyphonic voices are sometimes
called @q{layers} in other notation packages} to be instantiated.
They bear the names @code{"1"}, @code{"2"}, etc.  In each of these
contexts, vertical direction of slurs, stems, etc., is set
appropriately.

These voices are all separate from the voice that contains the
notes just outside the @code{<< \\ >>} construct.  This should be
noted when making changes at the voice level.  This also means
that slurs and ties cannot go into or out of a @code{<< \\ >>}
construct.  Conversely, parallel voices from separate @code{<< \\
>>} constructs on the same staff are the same voice.  Here is the
same example, with different noteheads and colors for each voice.
Note that the change to the note-head style in the main voice does
not affect the inside of the @code{<< \\ >>} constructs.  Also,
the change to the second voice in the first @code{<< \\ >>}
construct is effective in the second @code{<< \\ >>}, and the
voice is tied across the two constructs.

@cindex note heads, styles

@lilypond[quote,verbatim,fragment]
\new Staff \relative c' {
  \override NoteHead #'style = #'cross
  \override NoteHead #'color = #red
  c16 d e f
  <<
    { g4 f e } \\
    { \override NoteHead #'style = #'triangle
      \override NoteHead #'color = #blue
    r8 e4 d c8 ~ }
  >> |
  <<
    { d2 e2 } \\
    { c8 b16 a b8 g ~ g2 } \\
    { \override NoteHead #'style = #'slash 
      \override NoteHead #'color = #green
      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.

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

@code{noteC} is relative to @code{noteB}, not @code{noteA};
@code{noteD} is relative to @code{noteC}, not @code{noteB} or
@code{noteA}.


@node Explicitly instantiating voices
@subsection Explicitly instantiating voices

TODO: more colors and stuff.

@internalsref{Voice} contexts can also be instantiated manually
inside a @code{<< >>} block to create polyphonic music, using
@code{\voiceOne}, up to @code{\voiceFour} to assign stem
directions and a horizontal shift for each part.

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

@noindent
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.  The command
@code{\oneVoice} will revert back to the normal setting.

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 crossed colored
noteheads demonstrate that the main melody is now in a single
voice context.

@lilypond[quote,ragged-right,verbatim]
\new Staff \relative c' {
  \override NoteHead #'style = #'cross
  \override NoteHead #'color = #red
  c16 d e f
  \voiceOne
  <<
    { g4 f e | d2 e2 }
    \new Voice="1" { \voiceTwo
      r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
      \oneVoice
    }
    \new Voice { \voiceThree
      s2. | s4 b4 c2
      \oneVoice
    }
  >>
  \oneVoice
}
@end lilypond

The correct definition of the voices allows the melody to be
slurred.

@lilypond[quote,ragged-right,verbatim]
\new Staff \relative c' {
  c16^( d e f
  \voiceOne
  <<
    { g4 f e | d2 e2) }
    \context Voice="1" { \voiceTwo
      r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
      \oneVoice
    }
    \new Voice { \voiceThree
      s2. s4 b4 c2
      \oneVoice
    }
  >>
  \oneVoice
}
@end lilypond

Avoiding the @code{\\} separator also allows nesting polyphony
constructs, which in some case might be a more natural way to
typeset the music.

@lilypond[quote,ragged-right,verbatim]
\new Staff \relative c' {
  c16^( d e f
  \voiceOne
  <<
    { g4 f e | d2 e2) }
    \context Voice="1" { \voiceTwo
      r8 e4 d c8 ~ |
      <<
        {c8 b16 a b8 g ~ g2}
        \new Voice { \voiceThree
          s4 b4 c2
          \oneVoice
        }
      >>
    \oneVoice
    }
  >>
  \oneVoice
}
@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, @code{\lyricsAdd@{@}} is
very limited.  For most music, you must explicitly link the lyrics
to the notes with @code{\lyricsTo@{@}}

@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

TODO: get some vocal person to write more.


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