1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
13 Tutorial guidelines: (different from policy.txt!)
14 - unless you have a really good reason, use either
15 @lilypond[verbatim,quote]
17 @lilypond[verbatim,quote,relative=2]
19 Don't use any other relative=X commands.
21 - use "aes" and "ees" instead of "as" and "es". I know it's not
22 correct Dutch naming, but let's not confuse people with this
23 until we get to the Basic notation chapter.
25 - Add "Music Glossary: @rglos{foo}" to the *top* of the relevant
26 portions of the tutorial.
32 @chapter Common notation
34 This tutorial starts with an introduction to the LilyPond music
35 language and explains how to produce printed music. After this first
36 contact we will explain how to create beautiful printed music
37 containing common musical notation.
40 * Single staff notation::
41 * Multiple notes at once::
47 @node Single staff notation
48 @section Single staff notation
50 This section introduces common notation that is used for one voice
54 * Accidentals and key signatures::
56 * Articulation and dynamics::
58 * Automatic and manual beams::
59 * Advanced rhythmic commands::
63 @node Accidentals and key signatures
64 @subsection Accidentals and key signatures
66 @subheading Accidentals
69 @cindex accidentals and key signatures
82 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
83 @rglos{double flat}, @rglos{accidental}.
85 A @notation{sharp} pitch is made by adding @code{is} to the name,
86 and a @notation{flat} pitch by adding @code{es}. As you might
87 expect, a @notation{double sharp} or @notation{double flat} is
88 made by adding @code{isis} or @code{eses}. This syntax is derived
89 from note naming conventions in Nordic and Germanic languages,
90 like German and Dutch. To use other names for
91 @notation{accidentals}, see @ruser{Note names in other languages}.
93 @lilypond[verbatim,quote,relative=2]
97 @cindex key signature, setting
98 @subheading Key signatures
100 @cindex key signature
103 @cindex accidentals and key signature
104 @cindex content vs. layout
105 @cindex layout vs. content
114 Music Glossary: @rglos{key signature}, @rglos{major},
117 The @notation{key signature} is set with the command @code{\key}
118 followed by a pitch and @code{\major} or @code{\minor}.
120 @lilypond[verbatim,quote,relative=2]
129 @subheading Warning: key signatures and pitches
131 Music Glossary: @rglos{accidental}, @rglos{key signature},
132 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
133 @rglos{transposition}.
135 To determine whether to print an @notation{accidental}, LilyPond
136 examines the pitches and the @notation{key signature}. The key
137 signature only affects the @emph{printed} accidentals, not the
138 note's @notation{pitch}! This is a feature that often causes
139 confusion to newcomers, so let us explain it in more detail.
141 LilyPond makes a sharp distinction between musical content and
142 layout. The alteration (@notation{flat}, @notation{natural sign} or
143 @notation{sharp}) of a note is part of the pitch, and is therefore
144 musical content. Whether an accidental (a @emph{printed} flat,
145 natural or sharp sign) is printed in front of the corresponding
146 note is a question of layout. Layout is something that follows
147 rules, so accidentals are printed automatically according to those
148 rules. The pitches in your music are works of art, so they will
149 not be added automatically, and you must enter what you want to
154 @lilypond[verbatim,quote,relative=2]
160 No note has a printed accidental, but you must still add
161 @code{is} and type @code{cis} and @code{fis} in the input file.
163 The code @code{b} does not mean @qq{print a black dot just on
164 the middle line of the staff.} Rather, it means @qq{there is a
165 note with pitch B-natural.} In the key of A-flat major, it
166 @emph{does} get an accidental:
168 @lilypond[verbatim,quote,relative=2]
173 Adding all alterations explicitly might require a little more
174 effort when typing, but the advantage is that
175 @notation{transposing} is easier, and accidentals can be printed
176 according to different conventions. For some examples how
177 accidentals can be printed according to different rules, see
178 @ruser{Automatic accidentals}.
182 Notation Reference: @ruser{Note names in other languages},
183 @ruser{Accidentals}, @ruser{Automatic accidentals},
184 @ruser{Key signature}.
186 Music Glossary: @rglos{Pitch names}.
190 @subsection Ties and slurs
194 @cindex slur, phrasing
195 @cindex phrasing slur
204 Music Glossary: @rglos{tie}.
206 A @notation{tie} is created by appending a tilde @code{~} to the
207 first note being tied.
209 @lilypond[verbatim,quote,relative=2]
217 Music Glossary: @rglos{slur}.
219 A @notation{slur} is a curve drawn across many notes. The
220 starting note and ending note are marked with @code{(} and
221 @code{)} respectively.
223 @lilypond[verbatim,quote,relative=2]
224 d4( c16) cis( d e c cis d) e( d4)
227 @subheading Phrasing slurs
229 Music Glossary: @rglos{slur}, @rglos{phrasing}.
231 Slurs to indicate longer @notation{phrasing} can be entered with
232 @code{\(} and @code{\)}. You can have both @notation{slurs}
233 and phrasing slurs at the same time, but you cannot have
234 simultaneous slurs or simultaneous phrasing slurs.
236 @lilypond[verbatim,quote,relative=2]
237 a8(\( ais b c) cis2 b'2 a4 cis,\)
242 @cindex slurs versus ties
243 @subheading Warnings: slurs vs. ties
245 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
247 A @notation{slur} looks like a @notation{tie}, but it has a
248 different meaning. A tie simply makes the first note longer, and
249 can only be used on pairs of notes with the same pitch. Slurs
250 indicate the @notation{articulation} of notes, and can be used on
251 larger groups of notes. Slurs and ties can be nested.
253 @lilypond[verbatim,quote,relative=2]
254 c2~( c8 fis fis4 ~ fis2 g2)
259 Notation Reference: @ruser{Ties}, @ruser{Slurs},
260 @ruser{Phrasing slurs}.
263 @node Articulation and dynamics
264 @subsection Articulation and dynamics
267 @subheading Articulations
273 Music Glossary: @rglos{articulation}.
275 Common @notation{articulations} can be added to a note using a
276 dash @code{-} and a single character:
278 @lilypond[verbatim,quote,relative=2]
279 c-. c-- c-> c-^ c-+ c-_
282 @subheading Fingerings
289 Music Glossary: @rglos{fingering}.
291 Similarly, @notation{fingering} indications can be added to a note
292 using a dash (@code{-}) and the digit to be printed:
294 @lilypond[verbatim,quote,relative=2]
298 Articulations and fingerings are usually placed automatically, but
299 you can specify a direction by replacing the dash (@code{-}) with
300 @code{^} (up) or @code{_} (down). You can also use multiple
301 articulations on the same note. However, in most cases it is best
302 to let LilyPond determine the articulation directions.
304 @lilypond[verbatim,quote,relative=2]
305 c_-^1 d^. f^4_2-> e^-_+
327 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
330 @notation{Dynamic} signs are made by adding the markings (with a
331 backslash) to the note:
333 @lilypond[verbatim,quote,relative=2]
338 @notation{Crescendi} and @notation{decrescendi} are started with
339 the commands @code{\<} and @code{\>}. The next dynamics sign, for
340 example @code{\f}, will end the (de)crescendo, or the command
341 @code{\!} can be used:
343 @lilypond[verbatim,quote,relative=2]
349 Notation Reference: @ruser{Articulations and ornamentations},
350 @ruser{Fingering instructions}, @ruser{Dynamics}.
354 @subsection Adding text
363 Text may be added to your scores:
365 @lilypond[verbatim,quote,relative=2]
369 Extra formatting may be added with the @code{\markup} command:
371 @lilypond[verbatim,quote,relative=2]
372 c1^\markup{ \bold espr}
374 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
380 Notation Reference: @ruser{Writing text}.
383 @node Automatic and manual beams
384 @subsection Automatic and manual beams
387 @cindex automatic beams
389 @cindex beams, automatic
390 @cindex beams, manual
391 @cindex beams, by hand
396 @funindex \autoBeamOff
397 @funindex autoBeamOff
398 @funindex \autoBeamOn
401 Music Glossary: @rglos{beam}.
403 All @notation{beams} are drawn automatically:
405 @lilypond[verbatim,quote,relative=2]
406 a8 ais d ees r d c16 b a8
409 If you do not like the automatic beams, they may be overridden
410 manually. To correct just an occasional beam mark the first note
411 to be beamed with @code{[} and the last one with @code{]}.
413 @lilypond[verbatim,quote,relative=2]
414 a8[ ais] d[ ees r d] a b
417 If you want to turn off automatic beaming entirely or for an
418 extended section of music, use the command @code{\autoBeamOff}
419 to turn off automatic beaming and @code{\autoBeamOn} to turn it
422 @lilypond[verbatim,quote,relative=2]
431 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
434 @node Advanced rhythmic commands
435 @subsection Advanced rhythmic commands
437 @subheading Partial measure
441 @cindex partial measure
446 Music Glossary: @rglos{anacrusis}.
448 A pickup (or @notation{anacrusis}) is entered with the keyword
449 @code{\partial}. It is followed by a duration: @code{\partial 4}
450 is a quarter note pickup and @code{\partial 8} an eighth note.
452 @lilypond[verbatim,quote,relative=2]
465 Music Glossary: @rglos{note value}, @rglos{triplet}.
467 @notation{Tuplets} are made with the @code{\times} keyword. It
468 takes two arguments: a fraction and a piece of music. The
469 duration of the piece of music is multiplied by the fraction.
470 Triplets make notes occupy 2/3 of their notated duration, so a
471 @notation{triplet} has 2/3 as its fraction
473 @lilypond[verbatim,quote,relative=2]
474 \times 2/3 { f8 g a }
476 \times 2/3 { f,8 g16[ a g a] }
480 @subheading Grace notes
488 @funindex \acciaccatura
489 @funindex acciaccatura
490 @funindex \appoggiatura
491 @funindex acciaccatura
493 Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
494 @rglos{appoggiatura}.
496 @notation{Grace notes} are created with the @code{\grace} command,
497 although they can also be created by prefixing a music expression
498 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
500 @lilypond[verbatim,quote,relative=2]
501 c2 \grace { a32[ b] } c2
502 c2 \appoggiatura b16 c2
503 c2 \acciaccatura b16 c2
508 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
512 @node Multiple notes at once
513 @section Multiple notes at once
515 This section introduces having more than one note at the same
516 time: multiple instruments, multiple staves for a single
517 instrument (i.e. piano), and chords.
519 Polyphony in music refers to having more than one voice occurring
520 in a piece of music. Polyphony in LilyPond refers to having more
521 than one voice on the same staff.
524 * Music expressions explained::
527 * Combining notes into chords::
528 * Single staff polyphony::
532 @node Music expressions explained
533 @subsection Music expressions explained
535 @cindex music expression
536 @cindex expression, music
537 @cindex compound music expression
538 @cindex music expression, compound
540 In LilyPond input files, music is represented by @emph{music
541 expressions}. A single note is a music expression:
543 @lilypond[verbatim,quote,relative=2]
547 Enclosing a note in braces creates a @emph{compound music
548 expression}. Here we have created a compound music expression
551 @lilypond[verbatim,quote,relative=2]
555 Putting a group of music expressions (e.g. notes) in braces means
556 that they are in sequence (i.e. each one follows the previous
557 one). The result is another music expression:
559 @lilypond[verbatim,quote,relative=2]
563 @subheading Analogy: mathematical expressions
565 This mechanism is similar to mathematical formulas: a big formula
566 is created by composing small formulas. Such formulas are called
567 expressions, and they can contain other expressions, so you can
568 make arbitrarily complex and large expressions. For example,
577 ((1 + 2) * 3) / (4 * 5)
580 This is a sequence of expressions, where each expression is
581 contained in the next (larger) one. The simplest expressions are
582 numbers, and larger ones are made by combining expressions with
583 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
584 Like mathematical expressions, music expressions can be nested
585 arbitrarily deep, which is necessary for complex music like
589 @subheading Simultaneous music expressions: multiple staves
591 @cindex multiple staves
592 @cindex staves, multiple
594 @cindex combining expressions in parallel
595 @cindex parallel expressions
596 @cindex expressions, parallel
597 @cindex relative notes and simultaneous music
598 @cindex relative notes and parallel expressions
599 @cindex simultaneous music and relative notes
600 @cindex parallel expressions and relative notes
606 Music Glossary: @rglos{polyphony}.
608 This technique is useful for @notation{polyphonic} music. To
609 enter music with more voices or more staves, we combine
610 expressions in parallel. To indicate that two voices should play
611 at the same time, simply enter a simultaneous combination of music
612 expressions. A @q{simultaneous} music expression is formed by
613 enclosing expressions inside @code{<<} and @code{>>}. In the
614 following example, three sequences (all containing two separate
615 notes) are combined simultaneously:
617 @lilypond[verbatim,quote]
627 Note that we have indented each level of the input with a
628 different amount of space. LilyPond does not care how much (or
629 little) space there is at the beginning of a line, but indenting
630 LilyPond code like this makes it much easier for humans to read.
632 @warning{each note is relative to the previous note in
633 the input, not relative to the @code{c''} in the initial
634 @code{@bs{}relative} command.}
637 @subheading Simultaneous music expressions: single staff
639 To determine the number of staves in a piece, LilyPond looks at
640 the beginning of the first expression. If there is a single note,
641 there is one staff; if there is a simultaneous expression, there
642 is more than one staff. The following example shows a complex
643 expression, but as it begins with a single note it will be set
644 out on a single staff.
646 @lilypond[verbatim,quote]
649 << { e f } { c <<b d>> } >>
653 @node Multiple staves
654 @subsection Multiple staves
656 @cindex multiple staves
657 @cindex staves, multiple
659 @cindex context, notation
660 @cindex notation context
672 LilyPond input files are constructed out of music expressions, as
673 we saw in @ref{Music expressions explained}. If the score begins
674 with simultaneous music expressions, LilyPond creates multiples
675 staves. However, it is easier to see what happens if we create
676 each staff explicitly.
678 To print more than one staff, each piece of music that makes up a
679 staff is marked by adding @code{\new Staff} before it. These
680 @code{Staff} elements are then combined in parallel with @code{<<}
683 @lilypond[verbatim,quote]
686 \new Staff { \clef treble c }
687 \new Staff { \clef bass c,, }
692 The command @code{\new} introduces a @q{notation context.} A
693 notation context is an environment in which musical events (like
694 notes or @code{\clef} commands) are interpreted. For simple
695 pieces, such notation contexts are created automatically. For
696 more complex pieces, it is best to mark contexts explicitly.
698 There are several types of contexts. @code{Score}, @code{Staff},
699 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
700 lyric texts and @code{ChordNames} prints chord names.
702 In terms of syntax, prepending @code{\new} to a music expression
703 creates a bigger music expression. In this way it resembles the
704 minus sign in mathematics. The formula @math{(4+5)} is an
705 expression, so @math{-(4+5)} is a bigger expression.
707 Time signatures entered in one staff affects all other staves by
708 default. On the other hand, the key signature of one staff does
709 @emph{not} affect other staves. This different default behavior
710 is because scores with transposing instruments are more common
711 than polyrhythmic scores.
713 @lilypond[verbatim,quote]
716 \new Staff { \clef treble \key d \major \time 3/4 c }
717 \new Staff { \clef bass c,, }
726 @subsection Staff groups
740 Music Glossary: @rglos{brace}.
742 Piano music is typeset in two staves connected by a
744 Printing such a staff is similar to the polyphonic example in
745 @ref{Multiple staves}. However, now this entire expression is
746 inserted inside a @code{PianoStaff}:
755 Here is a small example:
757 @lilypond[verbatim,quote]
760 \new Staff { \time 2/4 c4 e g g, }
761 \new Staff { \clef bass c,, c' e c }
766 Other staff groupings are introduced with @code{\new GrandStaff},
767 suitable for orchestral scores, and @w{@code{\new ChoirStaff}},
768 suitable for vocal scores. These staff groups each form another
769 type of context, one that generates the brace at the left end of
770 every system and also controls the extent of bar lines.
774 Notation Reference: @ruser{Keyboard and other multi-staff
776 @ruser{Displaying staves}.
779 @node Combining notes into chords
780 @subsection Combining notes into chords
783 @cindex note durations in chords
789 Music Glossary: @rglos{chord}.
791 We saw earlier how notes can be combined into @notation{chords} by
792 indicating they are simultaneous by enclosing them in double angle
793 brackets. However, the normal way of indicating a chord is to
794 surround the pitches with @emph{single} angle brackets. Note that
795 all the notes in a chord must have the same duration, and that the
796 duration is placed after the closing bracket.
798 @lilypond[verbatim,quote,relative=2]
802 Think of chords as almost equivalent to single notes:
803 almost everything you can attach to a single note can be attached
804 to a chord, and everything must go @emph{outside} the angle
805 brackets. For example, you can combine markings like beams and
806 ties with chords. They must be placed outside the angle brackets.
808 @lilypond[verbatim,quote,relative=2]
809 r4 <c e g>8[ <c f a>]~ <c f a>2
810 r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
814 @node Single staff polyphony
815 @subsection Single staff polyphony
818 @cindex multiple voices
819 @cindex voices, more on one staff
820 @cindex single staff polyphony
824 @funindex << ... \\ ... >>
829 Polyphonic music in lilypond, while not difficult, uses concepts
830 that we haven't discussed yet, so we're not going to introduce
831 them here. Instead, the following sections introduce these concepts
832 and explain them thoroughly.
835 Learning Manual: @ref{Voices contain music}.
837 Notation Reference: @ruser{Simultaneous notes}.
842 This section introduces vocal music and simple song sheets.
845 * Setting simple songs::
846 * Aligning lyrics to a melody::
847 * Lyrics to multiple staves::
851 @node Setting simple songs
852 @subsection Setting simple songs
860 Music Glossary: @rglos{lyrics}.
862 Here is the start of the melody to a nursery
863 rhyme, @notation{Girls and boys come out to play}:
865 @lilypond[verbatim,quote]
873 The @notation{lyrics} can be set to these notes, combining both
874 with the @code{\addlyrics} keyword. Lyrics are entered by
875 separating each syllable with a space.
877 @lilypond[verbatim,quote]
885 Girls and boys come out to play,
890 Note the curly brackets delimiting both the music and the lyrics.
891 It is essential that the final syllable is separated from the
892 terminating curly bracket by a space or a newline, or it will be
893 assumed to be part of the syllable, giving rise to an obscure
894 error, see @ref{Apparent error in ../ly/init.ly}.
896 Note also the double angle brackets @w{@code{<< ... >>}} around the
897 whole piece to show that the music and lyrics are to occur at the
900 @node Aligning lyrics to a melody
901 @subsection Aligning lyrics to a melody
904 @cindex extender line
907 @cindex lyrics, aligning
908 @cindex aligning lyrics
909 @cindex lyrics, multi-syllable words
910 @cindex words with multiple syllables in lyrics
912 Music Glossary: @rglos{melisma}, @rglos{extender line}.
914 The next line in the nursery rhyme is @notation{The moon doth
915 shine as bright as day}. Let's extend it:
917 @lilypond[verbatim,quote]
923 g8 a4 b8 c b a d4 b8 g4.
926 Girls and boys come out to play,
927 The moon doth shine as bright as day;
932 We see the extra lyrics do not align properly with the notes. The
933 word @notation{shine} should be sung on two notes, not one. This
934 is called a @notation{melisma}, a single syllable sung to more
935 than one note. There are several ways to spread a syllable over
936 multiple notes, the simplest being to add a slur across them, for
937 details, see @ref{Ties and slurs}:
939 @lilypond[verbatim,quote]
945 g8 a4 b8 c( b) a d4 b8 g4.
948 Girls and boys come out to play,
949 The moon doth shine as bright as day;
954 The words now line up correctly with the notes, but the automatic
955 beaming for the notes above @notation{shine as} does not look right.
956 We can correct this by inserting manual beaming commands to override
957 the automatic beaming here, for details, see @ref{Automatic and
960 @lilypond[verbatim,quote]
966 g8 a4 b8 c([ b]) a d4 b8 g4.
969 Girls and boys come out to play,
970 The moon doth shine as bright as day;
975 As an alternative to using slurs, the melismata may be indicated
976 in just the lyrics by using an underscore @code{_} for each note
977 that should be included in the melisma:
979 @lilypond[verbatim,quote]
985 g8 a4 b8 c[ b] a d4 b8 g4.
988 Girls and boys come out to play,
989 The moon doth shine _ as bright as day;
994 If a syllable extends over several notes or a single very long
995 note an @notation{extender line} is usually drawn from the
996 syllable extending under all the notes for that syllable. It is
997 entered as two underscores @code{__}. Here is an example from the
998 first three bars of @notation{Dido's Lament}, from Purcell's
999 @notation{Dido and Æneas}:
1001 @lilypond[verbatim,quote]
1007 b c4.( bes8 a4. g8 fis4.) g8 fis1
1011 am laid __ in earth,
1016 None of the examples so far have involved words containing more
1017 than one syllable. Such words are usually split one syllable to a
1018 note, with hyphens between syllables. Such hyphens are entered as
1019 two dashes, resulting in a centered hyphen between the syllables.
1020 Here is an example showing this and everything we have learned so
1021 far about aligning lyrics to notes.
1023 @c no ragged-right here because otherwise the hyphens get lost,
1024 @c but the example is long enough to avoid looking strange.
1025 @lilypond[verbatim,quote,noragged-right]
1031 d4 g4 g a8( b) g4 g4
1035 A -- way in a __ man -- ger,
1036 no __ crib for a bed, __
1041 Some lyrics, especially those in Italian, require the opposite:
1042 setting more than one syllable to a single note. This is
1043 achieved by linking the syllables together with a single
1044 underscore @code{_} (with no spaces), or enclosing them in quotes.
1045 Here's an example from Rossini's @notation{Figaro}, where
1046 @notation{al} has to be sung on the same note as the @notation{go} of
1047 @notation{Largo} in Figaro's aria @notation{Largo al factotum}:
1049 @c no ragged-right here because otherwise the hyphens get lost,
1050 @c but the example is long enough to avoid looking strange.
1051 @lilypond[verbatim,quote,noragged-right]
1057 c4.~ c8 d b c([ d]) b c d b c
1060 Lar -- go_al fac -- to -- tum del -- la cit -- tÃ
1067 Notation Reference: @ruser{Vocal music}.
1070 @node Lyrics to multiple staves
1071 @subsection Lyrics to multiple staves
1073 @cindex lyrics and multiple staves
1074 @cindex multiple staves and lyrics
1076 The simple approach using @code{\addlyrics} can be used for
1077 placing lyrics under more than one staff. Here is an
1078 example from Handel's @notation{Judas Maccabæus}:
1080 @lilypond[verbatim,quote]
1086 c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
1089 Let flee -- cy flocks the hills a -- dorn, __
1095 r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
1098 Let flee -- cy flocks the hills a -- dorn,
1103 Scores any more complex than this simple example are better
1104 produced by separating out the score structure from the notes and
1105 lyrics with variables. These are discussed in @ref{Organizing
1106 pieces with variables}.
1110 Notation Reference: @ruser{Vocal music}.
1114 @section Final touches
1116 This is the final section of the tutorial; it demonstrates how to
1117 add the final touches to simple pieces, and provides an
1118 introduction to the rest of the manual.
1121 * Organizing pieces with variables::
1124 * Absolute note names::
1125 * After the tutorial::
1129 @node Organizing pieces with variables
1130 @subsection Organizing pieces with variables
1133 @cindex variables, defining
1136 @cindex assigning variables
1137 @cindex using variables
1138 @cindex variables, using
1139 @cindex variables, characters allowed in
1140 @cindex characters allowed in variables
1142 When all of the elements discussed earlier are combined to produce
1143 larger files, the music expressions get a lot bigger. In
1144 polyphonic music with many staves, the input files can become very
1145 confusing. We can reduce this confusion by using
1148 With variables (also known as identifiers or macros), we can break
1149 up complex music expressions. A variable is assigned as
1153 namedMusic = @{ @dots{} @}
1156 The contents of the music expression @code{namedMusic} can be used
1157 later by placing a backslash in front of the name
1158 (@code{\namedMusic}, just like a normal LilyPond command).
1160 @lilypond[verbatim,quote]
1161 violin = \new Staff {
1166 cello = \new Staff {
1181 The name of a variable must have alphabetic characters only, no
1182 numbers, underscores, or dashes.
1184 Variables must be defined @emph{before} the main music
1185 expression, but may be used as many times as required anywhere after
1186 they have been defined. They may even be used in a later definition
1187 of another variable, giving a way of shortening the input if a
1188 section of music is repeated many times.
1190 @lilypond[verbatim,quote]
1191 tripletA = \times 2/3 { c,8 e g }
1192 barA = { \tripletA \tripletA \tripletA \tripletA }
1199 Variables may be used for many other types of objects in
1200 the input. For example,
1205 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1208 Depending on its contents, the variable can be used in different
1209 places. The following example uses the above variables:
1222 @node Version number
1223 @subsection Version number
1227 @cindex version number
1229 @cindex future upgrades
1230 @cindex updating files
1231 @cindex files, updating
1235 @funindex convert-ly
1237 The @code{\version} statement records the version of LilyPond that
1238 was used to write the file:
1241 \version @w{"@version{}"}
1245 By convention, this is placed at the top of your LilyPond file.
1247 These annotations make future upgrades of LilyPond go more
1248 smoothly. Changes in the syntax are handled with a special
1249 program, @command{convert-ly}, and it uses @code{\version} to
1250 determine what rules to apply. For details, see
1251 @rprogram{Updating files with convert-ly}.
1255 @subsection Adding titles
1259 @cindex header block
1264 The title, composer, opus number, and similar information are
1265 entered in the @code{\header} block. This exists outside of the
1266 main music expression; the @code{\header} block is usually placed
1267 underneath the version number.
1270 \version @w{"@version{}"}
1278 @dots{} music @dots{}
1282 When the file is processed, the title and composer are printed
1283 above the music. More information on titling can be found in
1284 @ruser{Creating titles}.
1287 @node Absolute note names
1288 @subsection Absolute note names
1291 @cindex note names, absolute
1292 @cindex absolute mode
1293 @cindex absolute values for pitches
1294 @cindex pitches, absolute values
1295 @cindex absolute note names
1297 So far we have always used @code{\relative} to define pitches.
1298 This is the easiest way to enter most music, but another way of
1299 defining pitches exists: absolute mode.
1301 If you omit the @code{\relative}, LilyPond treats all pitches as
1302 absolute values. A @code{c'} will always mean middle C, a
1303 @code{b} will always mean the note one step below middle C, and a
1304 @code{g,} will always mean the note on the bottom staff of the
1307 @lilypond[verbatim,quote]
1315 Here is a four-octave scale:
1317 @lilypond[verbatim,quote]
1332 As you can see, writing a melody in the treble clef involves a lot
1333 of quote @code{'} marks. Consider this fragment from Mozart:
1335 @lilypond[verbatim,quote]
1339 cis''8. d''16 cis''8 e''4 e''8
1340 b'8. cis''16 b'8 d''4 d''8
1344 All these quotes makes the input less readable and they are a source
1345 of errors. With @code{\relative}, the previous example is much
1346 easier to read and type:
1348 @lilypond[verbatim,quote]
1352 cis8. d16 cis8 e4 e8
1357 If you make a mistake with an octave mark (@code{'} or @code{,})
1358 while working in @code{\relative} mode, it is very obvious -- many
1359 notes will be in the wrong octave. When working in absolute mode,
1360 a single mistake will not be as visible, and will not be as easy
1363 However, absolute mode is useful for music which has large
1364 intervals, and is extremely useful for computer-generated LilyPond
1369 @node After the tutorial
1370 @subsection After the tutorial
1372 After finishing the tutorial, you should probably try writing a
1373 piece or two. Start by adding notes to one of the
1374 @ref{Templates}. If you need any notation that was not covered in
1375 the tutorial, look at the Notation Reference, starting with
1376 @ruser{Musical notation}. If you want to write for an instrument
1377 ensemble that is not covered in the templates, take a look at
1378 @ref{Extending the templates}.
1380 Once you have written a few short pieces, read the rest of the
1381 Learning Manual (chapters 3-5). There's nothing wrong with
1382 reading it now, of course! However, the rest of the Learning
1383 Manual assumes that you are familiar with LilyPond input. You may
1384 wish to skim these chapters right now, and come back to them after
1385 you have more experience.
1387 In this tutorial and in the rest of the Learning Manual, there is a
1388 paragraph @strong{See also} at the end of each section, which contains
1389 cross-references to other sections: you should not follow these
1390 cross-references at first reading; when you have read all of the
1391 Learning Manual, you may want to read some sections again and follow
1392 cross-references for further reading.
1394 If you have not done so already, @emph{please} read
1396 @c @ref{About the documentation}.
1397 There is a lot of information about LilyPond, so
1398 newcomers often do not know where they should look for help. If
1399 you spend five minutes reading that section carefully, you might
1400 save yourself hours of frustration looking in the wrong places!