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

@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.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.19.21"

@ignore
Tutorial guidelines:  (different from policy.txt!)
- unless you have a really good reason, use
    @lilypond[verbatim,quote]

- 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 Common notation
@chapter Common notation

This chapter explains how to create beautifully printed music
containing common musical notation.  For the most basic steps,
@pxref{Tutorial}.

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


@node Single staff notation
@section Single staff notation

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

@menu
* Bar lines and bar checks::
* Pitches and key signatures::
* Ties and slurs::
* Articulations and dynamics::
* Adding text::
* Automatic and manual beams::
* Advanced rhythmic commands::
@end menu

@node Bar lines and bar checks
@subsection Bar lines and bar checks

@menu
* Bar lines::
* Bar checks::
@end menu

@node Bar lines
@unnumberedsubsubsec Bar lines


Single bar lines are automatically placed in the music so there is
no need to add them manually.  Other types of bar lines are added
using @code{\bar}, for example @code{\bar "||"} for a double bar
line, or @code{\bar "|."}  for an ending bar line.  For a full
list of bar lines see @ruser{Bar lines}.

@lilypond[verbatim,quote]
\relative { g'1 e1 \bar "||" c2. c'4 \bar "|." }
@end lilypond


@node Bar checks
@unnumberedsubsubsec Bar checks

Though not strictly necessary, @emph{bar checks} should be used in
the input code to show where bar lines are expected to fall.  They
are entered using the bar symbol, @samp{|}.  With bar checks, the
program can verify that you have input durations where each
measure adds up to the correct length.  Bar checks also make your
input code easier to read, since they help keep things organized.

@c This example deliberately produces a warning.
@lilypond[verbatim,quote]
\relative {
  g'1 | e1 | c2. c' | g4 c g e | c4 r r2 |
}
@end lilypond

If you compile the code in the example above, you should see a
warning in the console output:

@example
warning: barcheck failed at: 1/2
 g'1 | e1 | c2. c'
                   | g4 c g e | c4 r r2 |
@end example

@noindent
Although the missing duration is clear in the musical output in
this simple example, the warning in the console output is far more
effective in drawing attention to the missing @samp{4} in
bar@tie{}3.

@morerefs
Notation Reference:
@ruser{Bar and bar number checks}.
@endmorerefs


@node Pitches and key signatures
@subsection Pitches and key signatures

@menu
* Pitch alterations::
* Key signatures::
* Warning key signatures and pitches::
@end menu

@warning{New users often misunderstand how LilyPond uses the key
signature -- please read the warning at the end of this section.}


@node Pitch alterations
@unnumberedsubsubsec Pitch alterations

@cindex accidentals
@cindex natural
@cindex sharp
@cindex double sharp
@cindex sharp, double
@cindex flat
@cindex double flat
@cindex flat, double

@funindex es
@funindex is
@funindex eses
@funindex isis

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

@notation{Note names} in LilyPond identify pitches.  For example,
@samp{c} always means C-natural, regardless of the key signature.

In many languages, a note name consists of a base name referring
to the diatonic steps of the C@tie{}major/@/a@tie{}minor scale
(for example, @samp{d}) and a suffix, which indicates
@notation{alteration} of this base pitch.  The default input
language for note names is @q{nederlands} (Dutch).  A
@notation{sharp} pitch is made by adding @samp{is} to the name,
and a @notation{flat} pitch by adding @samp{es}.  As you might
expect, a @notation{double sharp} or @notation{double flat} is
made by adding @samp{isis} or @samp{eses}.  This syntax is derived
from note naming conventions in Nordic and Germanic languages,
like German and Dutch.  To use other naming schemes for note
names, see @ruser{Note names in other languages}.

@lilypond[verbatim,quote]
\relative { cis''4 ees fisis, aeses }
@end lilypond


@node Key signatures
@unnumberedsubsubsec Key signatures

@cindex key signature
@cindex major
@cindex minor
@cindex accidentals and key signature
@cindex content vs.@: layout
@cindex layout vs.@: content

@funindex \key
@funindex \major
@funindex \minor

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]
\relative {
  \key d \major
  d'4 fis a c |
  \bar "||" \key c \minor
  c,4 ees g b |
}
@end lilypond

@smallspace


@node Warning key signatures and pitches
@unnumberedsubsubsec Warning: key signatures and pitches

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

LilyPond makes a distinction between musical content and its
printed representation.  Input such as @samp{d4 e fis2} defines
the pitches and durations of notes, which is musical content.  The
@notation{key signature} is part of the printed representation.
The key signature also sets rules for the printed representations
of notes.  LilyPond compares each input pitch to the key signature
to determine whether to print an @notation{accidental}.

The command @code{\key} sets the @notation{key signature}, which
affects the printed representation, but does @emph{not} change the
pitch assigned to a note such as @samp{c} in the input.

Consider this example.

@lilypond[verbatim,quote]
\relative {
  \key d \major
  cis''4 d e fis
}
@end lilypond

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

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

@lilypond[verbatim,quote]
\relative {
  \key aes \major
  aes'4 c b c
}
@end lilypond

To say it differently: Whenever you enter a pitch that is a black
key on the piano, you @emph{must} add @samp{is} or @samp{es} to
the note name.

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 of how
accidentals can be printed according to different rules, see
@ruser{Automatic accidentals}.

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


@node Ties and slurs
@subsection Ties and slurs

@cindex tie
@cindex slur
@cindex slur, phrasing
@cindex phrasing slur

@funindex ~
@funindex ( ... )
@funindex \( ... \)


@menu
* Ties::
* Slurs::
* Phrasing slurs::
* Warnings slurs vs. ties::
@end menu


@node Ties
@unnumberedsubsubsec Ties

Music Glossary:
@rglos{tie}.

A @notation{tie} is created by appending a tilde @samp{~} to the
first of the two notes being tied.

@lilypond[verbatim,quote]
\relative { g'4~ g c2~ | c4~ c8 a~ a2 | }
@end lilypond

@cindex bare duration
@cindex duration, bare

When the pitch does not change, as is always the case with tied notes,
subsequent pitches may be omitted, specifying just the bare duration:

@lilypond[verbatim,quote]
\relative { g'4~ 4 c2~ | 4~ 8 a~ 2 | }
@end lilypond

This shorthand may be useful in other places where the rhythm
changes with an unchanging pitch, but remember that a bare pitch
followed by a space and a bare duration will be interpreted as a
single note.  In other words, @samp{c4 a 8 8} would be interpreted
as @samp{c4 a8 a8}, not as @samp{c4 a4 a8 a8}.  Write @samp{c4 a4
8 8} instead.


@node Slurs
@unnumberedsubsubsec Slurs

Music Glossary:
@rglos{slur}.

A @notation{slur} is a curve drawn across many notes.  The
starting note and ending note are marked with @samp{(} and
@samp{)}, respectively.  Note that @samp{(} comes after the first
note of the slur.

@lilypond[verbatim,quote]
\relative { d''4( c16) cis( d e c cis d) e( d4) }
@end lilypond


@node Phrasing slurs
@unnumberedsubsubsec Phrasing slurs

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

Slurs to indicate longer @notation{phrasing} can be entered with
@code{\(} and @code{\)}.  You can have both slurs and phrasing
slurs at the same time.

@lilypond[verbatim,quote]
\relative { g'4\( g8( a) b( c) b4\) }
@end lilypond

@smallspace


@node Warnings slurs vs. ties
@unnumberedsubsubsec Warnings: slurs vs.@: ties

@cindex slurs versus ties

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

A slur looks like a 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]
\relative { c''4(~ c8 d~ 4 e) }
@end lilypond

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


@node Articulations and dynamics
@subsection Articulations and dynamics

Articulations and dynamics are indicated by adding special codes
after the notes to which they apply.

@menu
* Articulations::
* Fingerings::
* Dynamics::
@end menu


@node Articulations
@unnumberedsubsubsec Articulations

@cindex articulation
@cindex accent
@cindex staccato

Music Glossary:
@rglos{articulation}.

Common @notation{articulations} can be added to a note using a
dash (@samp{-}) and a single character.

@lilypond[verbatim,quote]
\relative {
  c''4-^ c-+ c-- c-!
  c4-> c-. c2-_
}
@end lilypond


@node Fingerings
@unnumberedsubsubsec Fingerings

@cindex fingering

@funindex ^
@funindex _

Music Glossary:
@rglos{fingering}.

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

@lilypond[verbatim,quote]
\relative { c''4-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 (@samp{-}) with
@samp{^} (up) or @samp{_} (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]
\relative { c''4_-^1 d^. f^4_2-> e^-_+ }
@end lilypond


@node Dynamics
@unnumberedsubsubsec Dynamics

@cindex dynamics
@cindex decrescendo
@cindex crescendo

@funindex \f
@funindex \ff
@funindex \mp
@funindex \p
@funindex \mf
@funindex \pp
@funindex \<
@funindex \>
@funindex \!

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]
\relative { c''2\ff c\mf c\p c\pp }
@end lilypond

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

@lilypond[verbatim,quote]
\relative { c''2\< c | c4\ff\> c c c\! }
@end lilypond

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


@node Adding text
@subsection Adding text

@cindex text, adding
@cindex adding text
@cindex markup

@funindex \markup

Text may be added to your scores:

@lilypond[verbatim,quote]
\relative { c''2^"espr" a_"legato" }
@end lilypond

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

@lilypond[verbatim,quote]
\relative {
  c''2^\markup { \bold espr }
  a2_\markup {
    \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
}
@end lilypond

@morerefs
Notation Reference:
@ruser{Writing text}.
@endmorerefs


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

@cindex beaming
@cindex automatic beams
@cindex manual beams
@cindex beams, automatic
@cindex beams, manual
@cindex beams, by hand

@funindex [ ... ]
@funindex [
@funindex ]
@funindex \autoBeamOff
@funindex \autoBeamOn

Music Glossary:
@rglos{beam}.

All @notation{beams} are drawn automatically:

@lilypond[verbatim,quote]
\relative { a'8 ais d ees r d c16 b a8 }
@end lilypond

If you do not like the automatic beams, they may be overridden
manually.  To correct just an occasional beam mark the first note
to be beamed with @samp{[} and the last one with @samp{]}.  Note
that @samp{[} comes after the first beamed note.

@lilypond[verbatim,quote]
\relative { a'8[ ais] d[ ees r d] c16 b a8 }
@end lilypond

If you want to turn off automatic beaming entirely or for an
extended section of music, use the command @code{\autoBeamOff}
to turn off automatic beaming and @code{\autoBeamOn} to turn it
on again.

@lilypond[verbatim,quote]
\relative {
  \autoBeamOff
  a'8 c b4 d8. c16 b4 |
  \autoBeamOn
  a8 c b4 d8. c16 b4 |
}
@end lilypond

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


@node Advanced rhythmic commands
@subsection Advanced rhythmic commands

@menu
* Partial measure::
* Tuplets::
* Grace notes::
@end menu


@node Partial measure
@unnumberedsubsubsec Partial measure

@cindex pickup
@cindex anacrusis
@cindex partial measure

@funindex \partial

Music Glossary:
@rglos{anacrusis}.

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

@lilypond[verbatim,quote]
\relative {
  \partial 8 f''8 |
  c2 d |
}
@end lilypond


@node Tuplets
@unnumberedsubsubsec Tuplets

@cindex tuplets
@cindex triplets

@funindex \tuplet

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

@notation{Tuplets} are made with the @code{\tuplet} keyword.  It
takes two arguments: a fraction and a piece of music.  The
fraction is the number of tuplet notes over the number
of notes normally filling the same duration.
For triplets, there are three notes instead of two, so
@notation{triplets} have 3/2 as their fraction.

@lilypond[verbatim,quote]
\relative {
  \tuplet 3/2 { f''8 g a }
  \tuplet 3/2 { c8 r c }
  \tuplet 3/2 { f,8 g16[ a g a] }
  \tuplet 3/2 { d4 a8 }
}
@end lilypond


@node Grace notes
@unnumberedsubsubsec Grace notes

@cindex grace notes
@cindex acciaccatura
@cindex appoggiatura

@funindex \grace
@funindex \acciaccatura
@funindex \appoggiatura
@funindex acciaccatura

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]
\relative {
  c''2 \grace { a32 b } c2 |
  c2 \appoggiatura b16 c2 |
  c2 \acciaccatura b16 c2 |
}
@end lilypond

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


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

This section introduces notation 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

@cindex music expression
@cindex expression, music
@cindex compound music expression
@cindex music expression, compound

@menu
* Analogy mathematical expressions::
* Simultaneous music expressions multiple staves::
* Simultaneous music expressions single staff::
@end menu

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

@lilypond[verbatim,quote,fragment]
a'4
@end lilypond

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

@lilypond[verbatim,quote]
\relative { a'4 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]
\relative { { a'4 g } f4 g }
@end lilypond


@node Analogy mathematical expressions
@unnumberedsubsubsec 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,

@display
@math{1}
@math{1 + 2}
@math{(1 + 2) * 3}
@math{((1 + 2) * 3) / (4 * 5)}
@end display

@noindent
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 @math{+}, @math{*}, and @math{/}) and parentheses.
Like mathematical expressions, music expressions can be nested
arbitrarily deep, which is necessary for complex music like
polyphonic scores.


@node Simultaneous music expressions multiple staves
@unnumberedsubsubsec Simultaneous music expressions: multiple staves

@cindex multiple staves
@cindex staves, multiple
@cindex polyphony
@cindex combining expressions in parallel
@cindex parallel expressions
@cindex expressions, parallel
@cindex relative notes and simultaneous music
@cindex relative notes and parallel expressions
@cindex simultaneous music and relative notes
@cindex parallel expressions and relative notes

@funindex <<
@funindex >>
@funindex << ... >>

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]
<<
  \relative { a'2 g }
  \relative { f'2 e }
  \relative { d'2 b }
>>
@end lilypond

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

@warning{Each note is relative to the previous note in the input;
the first one in a @code{@bs{}relative} block is relative to @samp{c}
(one octave below the middle@tie{}C).}


@node Simultaneous music expressions single staff
@unnumberedsubsubsec Simultaneous music expressions: single staff

To determine the number of staves in a piece, LilyPond looks at
the beginning of the first expression.  If there is a single note,
there is one staff; if there is a simultaneous expression, there
is more than one staff.  The following example shows a complex
expression, but as it begins with a single note it will be set
out on a single staff.

@lilypond[verbatim,quote]
\relative {
  c''2 <<c e>> |
  << { e2 f } { c2 <<b d>> } >> |
}
@end lilypond


@node Multiple staves
@subsection Multiple staves

@cindex multiple staves
@cindex staves, multiple
@cindex context
@cindex context, notation
@cindex notation context

@funindex \new Staff
@funindex Staff
@funindex \new
@funindex Score
@funindex Voice
@funindex Lyrics
@funindex ChordNames

LilyPond input files are constructed out of music expressions
(@pxref{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]
<<
  \new Staff { \clef treble c''4 }
  \new Staff { \clef bass c4 }
>>
@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 affect all other staves by
default.  On the other hand, the key signature of one staff does
@emph{not} affect other staves.  This different default behavior
is because scores with transposing instruments are more common
than polyrhythmic scores.

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


@node Staff groups
@subsection Staff groups

@cindex piano staff
@cindex staff, piano
@cindex choir staff
@cindex staff, choir
@cindex grand staff
@cindex staff, grand
@cindex staff group

@funindex PianoStaff
@funindex GrandStaff
@funindex ChoirStaff

Music Glossary:
@rglos{brace},
@rglos{staff},
@rglos{system}.

Piano music is typeset in two staves connected by a
@notation{brace}.  Printing such a staff is similar to polyphonic
music in multiple staves (@pxref{Multiple staves}).  However, now
this entire expression is inserted into a @code{PianoStaff}:

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

Here is a small example.

@lilypond[verbatim,quote]
\new PianoStaff <<
  \new Staff \relative { \time 2/4 c''4 e | g g, | }
  \new Staff \relative { \clef bass c4 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 side of
every system and also controls the extent of bar lines.

@morerefs
Notation Reference:
@ruser{Keyboard and other multi-staff instruments},
@ruser{Displaying staves}.
@endmorerefs


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

Music Glossary:
@rglos{chord}.

@cindex chords
@cindex note durations in chords

@funindex <
@funindex >
@funindex < ... >
@funindex q

We saw earlier how notes can be combined into @notation{chords}:
by enclosing them in double angle brackets we indicated that they
are simultaneous.  However, the normal way of producing a chord is
to surround the pitches with @emph{single} angle brackets.  Note
that all notes in a chord must have the same duration, and that
the duration is placed @emph{after} the closing bracket.

@lilypond[verbatim,quote]
\relative { r4 <c'' e g> <c f a>2 }
@end lilypond

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

@lilypond[verbatim,quote]
\relative {
  r4 <c'' e g>~ <c f a>2 |
  <c e g>8[ <c f a> <c e g> <c f a>]
    <c e g>8\>[ <c f a> q q]\! |
  r4 <c e g>8.\p q16( q4-. <c f a>) |
}
@end lilypond

@cindex chord repetition
@cindex repetition, of chords

@noindent
The above example also demonstrates a very useful feature: a chord
can be repeated by using the symbol @samp{q}.  This even works
with interspersed single notes.

@lilypond[verbatim,quote]
\relative { c'8 <e g>8 q q g, q q q }
@end lilypond

@morerefs
Notation Reference:
@ruser{Chorded notes}.
@endmorerefs


@node Single staff polyphony
@subsection Single staff polyphony

@cindex polyphony
@cindex multiple voices
@cindex voices, more on one staff
@cindex single staff polyphony
@cindex spacer rest
@cindex rest, spacer

@funindex << ... \\ ... >>
@funindex <<
@funindex \\
@funindex >>

Polyphonic music in LilyPond, while not difficult, uses concepts
that we have not discussed yet, so we are not going to introduce
them here.  Instead, the following sections establish the basics
of these concepts and explain them thoroughly.

@morerefs
Learning Manual:
@ref{Voices contain music}.

Notation Reference:
@ruser{Simultaneous notes}.
@endmorerefs


@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

@funindex \addlyrics

Music Glossary:
@rglos{lyrics}.

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

@lilypond[verbatim,quote]
\relative {
  \key g \major
  \time 6/8
  d''4 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]
<<
  \relative {
    \key g \major
    \time 6/8
    d''4 b8 c4 a8 | d4 b8 g4
  }
  \addlyrics {
    Girls and boys come out to play,
  }
>>
@end lilypond

@noindent
Note the double angle brackets @code{<<@tie{}@dots{}@tie{}>>}
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

@cindex melisma
@cindex extender line
@cindex hyphens
@cindex underscore
@cindex lyrics, aligning
@cindex aligning lyrics
@cindex lyrics, multi-syllable words
@cindex words with multiple syllables in lyrics

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

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

@lilypond[verbatim,quote]
<<
  \relative {
    \key g \major
    \time 6/8
    d''4 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

Looking at the music, we see that the extra lyrics do not align
properly with the notes.  The word @emph{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.  @xref{Ties and slurs}, for more information.

@lilypond[verbatim,quote]
<<
  \relative {
    \key g \major
    \time 6/8
    d''4 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

The words now line up correctly with the notes, but the automatic
beaming for the notes above @emph{shine as} does not look right.
We can correct this by inserting manual beaming commands to
override the automatic beaming here.  @xref{Automatic and manual
beams}, for more information.

@lilypond[verbatim,quote]
<<
  \relative {
    \key g \major
    \time 6/8
    d''4 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

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

@lilypond[verbatim,quote]
<<
  \relative {
    \key g \major
    \time 6/8
    d''4 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{__}).  It is important that the
underscores are separated with one or more spaces from the
preceding (and following) syllable.

Here is an example from the first three bars of @emph{Dido's
Lament}, from Purcell's opera @emph{Dido and Æneas}:

@c no ragged-right here to get less dense formatting
@lilypond[verbatim,quote,noragged-right]
<<
  \relative {
    \key g \minor
    \time 3/2
    g'2 a bes | bes2( a) b2 |
    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 consecutive dashes (@code{--}), resulting in a centered hyphen
between the syllables.  It is important that the dashes are
separated with one or more spaces from the preceding and following
syllable.

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,noragged-right]
<<
  \relative {
    \key g \major
    \time 3/4
    \partial 4
    d'4 | g4 g a8( b) | g4 g b8( c) |
    d4 d e | 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
(@samp{_}, with no spaces), or enclosing them in quotes.  Here is
an example from Rossini's opera @notation{Il barbiere di
Siviglia}, where @emph{al} has to be sung on the same note as the
@emph{go} of @emph{Largo} in Figaro's aria @notation{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,noragged-right]
<<
  \relative {
    \clef bass
    \key c \major
    \time 6/8
    c'4.~ 8 d b | c8([ d]) b c d b | c8
  }
  \addlyrics {
    Lar -- go_al fac -- to -- tum del -- la cit -- tà
  }
>>
@end lilypond

@morerefs
Notation Reference:
@ruser{Vocal music}.
@endmorerefs


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

@cindex lyrics and multiple staves
@cindex multiple staves and lyrics

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

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

Scores any more complex than this simple example are better
produced by separating out the score structure from the notes and
lyrics with variables.  @xref{Organizing pieces with variables},
for an introduction.

@morerefs
Notation Reference:
@ruser{Vocal music}.
@endmorerefs


@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::
* Adding titles::
* Absolute note names::
* After the tutorial::
@end menu


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

@cindex variables
@cindex variables, defining
@cindex identifiers
@cindex macros
@cindex assigning variables
@cindex using variables
@cindex variables, using
@cindex variables, characters allowed in
@cindex characters allowed in variables
@cindex variables containing music expressions

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]
violin = \new Staff {
  \relative {
    a'4 b c b
  }
}

cello = \new Staff {
  \relative {
    \clef bass
    e2 d
  }
}

{
  <<
    \violin
    \cello
  >>
}
@end lilypond

By convention, variable names consist of alphabetic characters
only.  For detailed information, see @ruser{File structure}.

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]
tripletA = \relative { \tuplet 3/2 { c'8 e g } }
barA = { \tripletA \tripletA \tripletA \tripletA }

{ \barA \barA }
@end lilypond

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

@example
myWidth = 60      % a number to pass to a \paper variable
                  % (the unit is millimeter)
myName = "Wendy"  % a string to pass to a markup
aFivePaper = \paper @{ #(set-paper-size "a5") @}
@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 = \myWidth
@}

@{
  c4^\myName
@}
@end example


@node Adding titles
@subsection Adding titles

@cindex title
@cindex headers
@cindex header block

@funindex \header

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 version number.

@example
\version @w{"@version{}"}

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

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

@noindent
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 headers and footers}.


@node Absolute note names
@subsection Absolute note names

@cindex note names
@cindex note names, absolute
@cindex absolute mode
@cindex absolute values for pitches
@cindex pitches, absolute values
@cindex absolute note names

So far we have used @code{\relative} to define pitches.
This is usually the fastest way to enter most music.  Without
@code{\relative}, pitches are interpreted in absolute mode.

In this mode, LilyPond treats all pitches as absolute values: a
@samp{c'} always means middle@tie{}C, a @samp{b} always means the
note one step below middle@tie{}C, and a @samp{g,} always means
the note on the bottom line of a staff with a bass clef.

@lilypond[verbatim,quote]
{
  \clef bass
  c'4 b g, g, |
  g,4 f, f c' |
}
@end lilypond

Writing a melody in the treble clef involves a lot of quote
@samp{'} marks.  Consider this fragment from Mozart:

@lilypond[verbatim,quote]
{
  \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

@funindex \fixed

Common octave marks can be indicated just once, using the command
@code{\fixed} followed by a reference pitch:

@lilypond[verbatim,quote]
\fixed c'' {
  \key a \major
  \time 6/8
  cis8. d16 cis8 e4 e8 |
  b,8. cis16 b,8 d4 d8 |
}
@end lilypond

With @code{\relative}, the previous example needs no octave marks
because this melody moves in steps no larger than three staff positions:

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

If you make a mistake with an octave mark (@samp{'} or @samp{,})
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 with large intervals,
and is extremely useful for computer-generated LilyPond files.
When cutting and pasting melody fragments, absolute mode preserves
the original octave.

Sometimes music is arranged in more complex ways.  If you are
using @code{\relative} inside of @code{\relative}, the outer and
inner relative sections are independent:

@lilypond[verbatim,quote]
\relative { c'4 \relative { f'' g } c }
@end lilypond

To use absolute mode inside of @code{\relative}, put the absolute
music inside @code{\fixed c @{ @dots{}@tie{}@}} and the absolute
pitches will not affect the octaves of the relative music:

@lilypond[verbatim,quote]
\relative {
  c'4 \fixed c { f'' g'' } c |
  c4 \fixed c'' { f g } c
}
@end lilypond


@node After the tutorial
@subsection After the tutorial

After finishing the tutorial, you should probably try writing a
piece or two.  Start by adding notes to one of the templates
(@pxref{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,
@pxref{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.

In this tutorial and in the rest of the Learning Manual, there is
a paragraph @strong{See also} at the end of each section, which
contains cross references to other sections: you should not follow
these cross references at first reading; when you have read all of
the Learning Manual, you may want to read some sections again and
follow cross references for further reading.

If you have not done so already, @emph{please} read @ref{Overview
of manuals}.  There is a lot of information about LilyPond, so
newcomers often do not know where they should look for help.  If
you spend five minutes reading that section carefully, you might
save yourself hours of frustration looking in the wrong places!

