@c TODO: LilyPond LilyPond LilyPond
-
@node Tutorial
@chapter Tutorial
-
+
+@html
+<!--- @@WEB-TITLE@@=Tutorial --->
+@end html
+
@menu
* First steps:: Music language of LilyPond
-* Simple legend:: Small table of music language symbols
+* Cheat sheet::
* Running LilyPond:: Printing music
* The first real tune:: The first real tune
* Lyrics and chords:: Lyrics and chords
* More movements :: Joining separate pieces of music
* A piano excerpt:: Piano music
+* Fine tuning a piece::
* An orchestral score:: Conductor's score and individual parts
* Other ways to run LilyPond:: Other ways to run LilyPond
* Integrating text and music:: Integrating text and music
* End of tutorial:: The end
@end menu
-
-The music is described in a text file, using a simple music language.
-LilyPond reads that text file and generates music that you can print or
-view.
-
-Therefore, creating music notation with LilyPond is done in two steps.
-Using a text editor, you write down the notes to print. Then, you run
-LilyPond to get your printed output.
+Operating lilypond is done through text files: to print a piece of
+music, you enter the music in a file. When you run lilypond, that
+file is read, and after some computations, the program produces a file
+containing the sheet music that you can print or view.
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
-your first sheets of music.
-
-The tutorial continues with a slightly more elaborate example of real music.
-This piece introduces and explains some finer details of LilyPond.
-Then, a number of more complex examples follow, that will help you to
-produce most complex music with LilyPond.
+your first sheets of music. The tutorial continues with more and more
+complex examples.
@c title?
@c @node Music language of LilyPond
@c @section Music language of LilyPond
-This section shows how easy writing music with LilyPond actually is. If
-you have not seen LilyPond input source before, this section is for you.
-
-The next section has a table (see @ref{Simple legend}) of all symbols
-that are introduced here, you may want to keep an eye on that.
-
-Writing music with LilyPond is explained below by a number of small
-examples. Each example has a small piece of text; the LilyPond input
-that you should type, with the resulting music printed below it.
+In this section, we show how to make small, very simple pieces of
+music in LilyPond. If you have not seen LilyPond input files before,
+this section is for you. The contents of this section are summarized
+in the Cheat Sheet (See @ref{Cheat sheet}).
You get a simple note by typing its note name, from @code{a} through
-@code{g}:
-
+@code{g}. So if you enter
@quotation
@example
c d e f g a b
@end example
-
+@end quotation
+then the result looks like this:
+@quotation
@lilypond[fragment]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
@end quotation
@separate
+We continue showing LilyPond input like we did previously: first a
+snippet of input, then the resulting output.
+
The length of a note is specified by adding a number, ``@code{1}'' for a
whole note, ``@code{2}'' for a half note, and so on:
@lilypond[fragment]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
%\property Staff.Clef = \turnOff
\transpose c'' { a1 a2 a4 a16 a32 }
s16_" "
@end quotation
@separate
-If you don't specify a duration, the previous duration is used:
-
+If you don't specify a duration, the previous one is used:
@quotation
@example
a a a2 a
@c as these are snippets anyway
@lilypond[fragment]
\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+\property Staff.TimeSignature \set #'transparent = ##t
%\property Staff.Clef = \turnOff
\transpose c'' { a2. a4 a8. a16 }
s16_" "
@end quotation
@separate
-The meter (or time signature) can be set with the ``@code{\time}'' command:
+The meter (or time signature) can be set with the @code{\time} command:
@quotation
@example
@c a clef here may lead to confusion
@lilypond[fragment]
-\property Staff.Clef = \turnOff
+\property Staff.Clef \set #'transparent = ##t
\time 3/4
s4_" "
\time 6/8
At this point, the piece of music is ready to be printed. This is done
by combining the music with a printing command.
-The printing command is the so-called ``@code{\paper}'' block. You will
-see later that the \paper block is necessary to customize all kinds of
-printing specifics. The music and the \paper block are combined by
-enclosing them in ``@code{\score @{ ... @}}''. This is what a full
-LilyPond source file looks like:
+The printing command is the so-called ``@code{\paper}'' block. You
+will see later that the \paper block is necessary to customize all
+kinds of printing specifics. The music and the \paper block are
+combined by enclosing them in ``@code{\score @{ ... @}}''. This is
+what a full LilyPond source file looks like:
@quotation
@example
@c maybe legend here?
-Rests are entered just like notes with the name ``@code{r}'':
+Normal rests are entered just like notes with the name ``@code{r}'':
@quotation
@example
doesn't matter where you make new lines in the source file.
The example also indicates that a piece of music written in a high
-register needs lots of quotes. This makes the input a bit unreadable,
+register needs lots of quotes. This makes the input less readable,
and is therefore also a potential source of errors.
@separate
@end ignore
Of course, you can combine beams and ties with chords. Notice that
-beam and tie markings are placed outside the chord markers:
+beam and tie markings must be placed outside the chord markers:
@quotation
@lilypond[relative 0, fragment,verbatim]
r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
@end lilypond
@end quotation
-When you want to combine chords with slurs and dynamics, an annoying
-technical detail crops up: you have type these commands next to the
-notes, which means that they have to be inside the @code{< >}:
+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{< >}:
@quotation
@lilypond[relative 0, fragment,verbatim]
@end quotation
@separate
-A nasty technical detail also crops up when you start a score with a
-chord:
-
+There is one golden rule that you should keep in mind when writing
+LilyPond input:
+@quotation
+@strong{DO NOT START A PIECE WITH A CHORD}
+@end quotation
+Of course, it is a allowed, but the result might not be what you expect:
@quotation
@lilypond[verbatim,singleline]
-\score { \notes <c'1 e'1> }
+\score { \notes <c'2 e'2> }
@end lilypond
@end quotation
@separate
-The program can not guess that you want the notes on only one staff. To
-force the chord on a staff, add @code{\context Staff} like this:
+Of course, it is possible to typeset pieces that start with a chord,
+but you must make explicit that the notes of chord are to be put on
+the same staff, in the same voice. This is done by specifying
+@code{\context Staff} for the notes:
@quotation
@lilypond[verbatim,singleline]
-\score { \notes \context Staff <c'1 e'1> }
+\score { \notes \context Voice <c'2 e'2> }
@end lilypond
@end quotation
@separate
@c refer to this section
-@node Simple legend
-@section Simple legend
+@node Cheat sheet
+@section Cheat sheet
@c need texinfo-4.0a or later for this
@quotation
-@multitable @columnfractions .10 .20 .40
+@multitable @columnfractions .20 .20 .40
+
+
+@item @code{1 2 8 16}
+@tab durations
+@tab
+@lilypond[fragment, relative 1]
+c1 c2 c8 c16
+@end lilypond
+
+@item @code{. ..}
+@tab augmentation dots
+@tab
+@lilypond[fragment, relative 1]
+c4. c4..
+@end lilypond
+
+@item @code{c d e f g a b }
+@tab scale
+@tab
+@lilypond[fragment, relative 1]
+c d e f g a b
+@end lilypond
+
+@item @code{es is}
+@tab flat/sharp
+@tab
+@lilypond[fragment, relative 2]
+bes4 cis4
+@end lilypond
+
+@item @code{-. -^ ->}
+@tab articulations (1)
+@tab
+@lilypond[fragment, relative 2]
+c-. c-^ c->
+@end lilypond
+
+
+@item @code{-\trill -\fermata}
+@tab articulations (2)
+@tab
+@lilypond[fragment, relative 2]
+c-\trill c-\fermata
+@end lilypond
+
+
+@item @code{\time 3/4 \time 6/8 \time 4/4 }
+@tab time signature
+@tab
+@lilypond[fragment]
+\property Staff.Clef \set #'transparent = ##t
+\time 3/4
+s4_" "
+\time 6/8
+s4_" "
+\time 4/4
+s16_" "
+@end lilypond
+
+
+@item @code{\clef treble \clef bass }
+@tab clefs
+@tab
+@lilypond[fragment]
+\property Staff.TimeSignature \set #'transparent = ##t
+\clef treble
+s4_" "
+\clef bass
+s4_" "
+@end lilypond
+
+
+@item @code{\sfz \mf }
+@tab dynamics
+@tab
+@lilypond[fragment,relative 1]
+c\sfz c\mf
+@end lilypond
@item @code{[ ]}
@tab beam
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
[a8 b]
@end lilypond
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
d ~ d
@end lilypond
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
c( d )e
@end lilypond
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
a a'
@end lilypond
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
c c,
@end lilypond
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
\context Voice { <a c> }
@end lilypond
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
a\< a \!a
@end lilypond
@lilypond[fragment, relative 1]
\property Score.timing = ##f
\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
+\property Staff.autoBeaming = ##f
\property Staff.Clef = \turnOff
a\> a \!a
@end lilypond
@node Running LilyPond
@section Running LilyPond
-You write music with LilyPond as follows: first you edit a text file
-containing a description of the notes. Then you run LilyPond on the
-file. This leaves you with an output file, which you can view or print.
-
-In this section we explain how to run LilyPond, and view or print the
-output. If you have not used LilyPond before, want to test your setup
-of LilyPond, or try to run an example file yourself, then 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.
+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,
+and how view or print the output. If you have not used LilyPond
+before, want to test your setup of LilyPond, or try to run an example
+file yourself, then 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.
You begin with opening a terminal window, and start up a text editor.
For example, open an xterm and execute @code{joe}. In your text editor,
@c now this is weird, running ly2dvi to run LilyPond
@c (therefore name change proposal)
-To run LilyPond, you invoke ly2dvi to compile your LilyPond source file:
+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
+then adds the titling and page layout instructions. To process
+@file{test.ly} with ly2dvi, proceed as follows:
@quotation
@example
@cindex PostScript
@unnumberedsubsec Windows users
-Windows users start the terminal by clicking on the LilyPond icon.
-Notepad is sufficient for editing the LilyPond file. Viewing the PS file
-can be done with @code{gsview32 test.ps}. Viewing DVI files can be done
-with @code{yap test.dvi}. The "print" button in Yap will print files.
-You can also print from the command line by executing @code{gsview32 /s
-test.ps}
+Windows users start the terminal by clicking on the LilyPond or Cygwin
+icon. Notepad is sufficient for editing the LilyPond file. Viewing
+the PS file can be done with:
+@quotation
+@example
+@code{gsview32 test.ps}
+@end example
+@end quotation
+You can also print from the command line by executing:
+@quotation
+@example
+@code{gsview32 /s test.ps}
+@end example
+@end quotation
@node The first real tune
% and is ignored by LilyPond
@end example
Percent signs introduce comments: everything after a percent sign is
-ignored. You can use this to write down mental notes to yourself. You
-can also make longer comments by enclosing text in @code{%@{} and
-@code{%@}}.
+ignored. You can use this If you want to write down mental notes to
+yourself in a file, then you can enter preceded with a @code{%} sign.
+These lines are called comments. If you have long winded mental notes,
+you can make comments that span several lines by enclosing text in
+@code{%@{} and @code{%@}}.
@cindex comment
@cindex block comment
@cindex line comment
@end example
@cindex @code{\include}
@cindex point, printer's
-@cindex staff size setting
+@cindex staff size, setting
+@cindex font size, setting
+
By default, LilyPond will typeset the music in a size such that each
staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output
(16 point staff height), so we must import the settings for that size,
@c octave higher is @code{c''}. One and two octaves below the central C is
@c denoted by @code{c} and @code{c,} respectively.
-Even though a piece of music often spans a range of several octaves, it
-mostly moves in small intervals. LilyPond has a special entry mode to
-save typing in this situation. In this ``relative'' octave mode,
-octaves of notes without quotes are chosen such that a note is as close
-as possible (graphically, on the staff) to the preceding note. If you
-add a high-quote an extra octave is added. A lowered quote (a comma)
-will subtract an extra octave.
-
-Because the first note has no predecessor,
-you have to give the (absolute) pitch of the note to start with.
+Even though a piece of music often spans a range of several octaves,
+often melodies move in small intervals. Such melodies can be entered
+easily using @code{\relative}. In this ``relative octave mode'',
+octaves of notes without quotes are chosen such that a note is as
+close as possible (graphically, on the staff) to the preceding note.
+If you add a high-quote an extra octave is added. A lowered quote (a
+comma) will subtract an extra octave.
+
+Absolute starting pitch for this relative mode is given as the
+argument to @code{\relative}. In this case it is the @code{c''}, one
+octave above central C.
+
@separate
@example
@end example
@cindex time signature, setting
@cindex @code{\time}
-Set (or change) the time signature of the current piece: a 3/4 sign is
-printed. The time signature setting is also used to generate bar lines
-at the right spots.
+The @code{\time} command sets (or changes) the time signature of the
+current piece: a 3/4 sign is printed. This setting is also used to
+generate bar lines at the right spots.
@separate
@example
indicates the type of repeat. In this case, @code{"volta"} means that
prima volta/secunda volta brackets are used for the alternative
endings---if there were any.
+
+A special notation for repeats allows you to get correct repeats in
+MIDI output. However, some extra trickery is needed to get this
+working, See @ref{Repeats and MIDI}.
@separate
@example
@end example
Two more notes, with pitch @code{a} and @code{b}. Because their
duration is the same as the @code{g,8}, there is no need to enter the
-duration, but you may enter it anyway, i.e., @code{a4 b4}
+duration, but you may enter it anyway, i.e., @code{a8 b8}
@separate
@example
c8 d e fis
@end example
-So far, no notes were chromatically altered. Here is the first one that
-is: @code{fis}. LilyPond by default uses Dutch@footnote{Note names are
-available in several languages, but we find the Dutch names quite
-convenient.} note names, and ``Fis'' is the Dutch note name for ``F
-sharp''. However, there is no sharp sign in the output. The program
-keeps track of key signatures, and will only print accidentals if they
-are needed.
+So far, no notes were chromatically altered. Here is the first one
+that is: @code{fis}. LilyPond uses Dutch note names, and ``Fis'' is
+the name for ``F sharp''. There is no sharp sign in the output. The
+program keeps track of key signatures, and will only print accidentals
+if they are needed. If you can not get used to Dutch names, then
+there also are names available in several other languages.
+
For groups of eighth notes and shorter, LilyPond can determine how the
notes should form a beam. In this case, the 4 eights are automatically
@end example
@cindex articulation
-You can enter articulation signs either in a verbose form or using a
-shorthand. Here we demonstrate the shorthand: it is formed by a dash
-and the character for the articulation to use, e.g. @code{-.} for
-staccato as shown above.
+Staccato signs are entered as a dash and a period. Some other
+articulations may also be entered in this short form.
@separate
@example
\addlyrics
\context Staff = mel @{
- \property Staff.noAutoBeaming = ##t
+ \property Staff.autoBeaming = ##f
\property Staff.automaticMelismata = ##t
\melody
@}
\addlyrics
\context Staff = mel {
- \property Staff.noAutoBeaming = ##t
+ \property Staff.autoBeaming = ##f
\property Staff.automaticMelismata = ##t
\melody
}
@cindex assignments
@cindex identifier assignment
the @code{\header} block contains assignments. In each assignment, a
-variable is set to a value. Lexically, both the variable name and the
-assigned value are strings. The values have to be quoted here, because
-they contain spaces. The variable names could also be put within quotes
-but it is not necessary.
+variable is set to a value.
@separate
@example
@separate
@example
- The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
+ The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
ri- ver is flo- __ wing down to the sea.
@}
@cindex hyphens, lyric
The syllables themselves are separated by spaces. You can get syllable
extenders by entering @code{__}, and centered hyphens with
-@code{-}@code{-}. We enter the syllables as if they are all quarter notes
-in length (hence the @code{4}), and use a feature to align the
-syllables to the music, which obviously isn't all quarter notes.
+@code{-}@code{-}. We don't enter durations for the syllables. They
+are aligned with the melody later.
@separate
@example
@separate
@example
- c2:3- f:3-.7
+ c2:3-
@end example
@cindex tonic
@cindex chord modifier
@cindex modifier, chord
-A chord is started by the tonic of the chord. The
-first one lasts a half note. An unadorned note creates a major
-triad. Since a minor triad is wanted, @code{3-} is added to modify the
-third to be small. @code{7} modifies (adds) a seventh, which is small by
+This is a c minor chord, lasting half a note. Chord are entered by
+entering the tonic. Then notes can be changed. In this case, a small third
+is used. The cod for this is @code{3-}.
+
+@separate
+@example
+f:3-.7
+@end example
+Similarly, @code{7} modifies (adds) a seventh, which is small by
default to create the @code{f a c es} chord. Multiple modifiers must be
separated by dots.
@separate
d:min es4 c8:min r8
@end example
-
Some modifiers have predefined names, e.g. @code{min} is the same as
@code{3-}, so @code{d-min} is a minor @code{d} chord.
@separate
(`notation context') and for generating sound (`performance
context'). These objects only exist during a run of LilyPond.
-By default, LilyPond will create a Staff context for you. If you would
-remove the @code{%} sign in the previous line, you would see that
-mechanism in action.
+When LilyPond interprets music, it will create a Staff context. If
+the @code{%} sign in the previous line were removed, you could see
+that mechanism in action.
We don't want that default here, because we want chord names. The
command above explicitly creates an interpretation context of
combining both with @code{\addlyrics}. @code{\addlyrics} takes two
pieces of music (usually a melody and lyrics, in that order) and
aligns the syllables of the second piece under the notes of the
-first piece. If you would reverse the order, the notes would be
-aligned on the lyrics, which is not very useful, and looks
-silly.
+first piece.
@separate
@example
@end example
-The first argument of @code{\addlyrics} is the melody. We instantiate
-a @code{Staff} context explicitly: should you choose to remove the
-comment before the ``note heads'' version of the accompaniment, the
-accompaniment will be on a nameless staff. The melody has to be on
-staff different from the accompaniment. This is accomplished by giving
-the melody and accompaniment staves different names.
+We place the melody on a staff called @code{mel}. We give it a name to
+differentiate it from the one that would contain note heads for the
+chords, if you would remove the comment before the ``note heads''
+version of the accompaniment. By giving this staff a name, it is
+forced to be different.
@separate
@example
- \property Staff.noAutoBeaming = ##t
+ \property Staff.autoBeaming = ##f
@end example
@cindex \property
@cindex context variables
@cindex setting context variables
An interpretation context has variables, called properties, that tune
-its behavior. One of the variables is @code{noAutoBeaming}. Setting
-this @code{Staff}'s property to @code{##t}, which is the boolean value
-@var{true}, turns the automatic beaming mechanism off for the current
+its behavior. One of the variables is @code{autoBeaming}. Setting
+this @code{Staff}'s property to @code{##f}, which is the boolean value
+@var{false}, turns the automatic beaming mechanism off for the current
staff.
+
+@ignore
@cindex GUILE
@cindex Scheme
@cindex accessing Scheme
If Scheme scares you, don't worry. You don't need to know Scheme to
create beautiful sheet music.
-
+@end ignore
@separate
For example, consider the following file (@file{miniatures.ly})
@example
-\version "1.4.0"
+\version "1.5.60"
\header @{
title = "Two miniatures"
tagline = "small is beautiful"
@code{point-and-click} to the value @var{line-column-location} (which
itself is a Scheme procedure).
-Editing input files can be quite complicated if you're working with
+Editing input files can be complicated if you're working with
large files: if you're digitizing existing music, you have to
synchronize the .ly file, the sheet music on your lap and the sheet
music on the screen. The point-and-click mechanism makes it easy to
@node A piano excerpt
@section A piano excerpt
-Our fourth subject is a piece of piano music. The fragment in the input
-file is a piano reduction of the G major Sinfonia by Giovanni Battista
-Sammartini. It was composed around 1740. It's in the source package
-under the name @file{sammartini.ly}.
-
-@lilypond[verbatim]
-\include "paper16.ly"
-
-stemDown = \property Voice.Stem \override #'direction = #-1
-stemUp = \property Voice.Stem \override #'direction = #1
-stemBoth = \property Voice.Stem \revert #'direction
-
-viola = \notes \relative c' \context Voice = viola {
- <c4-\f-\arpeggio g' c>
- \stemDown g'8. b,16
- s1 s2. r4
- g
-}
-
-oboes = \notes \relative c'' \context Voice = oboe {
- \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
- \grace { <e8( g> } <d4 )f> <c2 e>
- \times 2/3 { <d8 \< f> <e g> <f a> }
- <
- { \times 2/3 { a8 g c } \! c2 }
- \context Voice = oboeTwo {
- \stemDown
- \grace {
- \property Voice.Stem \override #'direction = #-1
- [f,16 g]
- \property Voice.Stem \revert #'direction
- }
- f8 e e2
- }
- >
- \stemBoth
- \grace { <c,8( e> } <)b8. d8.-\trill> <c16 e> |
- [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
- [<c16( e> < )e8. g>] <c8 e,>
-}
-
-hoomPah = \repeat unfold 8 \notes
- \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth }
-
-bassvoices = \notes \relative c' {
- c4 g8. b,16
- \autochange Staff \hoomPah
- \translator Staff = down
- \stemDown [c8 c'8] r4
- <g d'> r4
- < {\stemUp r2 <e4 c'> <c8 g'> }
- \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
-}
-
-\score {
- \context PianoStaff \notes <
- \context Staff = up < \time 2/2
- \viola
- \oboes
- >
- \context Staff = down < \time 2/2 \clef bass
- \bassvoices
- >
- >
- \midi { }
- \paper {
- indent = 0.0
- linewidth = 15.0 \cm }
-}
-@end lilypond
+Our fourth subject is a piece of piano music. The fragment in the
+input file is a piano reduction of the G major Sinfonia by Giovanni
+Battista Sammartini. It was composed around 1740. It's in the source
+package under the name @file{sammartini.ly}.
-If this looks like incomprehensible gibberish to you, you are right.
-This example has been doctored to have as many quirks as possible.
+@lilypondfile[verbatim]{sammartini.ly}
As you can see, this example features multiple voices on one staff. To
make room for those voices, their notes have to be stemmed in opposite
directions.
-Printed symbols are internally represented by so-called Graphical
-Objects (more colloquially: Grobs). These statements concern the
-grob called `Stem'. Each grob is described by a bunch of settings. These
-setting determine the fonts, offsets, sub-routines to be called on the
-grob, etc. The initial values of these settings are set in the Scheme
-file @file{scm/grob-description.scm}.
-
-@separate
-@example
- stemDown = \property Voice.Stem \override #'direction = #-1
-@end example
-
-Set a property for all Stem grobs in the current Voice:
-@code{direction} is set to @code{-1}, which encodes down. The setting
-remains in effect until it is reverted.
-
-@separate
-@example
- \property Voice.Stem \revert #'direction
-@end example
-
-Revert the to the previous setting. The effect of precisely one
-@code{\stemDown} or @code{\stemUp} is neutralized.
-
-
LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
with some other commonly used formatting instructions, but to explain how
it works, we wrote our own here. Of course, you should use predefined
@separate
@example
-<c4-\f-\arpeggio g' c>
+<c4-\arpeggio g' c>
@end example
The delimiters @code{<} and @code{>} are shorthands for
@code{\simultaneous @{} and @code{@}}. The expression enclosed in
@code{<} and @code{>} is a chord.
-@cindex dynamics
-@cindex loudness
-@cindex forte
@cindex arpeggio
-@code{\f} places a forte symbol under the chord. The forte applies to
-the whole chord, but the syntax requires that commands like forte and
-arpeggio are attached to a note, so here we attach them to the first
-note.
-
@code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
the chord.
@separate
@example
- \stemDown
+ \voiceTwo
@end example
+We want the viola to have stems down, and have all the other
+characteristics of a second voice. This is enforced using the
+@code{\voiceTwo} command: it inserts instructions that makes stem,
+ties, slurs, etc. go down.
+
+
@separate
@example
@code{\context}.
@separate
@example
-\stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
-@end example
-@code{\stemUp} is a reference to the @code{\property \override} command
-defined above.
+\voiceOne s4 g8. b,16 c8 r <e'8. g> <f16 a>
+@end example
+
+The oboes should have stems up, so they should have stems up, to keep
+them from interfering with the staff-jumping bass figure.
+
@separate
@example
-\grace { <e8 g> } < d4 f> <c2 e>
+\grace <e8( g> < d4 )f> <c2 e>
@end example
@cindex @code{\grace}
@cindex ornaments
@cindex grace notes
-
-[FIXME]
@code{\grace} introduces grace notes. It takes one argument, in this
-case a chord.
+case a chord. A slur is introduced starting from the @code{\grace}
+ending on the following chord.
-@ignore
-The slur started on the @code{e} of the chord
-will be attached to the next note.@footnote{LilyPond will squirm
-about unended Slurs. In this case, you can ignore the warning}.
-@end ignore
@separate
@example
\times 2/3
of their notated duration, so in this case the fraction is 2/3.
@separate
@example
-@{ <d8 \< f> <e g> <f a> @}
+@{ <d8 f> <e g> <f a> @}
@end example
The piece of music to be `tripletted' is sequential music containing
-three notes. On the first chord, a crescendo is started with
-@code{\<}. To be precise, the crescendo start is syntactically attached
-to the preceding note, the @code{d}.
-
-@cindex dynamics
-@cindex crescendo
-@cindex @code{\<}
+three chords.
@separate
@example
voice, which continues with upward stems:
@separate
@example
- @{ \times 2/3 @{ a8 g c @} \! c2 @}
+ @{ \times 2/3 @{ a8 g c @} c2 @}
@end example
-@cindex @code{\!}
-
-The crescendo is ended at the half note by the escaped exclamation
-mark @code{\!}.
@separate
-@example
-\context Voice = oboeTwo @{
-\stemDown
-@end example
-We can't share stems with the other voice, so we have to create a new
-@code{Voice} context. We give it the name @code{oboeTwo} to distinguish
-it from the other context. Stems go down in this voice.
-@separate
-@example
-\grace @{
+@example
+\\
@end example
-[FIXME]
-@cindex Grace context
-When a grace section is processed, a @code{Grace} context is
-created. This context acts like a miniature score of its own. It has
-its own time bookkeeping, and you can make notes, beams, slurs
-etc. Here we fiddle with a property and make a beam. The argument of
-@code{\grace} is sequential music.
-
-@separate
-@example
- \property Voice.Stem \override #'direction = #-1
- [f,16 g]
- \property Voice.Stem \revert #'direction
-@end example
-
-Normally, grace notes are always stem up, but in this case, the upper
-voice interferes, so we set the stems down here.
+The easiest way to enter multiple voices is demonstrated
+here. Separate the components of the voice (single notes or entire
+sequences) with @code{\\} in a simultaneous music expression. The
+@code{\\} separators split first voice, second voice, third voice, and
+so on.
As far as relative mode is concerned, the previous note is the
@code{c'''2} of the upper voice, so we have to go an octave down for
@separate
@example
- f8 e e2
+ f,8 e e2
@} >
@end example
This ends the two-part section.
@separate
@example
\stemBoth
-\grace { <c,8( e> } <)b8. d8.-\trill> <c16 e> |
+\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
@end example
@cindex trill
@cindex stemBoth
is the to-be-transposed music. As you can see, in this case, the
transposition has no effect, as central C stays at central C.
-The purpose of this no-op is circumventing relative mode. Relative mode
-can not be used together with transposition, so @code{\relative} will
-leave the contents of @code{\hoomPah} alone. We can use it without
-having to worry about getting the motive in a wrong octave.
+The purpose of this no-op is to protect it from being interpreted as
+relative notes. Relative mode can not be used together with
+transposition, so @code{\relative} will leave the contents of
+@code{\hoomPah} alone. We can use it without having to worry about
+getting the motive in a wrong octave.
+@separate
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+@cindex @code{\translator}
+
+@example
+ \translator Staff = down
+ \stemUp
+ c8
+ \translator Staff = up
+ \stemDown
+ c'8 @}
+@end example
+Voices can switch between staves. Here you see two staff switching
+commands. The first one moves to the lower staff, the second one to
+the lower one. If you set stem directions explicitly (using the
+identifiers @code{\stemUp} and @code{\stemDown}.
+
@separate
@example
bassvoices = \notes \relative c' @{
c4 g8. b,16
-\autochange Staff \hoomPah
+\autochange Staff \hoomPah \context Voice
@end example
-@cindex staff switch, automatic
-@cindex cross staff voice, automatic
-@cindex @code{\autochange}
-Voices can switch between staves. The easiest way to get this, is to use
-@code{\autochange}. This command looks at the pitch of each note, and if
-necessary, will cross to the other staff. For this to work, the two
-staves must be called @code{"up"} and @code{"down"}.
@separate
@example
\translator Staff = down
@end ignore
+@node Fine tuning a piece
+@section Fine tuning a piece
+
+In this section, we show some ways to fine tune the final output of a
+piece. We do so using a single measure of a moderately complex piano
+piece: a Brahms intermezzo (opus 119, no. 1).
+@cindex Brahms, Johannes
+
+The code for the untuned example shows us some new things.
+
+@lilypondfile[verbatim]{brahms-original.ly}
+
+
+@cindex dynamics
+@cindex loudness
+@cindex forte
+@cindex crescendo
+@cindex @code{\<}
+@cindex @code{\!}
+
+The crescendo is ended at the half note by the escaped exclamation
+mark @code{\!}.
+
+Hairpin dynamics can be indicated using @code{\>} to start a
+decrescendo, and @code{\!} to end one. The crescendo is started using
+@code{\<} and also ended using @code{\!}. Absolute dynamics can be
+entered using @code{\p}, @code{\mf}, etc. All these commands apply to
+the complete chord where they are entered, but for syntactical
+reasons, they must be attached to one of the notes of the chord.
+
+@cindex fingering instructions
+
+Fingering indications are entered simply using @code{-@var{N}}, where
+@var{N} is a digit.
+
+Now that we have the basic piece of music entered, we want to fine
+tune it, so we get something that resembles the original printed
+edition by Schott/Universal Edition:
+
+@lilypondfile{brahms-tweaked.ly}
+
+@cindex tuning grob behavior
+
+The basic process that we follow is that we override defaults in the
+printing system. We do this by setting variables in so-called grobs.
+Printed symbols are internally represented by Graphical Objects
+(Grobs). Each grob is described by a bunch of settings. These setting
+determine the fonts, offsets, sub-routines to be called on the grob,
+etc. The initial values of these settings are set in the Scheme file
+@file{scm/grob-description.scm}.
+
+@cindex slur attachments
+
+We start with the slur: the slur in the upper part, running from the F
+sharp to the A, runs from stem to stem in the printed edition, while
+ours starts from the note head at the left. The following property
+setting forces all slurs to run from stem to stem (and not from or to
+note head)
+
+@example
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+@end example
+
+More precisely, this command extends the definition of the @code{Slur}
+object in the current @code{Voice}. The variable @code{attachment} is
+set to the pair of symbols @code{'(stem . stem)}.
+
+Although this is useful information, it is not very helpful: the
+lilypond backend supports approximately 240 variables like
+@code{attachment}, each with their own meaning and own type
+(eg. number, symbol, list, etc). Besides slur, LilyPond has 80
+different types of Grobs, that may be created in 14 different context
+types besides Voice.
+
+@cindex internal documentation
+@cindex finding grobs
+@cindex grob descriptiosn
+
+The interesting information is how you can figure out which properties
+to tune for your own scores. To discover this, you must have a copy of
+the internals document. This is a set of HTML pages, which should be
+included if you run a binary distribution@footnote{You can also
+compile them by executing @code{make -C Documentation/user/
+out/lilypond-internals.html} in the source package.}. This document is
+also available on the web: go to the lilypond website, click
+``Documentation: other'' on the side bar, click
+``lilypond-internals'', under information for users.
+
+You might want to bookmark either the HTML files on disk, or the one
+on the web. One word of caution is in place here: the internals
+documentation is generated from the definitions that lily uses. For
+that reason, it is strongly tied to the version of LilyPond that you
+use. Before you proceed, please make sure that you are using the
+documentation that corresponds to the LilyPond version that you use.
+
+Suppose that you wanted to tune the behavior of the slur. The first
+step is to get some general info 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
+@internalsref{Voice} context.
+@end quotation
+
+So the grob for this object is called @code{Slur}, and slurs are
+created in the @code{Voice} context. If you are reading this tutorial
+in the HTML version, then you can simply click Slur, otherwise, you
+must look it up the internal documentation: click ``grob overview'' ,
+and select ``slur'' (the list is alphabetical.)
+
+Now you get a list of all the properties that the slur object
+supports, along with their default values. Among the properties we
+find the @code{attachment} property, leading to
+@example
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+@end example
+
+If you ran the previous example, you have unknowingly already used
+this kind of command. The @file{ly/property-init.ly} contains the
+definition of @code{\stemUp}
+@example
+ stemUp = \property Voice.Stem \set #'direction = #1
+@end example
+
+
+We also want to move around the fingering `3'. In the printed edition
+it is not above the stem, but a little lower, slightly left of the
+stem. From the user manual, we find that the associated grob is called
+@code{Fingering}, but how do we know if we should use @code{Voice} or
+@code{Staff}. In many cases, @code{Voice} is a safe bet, but you can
+also deduce this information from the internals documentation: if you
+visit the documentation of @code{Fingering}, you will notice
+@example
+Fingering grobs are created by: Fingering_engraver
+@end example
+
+
+
+Clicking @code{Fingering_engraver} will show you the documentation of
+the module responsible for interpreting the fingering instructions and
+translating them to a @code{Fingering} grob. Such a module is called
+an @emph{engraver}. The documentation of the @code{Fingering_engraver}
+says,
+@example
+Fingering_engraver is part of contexts: Voice and TabVoice
+@end example
+so tuning the settings for Fingering should be done using either
+@example
+ \property Voice.Fingering \set @dots{}
+@end example
+or
+@example
+ \property TabVoice.Fingering \set @dots{}
+@end example
+
+Since the @code{TabVoice} is only used for tab notation, we see that
+the first guess @code{Voice} was indeed correct.
+
+@cindex setting grob properties
+@cindex @code{extra-offset}
+
+For shifting the fingering, we use the grob property
+@code{extra-offset}. The following command manually adds an offset to
+the object. We move it a little to the left, and 1.8 staff space
+downwards.
+@example
+ \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
+@end example
+The @code{extra-offset} is a low-level feature: it moves around
+objects in the printout; the formatting engine is completely oblivious
+to these offsets.
+
+@cindex reverting grob properties
+@cindex undoing grob properties
+
+We only want to offset a single grob, so after the F-sharp, we must
+undo the setting. The technical term is to revert the grob property.
+@example
+ \property Voice.Fingering \revert #'extra-offset
+@end example
+
+@cindex property types
+@cindex translator properties
+@cindex grob properties
+@cindex music properties
+
+
+There is three different types of variables in LilyPond, something
+which is confusing at first (and for some, it stays like that).
+Variables such as @code{extra-offset} and @code{attachment} are called
+grob properties. They are something different from the translator
+properties, like @code{autoBeaming} and
+@code{automaticMelismata}. Finally, music expressions are internally
+also stored using properties, so-called music properties. You will
+encounter the latter type if you run Scheme functions on music using
+@code{\apply}.
+
+The second fingering instruction should be moved up a little, to avoid
+a collision with the slur. This could be achieved with
+@code{extra-offset}, but in this case, a simpler mechanism also
+works. We insert an empty text between the 5 and the note. The empty
+text pushes the fingering instruction away:
+@example
+ a^" "^#'(finger "5")
+@end example
+
+Lilypond tries to put fingering instructions closer to the notes as
+text instructions. To insert an empty text (@code{^" "}) between the
+finger and the note, we have disguised the fingering instruction as a
+text: @code{(finger "5")}.
+
+Normally, one would specify dynamics in a single voice, and start and
+end dynamics (such as @b{f} and @b{p}) will be aligned with
+hairpins. In this case, we want the decrescendo to be in a different
+place from the piano sign. We achieve this by putting the dynamic
+markings in different voices. The crescendo should be above the upper
+staff. This can be forced by the precooked command
+@example
+ \dynamicsUp
+@end example
+
+However, if you do that, the decrescendo will be too close to the
+upper voice, and collide with the stems. Looking at the manual for
+dynamics, we notice that ``Vertical positioning of these symbols is
+handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
+to the documentation of @code{DynamicLineSpanner}, we find that the
+@code{DynamicLineSpanner} supports several so-called
+`interfaces'. This grob not only puts dynamic objects next to the
+staff (@code{side-position-interface}), but it also groups dynamic
+objects (@code{axis-group-interface}), is considered a dynamic sign
+itself (@code{dynamic-interface}) and is a grob: it has the
+@code{grob-interface}, with all the variables that come with it.
+
+For the moment, we are interested in the side positioning:
+@quotation
+ side-position-interface
+
+ Position a victim object (this one) next to other objects (the
+ support). In this case, the direction signifies where to put the
+ victim object relative to the support (left or right, up or down?)
+@end quotation
+Between the grob and its support (in this case: the notes in the voice
+going down), there should be more space. This space is controlled by
+@code{padding}, so we increase it.
+@example
+ \property Voice.DynamicLineSpanner \override #'padding = #5.0
+@end example
+
+This command is almost like the command for setting slur attachments,
+but subtly different in its details. Grob properties can be
+manipulated with two commands: @code{\override} extends the grob
+variables with a setting, and @code{\revert} releases this
+setting. This has a certain theoretical appeal: the operations are
+simple and symmetric. For practical use, it can be cumbersome. Both
+commands act like parentheses: you should carefully balance the use of
+@code{\override} and @code{\revert}. The @code{\set} command is more
+friendly: it first does a @code{\revert} followed by @code{\override}.
+
+Finally, Brahms uses music notation is a slightly unorthodox way. Ties
+usually happen only within one voice. In this piece, the composer
+gladly produces ties that jump voices. We deal with this by faking
+these ties: whenever we need such a tie, we insert a notehead in a
+different voice, and blank the stem. This is done in the following
+snippet of code.
+
+@example
+ \property Voice.Stem \set #'transparent = ##t
+ d'
+ \property Voice.Stem \revert #'transparent
+@end example
+
+Finally, the last tie is forced up using @code{\tieUp}.
+
+
@node An orchestral score
@section An orchestral score
with a flat sign. LilyPond has a mechanism for font selection and
kerning called Scheme markup text (See @ref{Text markup}). The flat
sign is taken from the music font, and its name is @code{accidentals--1}
-(The sharp sign is called @code{accidentals-1}). The default font is
+(The natural sign is called @code{accidentals-0}). The default font is
too big for text, so we select a relative size of @code{-2}.
@separate
\property Score.BarNumber \override #'padding = #3
@end example
LilyPond prints bar numbers at the start of each line, but
-unfortunately, they end up a bit too close to the staff in this example.
-A bar number internally is a Grob called @var{BarNumber}. BarNumber
-Grobs can be manipulated through their @var{side-position-interface}. One
-of the properties of a @var{side-position-interface} that can be tweaked
-is the @var{padding}: the amount of extra space that is put between this
-Grob and other Grobs. We set the padding to three staff spaces.
+unfortunately, they end up a bit too close to the staff in this
+example. A bar number internally is a Grob called @var{BarNumber}.
+BarNumber Grobs can be manipulated through their
+@var{side-position-interface}. One of the properties of a
+@var{side-position-interface} that can be tweaked is the
+@var{padding}: the amount of extra space that is put between this Grob
+and other Grobs. We set the padding to three staff spaces.
You can find information on all these kind of properties in LilyPond's
automatically generated documentation in
$ cd input/tutorial
$ lilypond-book --outdir=out/ lilbook.tex
lilypond-book (GNU LilyPond) 1.3.146
-Reading `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/lilbook.tex'
-Reading
-`/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/sammartini.ly'
+Reading `input/tutorial/lilbook.tex'
+Reading `input/tutorial/sammartini.ly'
@var{lots of stuff deleted}
Writing `out/lilbook.latex'
$ cd out
projects / lilypond.git / blobdiff