@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond.tely
+@c This file is part of lilypond-learning.tely
@ignore
Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.61"
+
@ignore
-Tutorial guidelines:
+Tutorial guidelines: (different from policy.txt!)
- unless you have a really good reason, use either
- @l ilypond[quote,ragged-right,verbatim]
+ @lilypond[verbatim,quote]
or
- @l ilypond[quote,ragged-right,verbatim,fragment,relative=2]
- (without spaces)
- Don't use any other relative=X commands (make it a non-fragment
- example), and don't use fragment without relative=2.
-- use "aes" and "ees" instead of "as" and "aes". I know it's not
- correct Dutch naming, but let's not confuse people with this until
- we get to the Basic notation chapter.
-@end ignore
+ @lilypond[verbatim,quote,relative=2]
+ Don't use any other relative=X commands.
+- use "aes" and "ees" instead of "as" and "es". I know it's not
+ correct Dutch naming, but let's not confuse people with this
+ until we get to the Basic notation chapter.
-@c old info that will probably be removed.
-@c TODO:
-@c * more details about running lilypond; error messages,
-@c compiling/viewing (emacs?)
-@c * where to go from First steps+More basics?
+- Add "Music Glossary: @rglos{foo}" to the *top* of the relevant
+ portions of the tutorial.
-@c wherever possible, do not include index entries here; the
-@c index should point to stuff in the reference manual. -gp
+@end ignore
-@c Your first LilyPond score in 10 minutes?
@node Tutorial
@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.
-
-@ifhtml
-Many people learn programs by trying and fiddling around with the
-program. This is also possible with LilyPond. If you click on a
-picture in the HTML version of this manual, you will see the exact
-LilyPond input that was used to generate that image.
-Try it on this image
-
-@c no verbatim here
-@lilypond[quote,ragged-right]
-\relative c'' {
- c-\markup { \bold \huge { Click here. } }
-}
-@end lilypond
-
-By cutting and pasting everything in the @qq{ly snippet} section, you have a
-starting template for experiments. If you like learning in this way,
-you will probably want to print out or bookmark the
-@ruser{Cheat sheet}, which is a table listing of the most common
-commands for quick reference.
-@end ifhtml
+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 tutorial::
+* 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
-notation. For example, if we write
+@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
+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 example
@noindent
-the result looks like this
+the result looks like this:
@c in this case we don't want verbatim
-@lilypond[quote,ragged-right]
+@lilypond[quote]
{
c' e' g' e'
}
@end lilypond
-@strong{Warning:} Every piece of LilyPond input needs to have @strong{@{ curly
-braces @}} placed around the input. The braces should also be
-surrounded by a space unless they are at the beginning or end of a
-line to avoid ambiguities. These may be omitted in some examples in this
-manual, but don't forget them in your own music!
+@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 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.
-@sp 1
+@smallspace
@subheading Entering music and viewing output
-In this section we will explain what commands to run
-and how to view or print the output.
+@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.
+
+Note that there are several other text editors available with
+better support for LilyPond. For more information, see
+@rprogram{Text editor support}.
+
+@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 example
-file. Save it, for example, to @file{test.ly} on your Desktop, and
-then process it with the menu command @samp{Compile > Typeset File}.
-The resulting PDF file will be displayed on your screen.
-
-Be warned that the first time you ever run LilyPond, it will take a minute
-or two because all of the system fonts have to be analyzed first.
+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
+@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 any errors
-occur in processing, please see the log window.
+or @q{Open}. You must save your file before typesetting it. If
+any errors occur in processing, please see the log window.
+
@subsubheading Windows
-On Windows, if you double-click in the LilyPond icon on the Desktop, it
-will open a simple text editor with an example file. Save it, for
-example, to @file{test.ly} on your Desktop and then double-click on the
-file to process it (the file icon looks like a note). After some
-seconds, you will get a file @file{test.pdf}
-on your desktop. Double-click on this PDF file to view the typeset
+On Windows, if you double-click in the LilyPond icon on the
+Desktop, it will open a simple text editor with an example file.
+Save it, for example, to @file{test.ly} on your Desktop and then
+double-click on the file to process it (the file icon looks like a
+note). After some seconds, you will get a file @file{test.pdf} on
+your desktop. Double-click on this PDF file to view the typeset
score. An alternative method to process the @file{test.ly} file
-is to drag and drop it onto the LilyPond icon using your mouse pointer.
+is to drag and drop it onto the LilyPond icon using your mouse
+pointer.
-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.
+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, 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.
+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.
-Note that there are several other text editors available, with better
-support for LilyPond, see @rprogram{Text editor support}, for more information.
+@subsubheading UNIX
-@subsubheading Unix
+Create a text file called @file{test.ly} and enter:
-Begin by opening a terminal window and starting a text editor. For
-example, you could open an xterm and execute
-@code{joe}@footnote{There are macro files for VIM addicts, and there
-is a @code{LilyPond-mode} for Emacs addicts. If they have not been
-installed already, refer to the file @file{INSTALL.txt}. The
-easiest editing environment is @file{LilyPondTool}. See
-@rprogram{Text editor support}, for more information.}. In your
-text editor, enter the following input and save the file as
-@file{test.ly}
-
-@verbatim
-{
+@example
+@{
c' e' g' e'
-}
-@end verbatim
+@}
+@end example
-@noindent
-To process @file{test.ly}, proceed as follows
+To process @file{test.ly}, proceed as follows:
@example
lilypond test.ly
@end example
@noindent
-You will see something resembling
+You will see something resembling:
@example
lilypond test.ly
-GNU LilyPond 2.10.0
+GNU LilyPond @version{}
Processing `test.ly'
Parsing...
-Interpreting music... [1]
+Interpreting music...
Preprocessing graphical objects...
-Calculating line breaks... [2]
+Finding the ideal number of pages...
+Fitting music on 1 page...
+Drawing systems...
Layout output to `test.ps'...
Converting to `test.pdf'...
@end example
-@cindex PDF file
-@cindex Viewing music
-
-@noindent
-The result is the file @file{test.pdf} which you can print or view
-with the standard facilities of your operating system.@footnote{If
-your system does not have any such tools installed, you can try
-@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely
-available package for viewing and printing PDF and PostScript files.}
-
@node Simple notation
@subsection Simple notation
-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.
+@cindex simple notation
+@cindex notation, simple
-@lilypond[quote,ragged-right,verbatim]
+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.
+
+@lilypond[verbatim,quote]
{
c' e' g' e'
}
@end lilypond
@noindent
-This behavior may be altered, but in most cases these automatic values
-are useful.
+This behavior may be altered, but in most cases these automatic
+values are useful.
@subheading Pitches
-The easiest way to enter notes is by using @code{\relative} mode. In
-this mode, the @rglos{interval} between the previous note and the
-current note is assumed to be within a @rglos{fourth}. We begin by
-entering the most elementary piece of music, a @rglos{scale}.
-
-@lilypond[quote,ragged-right,verbatim]
+@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}.
+
+The easiest way to enter notes is by using @code{\relative} mode.
+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]
+% set the starting point to middle C
\relative c' {
c d e f
g a b c
}
@end lilypond
-The initial note is @rglos{middle C}. Each successive note
-is within a fourth of the previous note -- in other words, the first
-@samp{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:
+The initial note is @notation{middle C}. Each successive note is
+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, still using only @code{\relative} mode:
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
\relative c' {
d f a g
c b f d
@end lilypond
@noindent
-As you may notice, this example does not start on middle C. The first
-note -- the @samp{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.
+
+By adding (or removing) quotes @code{'} or commas @code{,} from
+the @code{@w{\relative c' @{}} command, we can change the starting
+octave:
+
+@lilypond[verbatim,quote]
+% one octave above middle C
+\relative 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 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]
+\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
-To add intervals that are larger than a fourth, we can raise the 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.
+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.
-@lilypond[quote,ragged-right,verbatim]
+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]
\relative c'' {
a a, c' f,
g g'' a,, f'
@end lilypond
@noindent
-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 this.
-
+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{@w{\relative c'}} may also be modified like
+this.
+@c " - keeps quotes in order for context-sensitive editor -td
@subheading Durations (rhythms)
-The @rglos{duration} of a note is specified by a number after the note
-name. @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note},
-@samp{4} for a @rglos{quarter note} and so on. Beams are added
-automatically.
+@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
+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[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
\relative c'' {
a1
a2 a4 a8 a
}
@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 @rglos{dotted note}s, 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[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
\relative c'' {
a a a4. a8
a8. a16 a a8. a8 a4.
@subheading Rests
-A @rglos{rest} is entered just like a note with the name @samp{r}:
+@cindex rest
+@cindex notating rests
-@lilypond[quote,ragged-right,verbatim]
+Music Glossary: @rglos{rest}.
+
+A @notation{rest} is entered just like a note with the name
+@code{r}@tie{}:
+
+@lilypond[verbatim,quote]
\relative c'' {
a r r2
r8 a r4 r4. r8
@subheading Time signature
-The @rglos{time signature}) can be set with the @code{\time} command:
+@cindex time signature
+
+@funindex \time
+@funindex time
-@lilypond[quote,ragged-right,verbatim]
+Music Glossary: @rglos{time signature}.
+
+The @notation{time signature} can be set with the @code{\time}
+command:
+
+@lilypond[verbatim,quote]
\relative c'' {
\time 3/4
a4 a a
@subheading Clef
-The @rglos{clef} can be set using the @code{\clef} command:
+@cindex clef
+@cindex treble
+@cindex alto
+@cindex tenor
+@cindex bass
+
+@funindex \clef
+@funindex clef
-@lilypond[quote,ragged-right,verbatim]
+Music Glossary: @rglos{clef}.
+
+The @notation{clef} can be set using the @code{\clef} command:
+
+@lilypond[verbatim,quote]
\relative c' {
\clef treble
c1
Here is a small example showing all these elements together:
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
\relative c, {
\time 3/4
\clef bass
}
@end lilypond
-@seeals
-@quotation
-@table @asis
-@item Entering pitches and durations
-see @ruser{Pitches}, and @ruser{Durations}.
-@item Rests
-see @ruser{Rests}.
-@item Time signatures and other timing commands
-see @ruser{Time signature}.
-@item Clefs
-see @ruser{Clef}.
-@end table
-@end quotation
+@seealso
+
+Notation Reference: @ruser{Writing pitches},
+@ruser{Writing rhythms}, @ruser{Writing rests},
+@ruser{Time signature}, @ruser{Clef}.
-@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 @{ @}, and comments are denoted with @code{%} or
-@code{%@{ ... %@}}.
+@node Working on input files
+@subsection Working on input files
-If the previous sentence sounds like nonsense, don't worry! We'll explain
-what all these terms mean:
+@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
+@{ @}, 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:
@itemize
-@cindex Case sensitive
-@item @strong{Case sensitive}:
-it matters whether you enter a letter
-in lower case (i.e. @code{a, b, s, t}) or upper case (i.e.
-@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.
-
-@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
+@item
+@strong{Case sensitive}:
+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.
+@w{@code{@{ c d e @}}} means the same thing as
+@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
+
@example
- @{
-c d
- e @}
+@{ c d
+ e @}
@end example
@noindent
-Of course, the previous example is hard to read. A good rule of thumb
-is to indent code blocks with either a tab or two spaces:
+Of course, the previous example is hard to read. A good rule of
+thumb is to indent code blocks with either a tab or two spaces:
+
@example
@{
c d e
@}
@end example
-@item @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
-parenthesis @samp{()} in mathematics. The braces should
-be surrounded by a space unless they are at the beginning or end of a
-line to avoid ambiguities.
+@item
+@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
+@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 @w{@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 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
+@item
+@strong{Comments}:
+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
+@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
c4 c g' g a a g2
%@{
- This line, and the notes below
- are ignored, since they are in a
- block comment.
+ This line, and the notes below are ignored,
+ since they are in a block comment.
- g g f f e e d d c2
+ f f e e d d c2
%@}
@end example
@end itemize
-There are more tips for constructing input files in
-@ruser{Suggestions for writing LilyPond files}.
-
-@node How to read the tutorial
-@subsection How to read the tutorial
-
-As we saw in @ruser{Working on text files}, LilyPond input must be
-surrounded by @{ @} marks or a @code{\relative c'' @{ ... @}}. For the
-rest of this manual, most examples will omit this.
+@node How to read the manual
+@subsection How to read the manual
-If you are reading the HTML documentation and wish to see the exact
-exact LilyPond code that was used to create the example, simply click
-on the picture. If you are not reading the HTML version, you could
-copy and paste the displayed input, but you @strong{must} add the
-@code{\relative c'' @{ @}} like this:
+@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
+@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
+@code{@w{\relative c'' @{ @}}} like this:
@example
\relative c'' @{
@}
@end example
-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}, so you would not be able to copy
-a small documentation example and paste it inside a longer piece
-of your own.
+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{@w{\relative c'' @{ @}}} --
+you should not place a @code{\relative} inside another
+@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
+format the manual this way.
+
+
+@subheading Clickable examples
+
+Many people learn programs by trying and fiddling around with the
+program. This is also possible with LilyPond. If you click on a
+picture in the HTML version of this manual, you will see the exact
+LilyPond input that was used to generate that image. Try it on
+this image:
+
+@c no verbatim here
+@lilypond[quote]
+\relative c'' {
+ c-\markup { \bold \huge { Click here. } }
+}
+@end lilypond
+
+By cutting and pasting everything in the @qq{ly snippet} section,
+you have a starting template for experiments. To see exactly the
+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 input files}. But it might be
+best to read through the rest of the tutorial first.
+
@node Single staff notation
on one staff.
@menu
-* Relative note names::
* Accidentals and key signatures::
* Ties and slurs::
* Articulation and dynamics::
+* Adding text::
* Automatic and manual beams::
* Advanced rhythmic commands::
@end menu
-@node Relative note names
-@subsection Relative note names
-
-As we saw in @ruser{Simple notation}, LilyPond calculates the pitch of
-each note relative to the previous one@footnote{There is another mode of
-entering pitches, @ruser{Absolute note names}, but in practice relative
-mode is much easier and safer to use.}. If no extra octave marks
-(@code{'} and @code{,}) are added, it assumes that each pitch is within
-a fourth of the previous note.
-
-LilyPond examines pitches based on the note names -- in other words,
-an augmented fourth is @emph{not} 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[quote,ragged-right,verbatim,fragment,relative=2]
-c2 fis
-c2 ges
-@end lilypond
-
-@seeals
-@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
-A @rglos{sharp} pitch is made by adding @samp{is} to
-the name, and a @rglos{flat} pitch by adding @samp{es}. As
-you might expect, a @rglos{double sharp} or @rglos{double flat} is
-made by adding @samp{isis} or @samp{eses}@footnote{This syntax
-derived from note naming conventions in Nordic and Germanic languages,
-like German and Dutch. To use other names for accidentals, see
-@ruser{Note names in other languages}.}
-
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@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}.
+
+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,relative=2]
cis1 ees fisis, aeses
@end lilypond
@cindex key signature, setting
@subheading Key signatures
-The key signature is set with the command @code{\key} followed by
-a pitch and @code{\major} or @code{\minor}.
+@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}.
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+The @notation{key signature} is set with the command @code{\key}
+followed by a pitch and @code{\major} or @code{\minor}.
+
+@lilypond[verbatim,quote,relative=2]
\key d \major
a1
\key c \minor
a
@end lilypond
-@sp 1
+@smallspace
@subheading Warning: key signatures and pitches
-To determine whether to print an accidental, LilyPond examines the
-pitches and the key signature. The key signature only affects
-the @emph{printed} accidentals, not the actual pitches! 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 (flat, natural or 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.
+Music Glossary: @rglos{accidental}, @rglos{key signature},
+@rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
+@rglos{transposition}.
-In this example
+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.
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+LilyPond makes a sharp distinction between musical content and
+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.
+
+In this example:
+
+@lilypond[verbatim,quote,relative=2]
\key d \major
d cis fis
@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
-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:
+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
+@emph{does} get an accidental:
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
\key aes \major
e
@end lilypond
-Adding all alterations explicitly might require a little more effort
-when typing, but the advantage is that transposing is easier, and
-accidentals can be printed according to different conventions. See
-@ruser{Automatic accidentals}, for some examples how accidentals can be printed
-according to different rules.
+Adding all alterations explicitly might require a little more
+effort when typing, but the advantage is that
+@notation{transposing} is easier, and accidentals can be printed
+according to different conventions. For some examples how
+accidentals can be printed according to different rules, see
+@ruser{Automatic accidentals}.
+
+@seealso
+
+Notation Reference: @ruser{Note names in other languages},
+@ruser{Accidentals}, @ruser{Automatic accidentals},
+@ruser{Key signature}.
-@seeals
-@quotation
-@table @asis
-@item Accidentals
-see @ruser{Accidentals}, and @ruser{Automatic accidentals}.
-@item Key signature
-see @ruser{Key signature}.
-@end table
-@end quotation
+Music Glossary: @rglos{Pitch names}.
@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
-A @rglos{tie} is created by appending a tilde @samp{~} to the first
-note being tied
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+
+Music Glossary: @rglos{tie}.
+
+A @notation{tie} is created by appending a tilde @code{~} to the
+first note being tied.
+
+@lilypond[verbatim,quote,relative=2]
g4~ g c2~
c4 ~ c8 a8 ~ a2
@end lilypond
-@cindex slurs
@subheading Slurs
-A @rglos{slur} is a curve drawn across many notes. The starting note
-and ending note are marked with @samp{(} and @samp{)} respectively.
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+Music Glossary: @rglos{slur}.
+
+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,relative=2]
d4( c16) cis( d e c cis d) e( d4)
@end lilypond
-@cindex slurs, phrasing
-@cindex phrasing slurs
@subheading Phrasing slurs
-Slurs to indicate longer phrasing can be entered with @code{\(} and
-@code{\)}. You can have both legato slurs and phrasing slurs at the
-same time, but you cannot have simultaneous slurs or simultaneous
-phrasing slurs.
+Music Glossary: @rglos{slur}, @rglos{phrasing}.
+
+Slurs to indicate longer @notation{phrasing} can be entered with
+@code{\(} and @code{\)}. You can have both @notation{slurs}
+and phrasing slurs at the same time, but you cannot have
+simultaneous slurs or simultaneous phrasing slurs.
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
a8(\( ais b c) cis2 b'2 a4 cis,\)
@end lilypond
-@sp 1
+@smallspace
@cindex slurs versus ties
@subheading Warnings: slurs vs. ties
-A slur looks like a @rglos{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 articulations
-of notes, and can be used on larger groups of notes. Slurs and ties
-can be nested.
+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.
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
c2~( c8 fis fis4 ~ fis2 g2)
@end lilypond
-@seeals
-@quotation
-@table @asis
-@item Ties
-see @ruser{Ties}.
-@item Slurs
-see @ruser{Slurs}.
-@item Phrasing slurs
-see @ruser{Phrasing slurs}.
-@end table
-@end quotation
+@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
-Common @rglos{articulation}s can be added to a note using a dash @samp{-}
-and a single character:
+Music Glossary: @rglos{articulation}.
+
+Common @notation{articulations} can be added to a note using a
+dash @code{-} and a single character:
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
c-. c-- c-> c-^ c-+ c-_
@end lilypond
-@cindex fingering
@subheading Fingerings
-Similarly, fingering indications can be added to a note using a dash
-(@samp{-}) and the digit to be printed:
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@cindex fingering
+
+@funindex ^
+@funindex _
+
+Music Glossary: @rglos{fingering}.
+
+Similarly, @notation{fingering} indications can be added to a note
+using a dash (@code{-}) and the digit to be printed:
+
+@lilypond[verbatim,quote,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.
+Articulations and fingerings are usually placed automatically, but
+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[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
c_-^1 d^. f^4_2-> e^-_+
@end lilypond
@subheading Dynamics
-Dynamic signs are made by adding the markings (with a backslash) to
-the note
-
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-c\ff c\mf c\p c\pp
-@end lilypond
@cindex dynamics
@cindex decrescendo
@cindex crescendo
-Crescendi and decrescendi are started with the commands @code{\<} and
-@code{\>}. An ending dynamic, for example @code{\f}, will finish the
-(de)crescendo, or the command @code{\!} can be used
+@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}.
+
+@notation{Dynamic} signs are made by adding the markings (with a
+backslash) to the note:
+
+@lilypond[verbatim,quote,relative=2]
+c\ff c\mf c\p c\pp
+@end lilypond
+
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@notation{Crescendi} and @notation{decrescendi} are started with
+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,relative=2]
c2\< c2\ff\> c2 c2\!
@end lilypond
-@seeals
-@quotation
-@table @asis
-@item Articulations
-see @ruser{Articulations}.
-@item Fingering
-see @ruser{Fingering instructions}.
-@item Dynamics
-see @ruser{Dynamics}.
-@end table
-@end quotation
+@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]
+c1^"espr" a_"legato"
+@end lilypond
+
+Extra formatting may be added with the @code{\markup} command:
+
+@lilypond[verbatim,quote,relative=2]
+c1^\markup{ \bold espr}
+a1_\markup{
+ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
+}
+@end lilypond
+
+
+@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
-All @rglos{beam}s are drawn automatically:
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@funindex [ ... ]
+@funindex [
+@funindex ]
+@funindex \autoBeamOff
+@funindex autoBeamOff
+@funindex \autoBeamOn
+@funindex autoBeamOn
+
+Music Glossary: @rglos{beam}.
+
+All @notation{beams} are drawn automatically:
+
+@lilypond[verbatim,quote,relative=2]
a8 ais d ees r d c16 b a8
@end lilypond
-@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. To correct just an occasional beam mark the first note
+to be beamed with @code{[} and the last one with @code{]}.
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
a8[ ais] d[ ees r d] a b
@end lilypond
-@seeals
-@quotation
-@table @asis
-@item Automatic beams
-see @ruser{Automatic beams}.
-@item Manual beams
-see @ruser{Manual beams}.
-@end table
-@end quotation
+If you want to turn off automatic beaming entirely or for an
+extended section of music, use the command @code{\autoBeamOff}
+to turn off automatic beaming and @code{\autoBeamOn} to turn it
+on again.
+
+@lilypond[verbatim,quote,relative=2]
+\autoBeamOff
+a8 c b4 d8. c16 b4
+\autoBeamOn
+a8 c b4 d8. c16 b4
+@end lilypond
+
+@seealso
+
+Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
@node Advanced rhythmic commands
@subsection Advanced rhythmic commands
+@subheading Partial measure
+
@cindex pickup
-@cindex anacruse
+@cindex anacrusis
@cindex partial measure
-@subheading Partial measure
-A pickup (or @rglos{anacrusis}) is entered with the keyword
-@code{\partial}. It is followed by a duration: @code{\partial 4} is
-a quarter note pickup and @code{\partial 8} an eighth note.
+@funindex \partial
+@funindex partial
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+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}
+is a quarter note pickup and @code{\partial 8} an eighth note.
+
+@lilypond[verbatim,quote,relative=2]
\partial 8
f8 c2 d
@end lilypond
+@subheading Tuplets
+
@cindex tuplets
@cindex triplets
-@subheading Tuplets
-Tuplets are made with the @code{\times} keyword. It takes two
-arguments: a fraction and a piece of music. The duration of the piece
-of music is multiplied by the fraction. Triplets make notes occupy
-2/3 of their notated duration, so a triplet has 2/3 as its fraction
+@funindex \times
+@funindex times
+
+Music Glossary: @rglos{note value}, @rglos{triplet}.
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@notation{Tuplets} are made with the @code{\times} keyword. It
+takes two arguments: a fraction and a piece of music. The
+duration of the piece of music is multiplied by the fraction.
+Triplets make notes occupy 2/3 of their notated duration, so a
+@notation{triplet} has 2/3 as its fraction
+
+@lilypond[verbatim,quote,relative=2]
\times 2/3 { f8 g a }
\times 2/3 { c r c }
\times 2/3 { f,8 g16[ a g a] }
\times 2/3 { d4 a8 }
@end lilypond
+@subheading Grace notes
+
@cindex grace notes
@cindex acciaccatura
@cindex appoggiatura
-@subheading Grace notes
-Grace notes are created with the @code{\grace} command, although they
-can also be created by prefixing a music expression with the
-keyword @code{\appoggiatura} or @code{\acciaccatura}
+@funindex \grace
+@funindex grace
+@funindex \acciaccatura
+@funindex acciaccatura
+@funindex \appoggiatura
+@funindex acciaccatura
+
+Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
+@rglos{appoggiatura}.
+
+@notation{Grace notes} are created with the @code{\grace} command,
+although they can also be created by prefixing a music expression
+with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
c2 \grace { a32[ b] } c2
c2 \appoggiatura b16 c2
c2 \acciaccatura b16 c2
@end lilypond
-@seeals
-@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
+@seealso
+
+Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
+@ruser{Upbeats}.
@node Multiple notes at once
@section Multiple notes at once
-This section introduces having more than one note at the same time:
-multiple instruments, multiple staves for a single instrument (i.e. piano),
-and chords.
+This section introduces having more than one note at the same
+time: multiple instruments, multiple staves for a single
+instrument (i.e. piano), and chords.
-Polyphony in music refers to having more than one voice occurring in
-a piece of music. Polyphony in LilyPond refers to having more than
-one voice on the same staff.
+Polyphony in music refers to having more than one voice occurring
+in a piece of music. Polyphony in LilyPond refers to having more
+than one voice on the same staff.
@menu
-* Music expressions explained::
-* Multiple staves::
-* Piano staves::
-* Combining notes into chords::
-* Single staff polyphony::
+* Music expressions explained::
+* Multiple staves::
+* Staff groups::
+* Combining notes into chords::
+* Single staff polyphony::
@end menu
@node Music expressions explained
@subsection Music expressions explained
+@cindex music expression
+@cindex expression, music
+@cindex compound music expression
+@cindex music expression, compound
+
In LilyPond input files, music is represented by @emph{music
-expressions}. A single note is a music expression, although it is not
-valid input all on its own.
+expressions}. A single note is a music expression:
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
a4
@end lilypond
-Enclosing a group of notes in braces creates a new music expression:
+Enclosing a note in braces creates a @emph{compound music
+expression}. Here we have created a compound music expression
+with two notes:
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
{ a4 g4 }
@end lilypond
-Putting a group of music expressions (e.g. notes) in braces means that
-they are in sequence (i.e. each one follows the previous one). The result
-is another music expression:
+Putting a group of music expressions (e.g. notes) in braces means
+that they are in sequence (i.e. each one follows the previous
+one). The result is another music expression:
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
{ { a4 g } f g }
@end lilypond
-@subheading Simultaneous music expressions: multiple staves
+@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
-This technique is useful for polyphonic music. To enter music
-with more voices or more staves, we combine expressions in
-parallel. To indicate that two voices should play at the same time,
-simply enter a simultaneous combination of music expressions. A
-@q{simultaneous} music expression is formed by enclosing expressions inside
-@code{<<} and @code{>>}. In the following example, three sequences (all
-containing two separate notes) are combined simultaneously:
+1 + 2
+
+(1 + 2) * 3
+
+((1 + 2) * 3) / (4 * 5)
+@end example
-@lilypond[quote,ragged-right,verbatim]
+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
+
+@cindex multiple staves
+@cindex staves, multiple
+@cindex polyphony
+@cindex combining expressions in parallel
+@cindex parallel expressions
+@cindex expressions, parallel
+@cindex relative notes and simultaneous music
+@cindex relative notes and parallel expressions
+@cindex simultaneous music and relative notes
+@cindex parallel expressions and relative notes
+
+@funindex <<
+@funindex >>
+@funindex << ... >>
+
+Music Glossary: @rglos{polyphony}.
+
+This technique is useful for @notation{polyphonic} music. To
+enter music with more voices or more staves, we combine
+expressions in parallel. To indicate that two voices should play
+at the same time, simply enter a simultaneous combination of music
+expressions. A @q{simultaneous} music expression is formed by
+enclosing expressions inside @code{<<} and @code{>>}. In the
+following example, three sequences (all containing two separate
+notes) are combined simultaneously:
+
+@lilypond[verbatim,quote]
\relative c'' {
<<
{ a4 g }
}
@end lilypond
-Note that we have indented each level of the input with a different
-amount of space. LilyPond does not care how much (or little) space there
-is at the beginning of a line, but indenting LilyPond code like this makes
-it much easier for humans to read.
+Note that we have indented each level of the input with a
+different amount of space. LilyPond does not care how much (or
+little) space there is at the beginning of a line, but indenting
+LilyPond code like this makes it much easier for humans to read.
-@strong{Warning}: each note is relative to the
-previous note in the input, not relative to the @code{c''} in the
-initial @code{\relative} command.
+@warning{each note is relative to the previous note in
+the input, not relative to the @code{c''} in the initial
+@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.
+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.
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
\relative c'' {
c2 <<c e>>
<< { e f } { c <<b d>> } >>
}
@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
-As we saw in @ruser{Music expressions explained}, LilyPond input files
-are constructed out of music expressions. If the score begins with
-simultaneous music expressions, LilyPond creates multiples staves. However,
-it is easier to see what happens if we create each staff explicitly.
+@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
+staves. However, it is easier to see what happens if we create
+each staff explicitly.
To print more than one staff, each piece of music that makes up a
staff is marked by adding @code{\new Staff} before it. These
-@code{Staff} elements are then combined in parallel with @code{<<} and
-@code{>>}:
+@code{Staff} elements are then combined in parallel with @code{<<}
+and @code{>>}:
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
\relative c'' {
<<
\new Staff { \clef treble c }
}
@end lilypond
-The command @code{\new} introduces a @q{notation context.} A notation
-context is an environment in which musical events (like notes or
-@code{\clef} commands) are interpreted. For simple pieces, such
-notation contexts are created automatically. For more complex pieces, it
-is best to mark contexts explicitly.
+The command @code{\new} introduces a @q{notation context.} A
+notation context is an environment in which musical events (like
+notes or @code{\clef} commands) are interpreted. For simple
+pieces, such notation contexts are created automatically. For
+more complex pieces, it is best to mark contexts explicitly.
There are several types of contexts. @code{Score}, @code{Staff},
-and @code{Voice} handle melodic notation, while @code{Lyrics} sets lyric
-texts and @code{ChordNames} prints chord names.
+and @code{Voice} handle melodic notation, while @code{Lyrics} sets
+lyric texts and @code{ChordNames} prints chord names.
In terms of syntax, prepending @code{\new} to a music expression
-creates a bigger music expression. In this way it resembles the minus
-sign in mathematics. The formula @math{(4+5)} is an expression, so
-@math{-(4+5)} is a bigger expression.
+creates a bigger music expression. In this way it resembles the
+minus sign in mathematics. The formula @math{(4+5)} is an
+expression, so @math{-(4+5)} is a bigger expression.
-Time signatures entered in one staff affects all other
-staves@footnote{This behavior may be changed if desired; see
-@ruser{Polymetric notation}, for details.}. 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 behavior
+is because scores with transposing instruments are more common
+than polyrhythmic scores.
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
\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 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}.
-@cindex staff switch, manual
-@cindex cross staff voice, manual
-Piano music is typeset in two staves connected by a brace. Printing
-such a staff is similar to the polyphonic example in @ruser{Multiple staves},
-but now this entire expression is inserted inside a @code{PianoStaff}:
+Piano music is typeset in two staves connected by a
+@notation{brace}.
+Printing such a staff is similar to the polyphonic example in
+@ref{Multiple staves}. However, now this entire expression is
+inserted inside a @code{PianoStaff}:
@example
\new PianoStaff <<
>>
@end example
-Here is a small example
+Here is a small example:
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
\relative c'' {
\new PianoStaff <<
\new Staff { \time 2/4 c4 e g g, }
}
@end lilypond
-@seeals
-@quotation
-See @ruser{Piano music}.
-@end quotation
+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{Keyboard and other multi-staff
+instruments},
+@ruser{Displaying staves}.
@node Combining notes into chords
@subsection Combining notes into chords
@cindex chords
-Chords can be made by surrounding pitches with single angle brackets. Angle
-brackets are the symbols @samp{<} and @samp{>}.
+@cindex note durations in chords
+
+@funindex <
+@funindex >
+@funindex < ... >
-@lilypond[quote,fragment,verbatim,relative=2,fragment]
+Music Glossary: @rglos{chord}.
+
+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,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[quote,fragment,verbatim,relative=2,fragment]
+@lilypond[verbatim,quote,relative=2]
r4 <c e g>8[ <c f a>]~ <c f a>2
-@end lilypond
-
-@lilypond[quote,fragment,verbatim,relative=2,fragment]
-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
@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
-@code{@{...@}}) and combining these simultaneously, separating the
-voices with @code{\\}
-
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+@cindex voices, more on one staff
+@cindex single staff polyphony
+@cindex spacer rest
+@cindex rest, spacer
+
+@funindex << ... \\ ... >>
+@funindex <<
+@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 (@samp{s}) instead of a normal rest (@samp{r}),
+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[quote,ragged-right,verbatim,fragment,relative=2]
+@lilypond[verbatim,quote,relative=2]
<<
{ a4 g2 f4~ f4 } \\
{ s4 g4 f2 f4 }
@noindent
Again, these expressions can be nested arbitrarily.
-@lilypond[quote,fragment,verbatim,relative=2,fragment]
+@lilypond[verbatim,quote,relative=2]
<<
\new Staff <<
{ a4 g2 f4~ f4 } \\
>>
@end lilypond
-@seeals
-@quotation
-See @ruser{Basic polyphony}.
-@end quotation
+@seealso
+
+Notation Reference: @ruser{Simultaneous notes}.
@node Songs
This section introduces vocal music and simple song sheets.
@menu
-* Printing lyrics::
-* A lead sheet::
+* Setting simple songs::
+* Aligning lyrics to a melody::
+* Lyrics to multiple staves::
@end menu
-@node Printing lyrics
-@subsection Printing lyrics
+@node Setting simple songs
+@subsection Setting simple songs
+
+@cindex lyrics
+@cindex songs
+
+@funindex \addlyrics
+@funindex addlyrics
-@cindex Lyrics
-@cindex Songs
-Consider a simple melody:
+Music Glossary: @rglos{lyrics}.
-@lilypond[quote,ragged-right,verbatim]
+Here is the start of the melody to a nursery
+rhyme, @notation{Girls and boys come out to play}:
+
+@lilypond[verbatim,quote]
\relative c'' {
- a4 e c8 e r4
- b2 c4( d)
+ \key g \major
+ \time 6/8
+ d4 b8 c4 a8 d4 b8 g4
}
@end lilypond
-The lyrics can be set to these notes, combining both with the
-@code{\addlyrics} keyword. Lyrics are entered by separating each
-syllable with a space.
+The @notation{lyrics} can be set to these notes, combining both
+with the @code{\addlyrics} keyword. Lyrics are entered by
+separating each syllable with a space.
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote]
<<
\relative c'' {
- a4 e c8 e r4
- b2 c4( d)
+ \key g \major
+ \time 6/8
+ d4 b8 c4 a8 d4 b8 g4
+ }
+ \addlyrics {
+ Girls and boys come out to play,
}
- \addlyrics { One day this shall be free }
>>
@end lilypond
+Note the curly brackets delimiting both the music and the lyrics,
+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
+
@cindex melisma
@cindex extender line
-This melody ends on a @rglos{melisma}, a single syllable (@q{free})
-sung to more than one note. This is indicated with an @emph{extender
-line}. It is entered as two underscores @code{__}:
+@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}.
-@lilypond[quote,ragged-right,verbatim]
+The next line in the nursery rhyme is @notation{The moon doth
+shine as bright as day}. Let's extend it:
+
+@lilypond[verbatim,quote]
<<
\relative c'' {
- a4 e c8 e r4
- b2 c4( d)
+ \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;
}
- \addlyrics { One day this shall be free __ }
>>
@end lilypond
-Similarly, hyphens between words can be entered as two dashes,
-resulting in a centered hyphen between two syllables
+We see the extra lyrics do not align properly with the notes. The
+word @notation{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, for
+details, see @ref{Ties and slurs}:
-@c no ragged-right here because otherwise the hypens get lost.
-@lilypond[quote,verbatim]
+@lilypond[verbatim,quote]
<<
- \relative c' {
- \time 2/4
- f4 f c c
+ \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;
}
- \addlyrics { A -- le -- gri -- a }
>>
@end lilypond
-@seeals
-@quotation
-More options, such as putting multiple stanzas below a melody, are
-discussed in @ruser{Vocal music}.
-@end quotation
+The words now line up correctly with the notes, but the automatic
+beaming for the notes above @notation{shine as} does not look right.
+We can correct this by inserting manual beaming commands to override
+the automatic beaming here, for details, see @ref{Automatic and
+manual beams}.
+@lilypond[verbatim,quote]
+<<
+ \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
-@node A lead sheet
-@subsection A lead sheet
+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:
-@cindex Lead sheets
-@cindex chords
-@cindex chord names
+@lilypond[verbatim,quote]
+<<
+ \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
-In popular music it is common to denote accompaniment with chord names.
-Such chords can be entered like notes,
+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 @notation{Dido's Lament}, from Purcell's
+@notation{Dido and Æneas}:
-@lilypond[quote,ragged-right,verbatim]
-\chordmode { c2 f4. g8 }
+@lilypond[verbatim,quote]
+<<
+ \relative c'' {
+ \key g \minor
+ \time 3/2
+ g2 a bes bes( a)
+ b c4.( bes8 a4. g8 fis4.) g8 fis1
+ }
+ \addlyrics {
+ When I am laid,
+ am laid __ in earth,
+ }
+>>
@end lilypond
-Now each pitch is read as the root of a chord instead of a note.
-This mode is switched on with @code{\chordmode}. Other chords can be
-created by adding modifiers after a colon. The
-following example shows a few common modifiers:
+None of the examples so far have involved words containing more
+than one syllable. Such words are usually split one syllable to a
+note, with hyphens between syllables. Such hyphens are entered as
+two dashes, resulting in a centered hyphen between the syllables.
+Here is an example showing this and everything we have learned so
+far about aligning lyrics to notes.
-@lilypond[quote,verbatim,ragged-right]
-\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
+@c no ragged-right here because otherwise the hyphens get lost,
+@c but the example is long enough to avoid looking strange.
+@lilypond[verbatim,quote,noragged-right]
+<<
+ \relative c' {
+ \key g \major
+ \time 3/4
+ \partial 4
+ d4 g4 g a8( b) g4 g4
+ b8( c) d4 d e4 c2
+ }
+ \addlyrics {
+ A -- way in a __ man -- ger,
+ no __ crib for a bed, __
+ }
+>>
@end lilypond
-For lead sheets, chords are not printed on staves, but as names on a
-line for themselves. This is achieved by using @code{\chords} instead
-of @code{\chordmode}. This uses the same syntax as @code{\chordmode},
-but renders the notes in a @code{ChordNames} context, with the
-following result:
-
-@lilypond[quote,verbatim,ragged-right]
-\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+Some lyrics, especially those in Italian, require the opposite:
+setting more than one syllable to a single note. This is
+achieved by linking the syllables together with a single
+underscore @code{_} (with no spaces), or enclosing them in quotes.
+Here's an example from Rossini's @notation{Figaro}, where
+@notation{al} has to be sung on the same note as the @notation{go} of
+@notation{Largo} in Figaro's aria @notation{Largo al factotum}:
+
+@c no ragged-right here because otherwise the hyphens get lost,
+@c but the example is long enough to avoid looking strange.
+@lilypond[verbatim,quote,noragged-right]
+<<
+ \relative c' {
+ \clef bass
+ \key c \major
+ \time 6/8
+ c4.~ c8 d b c([ d]) b c d b c
+ }
+ \addlyrics {
+ Lar -- go_al fac -- to -- tum del -- la cit -- tà
+ }
+>>
@end lilypond
-@cindex lead sheet
-When put together, chord names, lyrics and a melody form
-a lead sheet,
-@lilypond[quote,verbatim,ragged-right]
+@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}:
+
+@lilypond[verbatim,quote]
<<
- \chords { c2 g:sus4 f e }
\relative c'' {
- a4 e c8 e r4
- b2 c4( d)
+ \key f \major
+ \time 6/8
+ \partial 8
+ c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
+ }
+ \addlyrics {
+ Let flee -- cy flocks the hills a -- dorn, __
+ }
+ \relative c' {
+ \key f \major
+ \time 6/8
+ \partial 8
+ r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
+ }
+ \addlyrics {
+ Let flee -- cy flocks the hills a -- dorn,
}
- \addlyrics { One day this shall be free __ }
>>
@end lilypond
+Scores any more complex than this simple example are better
+produced by separating out the score structure from the notes and
+lyrics with variables. These are discussed in @ref{Organizing
+pieces with variables}.
+
+@seealso
+
+Notation Reference: @ruser{Vocal music}.
-@seeals
-@quotation
-A complete list of modifiers and other options for layout can be found
-in @ruser{Chords}.
-@end quotation
@node Final touches
@section Final touches
-This is the final section of the tutorial; it demonstrates how to add the
-final touches to simple pieces, and provides an introduction to the rest
-of the manual.
+This is the final section of the tutorial; it demonstrates how to
+add the final touches to simple pieces, and provides an
+introduction to the rest of the manual.
@menu
-* Version number::
-* Adding titles::
-* Absolute note names::
-* Organizing pieces with identifiers::
-* After the tutorial::
-* How to read the manual::
+* Organizing pieces with variables::
+* Version number::
+* Adding titles::
+* Absolute note names::
+* After the tutorial::
@end menu
+@node Organizing pieces with variables
+@subsection Organizing pieces with variables
+
+@cindex variables
+@cindex variables, defining
+@cindex identifiers
+@cindex macros
+@cindex assigning variables
+@cindex using variables
+@cindex variables, using
+@cindex variables, characters allowed in
+@cindex characters allowed in variables
+
+When all of the elements discussed earlier are combined to produce
+larger files, the music expressions get a lot bigger. In
+polyphonic music with many staves, the input files can become very
+confusing. We can reduce this confusion by using
+@emph{variables}.
+
+With variables (also known as identifiers or macros), we can break
+up complex music expressions. A variable is assigned as
+follows:
+
+@example
+namedMusic = @{ @dots{} @}
+@end example
+
+The contents of the music expression @code{namedMusic} can be used
+later by placing a backslash in front of the name
+(@code{\namedMusic}, just like a normal LilyPond command).
+
+@lilypond[verbatim,quote]
+violin = \new Staff {
+ \relative 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]
+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
@cindex versioning
-The @code{\version} statement records the version of LilyPond that was
-used to write the file:
+@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:
@example
-\version "2.11.23"
+\version @w{"@version{}"}
@end example
@noindent
-by convention, this is placed at the top of your LilyPond file.
+By convention, this is placed at the top of your LilyPond file.
-These annotations make future upgrades of LilyPond go more smoothly.
-Changes in the syntax are handled with a special program,
-@file{convert-ly} (see @rprogram{Updating files with convert-ly}), and
-it uses @code{\version} to determine what rules to apply.
+These annotations make future upgrades of LilyPond go more
+smoothly. Changes in the syntax are handled with a special
+program, @command{convert-ly}, and it uses @code{\version} to
+determine what rules to apply. For details, see
+@rprogram{Updating files with convert-ly}.
@node Adding titles
@subsection Adding titles
-The title, composer, opus number, and similar information are entered
-in the @code{\header} block. This exists outside of the main
-music expression; the @code{\header} block is usually placed underneath
-the @ruser{Version number}.
+@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
+underneath the version number.
@example
-\version "2.11.23"
+\version @w{"@version{}"}
\header @{
title = "Symphony"
composer = "Me"
@}
@end example
-When the file is processed, the title and composer are printed above
-the music. More information on titling can be found in @ruser{Creating
-titles}.
+When the file is processed, the title and composer are printed
+above the music. More information on titling can be found in
+@ruser{Creating titles}.
@node Absolute note names
@subsection 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.
+@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 omit the @code{\relative}, LilyPond treats all pitches as
-absolute values. A @code{c'} will always mean middle C, a @code{b} will
-always mean the note one step below middle C, and a @code{g,} will
-always mean the note on the bottom staff of the bass clef.
+absolute values. A @code{c'} will always mean middle C, a
+@code{b} will always mean the note one step below middle C, and a
+@code{g,} will always mean the note on the bottom staff of the
+bass clef.
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[verbatim,quote]
{
\clef bass
c' b g, g,
Here is a four-octave scale:
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[verbatim,quote]
{
\clef bass
c, d, e, f,
}
@end lilypond
-As you can see, writing a melody in the treble clef involves a lot of
-quote ' marks. Consider this fragment from Mozart:
+As you can see, writing a melody in the treble clef involves a lot
+of quote @code{'} marks. Consider this fragment from Mozart:
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[verbatim,quote]
{
\key a \major
\time 6/8
}
@end lilypond
-All these quotes makes the input less readable and it is a source of
-errors. With @code{\relative}, the previous example is much easier
-to read:
+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 and type:
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[verbatim,quote]
\relative c'' {
\key a \major
\time 6/8
}
@end lilypond
-If you make a mistake with an octave mark (@code{'} or @code{,}) while
-working in @code{\relative} mode, it is very obvious -- many notes will
-be in the wrong octave. When working in absolute mode, a single mistake
-will not be as visible, and will not be as easy to find.
-
-However, absolute mode is useful for music which has large intervals, and
-is extremely useful for computer-generated LilyPond files.
-
-
-@node Organizing pieces with identifiers
-@subsection Organizing pieces with identifiers
-
-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{identifiers}.
-
-With identifiers (also known as variables or macros), we can break up
-complex music expressions. An identifier 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). Identifiers
-must be defined @emph{before} the main music expression.
-
-@lilypond[quote,verbatim,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 identifier 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
+If you make a mistake with an octave mark (@code{'} or @code{,})
+while working in @code{\relative} mode, it is very obvious -- many
+notes will be in the wrong octave. When working in absolute mode,
+a single mistake will not be as visible, and will not be as easy
+to find.
-Depending on its contents, the identifier can be used in different
-places. The following example uses the above variables:
+However, absolute mode is useful for music which has large
+intervals, and is extremely useful for computer-generated LilyPond
+files.
-@example
-\paper @{
- \aFivePaper
- line-width = \width
-@}
-@{ c4^\name @}
-@end example
@node After the tutorial
@subsection After the tutorial
After finishing the tutorial, you should probably try writing a
-piece or two. Start with one of the @ruser{Templates}, and
-add notes. If you need any notation that was not covered in the
-tutorial, look at the Notation Reference, starting with
-@ruser{Basic notation}. If you want to write for an instrument
-ensemble that is not covered in the templates,
-take a look at @ruser{Extending the templates}.
-
-Once you have written a few short pieces, read the rest of
-the Learning Manual (chapters 3-5). There's nothing wrong
-with reading it now, of course! However, the rest of the
-Learning Manual assumes that you are familiar with
-LilyPond input. You may wish to skim these chapters right
-now, and come back to them after you have more experience.
-
-
-@node How to read the manual
-@subsection How to read the manual
-
-As we saw in @ruser{How to read the tutorial}, many examples in the
-tutorial omitted a @code{\relative c'' @{ ... @}} around the printed
-example.
-
-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
-@ruser{About this manual}.
+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}.
+
+Once you have written a few short pieces, read the rest of the
+Learning Manual (chapters 3-5). There's nothing wrong with
+reading it now, of course! However, the rest of the Learning
+Manual assumes that you are familiar with LilyPond input. You may
+wish to skim these chapters right now, and come back to them after
+you have more experience.
+
+In this tutorial and in the rest of the Learning Manual, there is a
+paragraph @strong{See also} at the end of each section, which contains
+cross-references to other sections: you should not follow these
+cross-references at first reading; when you have read all of the
+Learning Manual, you may want to read some sections again and follow
+cross-references for further reading.
+
+If you have not done so already, @emph{please} read @ref{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
+save yourself hours of frustration looking in the wrong places!
projects / lilypond.git / blobdiff