@node Tutorial
@chapter Tutorial
-@html
-<!--- @@WEB-TITLE@@=Tutorial --->
-@end html
-@menu
-* First steps:: Music language of LilyPond.
-* Running LilyPond:: Printing music.
-* More about pitches and accidentals::
-* Octave entry ::
-* Relative 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 staffs::
-* Setting variables::
-* Fine tuning layout::
-* Organizing larger pieces::
-* An orchestral part::
-* Integrating text and music:: Integrating text and music.
-@end menu
Using LilyPond comes down to encoding music in an input file. After
entering the music, the program is run on the file producing output
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
+For example, consider the following input:
@c TODO: intertext fixme
-@lilypond[relative 1,singleline,verbatim,intertext="with the following output"]
+@lilypond[relative 1,singleline,verbatim,intertext="with the following output:"]
c'^\markup { \bold \huge { Click on this image! } }
@end lilypond
-If you click it, you can see that the input shown is simplified a
-little. This has been done for reasons of space and clarity. If you
-want to fiddle, you need the full input, otherwise LilyPond will not
-accept it.
+
@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,
produce printed output, normally using the program @code{ly2dvi}. You
should then be able to create and print your first sheets of music.
+@menu
+* First steps:: Music language of LilyPond.
+* Running LilyPond:: Printing music.
+* More about pitches and accidentals::
+* 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:: Integrating text and music.
+@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 @htmlref{note name}, from @samp{a}
+you get a note simply by typing its note name, from @samp{a}
through @samp{g}. So if you enter
@example
@cindex Viewing music
@cindex xdvi
-The result of the ly2dvi is the file @file{test.pdf}.@footnote{ For
-@TeX{} afficionados, there is also a (@file{test.dvi}) file. It can be
+The result of the ly2dvi 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
@cindex dvips
@cindex dvilj
@cindex DVI driver
-} One the following commands should put the PDF on your
-screen.
-@c eeek
+} One of the following commands should put the PDF on your
+screen:
@quotation
@example
gv test.pdf
xpdf test.pdf
gpdf test.pdf
acroread test.pdf
+ gsview32 test.pdf
@end example
@end quotation
If the music on your screen looks good, you can print it by clicking
@cindex PDF
-On Windows, 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. If you have a PDF viewer installed,
-use that for viewing the PDF
-@c where on file system for double-click people?
-If you have no viewer, then you can download @code{GSView} from
-@uref{http://www.cs.wisc.edu/~ghost}. With @code{GSView},
-the PDF file can viewed with
-@quotation
-@example
-@code{gsview32 test.pdf}
-@end example
-@end quotation
-Printing may be done with
-@quotation
-@example
-@code{gsview32 /s test.pdf}
-@end example
-@end quotation
+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.
-The commands for formatting and printing music are detailed in
-@ref{Invoking 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 also try the list of commands
+shown before. If none work, go to
+@uref{http://www.cs.wisc.edu/~ghost/} to install the proper software.
+@end itemize
+
+The commands for formatting and printing music on all platforms are
+detailed in @ref{Invoking LilyPond}.
@node More about pitches and accidentals
@section More about pitches and accidentals
@cindex tie
A tie is created by adding a tilde ``@code{~}'' to the first note
-being tied.
+being tied:
@quotation
@lilypond[fragment,verbatim,relative 2]
g4-~ g a2-~ a4
@end quotation
@separate
-This example shows the key signature, accidentals and ties in action.
+This example shows the key signature, accidentals and ties in action:
@quotation
@example
you just enter the pitch of the note, and an accidental is printed
only when necessary. The flip side of this mechanism, is that you have
to mark notes as sharp or flat, even when they do not get accidentals.
-For example, in this example,
+For example, in this example:
@lilypond[fragment]
\clef bass
\property Staff.TimeSignature = #'()
it possible to use different conventions for when to print
accidentals.
-@node Octave entry
+@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
+
+Rests are described in full detail in @ref{Rests}.
+
+The notation manual discusses ties in @ref{Ties}.
+
+
+@node Octave entry
@section Octave entry
@end quotation
@separate
-An example of the use of quotes is in the following Mozart fragment.
+An example of the use of quotes is in the following Mozart fragment:
@lilypond[singleline,fragment,verbatim]
\key a \major
\time 6/8
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.
+For example, @code{c f} goes up while @code{c g} goes down:
@quotation
@example
-@node Relative octave entry
-@section Relative octave entry
-@c lousy example
-@c ? --hwn
-@c fragment of 1st hrn in Adams' The Chairman Dances, with creative
-@c chromatic thing pasted in front. (admittedly the original does not
-@c have a phrasing slur. The problem is that we do not want the slur
-@c and the Phrasing slur to collide. We are trying to make a good
-@c impression here.
-
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
-@end lilypond
-@end quotation
-@separate
-
-@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
-
-Rests are described in full detail in @ref{Rests}.
-
-The notation manual discusses ties in @ref{Ties}.
\time 3/4
\clef violin
\relative c'' {
- e2-( d4 c2 b4 a8-[ a-]
- b-[ b-] g-[ g-] a2.-) }
+ e2( d4 c2 b4 a8[ a]
+ b[ b] g[ g] a2.) }
}
\context Staff = staffB {
\clef bass
@end lilypond
@end quotation
-The example shows how small chunks of music, for example the notes
+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{\context Staff} to it, and that chunk is
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
+braces at the end of an expression. For example,
@example
\score @{
\notes <
-@node Adding articulation marks to notes
+@node Adding articulation marks to notes
@section Adding articulation marks to notes
@cindex articulation
@cindex fingering
Similarly, fingering indications can be added to a note using a dash
-(`@code{-}') and the digit to be printed.
+(`@code{-}') and the digit to be printed:
@c
@lilypond[verbatim,relative 1]
c-3 e-5 b-2 a-1
Crescendi and decrescendi are started with the commands @code{\<} and
@code{\>}. The command @code{\!} finishes a crescendo on the note it
-is attached to.
+is attached to:
@quotation
@lilypond[verbatim,relative 1]
c2-\< c2-\!-\ff c2-\> c2-\!
@quotation
@lilypond[fragment,relative 1, verbatim]
-d4-( c16-)-( cis d e c cis d e-)-( d4-)
+d4( c16)( cis d e c cis d e)( d4)
@end lilypond
@end quotation
@separate
pitch. Slurs indicate the articulations of notes, and can be used on
larger groups of notes. Slurs and ties are also nested in practice:
@lilypond[fragment, relative=1]
-c2-~-( c8 fis fis4 ~ fis2 g2-)
+c2-~( c8 fis fis4 ~ fis2 g2)
@end lilypond
@cindex phrasing slurs
phrasing), you can also make a phrasing slur with @code{\(} and
@code{\)}.
+@quotation
+@lilypond[fragment,relative 1, verbatim]
+a8(-\( ais b c) cis2 b'2 a4 cis, c-\)
+@end lilypond
+@end quotation
+
+
More information on fingering, articulation, slurs, phrasing slurs,
and dynamics can be found in @ref{Fingering instructions},
-@ref{Articulations}, @ref{Slurs}, @ref{Phrasing slurs} @ref{Dynamics}
+@ref{Articulations}, @ref{Slurs}, @ref{Phrasing slurs}, and @ref{Dynamics},
respectively.
@node Combining notes into chords
must be placed outside the chord markers:
@quotation
@lilypond[relative 0, fragment,verbatim]
-r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
+r4 <<c e g>>8[ <<c f a>>]-~ <<c f a>>
@end lilypond
@end quotation
@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
@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.
+and @code{\partial 8} an eighth note:
@lilypond[relative 1,verbatim,fragment]
\partial 8
f8 c2 d e
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.
+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 }
@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 keyword is @code{\grace}.
+a keyword. In this case, the keyword is @code{\grace}:
@lilypond[relative 1, verbatim,fragment]
- c4 \grace b16-( c4-)
- \grace { d16-( e } d4-)
+ c4 \grace b16( c4)
+ \grace { d16( e } d4)
@end lilypond
@noindent
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.
+for comments:
@example
% notes for twinkle twinkle follow:
@cindex Lyrics
@cindex Songs
Lyrics are entered by separating each syllable with a space, and
-surrounding them with @code{\lyrics @{ @dots{} @}}, for example
+surrounding them with @code{\lyrics @{ @dots{} @}}, for example,
@example
\lyrics @{ I want to break free @}
@end example
@example
\context Lyrics \lyrics @{ I want to break free @}
@end example
-The melody for this song is as follows
+The melody for this song is as follows:
@lilypond[fragment,relative=1]
\partial 8
c8
- \times 2/3 { f4 g g } \times 2/3 { g4-( a2-) }
+ \times 2/3 { f4 g g } \times 2/3 { g4( a2) }
@end lilypond
The lyrics can be set to these notes, combining both with the
\relative c' {
\partial 8
c8
- \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
+ \times 2/3 { f g g } \times 2/3 { g4( a2) }
}
\context Lyrics \lyrics { I want to break free }
}
@c synonyms?
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.,
+line}. It is entered as two underscores, i.e.
@example
\lyrics @{ I want to break free __ @}
@end example
\relative c' {
\partial 8
c8
- \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
+ \times 2/3 { f g g } \times 2/3 { g4( a2) }
%% ugh, this is to deal with bugs in the extender implementation
\hideNotes
@end lilypond
Similarly, hyphens between words can be entered as two dashes,
-resulting in a centered hyphen between two syllables.
+resulting in a centered hyphen between two syllables:
@example
Twin -- kle twin -- kle
@end example
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.
+root of the chord), and a durations following that:
@c
@lilypond[verbatim]
\chords { c2 f4. g8 }
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
+following example shows a few common modifiers:
@c
@lilypond[verbatim]
\chords { c2 f4:m g4:maj7 gis1:dim7 }
\notes \relative c' {
\partial 8
c8
- \times 2/3 { f g g } \times 2/3 { g4-( a2-) } }
+ \times 2/3 { f g g } \times 2/3 { g4( a2) } }
\context Lyrics \lyrics { I want to break free __ }
>
\paper{ raggedright = ##t }
the musical transcription.
@code{\midi} can be used in similarly to @code{\paper @{ @}}, for
-example
+example,
@example
\score @{
@var{..music..}
-@node Titling
+@node Titling
@section Titling
Bibliographic information is entered in a separate block, the
specified are printed above the music. The `tagline' is a short line
printed at bottom of the last page, which normally says ``Lily was
here, version @dots{}''. In the example above, it is replaced by the
-line ``small is beautiful.''
+line ``small is beautiful''.
Normally, the @code{\header} is put at the top of the file. However,
for a document that contains multiple pieces (e.g. a etude book, or
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.
+@code{\score} block as follows; in this case, the name of each piece
+will be printed before each movement:
@cindex Lily was here
More information on titling can be found in @ref{Invoking ly2dvi}.
-@node Single staff polyphony
+@node Single staff polyphony
@section Single staff polyphony
@cindex polyphony
{ s4 g4 f2 f4 } >
@end lilypond
-Again, these expressions can be nested arbitrarily.
+Again, these expressions can be nested arbitrarily:
@lilypond[fragment]
<
More features of polyphonic typesetting are in the notation manual
in @ref{Polyphony}.
-@node Piano staffs
-@section Piano staffs
+@node Piano staves
+@section Piano staves
@cindex staff switch, manual
@cindex cross staff voice, manual
@cindex @code{\translator}
-Piano music is always typeset in two staffs connected by a brace.
+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
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
+entered as follows:
@itemize @bullet
-@item a string, enclosed in double quotes, for example
+@item a string, enclosed in double quotes, for example,
@example
\property Staff.instrument = #"French Horn"
@end example
\property Score.skipBars = ##t
@end example
-@item a number
+@item a number, such as
@example
\property Score.currentBarNumber = #20
@end example
-@item a symbol, which is introduced by a quote character,
+@item a symbol, which is introduced by a quote character, as in
@example
\property Staff.crescendoSpanner = #'dashed-line
@end example
-@item a pair, which is also introduced by a quote character.
-The following statements set properties to the pairs (-7.5, 6) and
-(3, 4) respectively.
+@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)
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.
+values, we can alter the look of a formatted score:
@lilypond[verbatim,relative 0]
c4
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.,
+@code{\property} statement, i.e.
@example
\once \property Voice.Stem \set #'thickness = #3.0
used to apply generic tweaks. We mention a couple of these:
@itemize @bullet
-@cindex @code{extra-offset}
@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
these offsets.
In the following example example, the second fingering is moved a
-little to the left, and 1.8 staff space downwards.
+little to the left, and 1.8 staff space downwards:
@cindex setting object properties
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.
+in that voice, the tie appears to cross voices:
@lilypond[fragment,relative 1,verbatim]
\context Staff < {
\once \property Voice.Stem \set #'transparent = ##t
b8~ b8
} \\ {
- b-[ g8-]
+ b[ g8]
} >
@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}.
+tweak}:
@lilypond[relative 1]
c2-\fermata
By using variables, also known as identifiers, it is possible to break
up complex music expressions.
-An identifier is assigned as follows
+An identifier is assigned as follows:
@example
namedMusic = \notes @{ @dots{}
@end example
@}
@end example
-Then, an individual part is made by putting the following in a file
+Then, an individual part is made by putting the following in a file:
@example
\include "horn-music.ly"
\header @{
@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. Since the horn is tuned in F, the @code{\transpose}
-command is used. The code @code{\transpose c' f} indicates that the
+afterwards. The code @code{\transpose f c'} indicates that the
argument, being @code{\hornNotes}, should be transposed by a fifth
-downwards: the @code{c'} becomes a @code{f}. The transposition can be
-seen in the following output:
+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 c' f \notes \relative c' {
+ \notes \transpose f c' \notes \relative c {
\time 2/4
r4 f8 a cis4 f e d
}
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.
+takes 3 measures in 2/4 time:
@example
R2*3
@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.
+rests:
@example
\property Score.skipBars = ##t
@end example
Prepending the rest and the property setting above, leads to the
-following result.
+following result:
@lilypond[singleline]
-\score {\notes { \transpose c' f \relative c' { \time 2/4
+\score {\notes { \transpose f c' \relative c { \time 2/4
\property Score.skipBars = ##t
R2*3
r4 f8 a cis4 f e d } }}
@} @}
@end example
-This would lead to the simple score depicted below.
+This would lead to the simple score depicted below:
@lilypond[singleline]
\score {
@cindex Texinfo, music in
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)
+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.
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.
+we show a small example; since the example contains also explanatory
+text, we will not comment it further:
@example
\documentclass[a4paper]@{article@}
\end@{document@}
@end example
-Under Unix, you can view the results as follows.
+Under Unix, you can view the results as follows:
@example
$ cd input/tutorial
$ mkdir -p out/
projects / lilypond.git / blobdiff