Updates from Trevor.

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

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond-learning.tely
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@ignore
Tutorial guidelines:  (different from policy.txt!)
- unless you have a really good reason, use either
    @lilypond[verbatim,quote,ragged-right]
  or
    @lilypond[verbatim,quote,ragged-right,fragment,relative=2]

  Don't use any other relative=X commands (make it a non-fragment
  example), and don't use fragment without relative=2.

- use "aes" and "ees" instead of "as" and "es".  I know it's not
  correct Dutch naming, but let's not confuse people with this
  until we get to the Basic notation chapter.

- Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant
  portions of the tutorial.

@end ignore


@node Tutorial
@chapter Tutorial

This tutorial starts with an introduction to the LilyPond music
language and explains how to produce printed music.  After this first
contact we will explain how to create beautiful printed music 
containing common musical notation.

@menu
* First steps::                 
* Single staff notation::       
* Multiple notes at once::      
* Songs::                       
* Final touches::               
@end menu


@node First steps
@section First steps

This section gives a basic introduction to working with LilyPond.

@menu
* Compiling a file::            
* Simple notation::             
* Working on text files::       
* How to read the manual::      
@end menu


@node Compiling a file
@subsection Compiling a file

The first example demonstrates how to start working with LilyPond.
To create sheet music, we write a text file that specifies the
notation.  For example, if we write:

@example
@{
  c' e' g' e'
@}
@end example

@noindent
the result looks like this:

@c  in this case we don't want verbatim
@lilypond[quote,ragged-right]
{
  c' e' g' e'
}
@end lilypond

@warning{Every piece of LilyPond input needs to have
@strong{@{ curly braces @}} placed around the input.  The braces
should also be surrounded by a space unless they are at the
beginning or end of a line to avoid ambiguities.  The braces may
be omitted in some examples in this manual, but don't forget them
in your own music!  For more information about the display of
examples in the manual, see @ref{How to read the manual}.}

@cindex case sensitive
In addition, LilyPond input is @strong{case sensitive}.  @code{
@{ c d e @}} is valid input; @code{@{ C D E @}} will produce an
error message.

@smallspace

@subheading Entering music and viewing output

@cindex PDF file
@cindex viewing music

In this section we will explain what commands to run and how to
view or print the output.

Note that there are several other text editors available with
better support for LilyPond.  For more information, see
@rprogram{Text editor support}.

@warning{The first time you ever run LilyPond, it may take a
minute or two because all of the system fonts have to be analyzed
first.  After this, LilyPond will be much faster!}

@subsubheading MacOS X

If you double click @code{LilyPond.app}, it will open with an
example file.  Save it, for example, to @file{test.ly} on your
Desktop, and then process it with the menu command @code{Compile >
Typeset File}.  The resulting PDF file will be displayed on your
screen.

For future use of LilyPond, you should begin by selecting @q{New}
or @q{Open}.  You must save your file before typesetting it.  If
any errors occur in processing, please see the log window.


@subsubheading Windows

On Windows, if you double-click in the LilyPond icon on the
Desktop, it will open a simple text editor with an example file.
Save it, for example, to @file{test.ly} on your Desktop and then
double-click on the file to process it (the file icon looks like a
note).  After some seconds, you will get a file @file{test.pdf} on
your desktop.  Double-click on this PDF file to view the typeset
score.  An alternative method to process the @file{test.ly} file
is to drag and drop it onto the LilyPond icon using your mouse
pointer.

To edit an existing @file{.ly} file, right-click on it and
select @qq{Edit source}.  To get an empty file to start from, run
the editor as described above and use @qq{New} in
the @qq{File} menu, or right-click on the desktop and select
@qq{New..Text Document}, change its name to a name of your choice
and change the file extension to @code{.ly}.  Double-click the
icon to type in your LilyPond source code as before.

Double-clicking the file does not only result in a PDF file, but
also produces a @file{.log} file that contains some information on
what LilyPond has done to the file.  If any errors occur, please
examine this file.

@subsubheading Unix

Create a text file called @file{test.ly} and enter:

@example
@{
  c' e' g' e'
@}
@end example

To process @file{test.ly}, proceed as follows:

@example
lilypond test.ly
@end example

@noindent
You will see something resembling:

@example
lilypond test.ly
GNU LilyPond 2.12.0
Processing `test.ly'
Parsing...
Interpreting music...
Preprocessing graphical objects...
Finding the ideal number of pages...
Fitting music on 1 page...
Drawing systems...
Layout output to `test.ps'...
Converting to `test.pdf'...
@end example


@node Simple notation
@subsection Simple notation

LilyPond will add some notation elements automatically.  In the
next example, we have only specified four pitches, but LilyPond
has added a clef, time signature, and rhythms.

@lilypond[verbatim,quote,ragged-right]
{
  c' e' g' e'
}
@end lilypond

@noindent
This behavior may be altered, but in most cases these automatic
values are useful.


@subheading Pitches

Music Glossary: @rglos{pitch}, @rglos{interval},
@rglos{scale}, @rglos{middle C}, @rglos{octave},
@rglos{accidental}.

The easiest way to enter notes is by using @code{\relative} mode.
In this mode, the octave is chosen automatically by assuming the
following note is always to be placed closest to the previous
note, i.e., it is to be placed in the octave which is within three
staff spaces of the previous note.  We begin by entering the most
elementary piece of music, a @notation{scale}, in which every note
is within just one staff space of the previous note.

@lilypond[verbatim,quote,ragged-right]
\relative c' {  % set the starting point to middle C
  c d e f
  g a b c
}
@end lilypond

The initial note is @notation{middle C}.  Each successive note is
placed closest to the previous note -- in other words, the first
@code{c} is the closest C to middle C.  This is followed by the
closest D to the previous note.  We can create melodies which have
larger intervals, still using only @code{\relative} mode:

@lilypond[verbatim,quote,ragged-right]
\relative c' {
  d f a g
  c b f d
}
@end lilypond

@noindent
It is not necessary for the first note of the melody to start on
the note which specifies the starting pitch.  In the previous
example, the first note -- the @code{d} -- is the closest D to
middle C.

By adding (or removing) quotes @code{'} or commas @code{,} from
the @code{\relative c' @{} command, we can change the starting
octave:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {  % one octave above middle C
  e c a c
}
@end lilypond

Relative mode can be confusing initially, but is the easiest way
to enter most melodies.  Let us see how this relative calculation
works in practice.  Starting from a B, which is on the middle line
in a treble clef, you can reach a C, D and E within 3 staff spaces
going up, and an A, G and F within 3 staff spaces going down.  So
if the note following a B is a C, D or F it will be assumed to be
above the B, and an A, G or F will be assumed to be below.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  b c  % c is 1 staff space up, so is the c above
  b d  % d is 2 up or 5 down, so is the d above
  b e  % e is 3 up or 4 down, so is the e above
  b a  % a is 6 up or 1 down, so is the a below
  b g  % g is 5 up or 2 down, so is the g below
  b f  % f is 4 up or 3 down, so is the f below
}
@end lilypond

Exactly the same happens even when any of these notes are
sharpened or flattened.  @notation{Accidentals} are
@strong{totally ignored} in the calculation of relative position.
Precisely the same staff space counting is done from a note at any
other position on the staff.

To add intervals that are larger than three staff spaces, we can
raise the @notation{octave} by adding a single quote @code{'} (or
apostrophe) to the note name.  We can lower the octave by adding a
comma @code{,} to the note name.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  a a, c' f,
  g g'' a,, f'
}
@end lilypond

@noindent
To change a note by two (or more!) octaves, we use multiple
@code{''} or @code{,,} -- but be careful that you use two single
quotes @code{''} and not one double quote @code{"}@tie{}!  The
initial value in @code{\relative c'} may also be modified like
this.
@c " - keeps quotes in order for context-sensitive editor -td

@subheading Durations (rhythms)

Music Glossary: @rglos{beam}, @rglos{duration},
@rglos{whole note}, @rglos{half note}, @rglos{quarter note},
@rglos{dotted note}.

The @notation{duration} of a note is specified by a number after
the note name.  @code{1} for a @notation{whole note}, @code{2} for
a @notation{half note}, @code{4} for a @notation{quarter note} and
so on.  @notation{Beams} are added automatically.

If you do not specify a duration, the previous duration is used
for the next note.  The duration of the first note defaults to a
quarter.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  a1
  a2 a4 a8 a
  a16 a a a a32 a a a a64 a a a a a a a a2
}
@end lilypond

To create @notation{dotted notes}, add a dot @code{.} to the
duration number.  The duration of a dotted note must be stated
explicitly (i.e., with a number).

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  a a a4. a8
  a8. a16 a a8. a8 a4.
}
@end lilypond


@subheading Rests

Music Glossary: @rglos{rest}.

A @notation{rest} is entered just like a note with the name
@code{r}:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  a r r2
  r8 a r4 r4. r8
}
@end lilypond


@subheading Time signature

Music Glossary: @rglos{time signature}.

The @notation{time signature} can be set with the @code{\time}
command:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  \time 3/4
  a4 a a
  \time 6/8
  a4. a
  \time 4/4
  a4 a a a
}
@end lilypond


@subheading Clef

Music Glossary: @rglos{clef}.

The @notation{clef} can be set using the @code{\clef} command:

@lilypond[verbatim,quote,ragged-right]
\relative c' {
  \clef treble
  c1
  \clef alto
  c1
  \clef tenor
  c1
  \clef bass
  c1
}
@end lilypond


@subheading All together

Here is a small example showing all these elements together:

@lilypond[verbatim,quote,ragged-right]
\relative c, {
  \time 3/4
  \clef bass
  c2 e8 c' g'2.
  f4 e d c4 c, r4
}
@end lilypond


@seealso

Notation Reference: @ruser{Writing pitches},
@ruser{Writing rhythms}, @ruser{Writing rests},
@ruser{Time signature}, @ruser{Clef}.


@node Working on text files
@subsection Working on text files

LilyPond input files are similar to source files in many common
programming languages.  They are case sensitive, and white-space
is generally ignored.  Expressions are formed with curly braces
@{ @}, and comments are denoted with @code{%} or @code{%@{ ...
%@}}.

If the previous sentences sound like nonsense, don't worry!  We'll
explain what all these terms mean:

@itemize

@cindex case sensitive
@item
@strong{Case sensitive}:
it matters whether you enter a letter in lower case (e.g. @code{a,
b, s, t}) or upper case (e.g.  @code{A, B, S, T}).  Notes are
lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
will produce an error message.

@item
@strong{Whitespace insensitive}:
it does not matter how many spaces (or new lines) you add.
@code{@{ c d e @}} means the same thing as @code{@{ c @tie{}
@tie{} @tie{} d e @}} and:

@example
@{ c                        d
                   e   @}
@end example

@noindent
Of course, the previous example is hard to read.  A good rule of
thumb is to indent code blocks with either a tab or two spaces:

@example
@{
  c d e
@}
@end example

@item
@strong{Expressions}:
every piece of LilyPond input needs to have @strong{@{ curly
braces @}} placed around the input.  These braces tell LilyPond
that the input is a single music expression, just like parentheses
@code{()} in mathematics.  The braces should be surrounded by a
space unless they are at the beginning or end of a line to avoid
ambiguities.

A LilyPond command followed by a simple expression in braces (such
as @code{\relative @{ @}}) also counts as a single music 
expression.

@cindex comments
@cindex line comment
@cindex block comment
@item
@strong{Comments}:
a comment is a remark for the human reader of the music input; it
is ignored while parsing, so it has no effect on the printed
output.  There are two types of comments.  The percent symbol
@code{%} introduces a line comment; anything after @code{%} on
that line is ignored.  A block comment marks a whole section of
music input as a comment.  Anything that is enclosed in @code{%@{}
and @code{%@}} is ignored.  However, block comments do not @q{nest}.
This means that you cannot place a block comment inside another 
block comment.  If you try, the first @code{%@}} will terminate 
@emph{both} block comments.  The following
fragment shows possible uses for comments:

@example
% notes for twinkle twinkle follow
  c4 c g' g a a g2

%@{
  This line, and the notes below
  are ignored, since they are in a
  block comment.

  g g f f e e d d c2
%@}
@end example

@end itemize


@node How to read the manual
@subsection How to read the manual

LilyPond input must be surrounded by @{ @} marks or a
@code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
files}.  For the rest of this manual, most examples will omit
this.  To replicate the examples, you may copy and paste the
displayed input but you @strong{must} add the @code{\relative c''
@{ @}} like this:

@example
\relative c'' @{
  ... example goes here...
@}
@end example

Why omit the braces?  Most examples in this manual can be inserted
into the middle of a longer piece of music.  For these examples,
it does not make sense to add @code{\relative c'' @{ @}} -- you
should not place a @code{\relative} inside another
@code{\relative}!  If we included @code{\relative c'' @{ @}}
around every example, you would not be able to copy a small
documentation example and paste it inside a longer piece of your
own.  Most people want to add material to an existing piece, so we
format the manual this way.


@subheading Clickable examples

Many people learn programs by trying and fiddling around with the
program.  This is also possible with LilyPond.  If you click on a
picture in the HTML version of this manual, you will see the exact
LilyPond input that was used to generate that image.  Try it on
this image:

@c no verbatim here
@lilypond[quote,ragged-right]
\relative c'' {
  c-\markup { \bold \huge { Click here.  } }
}
@end lilypond

By cutting and pasting everything in the @qq{ly snippet} section,
you have a starting template for experiments.  To see exactly the
same output (line-width and all), copy everything from @qq{Start
cut-&-pastable section} to the bottom of the file.

@seealso


There are more tips for constructing input files in
@ref{Suggestions for writing LilyPond files}.  But it might be
best to read through the rest of the tutorial first.



@node Single staff notation
@section Single staff notation

This section introduces common notation that is used for one voice
on one staff.

@menu
* Accidentals and key signatures::  
* Ties and slurs::              
* Articulation and dynamics::   
* Adding text::                 
* Automatic and manual beams::  
* Advanced rhythmic commands::  
@end menu


@node Accidentals and key signatures
@subsection Accidentals and key signatures

@subheading Accidentals

Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
@rglos{double flat}, @rglos{accidental}.

A @notation{sharp} pitch is made by adding @code{is} to the name,
and a @notation{flat} pitch by adding @code{es}.  As you might
expect, a @notation{double sharp} or @notation{double flat} is
made by adding @code{isis} or @code{eses}.  This syntax is derived
from note naming conventions in Nordic and Germanic languages,
like German and Dutch.  To use other names for
@notation{accidentals}, see @ruser{Note names in other languages}.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
cis1 ees fisis, aeses
@end lilypond

@cindex key signature, setting
@subheading Key signatures

Music Glossary: @rglos{key signature}, @rglos{major},
@rglos{minor}.

The @notation{key signature} is set with the command @code{\key}
followed by a pitch and @code{\major} or @code{\minor}.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\key d \major
a1
\key c \minor
a
@end lilypond

@smallspace

@subheading Warning: key signatures and pitches

Music Glossary: @rglos{accidental}, @rglos{key signature},
@rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
@rglos{transposition}.

To determine whether to print an @notation{accidental}, LilyPond
examines the pitches and the @notation{key signature}.  The key
signature only affects the @emph{printed} accidentals, not the
note's @notation{pitch}!  This is a feature that often causes
confusion to newcomers, so let us explain it in more detail.

LilyPond makes a sharp distinction between musical content and
layout.  The alteration (@notation{flat}, @notation{natural} or
@notation{sharp}) of a note is part of the pitch, and is therefore
musical content.  Whether an accidental (a @emph{printed} flat,
natural or sharp sign) is printed in front of the corresponding
note is a question of layout.  Layout is something that follows
rules, so accidentals are printed automatically according to those
rules.  The pitches in your music are works of art, so they will
not be added automatically, and you must enter what you want to
hear.

In this example:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\key d \major
d cis fis
@end lilypond

@noindent
No note has a printed accidental, but you must still add
@code{is} and type @code{cis} and @code{fis} in the input file.

The code @code{e} does not mean @qq{print a black dot just below
the first line of the staff.}  Rather, it means @qq{there is a
note with pitch E-natural.}  In the key of A-flat major, it
@emph{does} get an accidental:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\key aes \major
e
@end lilypond

Adding all alterations explicitly might require a little more
effort when typing, but the advantage is that
@notation{transposing} is easier, and accidentals can be printed
according to different conventions.  For some examples how
accidentals can be printed according to different rules, see
@ruser{Automatic accidentals}.

@seealso

Notation Reference: @ruser{Note names in other languages},
@ruser{Accidentals}, @ruser{Automatic accidentals},
@ruser{Key signature}.

Music Glossary: @rglos{Pitch names}.


@node Ties and slurs
@subsection Ties and slurs

@cindex ties
@subheading Ties

Music Glossary: @rglos{tie}.

A @notation{tie} is created by appending a tilde @code{~} to the
first note being tied.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
g4~ g c2~
c4 ~ c8 a8 ~ a2
@end lilypond

@cindex slurs
@subheading Slurs

Music Glossary: @rglos{slur}.

A @notation{slur} is a curve drawn across many notes.  The
starting note and ending note are marked with @code{(} and
@code{)} respectively.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
d4( c16) cis( d e c cis d) e( d4)
@end lilypond

@cindex slurs, phrasing
@cindex phrasing slurs
@subheading Phrasing slurs

Music Glossary: @rglos{phrasing}, @rglos{legato}.

Slurs to indicate longer @notation{phrasing} can be entered with
@code{\(} and @code{\)}.  You can have both @notation{legato}
slurs and phrasing slurs at the same time, but you cannot have
simultaneous legato slurs or simultaneous phrasing slurs.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a8(\( ais b c) cis2 b'2 a4 cis,\)
@end lilypond

@smallspace

@cindex slurs versus ties
@subheading Warnings: slurs vs. ties

Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.

A @notation{slur} looks like a @notation{tie}, but it has a
different meaning.  A tie simply makes the first note longer, and
can only be used on pairs of notes with the same pitch.  Slurs
indicate the @notation{articulation} of notes, and can be used on
larger groups of notes.  Slurs and ties can be nested.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c2~( c8 fis fis4 ~ fis2 g2)
@end lilypond

@seealso

Notation Reference: @ruser{Ties}, @ruser{Slurs},
@ruser{Phrasing slurs}.


@node Articulation and dynamics
@subsection Articulation and dynamics

@cindex articulation
@cindex accents
@cindex staccato
@subheading Articulations

Music Glossary: @rglos{articulation}.

Common @notation{articulations} can be added to a note using a
dash @code{-} and a single character:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c-. c-- c-> c-^ c-+ c-_
@end lilypond

@cindex fingering
@subheading Fingerings

Music Glossary: @rglos{fingering}.


Similarly, @notation{fingering} indications can be added to a note
using a dash (@code{-}) and the digit to be printed:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c-3 e-5 b-2 a-1
@end lilypond

Articulations and fingerings are usually placed automatically, but
you can specify a direction by replacing the dash (@code{-}) with
@code{^} (up) or @code{_} (down).  You can also use multiple
articulations on the same note.  However, in most cases it is best
to let LilyPond determine the articulation directions.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c_-^1 d^. f^4_2-> e^-_+
@end lilypond

@subheading Dynamics

Music Glossary: @rglos{dynamics}, @rglos{crescendo},
@rglos{decrescendo}.

@notation{Dynamic} signs are made by adding the markings (with a
backslash) to the note:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c\ff c\mf c\p c\pp
@end lilypond

@cindex dynamics
@cindex decrescendo
@cindex crescendo

@notation{Crescendi} and @notation{decrescendi} are started with
the commands @code{\<} and @code{\>}.  The next dynamics sign, for
example @code{\f}, will end the (de)crescendo, or the command
@code{\!} can be used:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c2\< c2\ff\> c2 c2\!
@end lilypond

@seealso

Notation Reference: @ruser{Articulations and ornamentations},
@ruser{Fingering instructions}, @ruser{Dynamics}.


@node Adding text
@subsection Adding text

Text may be added to your scores:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c1^"espr" a_"legato"
@end lilypond

Extra formatting may be added with the @code{\markup} command:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c1^\markup{ \bold espr}
a1_\markup{
  \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
}
@end lilypond


@seealso

Notation Reference: @ruser{Writing text}.


@node Automatic and manual beams
@subsection Automatic and manual beams

Music Glossary: @rglos{beam}.

@cindex beams, by hand
All @notation{beams} are drawn automatically:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a8 ais d ees r d c16 b a8
@end lilypond

@noindent
If you do not like the automatic beams, they may be overridden
manually.  Mark the first note to be beamed with @code{[} and the
last one with @code{]}.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a8[ ais] d[ ees r d] a b
@end lilypond

@seealso

Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.


@node Advanced rhythmic commands
@subsection Advanced rhythmic commands

@cindex pickup
@cindex anacrusis
@cindex partial measure
@subheading Partial measure

Music Glossary: @rglos{anacrusis}.

A pickup (or @notation{anacrusis}) is entered with the keyword
@code{\partial}.  It is followed by a duration: @code{\partial 4}
is a quarter note pickup and @code{\partial 8} an eighth note.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\partial 8
f8 c2 d
@end lilypond

@cindex tuplets
@cindex triplets
@subheading Tuplets

Music Glossary: @rglos{note value}, @rglos{triplet}.

@notation{Tuplets} are made with the @code{\times} keyword.  It
takes two arguments: a fraction and a piece of music.  The
duration of the piece of music is multiplied by the fraction.
Triplets make notes occupy 2/3 of their notated duration, so a
@notation{triplet} has 2/3 as its fraction

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
\times 2/3 { f8 g a }
\times 2/3 { c r c }
\times 2/3 { f,8 g16[ a g a] }
\times 2/3 { d4 a8 }
@end lilypond

@cindex grace notes
@cindex acciaccatura
@cindex appoggiatura
@subheading Grace notes

Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
@rglos{appoggiatura}.

@notation{Grace notes} are created with the @code{\grace} command,
although they can also be created by prefixing a music expression
with the keyword @code{\appoggiatura} or @code{\acciaccatura}:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c2 \grace { a32[ b] } c2
c2 \appoggiatura b16 c2
c2 \acciaccatura b16 c2
@end lilypond

@seealso

Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
@ruser{Upbeats}.


@node Multiple notes at once
@section Multiple notes at once

This section introduces having more than one note at the same
time: multiple instruments, multiple staves for a single
instrument (i.e. piano), and chords.

Polyphony in music refers to having more than one voice occurring
in a piece of music.  Polyphony in LilyPond refers to having more
than one voice on the same staff.

@menu
* Music expressions explained::  
* Multiple staves::             
* Staff groups::                
* Combining notes into chords::  
* Single staff polyphony::      
@end menu


@node Music expressions explained
@subsection Music expressions explained

In LilyPond input files, music is represented by @emph{music
expressions}.  A single note is a music expression:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a4
@end lilypond

Enclosing a note in braces creates a @emph{compound music
expression}.  Here we have created a compound music expression
with two notes:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
{ a4 g4 }
@end lilypond

Putting a group of music expressions (e.g. notes) in braces means
that they are in sequence (i.e. each one follows the previous
one).  The result is another music expression:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
{ { a4 g } f g }
@end lilypond

@cindex expression
@cindex music expression
@subheading Analogy: mathematical expressions

This mechanism is similar to mathematical formulas: a big formula
is created by composing small formulas.  Such formulas are called
expressions, and they can contain other expressions, so you can
make arbitrarily complex and large expressions.  For example,

@example
1

1 + 2

(1 + 2) * 3

((1 + 2) * 3) / (4 * 5)
@end example

This is a sequence of expressions, where each expression is
contained in the next (larger) one.  The simplest expressions are
numbers, and larger ones are made by combining expressions with
operators (like @code{+}, @code{*} and @code{/}) and parentheses.
Like mathematical expressions, music expressions can be nested
arbitrarily deep, which is necessary for complex music like
polyphonic scores.


@subheading Simultaneous music expressions: multiple staves

Music Glossary: @rglos{polyphony}.

This technique is useful for @notation{polyphonic} music.  To
enter music with more voices or more staves, we combine
expressions in parallel.  To indicate that two voices should play
at the same time, simply enter a simultaneous combination of music
expressions.  A @q{simultaneous} music expression is formed by
enclosing expressions inside @code{<<} and @code{>>}.  In the
following example, three sequences (all containing two separate
notes) are combined simultaneously:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  <<
    { a4 g }
    { f e }
    { d b }
  >>
}
@end lilypond

Note that we have indented each level of the input with a
different amount of space.  LilyPond does not care how much (or
little) space there is at the beginning of a line, but indenting
LilyPond code like this makes it much easier for humans to read.

@c FIXME: number of backslashes?!  works in html but not pdf.
@warning{each note is relative to the previous note in
the input, not relative to the @code{c''} in the initial
@code{\\relative} command.}


@subheading Simultaneous music expressions: single staff

To determine the number of staves in a piece, LilyPond looks at
the first expression.  If it is a single note, there is one staff;
if there is a simultaneous expression, there is more than one
staff.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  c2 <<c e>>
  << { e f } { c <<b d>> } >>
}
@end lilypond

@node Multiple staves
@subsection Multiple staves

LilyPond input files are constructed out of music expressions, as
we saw in @ref{Music expressions explained}.  If the score begins
with simultaneous music expressions, LilyPond creates multiples
staves.  However, it is easier to see what happens if we create
each staff explicitly.

To print more than one staff, each piece of music that makes up a
staff is marked by adding @code{\new Staff} before it.  These
@code{Staff} elements are then combined in parallel with @code{<<}
and @code{>>}:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  <<
    \new Staff { \clef treble c }
    \new Staff { \clef bass c,, }
  >>
}
@end lilypond

The command @code{\new} introduces a @q{notation context.}  A
notation context is an environment in which musical events (like
notes or @code{\clef} commands) are interpreted.  For simple
pieces, such notation contexts are created automatically.  For
more complex pieces, it is best to mark contexts explicitly.

There are several types of contexts.  @code{Score}, @code{Staff},
and @code{Voice} handle melodic notation, while @code{Lyrics} sets
lyric texts and @code{ChordNames} prints chord names.

In terms of syntax, prepending @code{\new} to a music expression
creates a bigger music expression.  In this way it resembles the
minus sign in mathematics.  The formula @math{(4+5)} is an
expression, so @math{-(4+5)} is a bigger expression.

Time signatures entered in one staff affects all other staves by
default.  On the other hand, the key signature of one staff does
@emph{not} affect other staves.  This different default behaviour
is because scores with transposing instruments are more common
than polyrhythmic scores.

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  <<
    \new Staff { \clef treble \key d \major \time 3/4 c }
    \new Staff { \clef bass c,, }
  >>
}
@end lilypond




@node Staff groups
@subsection Staff groups

@cindex piano staff
@cindex choir staff
@cindex grand staff

Music Glossary: @rglos{brace}.

Piano music is typeset in two staves connected by a
@notation{brace}.
Printing such a staff is similar to the polyphonic example in
@ref{Multiple staves}.  However, now this entire expression is
inserted inside a @code{PianoStaff}:

@example
\new PianoStaff <<
  \new Staff @dots{}
  \new Staff @dots{}
>>
@end example

Here is a small example:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  \new PianoStaff <<
    \new Staff { \time 2/4 c4 e g g, }
    \new Staff { \clef bass c,, c' e c }
  >>
}
@end lilypond

Other staff groupings are introduced with
@code{\new GrandStaff,} suitable for orchestral
scores, and @code{\new ChoirStaff,} suitable for
vocal scores.  These staff groups each form another
type of context, one that generates the brace at the
left end of every system and also controls the extent
of barlines.

@seealso

Notation Reference: @ruser{Piano music}, 
@ruser{Displaying staves}.


@node Combining notes into chords
@subsection Combining notes into chords

@cindex chords

Music Glossary: @rglos{chord}.

@notation{Chords} can be made by surrounding pitches with single
angle brackets.  Note that all the notes in a chord must have the
same duration, and that duration is placed after the closing 
bracket. 

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
r4 <c e g>4 <c f a>2
@end lilypond

Think of chords as almost equivalent to single notes:
almost everything you can attach to a single note can be attached
to a chord, and everything must go @emph{outside} the angle 
brackets.  For example, you can combine markings like beams and 
ties with chords.  They must be placed outside the angle brackets.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
r4 <c e g>8[ <c f a>]~ <c f a>2
r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
@end lilypond


@node Single staff polyphony
@subsection Single staff polyphony

@cindex polyphony
@cindex multiple voices
@cindex voices, more -- on a staff
When different melodic lines are combined on a single staff they
are printed as polyphonic voices; each voice has its own stems,
slurs and beams, and the top voice has the stems up, while the
bottom voice has them down.

Entering such parts is done by entering each voice as a sequence
(with @code{@{...@}}) and combining these simultaneously,
separating the voices with @code{\\}

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
<<
  { a4 g2 f4~ f4 } \\
  { r4 g4 f2 f4 }
>>
@end lilypond

For polyphonic music typesetting, spacer rests can also be
convenient; these are rests that do not print.  They are useful
for filling up voices that temporarily do not play.  Here is the
same example with a spacer rest (@code{s}) instead of a normal
rest (@code{r}),

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
<<
  { a4 g2 f4~ f4 } \\
  { s4 g4 f2 f4 }
>>
@end lilypond

@noindent
Again, these expressions can be nested arbitrarily.

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
<<
  \new Staff <<
    { a4 g2 f4~ f4 } \\
    { s4 g4 f2 f4 }
  >>
  \new Staff <<
    \clef bass
    { <c g>1 ~ <c g>4 } \\
    { e,,4 d e2 ~ e4}
  >>
>>
@end lilypond

@seealso

Notation Reference: @ruser{Simultaneous notes}.


@node Songs
@section Songs

This section introduces vocal music and simple song sheets.

@menu
* Setting simple songs::        
* Aligning lyrics to a melody::  
* Lyrics to multiple staves::   
@end menu


@node Setting simple songs
@subsection Setting simple songs

@cindex lyrics
@cindex songs

Music Glossary: @rglos{lyrics}.

Here is the start of the melody to a nursery
rhyme, @qq{Girls and boys come out to play}:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  \key g \major
  \time 6/8
  d4 b8 c4 a8 d4 b8 g4
}
@end lilypond

The @notation{lyrics} can be set to these notes, combining both
with the @code{\addlyrics} keyword.  Lyrics are entered by
separating each syllable with a space.

@lilypond[verbatim,quote,ragged-right]
<<
  \relative c'' {
    \key g \major
    \time 6/8
    d4 b8 c4 a8 d4 b8 g4
  }
  \addlyrics {
    Girls and boys come out to play,
  }
>>
@end lilypond

Note the curly brackets delimiting both the music and the lyrics,
and the double angle brackets @code{<< ... >>} around the whole 
piece to show that the music and lyrics are to occur at the same 
time.

@node Aligning lyrics to a melody
@subsection Aligning lyrics to a melody

Music Glossary: @rglos{melisma}, @rglos{extender line}.

@cindex melisma
@cindex extender line
@cindex hyphens
@cindex underscore

The next line in the nursery rhyme is @q{The moon doth shine as
bright as day}.  Let's extend it:

@lilypond[verbatim,quote,ragged-right]
<<
  \relative c'' {
    \key g \major
    \time 6/8
    d4 b8 c4 a8 d4 b8 g4 
    g8 a4 b8 c b a d4 b8 g4.
  }
  \addlyrics {
    Girls and boys come out to play,
    The moon doth shine as bright as day;
  }
>>
@end lilypond

We see the extra lyrics do not align properly with the notes.  The
word @q{shine} should be sung on two notes, not one.  This is
called a @notation{melisma}, a single syllable sung to more than
one note.  There are several ways to spread a syllable over
multiple notes, the simplest being to add a slur across them (see
@ref{Ties and slurs}):

@lilypond[verbatim,quote,ragged-right]
<<
  \relative c'' {
    \key g \major
    \time 6/8
    d4 b8 c4 a8 d4 b8 g4 
    g8 a4 b8 c([ b)] a d4 b8 g4.
  }
  \addlyrics {
    Girls and boys come out to play,
    The moon doth shine as bright as day;
  }
>> 
@end lilypond

Here we have also used manual beaming (the square brackets @code{[
]} ) to generate the beaming which is customarily used with lyrics
(see @ref{Automatic and manual beams}).

As an alternative to using slurs, the melismata may be indicated
in just the lyrics by using an underscore, @code{_}, for each
note that should be included in the melisma:

@lilypond[verbatim,quote,ragged-right]
<<
  \relative c'' {
    \key g \major
    \time 6/8
    d4 b8 c4 a8 d4 b8 g4 
    g8 a4 b8 c[ b] a d4 b8 g4.
  }
  \addlyrics {
    Girls and boys come out to play,
    The moon doth shine _ as bright as day;
  }
>> 
@end lilypond

If a syllable extends over several notes or a single very long
note an @notation{extender line} is usually drawn from the
syllable extending under all the notes for that syllable.  It is
entered as two underscores @code{__}.  Here is an example from the
first three bars of Dido's Lament, from Purcell's Dido and Æneas:

@lilypond[verbatim,quote,ragged-right]
<<
  \relative c'' {
    \key g \minor
    \time 3/2
    g2 a bes bes( a) 
    b c4.( bes8 a4. g8 fis4.) g8 fis1
  }
  \addlyrics {
    When I am laid, 
    am laid __ in earth,
  }
>>
@end lilypond

None of the examples so far have involved words containing more
than one syllable.  Such words are usually split one syllable to a
note, with hyphens between syllables.  Such hyphens are entered as
two dashes, resulting in a centered hyphen between the syllables.
Here is an example showing this and everything we have learned so
far about aligning lyrics to notes.

@c no ragged-right here because otherwise the hyphens get lost,
@c but the example is long enough to avoid looking strange.
@lilypond[verbatim,quote]
<<
  \relative c' {
    \key g \major
    \time 3/4
    \partial 4
    d4 g4 g a8( b) g4 g4 
    b8( c) d4 d e4 c2
  }
  \addlyrics {
    A -- way in a __ man -- ger, 
    no __ crib for a bed, __
  }
>>
@end lilypond

Some lyrics, especially those in Italian, require the opposite:
setting more than one syllable to a single note.  This is
achieved by linking the syllables together with a single
underscore @code{_} (with no spaces), or enclosing them in
quotes.  Here's an example from Rossini's Figaro, where
@q{al} has to be sung on the same note as the @q{go} of 
@q{Largo} in Figaro's aria @q{Largo al factotum}:

@c no ragged-right here because otherwise the hyphens get lost,
@c but the example is long enough to avoid looking strange.
@lilypond[verbatim,quote]
<<
  \relative c' {
    \clef bass
    \key c \major
    \time 6/8
    c4.~ c8 d b c([ d)] b c d b c
  }
  \addlyrics {
    Lar -- go_al fac -- to -- tum del -- la cit -- tà
  }
>>
@end lilypond


@seealso

Notation Reference: @ruser{Vocal music}.


@node Lyrics to multiple staves
@subsection Lyrics to multiple staves

The simple approach using @code{\addlyrics} can be used for
placing lyrics under more than one staff.  Here is an
example from Handel's Judas Maccabæus:

@lilypond[verbatim,quote,ragged-right]
<<
  {
    \time 6/8
    \partial 8
  }
  \relative c'' {
    \key f \major
    c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
  }
  \addlyrics {
    Let flee -- cy flocks the hills a -- dorn, __
  }
  \relative c' {
    \key f \major
    r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
  }
  \addlyrics {
    Let flee -- cy flocks the hills a -- dorn,
  }
>>
@end lilypond

@noindent
but scores any more complex than this simple example are
better produced by separating out the staff structure
from the notes and lyrics with variables.  These are
discussed in @ref{Organizing pieces with variables}.

@seealso

Notation Reference: @ruser{Vocal music}.



@node Final touches
@section Final touches

This is the final section of the tutorial; it demonstrates how to
add the final touches to simple pieces, and provides an
introduction to the rest of the manual.

@menu
* Organizing pieces with variables::  
* Version number::              
* Adding titles::               
* Absolute note names::         
* After the tutorial::          
@end menu


@node Organizing pieces with variables
@subsection Organizing pieces with variables

When all of the elements discussed earlier are combined to produce
larger files, the music expressions get a lot bigger.  In
polyphonic music with many staves, the input files can become very
confusing.  We can reduce this confusion by using
@emph{variables}.

With variables (also known as identifiers or macros), we can break
up complex music expressions.  A variable is assigned as
follows:

@example
namedMusic = @{ @dots{} @}
@end example

The contents of the music expression @code{namedMusic} can be used
later by placing a backslash in front of the name
(@code{\namedMusic}, just like a normal LilyPond command).

@lilypond[verbatim,quote,ragged-right]
violin = \new Staff { \relative c'' {
  a4 b c b
}}
cello = \new Staff { \relative c {
  \clef bass
  e2 d
}}
{
  <<
    \violin
    \cello
  >>
}
@end lilypond

@noindent
The name of a variable must have alphabetic characters only, no
numbers, underscores, or dashes.

Variables must be defined @emph{before} the main music
expression, but may be used as many times as required anywhere after
they have been defined.  They may even be used in a later definition
of another variable, giving a way of shortening the input if a
section of music is repeated many times.

@lilypond[verbatim,quote,ragged-right]
tripletA = \times 2/3 { c,8 e g }
barA = { \tripletA \tripletA \tripletA \tripletA }

\relative c'' {
 \barA \barA
}
@end lilypond

Variables may be used for many other types of objects in
the input.  For example,

@example
width = 4.5\cm
name = "Wendy"
aFivePaper = \paper @{ paperheight = 21.0 \cm @}
@end example

Depending on its contents, the variable can be used in different
places.  The following example uses the above variables:

@example
\paper @{
  \aFivePaper
  line-width = \width
@}
@{ c4^\name @}
@end example


@node Version number
@subsection Version number

@cindex versioning
The @code{\version} statement records the version of LilyPond that
was used to write the file:

@example
\version "2.11.23"
@end example

@noindent
By convention, this is placed at the top of your LilyPond file.

These annotations make future upgrades of LilyPond go more
smoothly.  Changes in the syntax are handled with a special
program, @file{convert-ly}, and it uses @code{\version} to
determine what rules to apply.  For details, see
@rprogram{Updating files with convert-ly}.


@node Adding titles
@subsection Adding titles

The title, composer, opus number, and similar information are
entered in the @code{\header} block.  This exists outside of the
main music expression; the @code{\header} block is usually placed
underneath the @ref{Version number}.

@example
\version "2.11.23"
\header @{
  title = "Symphony"
  composer = "Me"
  opus = "Op. 9"
@}

@{
  @dots{} music @dots{}
@}
@end example

When the file is processed, the title and composer are printed
above the music.  More information on titling can be found in
@ruser{Creating titles}.


@node Absolute note names
@subsection Absolute note names

So far we have always used @code{\relative} to define pitches.
This is the easiest way to enter most music, but another way of
defining pitches exists: absolute mode.

If you omit the @code{\relative}, LilyPond treats all pitches as
absolute values.  A @code{c'} will always mean middle C, a
@code{b} will always mean the note one step below middle C, and a
@code{g,} will always mean the note on the bottom staff of the
bass clef.

@lilypond[verbatim,quote,ragged-right]
{
  \clef bass
  c' b g, g,
  g, f, f c'
}
@end lilypond

Here is a four-octave scale:

@lilypond[verbatim,quote,ragged-right]
{
  \clef bass
  c, d, e, f,
  g, a, b, c
  d e f g
  a b c' d'
  \clef treble
  e' f' g' a'
  b' c'' d'' e''
  f'' g'' a'' b''
  c'''1
}
@end lilypond

As you can see, writing a melody in the treble clef involves a lot
of quote @code{'} marks.  Consider this fragment from Mozart:

@lilypond[verbatim,quote,ragged-right]
{
  \key a \major
  \time 6/8
  cis''8. d''16 cis''8 e''4 e''8
  b'8. cis''16 b'8 d''4 d''8
}
@end lilypond

All these quotes makes the input less readable and they are a source
of errors.  With @code{\relative}, the previous example is much
easier to read and type:

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  \key a \major
  \time 6/8
  cis8. d16 cis8 e4 e8
  b8. cis16 b8 d4 d8
}
@end lilypond

If you make a mistake with an octave mark (@code{'} or @code{,})
while working in @code{\relative} mode, it is very obvious -- many
notes will be in the wrong octave.  When working in absolute mode,
a single mistake will not be as visible, and will not be as easy
to find.

However, absolute mode is useful for music which has large
intervals, and is extremely useful for computer-generated LilyPond
files.



@node After the tutorial
@subsection After the tutorial

FIXME: rewrite slightly after the rest of the LM has been
stabilized.  Translators, ignore this section for now.

After finishing the tutorial, you should probably try writing a
piece or two.  Start by adding notes to one of the
@ref{Templates}.  If you need any notation that was not covered in
the tutorial, look at the Notation Reference, starting with
@ruser{Musical notation}.  If you want to write for an instrument
ensemble that is not covered in the templates, take a look at
@ref{Extending the templates}.

Once you have written a few short pieces, read the rest of the
Learning Manual (chapters 3-5).  There's nothing wrong with
reading it now, of course!  However, the rest of the Learning
Manual assumes that you are familiar with LilyPond input.  You may
wish to skim these chapters right now, and come back to them after
you have more experience.