version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.38"
+
@ignore
Tutorial guidelines: (different from policy.txt!)
- unless you have a really good reason, use either
@chapter Tutorial
This tutorial starts with an introduction to the LilyPond music
-language and how to produce printed music. After this first
-contact we will explain how to create common musical notation.
+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::
@menu
* Compiling a file::
* Simple notation::
-* Working on text files::
-* How to read the manual::
+* Working on input 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
+@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
+files are simple text files. The first example
+shows what a simple input file looks like.
+
+To create sheet music, we write an input file that specifies the
notation. For example, if we write:
@example
}
@end lilypond
-@warning{Every piece of LilyPond input needs to have
-@strong{@{ curly braces @}} placed around the input. The braces
+@warning{Notes and lyrics in LilyPond input must always be
+surrounded by @strong{@{ curly braces @}}. 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
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.
+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.
@smallspace
better support for LilyPond. For more information, see
@rprogram{Text editor support}.
-@warning{the first time you ever run LilyPond, it may take a
+@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
+If you double click @command{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.
+Desktop, and then process it with the menu command
+@w{@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
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.
+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
+@subsubheading UNIX
-Create a file (such as @file{test.ly}) and enter:
+Create a text file called @file{test.ly} and enter:
@example
@{
middle C.
By adding (or removing) quotes @code{'} or commas @code{,} from
-the @code{\relative c' @{} command, we can change the starting
+the @w{@code{\relative c' @{}} command, we can change the starting
octave:
@lilypond[verbatim,quote,ragged-right]
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
+if the note following a B is a C, D or E 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]
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 4 up or 3 down, so is the a below
+ 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 6 up or 1 down, so is the f below
+ b f % f is 4 up or 3 down, so is the f below
}
@end lilypond
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
+initial value in @w{@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{rest}.
A @notation{rest} is entered just like a note with the name
-@code{r}:
+@code{r}@tie{}:
@lilypond[verbatim,quote,ragged-right]
\relative c'' {
@ruser{Time signature}, @ruser{Clef}.
-@node Working on text files
-@subsection Working on text files
+@node Working on input files
+@subsection Working on input files
LilyPond input files are similar to source files in many common
programming languages. They are case sensitive, and white-space
-is generally equivalent. Expressions are formed with curly braces
-@{ @}, and comments are denoted with @code{%} or @code{%@{ ...
-%@}}.
+is generally ignored. Expressions are formed with curly braces
+@{ @}, and comments are denoted with @code{%} or
+@w{@code{%@{ ... %@}}}.
If the previous sentences sound like nonsense, don't worry! We'll
explain what all these terms mean:
@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.
+it matters whether you enter a letter in lower case (e.g.
+@w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
+Notes are lower case: @w{@code{@{ c d e @}}} is valid input;
+@w{@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:
+@w{@code{@{ c d e @}}} means the same thing as
+@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
@example
@{ c d
space unless they are at the beginning or end of a line to avoid
ambiguities.
-A function (such as @code{\relative @{ @}}) also counts as a
-single music expression.
+A LilyPond command followed by a simple expression in braces (such
+as @w{@code{\relative @{ @}}}) also counts as a single music
+expression.
@cindex comments
@cindex line comment
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. (Comments do not nest.) The following
-fragment shows possible uses for comments:
+that line is ignored. By convention, a line comment is placed
+@emph{above} the code it refers to.
+
+@example
+a4 a a a
+% this comment refers to the Bs
+b2 b
+@end example
+
+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
@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:
+@w{@code{\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:
@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 @code{\relative c'' @{ @}} -- you
-should not place a @code{\relative} inside another
-@code{\relative}! If we included @code{\relative c'' @{ @}}
+it does not make sense to add @w{@code{\relative c'' @{ @}}} --
+you should not place a @code{\relative} inside another
+@code{\relative}! If we included @w{@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
There are more tips for constructing input files in
-@ref{Suggestions for writing LilyPond files}.
+@ref{Suggestions for writing LilyPond input files}. But it might be
+best to read through the rest of the tutorial first.
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
+layout. The alteration (@notation{flat}, @notation{natural sign} 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
@end lilypond
@noindent
-No note has a printed accidental, but you must still add the
-@code{is} to @code{cis} and @code{fis}.
+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
@cindex phrasing slurs
@subheading Phrasing slurs
-Music Glossary: @rglos{phrasing}, @rglos{legato}.
+Music Glossary: @rglos{slur}, @rglos{phrasing}.
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.
+@code{\(} and @code{\)}. You can have both @notation{slurs}
+and phrasing slurs at the same time, but you cannot have
+simultaneous slurs or simultaneous phrasing slurs.
@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
a8(\( ais b c) cis2 b'2 a4 cis,\)
@cindex crescendo
@notation{Crescendi} and @notation{decrescendi} are started with
-the commands @code{\<} and @code{\>}. An ending dynamic, for
-example @code{\f}, will finish the (de)crescendo, or the command
+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]
@seealso
-Notation Reference: @ruser{Articulations},
+Notation Reference: @ruser{Articulations and ornamentations},
@ruser{Fingering instructions}, @ruser{Dynamics}.
@cindex appoggiatura
@subheading Grace notes
-Music Glossary: @rglos{grace notes}, @rglos{acciacccatura},
+Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
@rglos{appoggiatura}.
@notation{Grace notes} are created with the @code{\grace} command,
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 music expressions, so you
-can make arbitrarily complex and large expressions. For example,
+expressions, and they can contain other expressions, so you can
+make arbitrarily complex and large expressions. For example,
@example
1
@warning{each note is relative to the previous note in
the input, not relative to the @code{c''} in the initial
-@code{\\relative} command.}
+@code{@bs{}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.
+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.
@lilypond[verbatim,quote,ragged-right]
\relative c'' {
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@footnote{This behavior may be changed if desired; for
-details, see @ruser{Polymetric notation}.}. 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.
+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 behavior
+is because scores with transposing instruments are more common
+than polyrhythmic scores.
@lilypond[verbatim,quote,ragged-right]
\relative 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.
+Other staff groupings are introduced with @code{\new GrandStaff},
+suitable for orchestral scores, and @w{@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 bar lines.
@seealso
-Notation Reference: @ruser{Piano music},
+Notation Reference: @ruser{Keyboard instruments},
@ruser{Displaying staves}.
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.
+We saw earlier how notes can be combined into @notation{chords} by
+indicating they are simultaneous by enclosing them in double angle
+brackets. However, the normal way of indicating a chord is to
+surround the pitches with @emph{single} angle brackets. Note that
+all the notes in a chord must have the same duration, and that the
+duration is placed after the closing bracket.
@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
r4 <c e g>4 <c f a>2
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
+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
-@end lilypond
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
+r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
@end lilypond
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{\\}
+(with @w{@code{@{...@}}}) and combining these simultaneously,
+separating the voices with @code{\\}:
@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
<<
@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.
+and the double angle brackets @w{@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
>>
@end lilypond
-Here we have also used manual beaming (the square brackets @code{[
-]} ) to generate the beaming which is customarily used with lyrics
+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
-just in the lyrics by using an underscore, @code{_}, for each
+in just the lyrics by using an underscore, @code{_}, for each
note that should be included in the melisma:
@lilypond[verbatim,quote,ragged-right]
@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
+from the notes and lyrics with variables. These are
discussed in @ref{Organizing pieces with variables}.
@seealso
was used to write the file:
@example
-\version "2.11.23"
+\version @w{"@version{}"}
@end example
@noindent
underneath the @ref{Version number}.
@example
-\version "2.11.23"
+\version @w{"@version{}"}
\header @{
title = "Symphony"
composer = "Me"
+
projects / lilypond.git / blobdiff