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
+- Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant
portions of the tutorial.
@end ignore
@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::
* Compiling a file::
* Simple notation::
* Working on text files::
-* How to read the tutorial::
+* 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.
+@qq{Compiling} is the term used for processing an input text file
+in LilyPond format to produce a file which can be printed and
+(optionally) a MIDI file which can be played. The first example
+shows what a simple input text file looks like.
+
To create sheet music, we write a text file that specifies the
notation. For example, if we write:
}
@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
in your own music! For more information about the display of
-examples in the manual, see @ref{How to read the tutorial}.}
+examples in the manual, see @ref{How to read the manual}.}
-@cindex Case sensitive
+@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.
@subheading Entering music and viewing output
@cindex PDF file
-@cindex Viewing music
+@cindex viewing music
In this section we will explain what commands to run and how to
view or print the output.
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!}
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 @samp{Compile >
+Desktop, and then process it with the menu command @code{Compile >
Typeset File}. The resulting PDF file will be displayed on your
screen.
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
@subsubheading Unix
-Create a file (such as @file{test.ly}) and enter:
+Create a text file called @file{test.ly} and enter:
@example
@{
@subheading Pitches
-Music glossary: @rglos{pitch}, @rglos{interval}, @rglos{fourth},
-@rglos{scale}, @rglos{middle C}, @rglos{octave}.
+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 @notation{interval} between the previous note and
-the current note is assumed to be within a @notation{fourth}. We
-begin by entering the most elementary piece of music, a
-@notation{scale}.
+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' {
+\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
-within a fourth of the previous note -- in other words, the first
+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:
+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' {
@end lilypond
@noindent
-As you may notice, this example does not start on middle C. The first
-note -- the @code{d} -- is the closest D to middle C.
+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.
-To add intervals that are larger than a fourth, 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.
+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'' {
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}.
+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. @samp{1} for a @notation{whole note}, @samp{2} for
-a @notation{half note}, @samp{4} for a @notation{quarter note} and
+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
}
@end lilypond
-@noindent
-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.
-
-To create @notation{dotted notes}, add a dot @samp{.} to the duration
-number.
+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'' {
@subheading Rests
-Music glossary: @rglos{rest}.
+Music Glossary: @rglos{rest}.
-A @notation{rest} is entered just like a note with the name @samp{r}:
+A @notation{rest} is entered just like a note with the name
+@code{r}:
@lilypond[verbatim,quote,ragged-right]
\relative c'' {
@subheading Time signature
-Music glossary: @rglos{time signature}.
+Music Glossary: @rglos{time signature}.
The @notation{time signature} can be set with the @code{\time}
command:
@subheading Clef
-Music glossary: @rglos{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}.
-
+Notation Reference: @ruser{Writing pitches},
+@ruser{Writing rhythms}, @ruser{Writing rests},
+@ruser{Time signature}, @ruser{Clef}.
-@c HERE's where I started
@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 equivalent. Expressions are formed with curly braces
+is generally ignored. Expressions are formed with curly braces
@{ @}, and comments are denoted with @code{%} or @code{%@{ ...
%@}}.
-If the previous sentence sounds like nonsense, don't worry! We'll
+If the previous sentences sound like nonsense, don't worry! We'll
explain what all these terms mean:
@itemize
-@cindex Case sensitive
+@cindex case sensitive
@item
@strong{Case sensitive}:
it matters whether you enter a letter in lower case (e.g. @code{a,
@end example
@item
-@strong{Expressions:}
-Every piece of LilyPond input needs to have @strong{@{ curly
+@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
-@samp{()} in mathematics. The braces should be surrounded by a
+@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 function (such as @code{\relative @{ @}}) also counts as a
-single music expression.
+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
+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
-@samp{%} introduces a line comment; anything after @samp{%} 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:
+@code{%} introduces a line comment; anything after @code{%} on
+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
@end itemize
-There are more tips for constructing input files in
-@ref{Suggestions for writing LilyPond files}.
-
-@node How to read the tutorial
-@subsection How to read the tutorial
+@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
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
on one staff.
@menu
-* Relative note names::
* Accidentals and key signatures::
* Ties and slurs::
* Articulation and dynamics::
@end menu
-@node Relative note names
-@subsection Relative note names
-
-Music glossary: @rglos{octave}, @rglos{fourth}, @rglos{fifth}.
-
-LilyPond calculates the pitch of each note relative to the
-previous one@footnote{There is another mode of entering pitches,
-@ruser{Absolute note names}. However, in practice relative mode is
-much easier and safer to use.}, as we saw in @ref{Simple
-notation}. If no extra @notation{octave} marks (@code{'} and
-@code{,}) are added, it assumes that each pitch is within a
-@notation{fourth} of the previous note.
-
-LilyPond examines pitches based on the note names -- in other
-words, an augmented fourth is @emph{not} treated the same as a
-diminished fifth. If we begin at a C, then an F-sharp will be placed a
-higher than the C, while a G-flat will be placed lower than the C.
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c2 fis
-c2 ges
-@end lilypond
-
-@seealso
-@quotation
-@table @asis
-@item Relative octaves
-see @ruser{Relative octaves}.
-@item Octave check
-see @ruser{Octave check}.
-@end table
-@end quotation
-
-
@node Accidentals and key signatures
@subsection Accidentals and key signatures
@subheading Accidentals
-Music glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
+Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
@rglos{double flat}, @rglos{accidental}.
-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 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}.
+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
@cindex key signature, setting
@subheading Key signatures
-Music glossary: @rglos{key signature}, @rglos{major}, @rglos{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}.
@subheading Warning: key signatures and pitches
-Music glossary: @rglos{accidental}, @rglos{key signature},
+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.
+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
+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 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.
+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:
@end lilypond
@noindent
-No note has a printed accidental, but you must still add the
-@samp{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 @samp{e} does not mean @qq{print a black dot just below
+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:
@ruser{Automatic accidentals}.
@seealso
-@quotation
-@table @asis
-@item Accidentals
-see @ruser{Accidentals}, and @ruser{Automatic accidentals}.
-@item Key signature
-see @ruser{Key signature}
-@item Pitch names
-see @rglos{Pitch names}.
-@end table
-@end quotation
+
+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
@cindex ties
@subheading Ties
-Music glossary: @rglos{tie}.
+Music Glossary: @rglos{tie}.
-A @notation{tie} is created by appending a tilde @samp{~} to the
-first note being tied
+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~
@cindex slurs
@subheading Slurs
-Music glossary: @rglos{slur}.
+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.
+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)
@cindex phrasing slurs
@subheading Phrasing slurs
-Music glossary: @rglos{phrasing}, @rglos{legato}.
+Music Glossary: @rglos{slurs}, @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 slurs versus ties
@subheading Warnings: slurs vs. ties
-Music glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
+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.
+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
-@quotation
-@table @asis
-@item Ties
-see @ruser{Ties}.
-@item Slurs
-see @ruser{Slurs}.
-@item Phrasing slurs
-see @ruser{Phrasing slurs}.
-@end table
-@end quotation
+
+Notation Reference: @ruser{Ties}, @ruser{Slurs},
+@ruser{Phrasing slurs}.
@node Articulation and dynamics
@cindex staccato
@subheading Articulations
-Music glossary: @rglos{articulation}.
+Music Glossary: @rglos{articulation}.
Common @notation{articulations} can be added to a note using a
-dash @samp{-} and a single character:
+dash @code{-} and a single character:
@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c-. c-- c-> c-^ c-+ c-_
@cindex fingering
@subheading Fingerings
-Music glossary: @rglos{fingering}.
+Music Glossary: @rglos{fingering}.
-Similarly, @notation{fingering} indications can be added to a note using
-a dash (@samp{-}) and the digit to be printed:
+
+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 using @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.
+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^-_+
@subheading Dynamics
-Music glossary: @rglos{dynamics}, @rglos{crescendo},
+Music Glossary: @rglos{dynamics}, @rglos{crescendo},
@rglos{decrescendo}.
@notation{Dynamic} signs are made by adding the markings (with a
@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]
@end lilypond
@seealso
-@quotation
-@table @asis
-@item Articulations
-see @ruser{Articulations}.
-@item Fingering
-see @ruser{Fingering instructions}.
-@item Dynamics
-see @ruser{Dynamics} (Notation reference) and @rglos{dynamics}
-(Glossary).
-@end table
-@end quotation
-
-@c CONTINUE HERE
+
+Notation Reference: @ruser{Articulations and ornamentations},
+@ruser{Fingering instructions}, @ruser{Dynamics}.
+
@node Adding text
@subsection Adding text
@end lilypond
-@c Kurt: leave this alone for now.
-
@seealso
-Notation reference: @ruser{Writing text}.
+Notation Reference: @ruser{Writing text}.
@node Automatic and manual beams
@subsection Automatic and manual beams
-Music glossary: @rglos{beam}.
+Music Glossary: @rglos{beam}.
@cindex beams, by hand
All @notation{beams} are drawn automatically:
@noindent
If you do not like the automatic beams, they may be overridden
-manually. Mark the first note to be beamed with @samp{[} and the
-last one with @samp{]}.
+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
-@quotation
-@table @asis
-@item Automatic beams
-see @ruser{Automatic beams}.
-@item Manual beams
-see @ruser{Manual beams}.
-@end table
-@end quotation
+
+Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
@node Advanced rhythmic commands
@cindex partial measure
@subheading Partial measure
-Music glossary: @rglos{anacrusis}.
+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}
@cindex triplets
@subheading Tuplets
-Music glossary: @rglos{note value}, @rglos{triplet}.
+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
@cindex appoggiatura
@subheading Grace notes
-Music glossary: @rglos{grace notes}, @rglos{appoggiatura}.
+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
@end lilypond
@seealso
-@quotation
-@table @asis
-@item Grace notes
-see @ruser{Grace notes},
-@item Tuplets
-see @ruser{Tuplets},
-@item Pickups
-see @ruser{Partial measures}.
-@end table
-@end quotation
+
+Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
+@ruser{Upbeats}.
@node Multiple notes at once
@menu
* Music expressions explained::
* Multiple staves::
-* Piano staves::
+* Staff groups::
* Combining notes into chords::
* Single staff polyphony::
@end menu
{ { 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}.
+Music Glossary: @rglos{polyphony}.
This technique is useful for @notation{polyphonic} music. To
enter music with more voices or more staves, we combine
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.
+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'' {
}
@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 their definition is recursive 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 @samp{+}, @samp{*} and @samp{/}) and parentheses.
-Like mathematical expressions, music expressions can be nested
-arbitrarily deep, which is necessary for complex music like
-polyphonic scores.
-
-
@node Multiple staves
@subsection Multiple staves
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@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.
+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 \time 3/4 c }
- \new Staff { \clef bass \key d \major c,, }
+ \new Staff { \clef treble \key d \major \time 3/4 c }
+ \new Staff { \clef bass c,, }
>>
}
@end lilypond
-@node Piano staves
-@subsection Piano staves
+@node Staff groups
+@subsection Staff groups
-@cindex staff switch, manual
-@cindex cross staff voice, manual
+@cindex piano staff
+@cindex choir staff
+@cindex grand staff
-Music glossary: @rglos{brace}.
+Music Glossary: @rglos{brace}.
Piano music is typeset in two staves connected by a
@notation{brace}.
}
@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 bar lines.
+
@seealso
-@quotation
-See @ruser{Piano music}.
-@end quotation
+
+Notation Reference: @ruser{Piano music},
+@ruser{Displaying staves}.
@node Combining notes into chords
@cindex chords
-Music glossary: @rglos{chord}.
+Music Glossary: @rglos{chord}.
-@notation{Chords} can be made by surrounding pitches with single
-angle brackets. Angle brackets are the symbols @samp{<} and
-@samp{>}.
+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
@end lilypond
-You can combine markings like beams and ties with chords. They
-must be placed outside the angle brackets
+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
-@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
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 (@samp{s}) instead of a normal
-rest (@samp{r}),
+same example with a spacer rest (@code{s}) instead of a normal
+rest (@code{r}),
@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
<<
@end lilypond
@seealso
-@quotation
-See @ruser{Simultaneous notes}.
-@end quotation
+
+Notation Reference: @ruser{Simultaneous notes}.
@node Songs
@node Setting simple songs
@subsection Setting simple songs
-@cindex Lyrics
-@cindex Songs
+@cindex lyrics
+@cindex songs
-Music glossary: @rglos{lyrics}.
+Music Glossary: @rglos{lyrics}.
Here is the start of the melody to a nursery
rhyme, @qq{Girls and boys come out to play}:
@end lilypond
Note the curly brackets delimiting both the music and the lyrics,
-and the 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 @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}.
+Music Glossary: @rglos{melisma}, @rglos{extender line}.
@cindex melisma
@cindex extender line
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}):
+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]
<<
]} ) 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:
+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]
<<
@seealso
-@quotation
-More options, such as inserting explicit rhythms into lyrics,
-inserting lyric ties (e.g., between @q{go al}) above,
-alternative ways of handling melismata,
-and adding extra verses,
-are discussed in @ruser{Vocal music}.
-@end quotation
+
+Notation Reference: @ruser{Vocal music}.
+
@node Lyrics to multiple staves
@subsection Lyrics to multiple staves
>>
@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 later (see @ref{Organizing pieces with variables}).
+discussed in @ref{Organizing pieces with variables}.
@seealso
-@quotation
-More options, such as putting multiple stanzas below the score,
-setting choral music, and lyrics to divided voices,
-are discussed in @ruser{Vocal music}.
-@end quotation
+
+Notation Reference: @ruser{Vocal music}.
+
@node Final touches
introduction to the rest of the manual.
@menu
+* Organizing pieces with variables::
* Version number::
* Adding titles::
* Absolute note names::
-* Organizing pieces with variables::
* After the tutorial::
-* How to read the manual::
@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
was used to write the file:
@example
-\version "2.11.23"
+\version "2.11.38"
@end example
@noindent
underneath the @ref{Version number}.
@example
-\version "2.11.23"
+\version "2.11.38"
\header @{
title = "Symphony"
composer = "Me"
}
@end lilypond
-All these quotes makes the input less readable and it is a source
+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:
+easier to read and type:
@lilypond[verbatim,quote,ragged-right]
\relative c'' {
files.
-@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. An 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).
-Variables must be defined @emph{before} the main music
-expression.
-
-@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 an variable must have alphabetic characters only, no
-numbers, underscores, or dashes.
-
-It is possible to use variables 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 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
+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}.
you have more experience.
-@node How to read the manual
-@subsection How to read the manual
-Many examples in the tutorial omitted a @code{\relative c'' @{
-... @}} around the printed example, as we saw in
-@ref{How to read the tutorial}.
-
-In the rest of the manual, we are much more lax about the printed
-examples: sometimes they may have omitted a @code{\relative c'' @{
-... @}}, but other times a different initial pitch may be used
-(such as @code{c'} or @code{c,,}), and in some cases the whole
-example is in absolute note mode! However, ambiguities like this
-only exist where the pitches are not important. In any example
-where the pitch matters, we have explicitly stated
-@code{\relative} or absolute-mode @code{@{ @}}.
-
-If you are still confused about the exact LilyPond input that was
-used in an example, read the HTML version (if you are not already
-doing so) and click on the picture of the music. This will
-display the exact input that LilyPond used to generate this
-manual.
-
-For information about the structure of the rest of the manual, see
-@ref{About this manual}.