version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.61"
+@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
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
@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.
@seealso
-
Notation Reference: @ruser{Writing pitches},
@ruser{Writing rhythms}, @ruser{Writing rests},
@ruser{Time signature}, @ruser{Clef}.
@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
@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
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}.
c2~( c8 fis fis4 ~ fis2 g2)
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Ties}, @ruser{Slurs},
@ruser{Phrasing slurs}.
c2\< c2\ff\> c2 c2\!
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Articulations and ornamentations},
@ruser{Fingering instructions}, @ruser{Dynamics}.
@seealso
-
Notation Reference: @ruser{Writing text}.
a8 c b4 d8. c16 b4
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
c2 \acciaccatura b16 c2
@end lilypond
-@seealso
+@seealso
Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
@ruser{Upbeats}.
@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'' {
type of context, one that generates the brace at the left end of
every system and also controls the extent of bar lines.
-@seealso
+@seealso
Notation Reference: @ruser{Keyboard and other multi-staff
instruments},
@ruser{Displaying staves}.
@funindex \\
@funindex >>
-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
-
-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,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
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}.
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
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!