-@c -*-texinfo-*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond-learning.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-@c TODO:
-@c * more details about running lilypond; error messages,
-@c compiling/viewing (emacs?)
-@c * where to go from First steps+More basics?
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
-@node Tutorial
-@chapter Tutorial
+@ignore
+Tutorial Specification:
+The LM is written in a tutorial style which introduces the most
+important concepts, structure and syntax of the elements of a
+LilyPond score in a carefully graded sequence of steps.
+Explanations of all musical concepts used in the Manual can be
+found in the Music Glossary, and readers are assumed to have no
+prior knowledge of LilyPond. The objective is to take readers to
+a level where the Notation Reference can be understood and
+employed to both adapt the templates in the Appendix to their
+needs and to begin to construct their own scores. Commonly used
+tweaks are introduced and explained. Examples are provided
+throughout which, while being focussed on the topic being
+introduced, are long enough to seem real in order to retain the
+readers' interest. Each example builds on the previous material,
+and comments are used liberally. Every new aspect is thoroughly
+explained before it is used.
-Using LilyPond comes down to encoding music in an input file. After
-entering the music, the program is run on the file producing output
-which can be viewed or printed. In this tutorial, we will show step
-by step how to enter such files, and illustrate the process with
-fragments of input and the corresponding output. At the end of every
-section, a paragraph will list where to find further information on
-the topics discussed.
+@end ignore
-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.
-@ifhtml
-For example, consider the following input:
-@c TODO: intertext fixme
-@lilypond[relative 1,singleline,verbatim,intertext="with the following output:"]
- c'^\markup { \bold \huge { Click on this image! } }
-@end lilypond
+@ignore
+Tutorial guidelines: (different from policy.txt!)
+- unless you have a really good reason, use either
+ @lilypond[verbatim,quote,ragged-right]
+ or
+ @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+
+ 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 "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.
+
+- Add "Music Glossary: @rglos{foo}" to the _top_ of the relevant
+ portions of the tutorial.
-@end ifhtml
-By cutting and pasting the full input into a test file, you have a
-starting template for experiments. If you like learning in this way,
-you will probably want to print out or bookmark
-@ifhtml
-the
-@end ifhtml
-@ref{Cheat sheet}, which is a table listing all commands for quick
-reference.
+@end ignore
-This tutorial starts with a short introduction to the LilyPond music
-language. After this first contact, we will show you how to to
-produce printed output. You should then be able to create and print
-your first sheets of music.
+@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.
@menu
* First steps::
-* Running LilyPond::
-* More about pitches ::
-* Octave entry::
-* Combining music into compound expressions::
-* Adding articulation marks to notes::
-* Combining notes into chords::
-* Printing lyrics::
-* A lead sheet::
-* Listening to output::
-* Titling::
-* Single staff polyphony::
-* Piano staves::
-* Setting variables::
-* Fine tuning layout::
-* Organizing larger pieces::
-* An orchestral part::
-* Integrating text and music::
+* Single staff notation::
+* Multiple notes at once::
+* Songs::
+* Final touches::
@end menu
@node First steps
@section First steps
-We start off by showing how very simple music is entered in LilyPond:
-you get a note simply by typing its note name, from @samp{a}
-through @samp{g}. So if you enter
-
-@example
-c d e f g a b
-@end example
-
-@noindent
-then the result looks like this:
-
-@c ?
-@c \transpose c c' { c d e f g a b }
-@c @lily pond[notime]
-@c \property Score.timing = ##f
-@lilypond[notime, relative=2]
-c d e f g a b
-@end lilypond
+This section gives a basic introduction to working with LilyPond.
-The length of a note is specified by adding a number, @samp{1} for a
-@rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
+@menu
+* Compiling a file::
+* Simple notation::
+* Working on text files::
+* How to read the tutorial::
+@end menu
-@example
-a1 a2 a4 a16 a32
-@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\transpose c c' { a1 a2 a4 a16 a32 s16_" " }
-@end lilypond
+@node Compiling a file
+@subsection Compiling a file
-If you do not specify a @rglos{duration}, the previous one is used:
+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:
@example
-a4 a a2 a
+@{
+ c' e' g' e'
+@}
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { a a a2 a s16_" " }
-@end lilypond
-
-
-Rests are entered just like notes, but with the name ``@code{r}'':
-
-@cindex rests
-@quotation
-@example
-r2 r4 r8 r16
-@end example
+@noindent
+the result looks like this:
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.Clef = \turnOff
-\property Staff.TimeSignature = \turnOff
-r2 r4 r8 r16
-s16_" "
+@c in this case we don't want verbatim
+@lilypond[quote,ragged-right]
+{
+ c' e' g' e'
+}
@end lilypond
-@end quotation
-@separate
+@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. 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}.}
-Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
-
-@example
-a2. a4 a8. a16
-@end example
+@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.
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { a2. a4 a8. a16 s16_" " }
-@end lilypond
+@smallspace
+@subheading Entering music and viewing output
-The @rglos{meter} (or @rglos{time signature}) can be set with the
-@code{\time} command:
+@cindex PDF file
+@cindex viewing music
-@example
-\time 3/4
-\time 6/8
-\time 4/4
-@end example
+In this section we will explain what commands to run and how to
+view or print the output.
-@c a clef here may lead to confusion
-@lilypond
-\property Staff.Clef \set #'transparent = ##t
-\time 3/4
-s4_" "
-\time 6/8
-s4_" "
-\time 4/4
-s16_" "
-@end lilypond
+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!}
-The @rglos{clef} can be set using the @code{\clef} command:
+@subsubheading MacOS X
-@c what is more common name treble or violin?
-@c in Dutch, its violin.
-@c in English its definitely treble.
-@example
-\clef treble
-\clef bass
-\clef alto
-\clef tenor
-@end example
+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 @code{Compile >
+Typeset File}. The resulting PDF file will be displayed on your
+screen.
-@lilypond[notime]
-\property Score.timing = ##f
-\clef violin
-s4_" "
-\clef bass
-s4_" "
-\clef alto
-s4_" "
-\clef tenor
-s16_" "
-@end lilypond
+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.
-Notes and commands like @code{\clef} and @code{\time} , are enclosed
-in @code{\notes @{@dots{}@}}. This indicates that music (as opposed
-to @rglos{lyrics}) follows:
-@example
-\notes @{
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2 r4
-@}
-@end example
-Now the piece of music is almost ready to be printed. The final step is to
-combine the music with a printing command.
+@subsubheading Windows
-The printing command is the so-called @code{\paper} block:
+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.
-@example
-\paper @{ @}
-@end example
+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 @code{\paper} block is used to customize printing specifics. The
-customization commands go between @code{@{} and @code{@}}, but for
-now, we accept the defaults. The music and the @code{\paper} block
-are combined by enclosing them in @code{\score @{ ... @}}, so the
-following is a complete and valid input 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.
-@example
-\score @{
- \notes @{
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2 r4
- @}
- \paper @{ @}
-@}
-@end example
+@subsubheading Unix
-@lilypond[noindent]
-\score {
- \notes {
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2 r4
- }
- \paper {
- linewidth = 55 * \staffspace
- }
-}
-@end lilypond
+Create a file (such as @file{test.ly}) and enter:
-In the rest of the tutorial we will often leave out @code{\score}
-and @code{\paper} for clarity. However, both must be present when
-feeding the file to LilyPond.
-
-For more elaborate information on
-
-@table @asis
-@item entering pitches and durations
-see
-@ref{Pitches} and @ref{Durations}.
-@item Clefs
-see @ref{Clef}
-@item Time signatures and other timing commands
-see @ref{Time signature}.
-@end table
-
-@node Running LilyPond
-@section Running LilyPond
-
-In the last section we explained what kind of things you could enter
-in a LilyPond file. In this section we explain what commands to run
-and how to view or print the output. If you have not used LilyPond
-before, want to test your setup, or want to run an example file
-yourself, read this section. The instructions that follow are for
-Unix-like systems. Some additional instructions for Microsoft Windows
-are given at the end of this section.
-
-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 it has not been
-installed already, then refer to the file @file{INSTALL.txt}}. In
-your text editor, enter the following input and save the file as
-@file{test.ly}:
-
-@quotation
@example
-\score @{
- \notes @{ c'4 e' g' @}
-@}
+@{
+ c' e' g' e'
+@}
@end example
-@end quotation
To process @file{test.ly}, proceed as follows:
-@quotation
@example
lilypond test.ly
@end example
-@end quotation
+@noindent
You will see something resembling:
-@quotation
@example
-GNU LilyPond 1.8.0
-Now processing: `/home/fred/ly/test.ly'
+lilypond test.ly
+GNU LilyPond 2.12.0
+Processing `test.ly'
Parsing...
-Interpreting music...[1]
- @emph{ ... more interesting stuff ... }
-PDF output to `test.pdf'...
-DVI output to `test.dvi'...
-@end example
-@end quotation
-@cindex DVI file
-@cindex Viewing music
-@cindex xdvi
-
-The result is the file @file{test.pdf}.@footnote{For @TeX{}
-afficionados: there is also a @file{test.dvi} file. It can be viewed
-with @code{xdvi}. The DVI uses a lot of PostScript specials, which do
-not show up in the magnifying glass. The specials also mean that the
-DVI file cannot be processed with @code{dvilj}. Use @code{dvips} for
-printing.
-@cindex dvips
-@cindex dvilj
-@cindex DVI driver
-} One of the following commands should put the PDF on your
-screen:
-@quotation
-@example
- gv test.pdf
- ghostview test.pdf
- ggv test.pdf
- kghostview test.pdf
- xpdf test.pdf
- gpdf test.pdf
- acroread test.pdf
- gsview32 test.pdf
+Interpreting music...
+Preprocessing graphical objects...
+Finding the ideal number of pages...
+Fitting music on 1 page...
+Drawing systems...
+Layout output to `test.ps'...
+Converting to `test.pdf'...
@end example
-@end quotation
-@noindent
-If the music on your screen looks good, you can print it by clicking
-File/Print inside your viewing program.
-@cindex Ghostscript
-@cindex @code{lpr}
-@cindex Printing output
-@cindex PostScript
-@cindex PDF
+@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.
-On Windows, the same procedure should work, the terminal is started by
-clicking on the LilyPond or Cygwin icon. Any text editor (such as
-NotePad, Emacs or Vim) may be used to edit the LilyPond file.
+@lilypond[verbatim,quote,ragged-right]
+{
+ c' e' g' e'
+}
+@end lilypond
-To view the PDF file, try the following:
-@itemize
-@item
-If your system has a PDF viewer installed, open
-@file{C:\Cygwin\home\@var{your-name}} in the explorer and double-click
-@file{test.pdf}.
-@item
-If you prefer the keyboard, you can try to enter one of the commands
-from the list shown before in the terminal. If none work, go to
-@uref{http://www.cs.wisc.edu/~ghost/} to install the proper software.
-@end itemize
+@noindent
+This behavior may be altered, but in most cases these automatic
+values are useful.
-The commands for formatting and printing music on all platforms are
-detailed in @ref{Invoking LilyPond}.
-@node More about pitches
-@section More about pitches
+@subheading Pitches
-A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to
-the name, a @rglos{flat} (@texiflat{}) 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.}
+Music Glossary: @rglos{pitch}, @rglos{interval},
+@rglos{scale}, @rglos{middle C}, @rglos{octave},
+@rglos{accidental}.
-@example
-cis1 ees fisis aeses
-@end example
+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[notime]
-\property Score.timing = ##f
-\transpose c c' { cis1 ees fisis aeses s16_" " }
+@lilypond[verbatim,quote,ragged-right]
+\relative c' { % set the starting point to middle C
+ c d e f
+ g a b c
+}
@end lilypond
-
-@cindex key signature, setting
+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:
-The key signature is set with the command ``@code{\key}'', followed by
-a pitch and @code{\major} or @code{\minor}:
-@quotation
-@example
-\key d \major
-g1
-\key c \minor
-g
-@end example
+@lilypond[verbatim,quote,ragged-right]
+\relative c' {
+ d f a g
+ c b f d
+}
+@end lilypond
-@lilypond[fragment]
-\property Staff.TimeSignature = \turnOff
-\key d \major
-g'1
-\key c \minor
-g'
+@noindent
+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{\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
-@end quotation
+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.
-Key signatures together with the pitch (including alterations) are
-used together to determine when to print accidentals. This is a
-feature that often causes confusion to newcomers, so let us explain it
-in more detail:
+@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 4 up or 3 down, so is the a below
+ b g % g is 5 up or 2 down, so is the g below
+ b f % f is 6 up or 1 down, so is the f below
+}
+@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.
-LilyPond has 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
-flat, natural or sharp @emph{sign}) is a 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.
+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.
-For example, in this example:
-@lilypond[fragment]
-\property Staff.TimeSignature = #'()
-\key d \major
-d' cis' fis'
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ a a, c' f,
+ g g'' a,, f'
+}
@end lilypond
@noindent
-no note gets an explicit accidental, but still you enter
+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.
-@example
-\key d \major
-d cis fis
-@end example
-The code @code{d} does not mean ``print a black dot just below the
-staff.'' Rather, it means: ``a note with pitch D-natural.'' In the key
-of A-flat, it gets an accidental:
+@subheading Durations (rhythms)
-@lilypond[fragment]
-\property Staff.TimeSignature = #'()
-\key as \major
-d'
-@end lilypond
+Music Glossary: @rglos{beam}, @rglos{duration}, @rglos{whole note},
+@rglos{half note}, @rglos{quarter note}, @rglos{dotted note}.
-@noindent
-@example
-\key as \major
-d
-@end example
+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.
-Adding all alterations explicitly might require some more effort when
-typing, but the advantage is that transposing is easier, and music can
-be printed according to different conventions. See @ref{Accidentals}
-for some examples how accidentals can be printed according to
-different rules.
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ a1
+ a2 a4 a8 a
+ a16 a a a a32 a a a a64 a a a a a a a a2
+}
+@end lilypond
+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).
-@cindex tie
-A tie is created by adding a tilde ``@code{~}'' to the first note
-being tied:
-@quotation
-@lilypond[fragment,verbatim,relative 2]
-g4~ g a2~ a4
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ a a a4. a8
+ a8. a16 a a8. a8 a4.
+}
@end lilypond
-@end quotation
-@separate
-This example shows the key signature, accidentals and ties in action:
-@quotation
-@example
-\score @{
- \notes @{
- \time 4/4
- \key g \minor
- \clef violin
- r4 r8 a8 gis4 b
- g8 d4.~ d e8
- fis4 fis8 fis8 eis4 a8 gis~
- gis2 r2
- @}
- \paper @{ @}
-@}
-@end example
+@subheading Rests
-@lilypond
-\score {
- \notes { \transpose c c' {
- \time 4/4
- \key g \minor
- \clef violin
- r4 r8 a8 gis4 b
- g8 d4.~ d e8
- fis4 fis8 fis8 eis4 a8 gis~
- gis2 r2
- }}
- \paper { linewidth = #(* 50 staffspace) }
+Music Glossary: @rglos{rest}.
+
+A @notation{rest} is entered just like a note with the name @code{r}:
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ a r r2
+ r8 a r4 r4. r8
}
@end lilypond
-@end quotation
-@cindex accidentals
-
-There are some interesting points to note in this example. Bar lines
-and beams are drawn automatically. Line breaks are calculated
-automatically; it does not matter where the lines breaks are in the
-source file. Finally, the order of time, key and clef changes is not
-relevant: in the printout, these are ordered according to standard
-notation conventions.
-
-
-@cindex beams, by hand
-Beams are drawn automatically, but if you do not like where they are
-put, they can be entered by hand. Mark the first note to be beamed
-with @code{[} and the last one with @code{]}:
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8[ ais] d[ es r d]
-@end lilypond
-@end quotation
-@separate
-For more information on
-@table @asis
-@item Rests
-see @ref{Rests}.
-@item Ties
-see @ref{Ties}.
+@subheading Time signature
-@item Accidentals
-see @ref{Accidentals}
+Music Glossary: @rglos{time signature}.
-@item Key signature
-see @ref{Key signature}
+The @notation{time signature} can be set with the @code{\time}
+command:
-@item Beams
-see @ref{Beaming}
-@end table
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ \time 3/4
+ a4 a a
+ \time 6/8
+ a4. a
+ \time 4/4
+ a4 a a a
+}
+@end lilypond
-@node Octave entry
-@section Octave entry
+@subheading Clef
+Music Glossary: @rglos{clef}.
-@c Tim wants to move this quotes example just before the: quotes-do not-work
-@c score, but we'd need to remove quotes from the other two (key and
-@c tie) examples...
+The @notation{clef} can be set using the @code{\clef} command:
-@c better to have this just before the `octaves are bad' snipped
-@c but we'd need to remove the ', from \key and tie
-To raise a note by an octave, add a high quote @code{'} (apostrophe) to
-the note name, to lower a note one octave, add a ``low quote'' @code{,}
-(a comma). Middle C is @code{c'}:
+@lilypond[verbatim,quote,ragged-right]
+\relative c' {
+ \clef treble
+ c1
+ \clef alto
+ c1
+ \clef tenor
+ c1
+ \clef bass
+ c1
+}
+@end lilypond
-@quotation
-@example
-c'4 c'' c''' \clef bass c c,
-@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-c'4 c'' c''' \clef bass c c,
-@end lilypond
-@end quotation
-@separate
+@subheading All together
-An example of the use of quotes is in the following Mozart fragment:
-@lilypond[singleline,fragment,verbatim]
- \key a \major
- \time 6/8
- cis''8. d''16 cis''8 e''4 e''8
- b'8. cis''16 b'8 d''4 d''8
-@end lilypond
-
-This example shows that music in a high register needs lots of quotes.
-This makes the input less readable, and it is a source of errors. The
-solution is to use ``relative octave'' mode. In practice, this is the
-most convenient way to copy existing music. To use relative mode, add
-@code{\relative} before the piece of music. You must also give a note
-from which relative starts, in this case @code{c''}. If you do not
-use octavation quotes (i.e. do not add ' or , after a note), relative
-mode chooses the note that is closest to the previous one.
-For example, @code{c f} goes up while @code{c g} goes down:
-
-@quotation
-@example
-\relative c'' @{
- c f c g c
-@}
-@end example
+Here is a small example showing all these elements together:
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
- c f c g c
+@lilypond[verbatim,quote,ragged-right]
+\relative c, {
+ \time 3/4
+ \clef bass
+ c2 e8 c' g'2.
+ f4 e d c4 c, r4
}
@end lilypond
-@end quotation
-@separate
-Since most music has small intervals, pieces can be written almost
-without octavation quotes in relative mode. The previous example is
-entered as
-@c
-@lilypond[singleline,fragment,verbatim]
-\relative c'' {
- \key a \major
- \time 6/8
- cis8. d16 cis8 e4 e8
- b8. cis16 b8 d4 d8
-}
-@end lilypond
+@seealso
+Notation Reference: @ruser{Writing pitches}, @ruser{Writing rhythms},
+@ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}.
-@c needed better, maybe even redundant explanation
-@c added another example below.
-@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
-@c in eerste instantie drong het `relative' niet door zonder extra uitleg.
-Larger intervals are made by adding octavation quotes.
-@quotation
-@example
-\relative c'' @{
- c f, f c' c g' c,
-@}
-@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
- c f, f c' c g' c,
-}
-@end lilypond
-@end quotation
-@separate
+@c HERE's where I started
-Quotes or commas do not determine the absolute height of a note; the
-height of a note is relative to the previous one.
-@c do not use commas or quotes in this sentence
-For example: @code{c f,} goes down; @code{f, f} are both the same;
-@code{c' c} are the same; and @code{c g'} goes up:
+@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{%@{ ...
+%@}}.
+If the previous sentences sound like nonsense, don't worry! We'll
+explain what all these terms mean:
-Here is an example of the difference between relative mode and
-``normal'' (non-relative) mode:
+@itemize
-@quotation
-@example
-\relative a @{
-\clef bass
- a d a e d c' d'
-@}
-@end example
+@cindex case sensitive
+@item
+@strong{Case sensitive}:
+it matters whether you enter a letter in lower case (e.g. @code{a,
+b, s, t}) or upper case (e.g. @code{A, B, S, T}). Notes are
+lower case: @code{@{ c d e @}} is valid input; @code{@{ C D E @}}
+will produce an error message.
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative a {
-\clef bass
- a d a e d c' d'
-}
-@end lilypond
-@end quotation
-@separate
+@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:
-@quotation
@example
-\clef bass
- a d a e d c' d'
+@{ c d
+ e @}
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\clef bass
- a d a e d c' d'
-@end lilypond
-@end quotation
-@separate
+@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:
+@example
+@{
+ c d e
+@}
+@end example
-For more information on Relative octaves see @ref{Relative octaves}
-and @ref{Octave check}.
+@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.
+@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
+@code{%} introduces a line comment; anything after @code{%} on
+that line is ignored. A block comment marks a whole section of
+music input as a comment. Anything that is enclosed in @code{%@{}
+and @code{%@}} is ignored. (Comments do not nest.) The following
+fragment shows possible uses for comments:
+@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.
+ g g f f e e d d c2
+%@}
+@end example
-@node Combining music into compound expressions
-@section Combining music into compound expressions
+@end itemize
-To print more than one staff, each piece of music that makes up a
-staff is marked by adding @code{\context Staff} before it. These
-@code{Staff}'s are then grouped inside @code{\simultaneous @{} and
-@code{@}}, as is demonstrated here:
-
-@quotation
-@lilypond[fragment,verbatim]
-\simultaneous {
- \new Staff { \clef violin c'' }
- \new Staff { \clef bass c }
-}
-@end lilypond
-@end quotation
-
-
-In this example, @code{\simultaneous } indicates that both music
-fragments happen at the same time, and must be printed stacked
-vertically. The notation @code{<< .. >>} can also be used as a
-shorthand for @code{\simultaneous @{ .. @}}.
-
-The command @code{\new} introduces a ``notation context''. To
-understand this concept, imagine that you are performing a piece of
-music. When you are playing, you combine the symbols printed at a
-certain point with contextual information. For example, without
-knowing the current clef, and the accidentals in the last measure, it
-would be impossible to determine the pitch of a note. In other words,
-this information forms context that helps you decipher a
-score. LilyPond produces notation from music, so in effect, it does
-the inverse of reading scores. Therefore, it also needs to keep track
-of contextual information. This information is maintained in
-``notation contexts.'' There are several types of contexts,
-e.g. @code{Staff}, @code{Voice} and @code{Score}, but also
-@code{Lyrics} and @code{ChordNames}. Prepending @code{\new} to a chunk
-of music indicates what kind of context to use for interpreting it,
-and ensures that the argument is interpreted with a fresh instance of
-the context indicated.
-
-
-@separate
-
-We can now typeset a melody with two staves:
-
-@quotation
-@lilypond[verbatim,singleline]
-\score {
- \notes
- << \new Staff {
- \time 3/4
- \clef violin
- \relative c'' {
- e2( d4 c2 b4 a8[ a]
- b[ b] g[ g] a2.) }
- }
- \new Staff {
- \clef bass
- c2 e4 g2.
- f4 e d c2.
- }
- >>
- \paper {}
-}
-@end lilypond
-@end quotation
-
-The example shows how small chunks of music, for example, the notes
-@code{c2}, @code{e4}, etc. of the second staff, are combined to form a
-larger chunk by enclosing it in braces. Again, a larger chunk is
-formed by prefix @code{\new Staff} to it, and that chunk is combined
-with @code{<< >>}. This mechanism is similar with 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,
-
-@quotation
- 1
-
- 1 + 2
-
- (1 + 2) * 3
-
- ((1 + 2) * 3) / (4 * 5)
-@end quotation
-@cindex expression
-@cindex music expression
-This example shows a sequence of expressions, where each expression is
-contained in the next one. The simplest expressions are numbers and
-operators (like +, * and /). Parentheses are used to group
-expressions. In LilyPond input, a similar mechanism is used. Here,
-the simplest expressions are notes and rests. By enclosing
-expressions in @code{<< >>} and @code{@{ @}}, more complex music is
-formed. The @code{\new} command also forms new expressions; prepending
-it to a music expression yields a new expression.
-Like mathematical expressions, music expressions can be nested
-arbitrarily deep, e.g.
-@lilypond[verbatim,relative 1]
- { c <<c e>>
- << { e f } { c <<b d>> }
- >>
- }
-@end lilypond
+@node How to read the tutorial
+@subsection How to read the tutorial
+LilyPond input must be surrounded by @{ @} marks or a
+@code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
+files}. For the rest of this manual, most examples will omit
+this. To replicate the examples, you may copy and paste the
+displayed input but you @strong{must} add the @code{\relative c''
+@{ @}} like this:
-@cindex indent
-When spreading expressions over multiple lines, it is customary to use
-an indent that indicates the nesting level. Formatting music like this
-eases reading, and helps you insert the right amount of closing
-braces at the end of an expression. For example,
@example
-\score @{
- \notes <<
- @{
- @dots{}
- @}
- @{
- @dots{}
- @}
- >>
+\relative c'' @{
+ ... example goes here...
@}
@end example
-
-For more information on context see the Technical manual description
-in @ref{Interpretation context}.
+Why omit the braces? Most examples in this manual can be inserted
+into the middle of a longer piece of music. For these examples,
+it does not make sense to add @code{\relative c'' @{ @}} -- you
+should not place a @code{\relative} inside another
+@code{\relative}! If we included @code{\relative c'' @{ @}}
+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
-@node Adding articulation marks to notes
-@section Adding articulation marks to notes
-
-@cindex articulation
-@cindex accents
-@cindex staccato
+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:
-Common accents can be added to a note using a dash (`@code{-}') and a
-single character:
-@quotation
-@lilypond[verbatim,relative 1]
-c-. c-- c-> c-^ c-+ c-_
+@c no verbatim here
+@lilypond[quote,ragged-right]
+\relative c'' {
+ c-\markup { \bold \huge { Click here. } }
+}
@end lilypond
-@end quotation
-@separate
-@cindex fingering
-Similarly, fingering indications can be added to a note using a dash
-(`@code{-}') and the digit to be printed:
-@c
-@lilypond[verbatim,relative 1]
- c-3 e-5 b-2 a-1
-@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
-Dynamic signs are made by adding the markings to the note:
-@quotation
-@lilypond[verbatim,relative 1]
-c\ff c\mf
-@end lilypond
-@end quotation
-@separate
-@cindex dynamics
-@cindex decrescendo
-@cindex crescendo
+There are more tips for constructing input files in
+@ref{Suggestions for writing LilyPond files}.
-Crescendi and decrescendi are started with the commands @code{\<} and
-@code{\>}. The command @code{\!} finishes a crescendo on the note it
-is attached to:
-@quotation
-@lilypond[verbatim,relative 1]
-c2\< c2\!\ff\> c2 c2\!
-@end lilypond
-@end quotation
-@separate
+@node Single staff notation
+@section Single staff notation
-@cindex slur
+This section introduces common notation that is used for one voice
+on one staff.
-A slur is drawn across many notes, and indicates bound articulation
-(legato). The starting note and ending note are marked with a
-``@code{(}'' and a ``@code{)}'' respectively:
+@menu
+* Accidentals and key signatures::
+* Ties and slurs::
+* Articulation and dynamics::
+* Adding text::
+* Automatic and manual beams::
+* Advanced rhythmic commands::
+@end menu
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-d4( c16)( cis d e c cis d e)( d4)
-@end lilypond
-@end quotation
-@separate
-@cindex slurs versus ties
-A slur looks like a tie, but it has a different meaning. A tie simply
-makes the first note sound 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 are also
-nested in practice:
-@c
-@lilypond[fragment, relative=1]
-c2~( c8 fis fis4 ~ fis2 g2)
-@end lilypond
-@cindex phrasing slurs
-If you need two slurs at the same time (one for articulation, one for
-phrasing), you can also make a phrasing slur with @code{\(} and
-@code{\)}.
+@node Accidentals and key signatures
+@subsection Accidentals and key signatures
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8(\( ais b c) cis2 b'2 a4 cis, c\)
-@end lilypond
-@end quotation
-
-
-For more information on
-@table @asis
-@item fingering
- see @ref{Fingering instructions}
-@item articulations
- see @ref{Articulations}
-@item slurs
- see @ref{Slurs}
-@item phrasing slurs
- see @ref{Phrasing slurs}
-@item dynamics
- see @ref{Dynamics}
-@item fingering
-@end table
+@subheading Accidentals
-@node Combining notes into chords
-@section Combining notes into chords
+Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
+@rglos{double flat}, @rglos{accidental}.
-@cindex chords
-Chords can be made by
-surrounding pitches with @code{<} and @code{>}:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <c e g>4 <c f a>8
+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
@end lilypond
-@end quotation
-@separate
+@cindex key signature, setting
+@subheading Key signatures
+
+Music Glossary: @rglos{key signature}, @rglos{major}, @rglos{minor}.
-You can combine beams and ties with chords. Beam and tie markings
-must be placed outside the chord markers:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <c e g>8[ <c f a>]~ <c f a>
-@end lilypond
-@end quotation
+The @notation{key signature} is set with the command @code{\key}
+followed by a pitch and @code{\major} or @code{\minor}.
-@quotation
-@example
-r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
-@end example
-@lilypond[relative 0, fragment]
-\slurUp
-r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+\key d \major
+a1
+\key c \minor
+a
@end lilypond
-@end quotation
-@separate
+@smallspace
+@subheading Warning: key signatures and pitches
-@menu
-* Basic rhythmical commands::
-* Commenting input files::
-@end menu
+Music Glossary: @rglos{accidental}, @rglos{key signature},
+@rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
+@rglos{transposition}.
-@node Basic rhythmical commands
-@subsection Basic rhythmical commands
+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.
-@cindex pickup
-@cindex anacruse
-@cindex upstep
-@cindex partial measure
-A pickup (or upstep) is entered with the keyword @code{\partial}. It
-is followed by a duration: @code{\partial 4} is a quarter note upstep
-and @code{\partial 8} an eighth note:
-@lilypond[relative 1,verbatim,fragment]
- \partial 8
- f8 c2 d e
-@end lilypond
+LilyPond makes a sharp distinction between musical content and
+layout. The alteration (@notation{flat}, @notation{natural} 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.
-@cindex tuplets
-@cindex triplets
-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:
-@c
-@lilypond[relative 0,verbatim,fragment]
- \times 2/3 { f8 g a }
- \times 2/3 { c r c }
-@end lilypond
+In this example:
-@cindex grace notes
-@cindex accacciatura
-Grace notes are also made by prefixing a note, or a set of notes with
-a keyword. In this case, the keywords are @code{\appoggiatura}
-and @code{\acciaccatura}
-@cindex appoggiatura
-@cindex acciaccatura
-
-@lilypond[relative 1, verbatim,fragment]
- c4 \appoggiatura b16 c4
- c4 \acciaccatura b16 c4
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+\key d \major
+d cis fis
@end lilypond
@noindent
+No note has a printed accidental, but you must still add the
+@code{is} to @code{cis} and @code{fis}.
-For more information on
-@table @asis
-@item grace notes
-see @ref{Grace notes},
-@item tuplets
-see @ref{Tuplets},
-@item upsteps
-see @ref{Partial measures}.
-@end table
-
+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:
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+\key aes \major
+e
+@end lilypond
-@node Commenting input files
-@subsection Commenting input files
+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}.
-@cindex comments
-@cindex line comment
-@cindex block comment
-Comments are pieces of the input that are ignored. There are two
-types of comments. A line comments is introduced by @code{%}: after
-that, the rest of that line is ignored. Block comments span larger
-sections of input. Anything that is enclosed in @code{%@{} and
-@code{%@}} is ignored too. The following fragment shows possible uses
-for comments:
+@seealso
-@example
- % notes for twinkle twinkle follow:
- c4 c g' g a a
-
- %@{
-
- This line, and the notes below
- are ignored, since they are in a
- block comment.
-
- g g f f e e d d c2
- %@}
-@end example
+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
+@subsection Ties and slurs
-@node Printing lyrics
-@section Printing lyrics
-@cindex lyrics
+@cindex ties
+@subheading Ties
-@cindex Lyrics
-@cindex Songs
-Lyrics are entered by separating each syllable with a space, and
-surrounding them with @code{\lyrics @{ @dots{} @}}, for example,
-@example
- \lyrics @{ I want to break free @}
-@end example
+Music Glossary: @rglos{tie}.
-Like notes, lyrics are also a form of music, but they must not be
-printed on a staff, which is the default way to print music. To print
-them as lyrics, they must be marked with @code{ \new Lyrics}:
-@example
- \new Lyrics \lyrics @{ I want to break free @}
-@end example
-The melody for this song is as follows:
+A @notation{tie} is created by appending a tilde @code{~} to the
+first note being tied.
-@lilypond[fragment,relative=1]
- \partial 8
- c8
- \times 2/3 { f4 g g } \times 2/3 { g4( a2) }
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+g4~ g c2~
+c4 ~ c8 a8 ~ a2
@end lilypond
-The lyrics can be set to these notes, combining both with the
-@code{\addlyrics} keyword:
-@example
- \addlyrics
- \notes @{ @dots{} @}
- \new Lyrics @dots{}
-@end example
+@cindex slurs
+@subheading Slurs
-The final result is
-@lilypond[verbatim,linewidth=6.0cm]
-\score {
- \notes {
- \addlyrics
- \relative c' {
- \partial 8
- c8
- \times 2/3 { f g g } \times 2/3 { g4( a2) }
- }
- \new Lyrics \lyrics { I want to break free }
- }
- \paper{ }
-}
-@end lilypond
+Music Glossary: @rglos{slur}.
-@cindex melisma
-@cindex extender line
-@c synonyms?
-This melody ends on a @rglos{melisma}, a single syllable (``free'')
-sung to more than one note. This is indicated with an @emph{extender
-line}. It is entered as two underscores, i.e.
-@example
- \lyrics @{ I want to break free __ @}
-@end example
-@lilypond[]
-\score {
- \notes {
- \addlyrics
- \relative c' {
- \partial 8
- c8
- \times 2/3 { f g g } \times 2/3 { g4( a2) }
-
- %% ugh, this is to deal with bugs in the extender implementation
- \hideNotes
- c32
- }
- \new Lyrics \lyrics { I want to break free __ }
- }
- \paper{ linewidth = 9.0 \cm }
-}
-@end lilypond
+A @notation{slur} is a curve drawn across many notes. The starting
+note and ending note are marked with @code{(} and @code{)}
+respectively.
-Similarly, hyphens between words can be entered as two dashes,
-resulting in a centered hyphen between two syllables:
-@example
- Twin -- kle twin -- kle
-@end example
-@lilypond[singleline]
-\score {
- \addlyrics \notes \relative f' { \time 2/4
- f4 f c' c' }
- \new Lyrics \lyrics { Twin -- kle twin -- kle
- }
-\paper { linewidth = 6.0 \cm }
- }
-
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+d4( c16) cis( d e c cis d) e( d4)
@end lilypond
-More options, like putting multiple lines of lyrics below a melody are
-discussed in @ref{Vocal music}.
+@cindex slurs, phrasing
+@cindex phrasing slurs
+@subheading Phrasing slurs
+Music Glossary: @rglos{phrasing}, @rglos{legato}.
+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.
-@node A lead sheet
-@section A lead sheet
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+a8(\( ais b c) cis2 b'2 a4 cis,\)
+@end lilypond
-@cindex Lead sheets
-@cindex chords
-@cindex chord names
-
-In popular music, it is common to denote accompaniment as chord-names.
-Using them in LilyPond has two parts, just like lyrics: entering the
-chords (with @code{\chords}), and printing them (with @code{\new
-ChordNames}).
-
-Chord names are entered by starting chords mode (with @code{\chords}).
-In chords mode, you can enter chords with a letter (indicating the
-root of the chord), and a durations following that:
-@c
-@lilypond[verbatim]
- \chords { c2 f4. g8 }
+@smallspace
+
+@cindex slurs versus ties
+@subheading Warnings: slurs vs. ties
+
+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[verbatim,quote,ragged-right,fragment,relative=2]
+c2~( c8 fis fis4 ~ fis2 g2)
@end lilypond
-@noindent
-The result of @code{\chords} is a list of chords, and is equivalent
-to entering chords with @code{<@dots{}>}.
-
-Other chords can be created by adding modifiers, after a colon. The
-following example shows a few common modifiers:
-@c
-@lilypond[verbatim]
- \chords { c2 f4:m g4:maj7 gis1:dim7 }
+@seealso
+
+Notation Reference: @ruser{Ties}, @ruser{Slurs},
+@ruser{Phrasing slurs}.
+
+
+@node Articulation and dynamics
+@subsection Articulation and dynamics
+
+@cindex articulation
+@cindex accents
+@cindex staccato
+@subheading Articulations
+
+Music Glossary: @rglos{articulation}.
+
+Common @notation{articulations} can be added to a note using a
+dash @code{-} and a single character:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c-. c-- c-> c-^ c-+ c-_
+@end lilypond
+
+@cindex fingering
+@subheading Fingerings
+
+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,ragged-right,fragment,relative=2]
+c-3 e-5 b-2 a-1
@end lilypond
-Printing chords is done by adding @code{\context ChordNames}
-before the chords thus entered:
-@c
-@lilypond[verbatim]
- \context ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+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[verbatim,quote,ragged-right,fragment,relative=2]
+c_-^1 d^. f^4_2-> e^-_+
@end lilypond
-@cindex lead sheet
-@separate
-When put together, chord names, lyrics and a melody form
-a lead sheet, for example,
+@subheading Dynamics
-@example
-\score @{
- <<
- \context ChordNames \chords @{ @emph{chords} @}
- \addlyrics
- \notes @emph{the melody}
- \context Lyrics \lyrics @{ @emph{the text} @}
- >>
- \paper @{ @}
-@}
-@end example
-@lilypond[]
-\score {
- <<
- \context ChordNames \chords { r8 c2:sus4 f }
- \addlyrics
- \notes \relative c' {
- \partial 8
- c8
- \times 2/3 { f g g } \times 2/3 { g4( a2) } }
- \context Lyrics \lyrics { I want to break free __ }
- >>
- \paper{ raggedright = ##t }
+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,ragged-right,fragment,relative=2]
+c\ff c\mf c\p c\pp
+@end lilypond
+
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
+
+@notation{Crescendi} and @notation{decrescendi} are started with
+the commands @code{\<} and @code{\>}. An ending dynamic, for
+example @code{\f}, will finish the (de)crescendo, or the command
+@code{\!} can be used:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c2\< c2\ff\> c2 c2\!
+@end lilypond
+
+@seealso
+
+Notation Reference: @ruser{Articulations},
+@ruser{Fingering instructions}, @ruser{Dynamics}.
+
+
+@node Adding text
+@subsection Adding text
+
+Text may be added to your scores:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c1^"espr" a_"legato"
+@end lilypond
+
+Extra formatting may be added with the @code{\markup} command:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c1^\markup{ \bold espr}
+a1_\markup{
+ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
}
@end lilypond
-A complete list of modifiers, and other options for layout are in the
-reference manual section @ref{Chords}.
+@seealso
-@node Listening to output
-@section Listening to output
+Notation Reference: @ruser{Writing text}.
-@cindex sound
-@cindex MIDI
-MIDI (Musical Instrument Digital Interface) is a standard for
-connecting and recording digital instruments. A MIDI file is like a
-tape recording of a MIDI instrument. The @code{\midi} block makes the
-music go to a MIDI file, so you can listen to the music you entered.
-It is great for checking the music: octaves that are off, or
-accidentals that were mistyped, stand out very much when listening to
-the musical transcription.
+@node Automatic and manual beams
+@subsection Automatic and manual beams
-@code{\midi} can be used in similarly to @code{\paper @{ @}}, for
-example,
-@example
-\score @{
- @var{..music..}
- \midi @{ \tempo 4=72 @}
- \paper @{ @}
-@}
-@end example
-
-Here, the tempo is specified using the @code{\tempo} command. In this
-case the tempo of quarter notes is set to 72 beats per minute. More
-information on auditory output is in the @ref{Sound} section in the
-notation manual.
-
-
-
-@node Titling
-@section Titling
-
-Bibliographic information is entered in a separate block, the
-@code{\header} block. The name of the piece, its composer, etc. are
-entered as an assignment, within @code{\header @{ @dots{} @}}. For
-example,
-@example
- \header @{
- title = "Eight miniatures"
- composer = "Igor Stravinsky"
- tagline = "small is beautiful"
- @}
-
- \score @{ @dots{} @}
-@end example
+Music Glossary: @rglos{beam}.
-@cindex bibliographic information
-@cindex titles
-@cindex composer
-@cindex Engraved by LilyPond
-
-When the file is processed by the @code{lilypond} wrapper script, then
-the title and composer specified are printed above the music. The
-`tagline' is a short line printed at bottom of the last page, which
-normally says ``Engraved by LilyPond, version @dots{}''. In the
-example above, it is replaced by the line ``small is
-beautiful.''@footnote{Nicely printed parts are good PR for us, so do
-us a favor, and leave the tagline if you can.}
-
-Normally, the @code{\header} is put at the top of the file. However,
-for a document that contains multiple pieces (e.g. an etude book, or
-an orchestral part with multiple movements), then the header can be
-put into the @code{\score} block as follows; in this case, the name of
-each piece will be printed before each movement:
-
-
-@cindex Lily was here
-@cindex signature line
-@cindex tag line
-
-@example
- \header @{
- title = "Eight miniatures"
- composer = "Igor Stravinsky"
- tagline = "small is beautiful"
- @}
-
- \score @{ @dots{}
- \header @{ piece = "Adagio" @}
- @}
- \score @{ @dots{}
- \header @{ piece = "Menuetto" @}
- @}
-@end example
+@cindex beams, by hand
+All @notation{beams} are drawn automatically:
-More information on titling can be found in @ref{Invoking lilypond}.
+@lilypond[verbatim,quote,ragged-right,fragment,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 @code{[} and the
+last one with @code{]}.
-@node Single staff polyphony
-@section Single staff polyphony
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+a8[ ais] d[ ees r d] a b
+@end lilypond
-@cindex polyphony
-@cindex multiple voices
-@cindex voices, more -- on a staff
+@seealso
-When different melodic lines are combined on a single staff, these 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.
+Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
-Entering such parts is done by entering each voice as a sequence (with
-@code{@{ .. @}}), and combining those simultaneously, separating the
-voices with @code{\\}:
-@example
- << @{ a4 g2 f4~ f4 @} \\
- @{ r4 g4 f2 f4 @} >>
-@end example
-@lilypond[relative 1]
-\context Staff << { a4 g2 f4~ f4 } \\
- { r4 g4 f2 f4 } >>
+@node Advanced rhythmic commands
+@subsection Advanced rhythmic commands
+
+@cindex pickup
+@cindex anacrusis
+@cindex partial measure
+@subheading Partial measure
+
+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,ragged-right,fragment,relative=2]
+\partial 8
+f8 c2 d
+@end lilypond
+
+@cindex tuplets
+@cindex triplets
+@subheading Tuplets
+
+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
+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,ragged-right,fragment,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
+
+@cindex grace notes
+@cindex acciaccatura
+@cindex appoggiatura
+@subheading Grace notes
+
+Music Glossary: @rglos{grace notes}, @rglos{acciacccatura}, @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[verbatim,quote,ragged-right,fragment,relative=2]
+c2 \grace { a32[ b] } c2
+c2 \appoggiatura b16 c2
+c2 \acciaccatura b16 c2
+@end lilypond
+
+@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.
+
+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::
+@end menu
+
+
+@node Music expressions explained
+@subsection Music expressions explained
+
+In LilyPond input files, music is represented by @emph{music
+expressions}. A single note is a music expression:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+a4
+@end lilypond
+
+Enclosing a note in braces creates a @emph{compound music
+expression}. Here we have created a compound music expression
+with two notes:
+
+@lilypond[verbatim,quote,ragged-right,fragment,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:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+{ { a4 g } f g }
+@end lilypond
+
+@subheading Simultaneous music expressions: multiple staves
+
+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,ragged-right]
+\relative c'' {
+ <<
+ { a4 g }
+ { f e }
+ { d b }
+ >>
+}
+@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.
+
+@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.
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ c2 <<c e>>
+ << { e f } { c <<b d>> } >>
+}
@end lilypond
-For polyphonic music typesetting, spacer rests can also be convenient: these
-are rests that do not print. It is useful for filling up voices that
-temporarily do not play:
+@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 music expressions, so you
+can make arbitrarily complex and large expressions. For example,
+
@example
- << @{ a4 g2 f4~ f4 @} \\
- @{ s4 g4 f2 f4 @} >>
+1
+
+1 + 2
+
+(1 + 2) * 3
+
+((1 + 2) * 3) / (4 * 5)
@end example
-@lilypond[relative 1]
-\context Staff << { a4 g2 f4~ f4 } \\
- { s4 g4 f2 f4 } >>
+
+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.
+
+
+@node Multiple staves
+@subsection Multiple staves
+
+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{>>}:
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ <<
+ \new Staff { \clef treble c }
+ \new Staff { \clef bass c,, }
+ >>
+}
@end lilypond
-Again, these expressions can be nested arbitrarily:
+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.
-@lilypond[fragment]
-<<
- \new Staff
- \relative c''
- << { a4 g2 f4~ f4 } \\
- { s4 g4 f2 f4 } >>
- \new Staff
- << { \clef bass <c g>1 ~ <c g>4 } \\
- { f4 d e2 ~ e4}
+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.
+
+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.
+
+Time signatures entered in one staff affect all other
+staves@footnote{This behavior may be changed if desired; for
+details, see @ruser{Polymetric notation}.}. On the other hand,
+the key signature of one staff does @emph{not} affect other
+staves.
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ <<
+ \new Staff { \clef treble \key d \major \time 3/4 c }
+ \new Staff { \clef bass c,, }
>>
->>
+}
@end lilypond
-More features of polyphonic typesetting are in the notation manual
-in @ref{Polyphony}.
+
@node Piano staves
-@section Piano staves
+@subsection Piano staves
@cindex staff switch, manual
@cindex cross staff voice, manual
-@cindex @code{\translator}
-Piano music is always typeset in two staves connected by a brace.
-Printing such a staff is done similar to the polyphonic example in
-@ref{Combining music into compound expressions}:
-@example
- << \new Staff @{ @dots{} @}
- \new Staff @{ @dots{} @}
- >>
-@end example
-but now this entire expression must be interpreted as a
-@code{PianoStaff}:
+Music Glossary: @rglos{brace}.
+
+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 << \new Staff @dots{} >>
+\new PianoStaff <<
+ \new Staff @dots{}
+ \new Staff @dots{}
+>>
@end example
-Here is a full-fledged example:
+Here is a small example:
-@lilypond[relative 0,fragment]
-\new PianoStaff
- << \new Staff { \time 2/4
- c4 c g' g }
- \new Staff {
- \clef bass c,, c' e c }
- >>
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ \new PianoStaff <<
+ \new Staff { \time 2/4 c4 e g g, }
+ \new Staff { \clef bass c,, c' e c }
+ >>
+}
@end lilypond
-More information on formatting piano music is in @ref{Piano music}.
+@seealso
-@node Setting variables
-@section Setting variables
+Notation Reference: @ruser{Piano music}.
-When the music is converted from notes to print, it is interpreted
-from left-to-right order, similar to what happens when we read
-music. During this step, context-sensitive information, such as the
-accidentals to print, and where barlines must be placed, are stored in
-variables. These variables are called @emph{context properties}.
-The properties can also be manipulated from input files. Consider this input:
-@example
-\property Staff.autoBeaming = ##f
-@end example
-@noindent
-It sets the property named @code{autoBeaming} in the current staff at
-this point in the music to @code{##f}, which means `false'. This
-property controls whether beams are printed automatically:
-@c
-@lilypond[relative 1,fragment,verbatim]
- c8 c c c
- \property Staff.autoBeaming = ##f
- c8 c c c
+@node Combining notes into chords
+@subsection Combining notes into chords
+
+@cindex chords
+
+Music Glossary: @rglos{chord}.
+
+@notation{Chords} can be made by surrounding pitches with single
+angle brackets. Angle brackets are the symbols @code{<} and
+@code{>}.
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+r4 <c e g>4 <c f a>2
@end lilypond
-@noindent
-LilyPond includes a built-in programming language, namely, a dialect
-of Scheme. The argument to @code{\property}, @code{##f}, is an
-expression in that language. The first hash-mark signals that a piece
-of Scheme code follows. The second hash character is part of the
-boolean value true (@code{#t}). Values of other types may be
-entered as follows:
-@itemize @bullet
-@item a string, enclosed in double quotes, for example,
-@example
- \property Staff.instrument = #"French Horn"
-@end example
-@item a boolean: either @code{#t} or @code{#f}, for true and false
-respectively, e.g.
-@example
- \property Voice.autoBeaming = ##f
- \property Score.skipBars = ##t
-@end example
+You can combine markings like beams and ties with chords. They
+must be placed outside the angle brackets.
-@item a number, such as
-@example
- \property Score.currentBarNumber = #20
-@end example
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+r4 <c e g>8[ <c f a>]~ <c f a>2
+@end lilypond
-@item a symbol, which is introduced by a quote character, as in
-@example
- \property Staff.crescendoSpanner = #'dashed-line
-@end example
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
+@end lilypond
-@item a pair, which is also introduced by a quote character, like in
-the following statements, which set properties to the pairs (-7.5, 6)
-and (3, 4) respectively:
-@example
- \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
- \property Staff.timeSignatureFraction = #'(3 . 4)
-@end example
+@node Single staff polyphony
+@subsection Single staff polyphony
-@item a list, which is also introduced by a quote character. In the
-following example, the @code{breakAlignOrder} property is set to a
-list of symbols:
-@example
- \property Score.breakAlignOrder =
- #'(left-edge time-signature key-signatures)
-@end example
+@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{\\}
-@end itemize
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+<<
+ { a4 g2 f4~ f4 } \\
+ { r4 g4 f2 f4 }
+>>
+@end lilypond
+
+For polyphonic music typesetting, spacer rests can also be
+convenient; these are rests that do not print. They are useful
+for filling up voices that temporarily do not play. Here is the
+same example with a spacer rest (@code{s}) instead of a normal
+rest (@code{r}),
-There are many different properties, and not all of them are listed in
-this manual. However, the program reference lists them all in the
-section @internalsref{Context-properties}, and most properties are
-demonstrated in one of the
-@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
-@end ifhtml
-@ifnothtml
-tips-and-tricks
-@end ifnothtml
-examples.
-
-
-@node Fine tuning layout
-@section Fine tuning layout
-
-Sometimes it is necessary to change music layout by hand. When music
-is formatted, layout objects are created for each symbol. For
-example, every clef and every note head is represented by a layout
-object. These layout objects also carry variables, which we call
-@emph{layout properties}. By changing these variables from their
-values, we can alter the look of a formatted score:
-
-@lilypond[verbatim,relative 0]
- c4
- \property Voice.Stem \override #'thickness = #3.0
- c4 c4 c4
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+<<
+ { a4 g2 f4~ f4 } \\
+ { s4 g4 f2 f4 }
+>>
@end lilypond
@noindent
-In the example shown here, the layout property @code{thickness} (a
-symbol) is set to 3 in the @code{Stem} layout objects of the current
-Voice. As a result, the notes following @code{\property} have thicker
-stems.
+Again, these expressions can be nested arbitrarily.
-In most cases of manual overrides, only a single object must be
-changed. This can be achieved by prefixing @code{\once} to the
-@code{\property} statement, i.e.
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+<<
+ \new Staff <<
+ { a4 g2 f4~ f4 } \\
+ { s4 g4 f2 f4 }
+ >>
+ \new Staff <<
+ \clef bass
+ { <c g>1 ~ <c g>4 } \\
+ { e,,4 d e2 ~ e4}
+ >>
+>>
+@end lilypond
-@example
- \once \property Voice.Stem \set #'thickness = #3.0
-@end example
+@seealso
+
+Notation Reference: @ruser{Simultaneous notes}.
+
+
+@node Songs
+@section Songs
-@lilypond[relative 0]
- c4
- \once \property Voice.Stem \set #'thickness = #3.0
- c4 c4 c4
+This section introduces vocal music and simple song sheets.
+
+@menu
+* Setting simple songs::
+* Aligning lyrics to a melody::
+* Lyrics to multiple staves::
+@end menu
+
+
+@node Setting simple songs
+@subsection Setting simple songs
+
+@cindex lyrics
+@cindex songs
+
+Music Glossary: @rglos{lyrics}.
+
+Here is the start of the melody to a nursery
+rhyme, @qq{Girls and boys come out to play}:
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ \key g \major
+ \time 6/8
+ d4 b8 c4 a8 d4 b8 g4
+}
@end lilypond
-@noindent
-Some overrides are so common that predefined commands are provided as
-a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@ref{Notation manual}, under the sections for slurs and stems
-respectively.
+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.
-The exact tuning possibilities for each type of layout object are
-documented in the program reference of the respective
-object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a couple of these:
-
-@itemize @bullet
-@item The @code{extra-offset} property, which
-@cindex @code{extra-offset}
-has a pair of numbers as value, moves around objects in the printout.
-The first number controls left-right movement; a positive number will
-move the object to the right. The second number controls up-down
-movement; a positive number will move it higher. The unit of these
-offsets are staff-spaces. The @code{extra-offset} property is a
-low-level feature: the formatting engine is completely oblivious to
-these offsets.
-
-In the following example example, the second fingering is moved a
-little to the left, and 1.8 staff space downwards:
-
-@cindex setting object properties
-
-@lilypond[relative 1,verbatim]
-\stemUp
-f-5
-\once \property Voice.Fingering
- \set #'extra-offset = #'(-0.3 . -1.8)
-f-5
+@lilypond[verbatim,quote,ragged-right]
+<<
+ \relative c'' {
+ \key g \major
+ \time 6/8
+ d4 b8 c4 a8 d4 b8 g4
+ }
+ \addlyrics {
+ Girls and boys come out to play,
+ }
+>>
@end lilypond
-@item
-Setting the @code{transparent} property will make an object be printed
-in `invisible ink': the object is not printed, but all its other
-behavior is retained. The object still takes space, it takes part in
-collisions, and slurs, ties and beams can be attached to it.
-
-@cindex transparent objects
-@cindex removing objects
-@cindex invisible objects
-The following example demonstrates how to connect different voices
-using ties. Normally ties only happen between notes of the same
-voice. By introducing a tie in a different voice, and blanking a stem
-in that voice, the tie appears to cross voices:
-
-@lilypond[fragment,relative 1,verbatim]
- c4 << {
- \once \property Voice.Stem \set #'transparent = ##t
- b8~ b8
- } \\ {
- b[ g8]
- } >>
+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.
+
+@node Aligning lyrics to a melody
+@subsection Aligning lyrics to a melody
+
+Music Glossary: @rglos{melisma}, @rglos{extender line}.
+
+@cindex melisma
+@cindex extender line
+@cindex hyphens
+@cindex underscore
+
+The next line in the nursery rhyme is @q{The moon doth shine as
+bright as day}. Let's extend it:
+
+@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
-@item
-The @code{padding} property for objects with
-@cindex @code{padding}
-@code{side-position-interface} can be set to increase distance between
-symbols that are printed above or below notes. We only give an
-example; a more elaborate explanation is in @ref{Constructing a
-tweak}:
-
-@lilypond[relative 1,verbatim]
- c2\fermata
- \property Voice.Script \set #'padding = #3
- b2\fermata
+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}):
+
+@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
-@end itemize
+Here we have also used manual beaming (the square brackets @code{[
+]} ) to generate the beaming which is customarily used with lyrics
+(see @ref{Automatic and manual beams}).
-More specific overrides are also possible. The notation manual
-discusses in depth how to figure out these statements for yourself, in
-@ref{Tuning output}.
+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:
-@node Organizing larger pieces
-@section Organizing larger pieces
+@lilypond[verbatim,quote,ragged-right]
+<<
+ \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
-When all of the elements discussed earlier are combined to produce
-larger files, the @code{\score} blocks get a lot bigger, because the
-music expressions are longer, and, in the case of polyphonic and/or
-orchestral pieces, more deeply nested. Such large expressions can
-become unwieldy.
-
-By using variables, also known as identifiers, it is possible to break
-up complex music expressions. An identifier is assigned as follows:
-@c
-@example
- namedMusic = \notes @{ @dots{}
-@end example
+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.
-The contents of the music expression @code{namedMusic}, can be used
-later by preceding the name with a backslash, i.e. @code{\namedMusic}.
-In the next example, a two note motive is repeated two times by using
-variable substitution:
+@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]
+<<
+ \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
-@lilypond[singleline,verbatim]
-seufzer = \notes {
- dis'8 e'8
-}
-\score { \notes {
- \seufzer \seufzer
-} }
+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 Figaro, where
+@q{al} has to be sung on the same note as the @q{go} of
+@q{Largo} in Figaro's aria @q{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]
+<<
+ \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
-The name of an identifier should have alphabetic characters only, and
-no numbers, underscores or dashes. The assignment should be outside of
-the @code{\score} block.
-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 identifier can be used in different
-places. The following example uses the above variables:
-@example
- \score @{
- \notes @{ c4^\name @}
- \paper @{
- \aFivePaper
- linewidth = \width
- @}
- @}
-@end example
+@seealso
+
+Notation Reference: @ruser{Vocal music}.
+
+
+@node Lyrics to multiple staves
+@subsection Lyrics to multiple staves
+
+The simple approach using @code{\addlyrics} can be used for
+placing lyrics under more than one staff. Here is an
+example from Handel's Judas Maccabæus:
+
+@lilypond[verbatim,quote,ragged-right]
+<<
+ {
+ \time 6/8
+ \partial 8
+ }
+ \relative c'' {
+ \key f \major
+ 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
+ r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
+ }
+ \addlyrics {
+ Let flee -- cy flocks the hills a -- dorn,
+ }
+>>
+@end lilypond
+
+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}).
-More information on the possible uses of identifiers is in the
-technical manual, in @ref{Scheme datatypes}.
+@seealso
+Notation Reference: @ruser{Vocal music}.
-@node An orchestral part
-@section An orchestral part
-In orchestral music, all notes are printed twice: both in a part for
-the musicians, and in a full score for the conductor. Identifiers can
-be used to avoid double work: the music is entered once, and stored in
-variable. The contents of that variable is then used to generate
-both the part and the score.
+@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.
+
+@menu
+* Version number::
+* Adding titles::
+* Absolute note names::
+* Organizing pieces with variables::
+* After the tutorial::
+* How to read the manual::
+@end menu
+
+
+@node Version number
+@subsection Version number
+
+@cindex versioning
+The @code{\version} statement records the version of LilyPond that
+was used to write the file:
-It is convenient to define the notes in a special file, for example,
-suppose that the @file{horn-music.ly} contains the following part of a
-horn/bassoon duo.
@example
-hornNotes = \notes \relative c @{
- \time 2/4
- r4 f8 a cis4 f e d
-@}
+\version "2.11.23"
@end example
-Then, an individual part is made by putting the following in a file:
+@noindent
+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}, 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 @ref{Version number}.
+
@example
-\include "horn-music.lyinc"
+\version "2.11.23"
\header @{
- instrument = "Horn in F"
+ title = "Symphony"
+ composer = "Me"
+ opus = "Op. 9"
@}
-\score @{
- \notes \transpose f c' \hornNotes
-@}
-@end example
-The @code{\include} command substitutes the contents of the file at
-this position in the file, so that @code{hornNotes} is defined
-afterwards. The code @code{\transpose f c'} indicates that the
-argument, being @code{\hornNotes}, should be transposed by a fifth
-downwards: sounding @code{f} is denoted by notated @code{c'}, which
-corresponds with tuning of a normal French Horn in F. The
-transposition can be seen in the following output:
-
-@lilypond[singleline]
-\score {
- \notes \transpose f c' \notes \relative c {
- \time 2/4
- r4 f8 a cis4 f e d
-}
-}
-@end lilypond
-In ensemble pieces, one of the voices often does not play for many
-measures. This is denoted by a special rest, the multi-measure
-rest. It is entered with a capital R, and followed by a duration (1
-for a whole note, 2 for a half note, etc.) By multiplying the
-duration, longer rests can be constructed. For example, the next rest
-takes 3 measures in 2/4 time:
-@example
- R2*3
+@{
+ @dots{} music @dots{}
+@}
@end example
-When printing the part, the following @code{skipBars} property must be
-set to false, to prevent the rest from being expanded in three one bar
-rests:
-@example
- \property Score.skipBars = ##t
-@end example
-Prepending the rest and the property setting above, leads to the
-following result:
-
-@lilypond[singleline]
-\score {\notes { \transpose f c' \relative c { \time 2/4
-\property Score.skipBars = ##t
- R2*3
- r4 f8 a cis4 f e d } }}
-@end lilypond
+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}.
-The score is made by combining all of the music in a @code{\score}
-block, assuming that the other voice is in @code{bassoonNotes}, in the
-file @file{bassoon-music.ly}:
-@example
-\include "bassoon-music.lyinc"
-\include "horn-music.lyinc"
-
-\score @{
- \simultaneous @{
- \new Staff \hornNotes
- \new Staff \bassoonNotes
- @} @}
-@end example
-This would lead to the simple score depicted below:
+@node Absolute note names
+@subsection Absolute note names
-@lilypond[singleline]
-\score {
- \notes \relative c \simultaneous {
- \new Staff { \time 2/4
- R2*3
- r4 f8 a cis4 f e d }
- \new Staff { \clef bass
- r4 d,8 f | gis4 c | b bes |
- a8 e f4 | g d | gis f }
- } }
-@end lilypond
+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.
-More in-depth information on preparing parts and scores is in the
-notation manual, in @ref{Orchestral music}.
+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.
+@lilypond[verbatim,quote,ragged-right]
+{
+ \clef bass
+ c' b g, g,
+ g, f, f c'
+}
+@end lilypond
-@node Integrating text and music
-@section Integrating text and music
+Here is a four-octave scale:
-@cindex La@TeX{}, music in
-@cindex HTML, music in
-@cindex Texinfo, music in
+@lilypond[verbatim,quote,ragged-right]
+{
+ \clef bass
+ c, d, e, f,
+ g, a, b, c
+ d e f g
+ a b c' d'
+ \clef treble
+ e' f' g' a'
+ b' c'' d'' e''
+ f'' g'' a'' b''
+ c'''1
+}
+@end lilypond
-Sometimes you might want to use music examples in a text that you are
-writing (for example, a musicological treatise, a songbook, or (like us)
-the LilyPond manual). You can make such texts by hand, simply by
-importing a PostScript figure into your word processor. However,
-there is an automated procedure to reduce the amount of work.
+As you can see, writing a melody in the treble clef involves a lot
+of quote @code{'} marks. Consider this fragment from Mozart:
-If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
-code. A script called @code{lilypond-book} will extract the music
-fragments, run LilyPond on them, and put back the resulting notation.
-This program is fully described in @ref{lilypond-book manual}. Here
-we show a small example; since the example contains also explanatory
-text, we will not comment it further:
+@lilypond[verbatim,quote,ragged-right]
+{
+ \key a \major
+ \time 6/8
+ cis''8. d''16 cis''8 e''4 e''8
+ b'8. cis''16 b'8 d''4 d''8
+}
+@end lilypond
-@example
-\documentclass[a4paper]@{article@}
-\begin@{document@}
+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:
-In a lilypond-book document, you can freely mix music and text. For
-example:
-\begin@{lilypond@}
- \score @{ \notes \relative c' @{
- c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
- @} @}
-\end@{lilypond@}
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+ \key a \major
+ \time 6/8
+ cis8. d16 cis8 e4 e8
+ b8. cis16 b8 d4 d8
+}
+@end lilypond
-If you have no \verb+\score+ block in the fragment,
-\texttt@{lilypond-book@} will supply one:
+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.
-\begin@{lilypond@}
- c'4
-\end@{lilypond@}
+However, absolute mode is useful for music which has large
+intervals, and is extremely useful for computer-generated LilyPond
+files.
-In the example you see here, two things happened: a
-\verb+\score+ block was added, and the line width was set to natural
-length. You can specify options by putting them in brackets:
-\begin[26pt,verbatim]@{lilypond@}
- c'4 f16
-\end@{lilypond@}
+@node Organizing pieces with variables
+@subsection Organizing pieces with variables
-If you want to include large examples into the text, it is more
-convenient to put it in a separate file:
+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}.
-\lilypondfile@{screech-boink.ly@}
+With variables (also known as identifiers or macros), we can break
+up complex music expressions. A variable is assigned as
+follows:
-\end@{document@}
+@example
+namedMusic = @{ @dots{} @}
@end example
-Under Unix, you can view the results as follows:
+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 a 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
-$ cd input/tutorial
-$ mkdir -p out/
-$ lilypond-book --outdir=out/ lilbook.tex
-lilypond-book (GNU LilyPond) 1.7.23
-Reading `input/tutorial/lilbook.tex'
-Reading `input/screech-boink6.ly'
-@var{lots of stuff deleted}
-Writing `out/lilbook.latex'
-$ cd out
-$ latex lilbook.latex
-@var{lots of stuff deleted}
-$ xdvi lilbook
+width = 4.5\cm
+name = "Wendy"
+aFivePaper = \paper @{ paperheight = 21.0 \cm @}
@end example
-To convert the file into a nice PDF document, run the following
-commands:
+Depending on its contents, the variable can be used in different
+places. The following example uses the above variables:
+
@example
-$ dvips -Ppdf -u +lilypond lilbook
-$ ps2pdf lilbook.ps
+\paper @{
+ \aFivePaper
+ line-width = \width
+@}
+@{ c4^\name @}
@end example
-Running lilypond-book and running latex creates a lot of temporary
-files, and you would not want those to clutter up your working
-directory. The @code{outdir} option to lilypond-book creates the
-temporary files in a separate subdirectory @file{out}.
+@node After the tutorial
+@subsection After the tutorial
-The result looks more or less like this:
+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
+@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}.
-@separate
+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 a lilypond-book document, you can freely mix music and text. For
-example:
-@lilypond
-\score {
- \notes \relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
- }
- \paper {
- raggedright = ##t
- }
-}
-@end lilypond
-If you have no @code{\score} block in the fragment,
-@code{lilypond-book} will supply one:
+@node How to read the manual
+@subsection How to read the manual
-@lilypond
- c'4
-@end lilypond
+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 example you see here, two things happened: a
-@code{score} block was added, and the line width was set to natural
-length. You can specify options by putting them in brackets:
+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{@{ @}}.
-@lilypond[26pt,verbatim]
- c'4 f16
-@end lilypond
+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.
-If you want to include large examples into the text, it is more
-convenient to put it in a separate file:
+For information about the structure of the rest of the manual, see
+@ref{About this manual}.
-@lilypondfile{screech-boink.ly}