More Funamental stuff.

[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::     
* Score is a single musical expression::  
* I'm seeing Voices::           
* On the un-nestedness of brackets and ties::  
@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.



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

@cindex polyphony

@c TODO: sex this up with colors and stuff.  -gp 
@c 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}.


@c my name start sucking the more docs I write. -gp
@node On the un-nestedness of brackets and ties
@section 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?