LilyPond is a program to print sheet music. If you have used notation
programs before, then the way to use this program might be surprising
-at first sight. To print music with lilypond, you have to enter
-musical codes in a file. Then you run LilyPond on the file, and the
-music is produced without any further intervention. For example,
-something like this:
+at first sight: in order to print music you have to enter musical
+codes in a file. Then you run the program on the file, and the music
+is produced without any further intervention. For example, something
+like this:
@lilypond[fragment,verbatim, relative 1, intertext="produces this
easier than it seems. Entering music can be done quickly, and you
never have to remember how you made the program do something
complicated: it is all in the input code, and you only have to read
-the file to see how it works. Moreover, when you use LilyPond, you are
-rewarded with very nicely looking output.
+the file to see how it works. Moreover, you are rewarded with very
+nicely looking output.
In this chapter, we will explain the reasoning behind this unusual
design, and how this approach affects you as a user.
When we started developing LilyPond, we were still studying at the
university. We were interested in music notation, not as publishers
-or musicians, but as students and scientists. We wanted to figure to
-what extent formatting sheet music could be automated. Back then GUIs
-were not as ubiquitous as they are today, and we were immersed in the
-UNIX operating system, where it is very common to use compilers to
-achieve computing tasks, so our computerized music engraving
+or musicians, but as programmers and scientists. We wanted to figure
+to what extent formatting sheet music could be automated. Back then
+GUIs were not as ubiquitous as they are today, and we were immersed in
+the UNIX operating system, where it is very common to use compilers to
+achieve computing tasks. So, our computerized music engraving
experiment took on the form of a compiler.
@cindex blackness
@cindex balance
-The figure above shows a few notable glyphs. For example, the
-half-notehead is not elliptic but slightly diamond shaped. The
+
+The figure above shows a few notable glyphs. For example, the
vertical stem of a flat symbol should be slightly brushed,
-i.e. becoming wider at the top. Fine endings, such as the one on the
-bottom of the quarter rest, should not end in sharp points, but rather
-in rounded shapes. Taken together, the blackness of the font must be
+i.e. becoming wider at the top. the half-notehead is not elliptic but
+slightly diamond shaped. Fine endings, such as the one on the bottom
+of the quarter rest, should not end in sharp points, but rather in
+rounded shapes. Taken together, the blackness of the font must be
carefully tuned together with the thickness of lines, beams and slurs
to give a strong yet balanced overall impression.
big gaps with white space. The distances between notes should reflect
the durations between notes, but adhering with mathematical precision
to the duration will lead to a poor result. Shown here is an example
-of a motive, printed twice. It is printed using both exact,
+of a motive, printed twice. It is printed using both exact
mathematical spacing, and with some corrections. Can you spot which is
which?
played in a constant rhythm. The spacing should reflect
that. Unfortunately, the eye deceives us a little: the eye not only
notices the distance between note heads, but also between consecutive
-stems. The notes of a up-stem/down-stem combination should be put
-farther apart, and the notes of a down-up combination should be put
-closer together, all depending on the combined vertical positions of
-the notes. The first two measures are printed with this correction,
-the last two measures without. The notes in the last two measures form
-downstem/upstems clumps of notes.
+stems. As a result, the notes of a up-stem/down-stem combination
+should be put farther apart, and the notes of a down-up combination
+should be put closer together, all depending on the combined vertical
+positions of the notes. The first two measures are printed with this
+correction, the last two measures without. The notes in the last two
+measures form downstem/upstems clumps of notes.
We hope that these examples show that music typography is a subtle
business, and that it requires skill and knowledge to produce good
@section About this manual
The manual is divided into the following chapters
-@table @strong
-@item Tutorial
- Gives a gentle introduction into typesetting music.
- Start here if you have never used lilypond before.
-@item Reference manual
- Here, each aspect of typesetting music is discussed.
-@item Internals
- This chapter discusses how it works from the inside, and how you can
- extend the program.
-@item Invoking
- This chapter explains how to runn LilyPond and its helper programs.
-@end table
-
-Once you are experienced with, you can simply use the manual as
-reference: there is an extensive index@footnote{If you are looking for
-something, and you cannot find it by using the index, that is
-considered a bug. In that case, please file a bug report}, but the
-document is also available in
-@ifhtml
-One Big Page,
-@end ifhtml
+@itemize @bullet
+@item The @emph{tutorial}
+(@ref{Tutorial}) gives a gentle introduction into typesetting music.
+First time users should start here.
+@item The @emph{notation manual} (@ref{Notation manual}),
+is a user manual that discusses topics grouped by notation construct.
+@item The @emph{technical manual} (@ref{Advanced topics})
+discusses the general design of the program, and how to extend the
+functionality.
+@item The chapter
+on @emph{Invoking} (@ref{Invoking LilyPond}) explains how to run LilyPond and its helper
+programs.
+@end itemize
+
+Once you are experienced, you can simply use the manual as reference:
+there is an extensive index@footnote{If you are looking for something,
+and you cannot find it by using the index, that is considered a bug.
+In that case, please file a bug report}, but the document is also
+available in
@ifnothtml
-@uref{../lilypond.html,One Big Page}
+One Big Page,
@end ifnothtml
+@ifhtml
+@uref{One Big Page,../lilypond.html}
+@end ifhtml
which is is available for text search using your browser's search
facility.
@cindex search in manual
Almost all formatting functionality that is used internally, is
available directly to the user. For example, all variables that
-control thicknesses, distances, etc, can be changed from input
+control thicknesses, distances, etc, can be changed in input
files. There are a huge number of formatting options, and it would be
impossible to describe them all in a hand-written manual. The
generated internal documentation is a heavily crosslinked HTML
document, produced directly from the formatting definitions used. It
-the nit-gritty details of each and every LilyPond class, object and
+documents the nit-gritty details of each and every LilyPond class, object and
function.
Each section of the reference manual has a @b{See also}
@item
Templates
@ifhtml
-available @uref{../../../input/templates/out-www/collated-files.html,here}
+(available @uref{../../../input/templates/out-www/collated-files.html,here})
@end ifhtml
When you have gone through the tutorial, you theoretically should be
able to start writing input files. However, this turns out to be a
little intimidating. To give you a headstart, we have collected a
-number of often-used formats in example files. You can take one of
+number of often-used formats in example files. You can take one of
these example files, and add notes in the appropriate places to
generate output.
available @uref{../../../input/regression/out-www/collated-files.html,here}
@end ifhtml
-We strive to test each feature in a collection of input snippets. This
-is primarily to help us debug the program, but it can be instructive
-to see how we excercise the program. The format is like the input
-examples.
+We strive to test each feature in one test file. This collection of is
+primarily to help us debug problems, but it can be instructive to see
+how we excercise the program. The format is like the input examples.
@end itemize
+The location of the documentation files that are mentioned here can
+vary from system to system. Throughout this manual, we refer to input
+files relative to the top-directory of the source archive. For
+example, @file{input/test/bla.ly} may refer to the file
+@file{lilypond-1.7.19/input/test/bla.ly}. On binary packages for the
+Unix platform, these can typically be found somewhere below
+@file{/usr/share/doc/lilypond/}.
+
@cindex adjusting output
@cindex variables
@cindex properties
* Integrating text and music:: Integrating text and music
@end menu
-Operating lilypond is done through text files: To print a piece of
-music, you enter the music in a file. When you run lilypond (normally
-using the program @code{ly2dvi}) on that file, the program produces
-another file which contains sheet music that you can print or view.
+Operating is done through text files: To print a piece of music, you
+enter the music in a file. When LilyPond is run (normally using the
+program @code{ly2dvi}) on that file, another file containing formatted
+sheet music, is produced. That file may be printed or viewed.
This tutorial starts with a small introduction to the LilyPond music
-language. After this first contact, we will show you how to run
-LilyPond to produce printed output; you should then be able to create
+language. After this first contact, we will show which commands to
+run to produce printed output, so you should then be able to create
your first sheets of music. The tutorial continues with more and more
complex examples.
@end lilypond
A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
-@rglos{flat} (@texiflat{}) by adding @samp{es}. As you would expect,
+@rglos{flat} (@texiflat{}) 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}:
+@samp{isis} or @samp{eses}:@footnote{This syntax derived from note
+naming conventions in Nordic and Germanic languages, like German and
+Dutch}
@example
cis1 ees fisis aeses
\transpose c c' { a2. a4 a8. a16 s16_" " }
@end lilypond
+Entering pitches and durations is fully explained in @ref{Pitches} and
+@ref{Durations}.
+
+
The @rglos{meter} (or @rglos{time signature}) can be set with the
@code{\time} command:
s16_" "
@end lilypond
+Time signatures and other timing commands are described in @ref{Time
+signature}.
+
+
The @rglos{clef} can be set using the @code{\clef} command:
@c what is more common name treble or violin?
s16_" "
@end lilypond
+Clefs are fully explained in @ref{Clef}.
+
+
When you enter these commands in a file, you must to enclose them in
@code{\notes @{@dots{}@}}. This lets LilyPond know that music (as
opposed to @rglos{lyrics}) follows:
The printing command is the so-called @code{\paper} block. Later on
you will see that the @code{\paper} block is used to customize
printing specifics. The music and the @code{\paper} block are combined by
-enclosing them in @code{\score @{ ... @}}. This is what a full
-LilyPond source file looks like:
+enclosing them in @code{\score @{ ... @}}. This is what a full source file looks like:
@example
\score @{
@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 how to run LilyPond
+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 of LilyPond, or want to run an example
-file yourself, read this section. The instructions that follow
-are for running LilyPond on Unix-like systems. Some additional
-instructions for running LilyPond on Windows are given at the end of
-this section.
+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 MS 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}. In your
LilyPond is the program that computes the sheet music. All other
things, such as adding titles, page breaking and other page layout,
are done by a small wrapper program called
-@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
+@code{ly2dvi}. @code{ly2dvi} calls LilyPond to render the music, and
then adds the titling and page layout instructions. To process
@file{test.ly} with @code{ly2dvi}, proceed as follows:
ghostview test.pdf
ggv test.pdf
kghostview test.pdf
+ xpdf test.pdf
+ gpdf test.pdf
@end example
@end quotation
If the music on your screen looks good, you can print it by clicking
The DVI file (@file{test.dvi}) contains the same sheet music in a
different format. DVI files are more easily processed by the computer,
-so viewing them usually is quicker. You can run @code{xdvi test.dvi} or
-@code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse burtons
+so viewing them usually is quicker. You can run @code{xdvi test.dvi}
+@c KDVI doesn't grok the PS specials.
+@c or
+@c @code{kdvi test.dvi}
+@c
+to view the DVI file. In Xdvi, the mouse buttons
activate magnifying glasses. Unfortunately, variable symbols (such as
beams and slurs) are not displayed in the magnifying glasses.
@cindex PDF
If you are familiar with @TeX{}, be warned: do not use other DVI
-drivers like @code{dvilj}. The @TeX{} coming out of LilyPond uses
-embedded PostScript code and will not render correctly if you use
-anything other than @code{dvips}.
+drivers like @code{dvilj}. LilyPond DVI use embedded PostScript code
+and will not render correctly with other DVI drivers besides
+@code{dvips}.
@cindex dvips
@cindex dvilj
@cindex DVI driver
+
+Various commands for formatting and printing music are detailed in
+@ref{Invoking LilyPond}.
+
+
@unnumberedsubsec Windows users
+
Windows users can start the terminal by clicking on the LilyPond or
-Cygwin icon. You can use any text editor (such as NotePad, Emacs or
-Vim) to edit the LilyPond file. If you install the Cygwin's
-@code{XFree86} X11 window system, @code{tetex-x11} and
-@code{ghostscript-x11} packages too, you can view the @code{dvi}
-output doing @code{xdvi test.dvi} as described above. If you have
+Cygwin icon. Any text editor (such as NotePad, Emacs or Vim) may be
+used to edit the LilyPond file. When Cygwin's @code{XFree86} X11
+window system is installed along with @code{tetex-x11} and
+@code{ghostscript-x11} packages, then the @code{dvi} output may be
+viewed with @code{xdvi test.dvi} as described above. If you have
installed a PostScript/PDF viewer, such as @code{GSView} from
@uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
with:
@code{gsview32 test.pdf}
@end example
@end quotation
-You can also print from the command line by executing:
+Printing may be done by executing
@quotation
@example
@code{gsview32 /s test.pdf}
@end quotation
-@strong{SUMMARY}
-
-To run LilyPond, input a text file, then run the command @code{ly2dvi} on
-that file. The resulting files are either DVI or PostScript, and can
-be viewed with @code{xdvi} (Unix) and ghostview (Unix and Windows)
-respectively. The following table summarizes the constructs that were
-discussed in the previous two sections.
-
-@multitable @columnfractions .3 .3 .4
-
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
-
-@item @code{1 2 8 16}
-@tab durations
-@tab
-@lilypond[relative 1, notime]
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c1 c2 c8 c16
-@end lilypond
-
-@item @code{. ..}
-@tab augmentation dots
-@tab
-@lilypond[relative 1, notime]
-\property Staff.Clef = \turnOff
-c4. c4..
-@end lilypond
-
-@item @code{c d e f g a b }
-@tab scale
-@tab
-@lilypond[relative 1, notime]
-\property Staff.Clef = \turnOff
-c d e f g a b
-@end lilypond
-
-@item @code{\clef treble \clef bass }
-@tab clefs
-@tab
-@lilypond[notime]
-\clef treble
-s4_" "
-\clef bass
-s4_" "
-@end lilypond
-
-@item @code{\time 3/4 \time 4/4 }
-@tab time signature
-@tab
-@lilypond
-\property Staff.Clef \set #'transparent = ##t
-\time 3/4
-s4_" "
-\time 4/4
-s16_" "
-@end lilypond
-
-@end multitable
-
-
@node More basics
@section More basics
-We continue with the introduction of the remaining musical constructs.
-Normal rests are entered just like notes with the name ``@code{r}'':
+We continue with the introduction of more musical constructs. Normal
+rests are entered just like notes with the name ``@code{r}'':
@quotation
@example
@end quotation
@separate
+Rests are described in full detail in @ref{Rests}.
+
+
@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...
c2-~-( c8 fis fis4 ~ fis2 g2-)
@end lilypond
+The notation manual discusses ties in @ref{Ties}.
-The key signature is set with the command ``@code{\key}''. One
-caution word of caution: you need to specify whether the key is
-@code{\major} or @code{\minor}.
+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
@end quotation
+
@c bit on the long/complex/scary taste
@c cheating a bit: two lines makes for a friendlier look
This example shows notes, ties, octave marks, and rests in action.
@c accidentals...
There are some interesting points to note in this example.
-Accidentals (sharps and flats) do not have to be marked explicitly: you
-just enter the note name, and LilyPond determines whether or not to
-print an accidental. Bar lines and beams are drawn automatically.
-LilyPond calculates line breaks for you; it does not matter where you
-make new lines in the source file. Finally, the order of time, key and
-clef changes is not relevant: lilypond will use standard notation
-conventions for ordering these items.
+Accidentals (sharps and flats) do not have to be marked explicitly:
+you just enter the note name, and an accidental is printed
+automatically, only when necessary. 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 using standard notation conventions.
The example also indicates that a piece of music written in a high
register needs lots of quotes. This makes the input less readable,
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 (ie do not add ' or , after a note), relative mode
-chooses the note that is closest to the previous one. Since most music
-has small intervals, you can write quite a lot in relative mode without
-using octavation quotes.
+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.
@c do not use commas or quotes in this sentence
For example: @code{c f} goes up; @code{c g} goes down:
@separate
+Since most music has small intervals, in relative mode pieces can be
+written almost without using octavation quotes.
+
@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.
-You can make larger intervals by adding octavation quotes. Note that
-quotes or commas do not determine the absolute height of a note;
-the height of a note is relative to the previous one.
+Larger intervals are made by adding octavation quotes. 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:
@separate
-Here's an example of the difference between relative mode and
+Here is an example of the difference between relative mode and
``normal'' (non-relative) mode:
@quotation
@end quotation
@separate
-@strong{SUMMARY}
-
-The following table summarizes the syntax in this section.
-
-@c Is it possible to avoid page breaks directly after the
-@c table head? /Mats
-
-@multitable @columnfractions .3 .3 .4
-
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
-
-@item @code{r4 r8}
-@tab rest
-@tab
-@lilypond[relative 1, notime]
-\property Staff.Clef = \turnOff
-r4 r8
-@end lilypond
-
-@item @code{~}
-@tab tie
-@tab
-@lilypond[relative 1, notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-d ~ d
-@end lilypond
-
-@item @code{\key es \major }
-@tab key signature
-@tab
-@lilypond[notime]
-\clef treble
-\key es \major
-s4
-@end lilypond
-
-@item @var{note}@code{'}
-@tab raise octave
-@tab
-@lilypond[relative 1, notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a a'
-@end lilypond
-
-@item @var{note}@code{,}
-@tab lower octave
-@tab
-@lilypond[relative 1, notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c c,
-@end lilypond
-
-@end multitable
-
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:
In this example, @code{staffA} and @code{staffB} are names that are
given to the staves. It does not matter what names you give, as long
as each staff has a different name. If you give them the same name,
-LilyPond will assume that you only want one staff, and will but both
-pieces of music on the same staff.
-
+they are assumed to belong on the same staff, and will be printed like
+that.
@separate
@end quotation
@separate
-Chords can be made by surrounding notes with @code{<<} and @code{>>}:
+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
@end lilypond
@end quotation
-@ignore
-When you want to combine chords with slurs and dynamics, technical
-detail crops up: you have type these commands next to the notes, which
-means that they have to be inside the @code{< >}. Do Not get confused
-by the chord @code{< >} and the dynamic @code{\< \>}!
-@end ignore
-
@quotation
@example
-r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\)
+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-\!-\)
+r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
@end lilypond
@end quotation
@separate
-@strong{SUMMARY}
-
-@multitable @columnfractions .3 .3 .4
-
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
-
-
-@item @code{( )}
-@tab slur
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c-( d e-)
-@end lilypond
-
-
-@item @code{\( \)}
-@tab phrasing slur
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c-\( c-( d-) e-\)
-@end lilypond
-
-
-@item @code{[ ]}
-@tab beam
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a8-[ b-]
-@end lilypond
-
-
-@item @code{< \context Staff ... >}
-@tab more staffs
-@tab
-@lilypond[fragment]
-< \context Staff = SA { c'1 }
- \context Staff = SB { c'1 } >
-@end lilypond
-
-
-@item @code{-> -.}
-@tab articulations
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-c-> c-.
-@end lilypond
-
-
-@item @code{-\mf -\sfz}
-@tab dynamics
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-c-\mf c-\sfz
-@end lilypond
-
-
-@item @code{\< \!}
-@tab crescendo
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a\< a \!a
-@end lilypond
-
-@item @code{\> \!}
-@tab decrescendo
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a-\> a a-\!
-@end lilypond
-
-
-@item @code{<< >>}
-@tab chord
-@tab
-@lilypond[fragment, relative 1]
-<<c e>>
-@end lilypond
-
-@end multitable
+TODO: triplets, partial
Now you know the basic ingredients of a music file, so this is the
right moment to experiment and try your at hand typing some simple
@section Printing lyrics
@cindex lyrics
-In this section we shall explain how to typeset the following
-fragment of The Free Software Song:
-
-@lilypond[singleline]
-\score { \notes { \addlyrics
- \notes \relative c' {
- \time 7/4
- d'2 c4 b16-( a g a b a b c-) a2
- b2 c4 b8-( a16 g a4-) g2 }
- \context Lyrics \lyrics {
- Join us now __ and
- share the soft -- ware; }
-}
-\paper { raggedright = ##t }
-}
-@end lilypond
-
-
-@cindex lyric mode
-@cindex @code{\lyrics}
-
-
-Lyrics are a form of music. To get them printed, you must do two
-things: indicate that lyrics are entered with @code{\lyrics}, and
-indicate that this type of music must be interpreted as texts (and not
-notes). This is done with @code{\context Lyrics}.
-
-You can enter lyrics in a special input mode of LilyPond. This mode is
-called Lyrics mode, and it is introduced by the keyword
-@code{\lyrics}. In this mode you can enter lyrics, with punctuation
-and accents without any hassle. Syllables are entered like notes, but
-with pitches replaced by text. For example,
+Lyrics are entered by separating each syllable with a space, and
+surrounding them with @code{\lyrics @{ @dots{} @}}, for example
@example
- Twin- kle twin- kle
-@end example
-enters four syllables. Spaces can be introduced into a lyric either
-by using quotes: @code{"He could" not} or by using an underscore
-without quotes: @code{He_could not}.
-
-These are the lyrics for the free software song:
-
-@example
- \lyrics @{
- Join us now __ and
- share the soft -- ware; @}
+ \lyrics @{ I want to break free @}
@end example
- Extender lines are entered as @code{__}. This will create an
-extender, which is a line that extends over the entire duration of the
-lyric. This line will run all the way to the start of the next lyric,
-so you may want to shorten it by using a blank lyric (using @code{_}).
-
-
-You can use ordinary hyphens at the end of a syllable, i.e.
+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{ \context Lyrics}:
@example
- soft- ware
+ \context Lyrics \lyrics @{ I want to break free @}
@end example
-but then the hyphen will be attached to the end of the first syllable.
-
-If you want them centered between syllables you can use the special
-`@code{-}@code{-}' lyric as a separate word between syllables. The
-hyphen will have variable length depending on the space between
-the syllables and it will be centered between the syllables.
-
-Normally the notes that you enter are transformed into note heads.
-Note heads alone make no sense. They need surrounding information: a
-key signature, a clef, staff lines, etc. They need @emph{context}.
-In LilyPond, these symbols are created by objects called
-`interpretation contexts'. Interpretation contexts exist for
-generating notation (`notation context') and for generating sound
-(`performance context'). These objects only exist while LilyPond is
-executing. For lyrics, the command
+The melody for this song is as follows
+@lilypond[fragment,relative=1]
+ \partial 8
+ c8
+ \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
+@end lilypond
+
+The lyrics can be set to these notes, combining both with the
+@code{\addlyrics} keyword:
@example
- \context Lyrics
+ \addlyrics
+ \notes @{ @dots{} @}
+ \context Lyrics @dots{}
@end example
-must be used to interpret a set of syllables as lyrics.
-
-
-@cindex context
-@cindex interpretation context
-@cindex notation context
-
+The final result is
+@lilypond[singleline,verbatim]
+\score {
+ \notes {
+ \addlyrics
+ \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{ }
+}
+@end lilypond
-The melody and the lyrics can be combined with the @code{\addlyrics}:
+This melody ends on a @rglos{melisma}, a single syllable (``free'')
+sung to more than one note. This is indicated with a @emph{extender
+line}. It is entered as two underscores, i.e.,
@example
-\addlyrics
- \notes \relative c' @dots{}
- \context Lyrics \lyrics @dots{}
-@end example
-
-The lyrics are also music expressions, similar to notes. Each lyric
-syllable is put under a note of the melody. The complete file is
-listed here:
+ \lyrics @{ I want to break free __ @}
+@end example
+@lilypond[singleline]
+\score {
+ \notes {
+ \addlyrics
+ \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{ }
+}
+@end lilypond
+Similarly, hyphens between words can be entered as two dashes,
+resulting in a centered hyphen between two syllables.
@example
-\score @{ \notes @{ \addlyrics
- \notes \relative c' @{
- \time 7/4
- d'2 c4 b16 ( a g a b a b ) c a2
- b2 c4 b8 ( a16 g ) a4 g2 @}
- \context Lyrics \lyrics @{
- Join us now __ and
- share the soft -- ware; @}
-@}
-\paper @{ raggedright = ##t @}
-@}
+ Twin -- kle twin -- kle
@end example
-
+@lilypond[singleline]
+\score {
+ \addlyrics \notes \relative f' { \time 2/4
+ f4 f c' c' }
+ \lyrics { Twin -- kle twin -- kle
+ }}
+@end lilypond
@node A melody with chords
@section A melody with chords
-In this section we show how to typeset a melody with chord
-accompaniment. This file is included in
-@inputfileref{input/tutorial,flowing.ly}.
-
-@lilypondfile[verbatim,intertext="the result looks like"]{flowing.ly}
-
-@separate
-@example
-
- \include "paper16.ly"
-
-@end example
-Smaller size (suitable for inclusion in a book).
-@separate
-@example
-
- melody = \notes \relative c' @{
-
-@end example
-The structure of the file will be the same as the previous one: a
-@code{\score} block with music in it. To keep things readable, we will
-give different names to the different parts of music, and use the names
-to construct the music within the score block.
+@ignore
@separate
@example
@}
@end example
-Finally, we put the melody on the current staff. Note that the
+Finally, we put the melody on the current staff. The
@code{\property} directives and @code{\melody} are grouped in sequential
music, so the property settings are done before the melody is
processed.
We also want notation output. The linewidth is short so that the piece
will be set in two lines.
+@end ignore
+
+
@node More stanzas
@section More stanzas
We add the names of the singers. This can be done by setting
@code{LyricsVoice.Stanza} (for the first system) and
-@code{LyricsVoice.stz} for the following systems. Note that you must
+@code{LyricsVoice.stz} for the following systems. You must
surround dots with spaces in @code{\lyrics} mode.
@example
@end example
Lilypond and its language are still under development, and
occasionally details of the syntax are changed. The @code{version}
-fragment indicates which version of lilypond the input file was written
+fragment indicates which version of LilyPond the input file was written
for. When you compile this file, the version number will be checked
and you will get a warning when the file is too old. This version
number is also used by the @code{convert-ly} program (See
internals document. This is a set of HTML pages which should be
included if you installed a binary distribution. [TODO: revise for
new site.] These HTML pages are also available on the web: go to the
-lilypond website, click ``Documentation: Index'' on the side bar, look
+LilyPond website, click ``Documentation: Index'' on the side bar, look
in the ``Information for uses'' section, and click on ``Documentation
of internals''.
@c TODO: the quote is incorrect, although that shouldn't be a big
@c problem for the reader.
Suppose that you wanted to tune the behavior of the slur. The first
-step is to get some general information on slurs in lilypond. Turn to
+step is to get some general information on slurs in LilyPond. Turn to
the index, and look up ``slur''. The section on slurs says
@quotation
The grob for this object is @internalsref{Slur}, generally in
@separate
-Here's the complete ``fine tuned'' version, which includes all the
+Here is the complete ``fine tuned'' version, which includes all the
modifications we discussed in this section:
@lilypondfile[verbatim]{brahms-tweaked.ly}
\context Staff = flauti <
@end example
A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
-hold one or more @code{Staff}'s, and will print a big bracket at the
+hold one or more @code{Staff}s, and will print a big bracket at the
left of the score. This starts a new staff group for the woodwind
section (just the flutes in this case). Immediately after that, we
start the staff for the two flutes, who also play simultaneously.
\context Thread=one \tromboI
\context Thread=two \tromboII
@end example
-You have seen the notation contexts Staff and Voice, but here's a new
+You have seen the notation contexts Staff and Voice, but here is a new
one: Thread. One or more Threads can be part of a Voice. Thread
takes care of note heads and rests; Voice combine note heads onto a
stem.
The french horn (``Corno'') has the most complex scheme markup name, made
up of two lines of text. The second line has three elements (columns) --
the @code{(E}, the flat sign @code{text-flat} that we defined previously,
-and a final @code{")"}. Note that we use a backquote instead of an
+and a final @code{")"}. We use a backquote instead of an
ordinary quote at the beginning of the Scheme expression to be able to
access the @code{text-flat} identifier, `unquoting' it with a ``@code{,}''.
@separate
-Usually LilyPond's default setup of notation contexts (Thread,
-Voice, Staff, Staffgroup, Score) is just fine. But in this case we
-want a different type of Staff context.
+Usually the default setup of notation contexts (Thread, Voice, Staff,
+Staffgroup, Score) is just fine. But in this case we want a different
+type of Staff context.
@example
\translator@{
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
-also contains explanatory text, we will not comment it further.
+This program is fully described in @ref{lilypond-book manual}. Here
+we show a small example. Since the example also contains explanatory
+text, we will not comment it further.
@example
\documentclass[a4paper]@{article@}