version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.12.0"
@ignore
Tutorial guidelines: (different from policy.txt!)
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
+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::
+* First steps::
+* Single staff notation::
+* Multiple notes at once::
+* Songs::
+* Final touches::
@end menu
This section gives a basic introduction to working with LilyPond.
@menu
-* Compiling a file::
-* Simple notation::
+* Compiling a file::
+* Simple notation::
* Working on input files::
* How to read the manual::
@end menu
@node Compiling a file
@subsection Compiling a file
+@cindex compiling
+@cindex first example
+@cindex example, first
+@cindex case sensitive
+
@qq{Compiling} is the term used for processing an input file
in LilyPond format to produce a file which can be printed and
(optionally) a MIDI file which can be played. LilyPond input
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}.
@w{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
produce an error message.
@cindex PDF file
@cindex viewing music
+@cindex text editors
+@cindex running LilyPond under MacOS X
+@cindex MacOS X, running LilyPond
+@cindex running LilyPond under Windows
+@cindex Windows, running LilyPond
+@cindex running LilyPond under Unix
+@cindex Unix, running LilyPond
In this section we will explain what commands to run and how to
view or print the output.
@node Simple notation
@subsection Simple notation
+@cindex simple notation
+@cindex notation, simple
+
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.
@subheading Pitches
+@cindex pitches
+@cindex relative mode
+@cindex quote, single
+@cindex comma
+@cindex accidentals and relative mode
+@cindex relative mode, and accidentals
+
+@funindex \relative
+@funindex relative
+@funindex '
+@funindex ,
+
Music Glossary: @rglos{pitch}, @rglos{interval},
@rglos{scale}, @rglos{middle C}, @rglos{octave},
@rglos{accidental}.
middle C.
By adding (or removing) quotes @code{'} or commas @code{,} from
-the @w{@code{\relative c' @{}} command, we can change the starting
+the @code{@w{\relative c' @{}} command, we can change the starting
octave:
@lilypond[verbatim,quote]
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 @w{@code{\relative c'}} may also be modified like
+initial value in @code{@w{\relative c'}} may also be modified like
this.
@c " - keeps quotes in order for context-sensitive editor -td
@subheading Durations (rhythms)
+@cindex note durations
+@cindex durations
+@cindex rhythms
+@cindex whole note
+@cindex half note
+@cindex quarter note
+@cindex dotted note
+@cindex notating durations
+
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
+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.
@subheading Rests
+@cindex rest
+@cindex notating rests
+
Music Glossary: @rglos{rest}.
A @notation{rest} is entered just like a note with the name
@subheading Time signature
+@cindex time signature
+
+@funindex \time
+@funindex time
+
Music Glossary: @rglos{time signature}.
The @notation{time signature} can be set with the @code{\time}
@subheading Clef
+@cindex clef
+@cindex treble
+@cindex alto
+@cindex tenor
+@cindex bass
+
+@funindex \clef
+@funindex clef
+
Music Glossary: @rglos{clef}.
The @notation{clef} can be set using the @code{\clef} command:
@seealso
-
Notation Reference: @ruser{Writing pitches},
@ruser{Writing rhythms}, @ruser{Writing rests},
@ruser{Time signature}, @ruser{Clef}.
@node Working on input files
@subsection Working on input files
+@cindex curly braces
+@cindex braces, curly
+@cindex comments
+@cindex line comment
+@cindex comment, line
+@cindex block comment
+@cindex comment, line
+@cindex case sensitive
+@cindex whitespace insensitive
+@cindex expressions
+
+@funindex { ... }
+@funindex %
+@funindex %@{ ... %@}
+
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
@itemize
-@cindex case sensitive
@item
@strong{Case sensitive}:
it matters whether you enter a letter in lower case (e.g.
@item
@strong{Whitespace insensitive}:
-it does not matter how many spaces (or new lines) you add.
+it does not matter how many spaces (or tabs or new lines) you add.
@w{@code{@{ c d e @}}} means the same thing as
@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
@}
@end example
+However, whitespace @emph{is} required to separate many syntactical
+elements from others. In other words, whitespace can always be
+@emph{added}, but it cannot be @emph{eliminated}. As missing
+whitespace can give rise to strange errors it is advisable to
+always insert whitespace before and after every syntactic element,
+for example, before and after every curly brace.
+
@item
@strong{Expressions}:
every piece of LilyPond input needs to have @strong{@{ curly
@node How to read the manual
@subsection How to read the manual
+@cindex how to read the manual
+@cindex manual, reading
+@cindex reading the manual
+@cindex examples, clickable
+@cindex clickable examples
+@cindex tips for constructing files
+@cindex templates
+@cindex constructing files, tips
+@cindex files, tips for constructing
+
LilyPond input must be surrounded by @{ @} marks or a
-@w{@code{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
+@code{@w{\relative c'' @{ ... @}}}, as we saw in @ref{Working on
input 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
-@w{@code{\relative c'' @{ @}}} like this:
+@code{@w{\relative c'' @{ @}}} like this:
@example
\relative c'' @{
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 @w{@code{\relative c'' @{ @}}} --
+it does not make sense to add @code{@w{\relative c'' @{ @}}} --
you should not place a @code{\relative} inside another
-@code{\relative}! If we included @w{@code{\relative c'' @{ @}}}
+@code{\relative}! If we included @code{@w{\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
same output (line-width and all), copy everything from @qq{Start
cut-&-pastable section} to the bottom of the file.
-@seealso
+@seealso
There are more tips for constructing input files in
@ref{Suggestions for writing LilyPond input files}. But it might be
best to read through the rest of the tutorial first.
-
@node Single staff notation
@section Single staff notation
on one staff.
@menu
-* Accidentals and key signatures::
-* Ties and slurs::
-* Articulation and dynamics::
-* Adding text::
-* Automatic and manual beams::
-* Advanced rhythmic commands::
+* Accidentals and key signatures::
+* Ties and slurs::
+* Articulation and dynamics::
+* Adding text::
+* Automatic and manual beams::
+* Advanced rhythmic commands::
@end menu
@subheading Accidentals
+@cindex accidentals
+@cindex accidentals and key signatures
+@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}.
@cindex key signature, setting
@subheading 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 key
+@funindex \major
+@funindex major
+@funindex \minor
+@funindex minor
+
Music Glossary: @rglos{key signature}, @rglos{major},
@rglos{minor}.
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 on
-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
+The code @code{b} does not mean @qq{print a 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=2]
\key aes \major
-e
+b
@end lilypond
Adding all alterations explicitly might require a little more
accidentals can be printed according to different rules, see
@ruser{Automatic accidentals}.
-@seealso
+@seealso
Notation Reference: @ruser{Note names in other languages},
@ruser{Accidentals}, @ruser{Automatic accidentals},
@ruser{Key signature}.
@node Ties and slurs
@subsection Ties and slurs
-@cindex ties
+@cindex tie
+@cindex slur
+@cindex slur, phrasing
+@cindex phrasing slur
+
+@funindex ~
+@funindex ( ... )
+@funindex \( ... \)
+
@subheading Ties
+
Music Glossary: @rglos{tie}.
A @notation{tie} is created by appending a tilde @code{~} to the
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
d4( c16) cis( d e c cis d) e( d4)
@end lilypond
-@cindex slurs, phrasing
-@cindex phrasing slurs
@subheading Phrasing slurs
Music Glossary: @rglos{slur}, @rglos{phrasing}.
c2~( c8 fis fis4 ~ fis2 g2)
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Ties}, @ruser{Slurs},
@ruser{Phrasing slurs}.
@node Articulation and dynamics
@subsection Articulation and dynamics
+
+@subheading Articulations
+
@cindex articulation
-@cindex accents
+@cindex accent
@cindex staccato
-@subheading Articulations
Music Glossary: @rglos{articulation}.
c-. c-- c-> c-^ c-+ c-_
@end lilypond
-@cindex fingering
@subheading Fingerings
+@cindex fingering
+
+@funindex ^
+@funindex _
+
Music Glossary: @rglos{fingering}.
Similarly, @notation{fingering} indications can be added to a note
@subheading Dynamics
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
+
+@funindex \f
+@funindex \ff
+@funindex \mp
+@funindex \p
+@funindex \mf
+@funindex \pp
+@funindex \<
+@funindex <
+@funindex \>
+@funindex >
+@funindex \!
+@funindex !
+
Music Glossary: @rglos{dynamics}, @rglos{crescendo},
@rglos{decrescendo}.
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
c2\< c2\ff\> c2 c2\!
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Articulations and ornamentations},
@ruser{Fingering instructions}, @ruser{Dynamics}.
@node Adding text
@subsection Adding text
+@cindex text, adding
+@cindex adding text
+@cindex markup
+
+@funindex \markup
+@funindex markup
+
Text may be added to your scores:
@lilypond[verbatim,quote,relative=2]
@seealso
-
Notation Reference: @ruser{Writing text}.
@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 autoBeamOff
+@funindex \autoBeamOn
+@funindex autoBeamOn
+
Music Glossary: @rglos{beam}.
-@cindex beams, by hand
All @notation{beams} are drawn automatically:
@lilypond[verbatim,quote,relative=2]
a8 c b4 d8. c16 b4
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
@node Advanced rhythmic commands
@subsection Advanced rhythmic commands
+@subheading Partial measure
+
@cindex pickup
@cindex anacrusis
@cindex partial measure
-@subheading Partial measure
+
+@funindex \partial
+@funindex partial
Music Glossary: @rglos{anacrusis}.
f8 c2 d
@end lilypond
+@subheading Tuplets
+
@cindex tuplets
@cindex triplets
-@subheading Tuplets
+
+@funindex \times
+@funindex times
Music Glossary: @rglos{note value}, @rglos{triplet}.
\times 2/3 { d4 a8 }
@end lilypond
+@subheading Grace notes
+
@cindex grace notes
@cindex acciaccatura
@cindex appoggiatura
-@subheading Grace notes
+
+@funindex \grace
+@funindex grace
+@funindex \acciaccatura
+@funindex acciaccatura
+@funindex \appoggiatura
+@funindex acciaccatura
Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
@rglos{appoggiatura}.
c2 \acciaccatura b16 c2
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
@ruser{Upbeats}.
@node Music expressions explained
@subsection Music expressions explained
+@cindex music expression
+@cindex expression, music
+@cindex compound music expression
+@cindex music expression, compound
+
In LilyPond input files, music is represented by @emph{music
expressions}. A single note is a music expression:
{ { 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
@subheading 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
@subheading Simultaneous music expressions: single staff
To determine the number of staves in a piece, LilyPond looks at
-the beginning of the first expression. If is a single note, there
-is one staff; if there is a simultaneous expression, there is more
-than one staff.
+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'' {
@node Multiple staves
@subsection Multiple staves
+@cindex multiple staves
+@cindex staves, multiple
+@cindex context
+@cindex context, notation
+@cindex notation context
+
+@funindex \new Staff
+@funindex new Staff
+@funindex Staff
+@funindex \new
+@funindex new
+@funindex Score
+@funindex Voice
+@funindex Lyrics
+@funindex ChordNames
+
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
@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}.
type of context, one that generates the brace at the left end of
every system and also controls the extent of bar lines.
-@seealso
-Notation Reference: @ruser{Keyboard instruments},
+@seealso
+Notation Reference: @ruser{Keyboard and other multi-staff
+instruments},
@ruser{Displaying staves}.
@subsection Combining notes into chords
@cindex chords
+@cindex note durations in chords
+
+@funindex <
+@funindex >
+@funindex < ... >
Music Glossary: @rglos{chord}.
@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 @w{@code{@{...@}}}) and combining these simultaneously,
-separating the voices with @code{\\}:
-
-@lilypond[verbatim,quote,relative=2]
-<<
- { a4 g2 f4~ f4 } \\
- { r4 g4 f2 f4 }
->>
-@end lilypond
+@cindex voices, more on one staff
+@cindex single staff polyphony
+@cindex spacer rest
+@cindex rest, spacer
-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}),
+@funindex << ... \\ ... >>
+@funindex <<
+@funindex \\
+@funindex >>
-@lilypond[verbatim,quote,relative=2]
-<<
- { a4 g2 f4~ f4 } \\
- { s4 g4 f2 f4 }
->>
-@end lilypond
-
-@noindent
-Again, these expressions can be nested arbitrarily.
-
-@lilypond[verbatim,quote,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
+Polyphonic music in lilypond, while not difficult, uses concepts
+that we haven't discussed yet, so we're not going to introduce
+them here. Instead, the following sections introduce these concepts
+and explain them thoroughly.
@seealso
+Learning Manual: @ref{Voices contain music}.
Notation Reference: @ruser{Simultaneous notes}.
-
@node Songs
@section Songs
@cindex lyrics
@cindex songs
+@funindex \addlyrics
+@funindex addlyrics
+
Music Glossary: @rglos{lyrics}.
Here is the start of the melody to a nursery
@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
+@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 @notation{The moon doth
shine as bright as day}. Let's extend it:
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 @notation{Dido's Lament}, from Purcell's
+first three bars of @notation{Dido's Lament}, from Purcell's
@notation{Dido and Æneas}:
@lilypond[verbatim,quote]
@seealso
-
Notation Reference: @ruser{Vocal music}.
@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 @notation{Judas Maccabæus}:
lyrics with variables. These are discussed in @ref{Organizing
pieces with variables}.
-@seealso
+@seealso
Notation Reference: @ruser{Vocal music}.
-
@node Final touches
@section Final touches
@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
+
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
@subsection Version number
@cindex versioning
+@cindex version
+@cindex version number
+@cindex upgrades
+@cindex future upgrades
+@cindex updating files
+@cindex files, updating
+
+@funindex \version
+@funindex version
+@funindex convert-ly
+
The @code{\version} statement records the version of LilyPond that
was used to write the file:
@node Adding titles
@subsection Adding titles
+@cindex title
+@cindex headers
+@cindex header block
+
+@funindex \header
+@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
@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 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 have not done so already, @emph{please} read @ref{About the
documentation}. 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
+you spend five minutes reading that section carefully, you might
save yourself hours of frustration looking in the wrong places!
projects / lilypond.git / blobdiff