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 chapter explains how to create beautiful printed music
35 containing common musical notation, following the material in
39 * Single staff notation::
40 * Multiple notes at once::
46 @node Single staff notation
47 @section Single staff notation
49 This section introduces common notation that is used for one voice
53 * Accidentals and key signatures::
55 * Articulation and dynamics::
57 * Automatic and manual beams::
58 * Advanced rhythmic commands::
62 @node Accidentals and key signatures
63 @subsection Accidentals and key signatures
65 @subheading Accidentals
68 @cindex accidentals and key signatures
81 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
82 @rglos{double flat}, @rglos{accidental}.
84 A @notation{sharp} pitch is made by adding @code{is} to the name,
85 and a @notation{flat} pitch by adding @code{es}. As you might
86 expect, a @notation{double sharp} or @notation{double flat} is
87 made by adding @code{isis} or @code{eses}. This syntax is derived
88 from note naming conventions in Nordic and Germanic languages,
89 like German and Dutch. To use other names for
90 @notation{accidentals}, see @ruser{Note names in other languages}.
92 @lilypond[verbatim,quote,relative=2]
96 @cindex key signature, setting
97 @subheading Key signatures
102 @cindex accidentals and key signature
103 @cindex content vs. layout
104 @cindex layout vs. content
113 Music Glossary: @rglos{key signature}, @rglos{major},
116 The @notation{key signature} is set with the command @code{\key}
117 followed by a pitch and @code{\major} or @code{\minor}.
119 @lilypond[verbatim,quote,relative=2]
128 @subheading Warning: key signatures and pitches
130 Music Glossary: @rglos{accidental}, @rglos{key signature},
131 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
132 @rglos{transposition}.
134 To determine whether to print an @notation{accidental}, LilyPond
135 examines the pitches and the @notation{key signature}. The key
136 signature only affects the @emph{printed} accidentals, not the
137 note's @notation{pitch}! This is a feature that often causes
138 confusion to newcomers, so let us explain it in more detail.
140 LilyPond makes a sharp distinction between musical content and
141 layout. The alteration (@notation{flat}, @notation{natural sign} or
142 @notation{sharp}) of a note is part of the pitch, and is therefore
143 musical content. Whether an accidental (a @emph{printed} flat,
144 natural or sharp sign) is printed in front of the corresponding
145 note is a question of layout. Layout is something that follows
146 rules, so accidentals are printed automatically according to those
147 rules. The pitches in your music are works of art, so they will
148 not be added automatically, and you must enter what you want to
153 @lilypond[verbatim,quote,relative=2]
159 No note has a printed accidental, but you must still add
160 @code{is} and type @code{cis} and @code{fis} in the input file.
162 The code @code{b} does not mean @qq{print a black dot just on
163 the middle line of the staff.} Rather, it means @qq{there is a
164 note with pitch B-natural.} In the key of A-flat major, it
165 @emph{does} get an accidental:
167 @lilypond[verbatim,quote,relative=2]
172 Adding all alterations explicitly might require a little more
173 effort when typing, but the advantage is that
174 @notation{transposing} is easier, and accidentals can be printed
175 according to different conventions. For some examples how
176 accidentals can be printed according to different rules, see
177 @ruser{Automatic accidentals}.
181 Notation Reference: @ruser{Note names in other languages},
182 @ruser{Accidentals}, @ruser{Automatic accidentals},
183 @ruser{Key signature}.
185 Music Glossary: @rglos{Pitch names}.
189 @subsection Ties and slurs
193 @cindex slur, phrasing
194 @cindex phrasing slur
203 Music Glossary: @rglos{tie}.
205 A @notation{tie} is created by appending a tilde @code{~} to the
206 first note being tied.
208 @lilypond[verbatim,quote,relative=2]
216 Music Glossary: @rglos{slur}.
218 A @notation{slur} is a curve drawn across many notes. The
219 starting note and ending note are marked with @code{(} and
220 @code{)} respectively.
222 @lilypond[verbatim,quote,relative=2]
223 d4( c16) cis( d e c cis d) e( d4)
226 @subheading Phrasing slurs
228 Music Glossary: @rglos{slur}, @rglos{phrasing}.
230 Slurs to indicate longer @notation{phrasing} can be entered with
231 @code{\(} and @code{\)}. You can have both @notation{slurs}
232 and phrasing slurs at the same time, but you cannot have
233 simultaneous slurs or simultaneous phrasing slurs.
235 @lilypond[verbatim,quote,relative=2]
236 a8(\( ais b c) cis2 b'2 a4 cis,\)
241 @cindex slurs versus ties
242 @subheading Warnings: slurs vs. ties
244 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
246 A @notation{slur} looks like a @notation{tie}, but it has a
247 different meaning. A tie simply makes the first note longer, and
248 can only be used on pairs of notes with the same pitch. Slurs
249 indicate the @notation{articulation} of notes, and can be used on
250 larger groups of notes. Slurs and ties can be nested.
252 @lilypond[verbatim,quote,relative=2]
253 c2~( c8 fis fis4 ~ fis2 g2)
258 Notation Reference: @ruser{Ties}, @ruser{Slurs},
259 @ruser{Phrasing slurs}.
262 @node Articulation and dynamics
263 @subsection Articulation and dynamics
266 @subheading Articulations
272 Music Glossary: @rglos{articulation}.
274 Common @notation{articulations} can be added to a note using a
275 dash @code{-} and a single character:
277 @lilypond[verbatim,quote,relative=2]
278 c-. c-- c-> c-^ c-+ c-_
281 @subheading Fingerings
288 Music Glossary: @rglos{fingering}.
290 Similarly, @notation{fingering} indications can be added to a note
291 using a dash (@code{-}) and the digit to be printed:
293 @lilypond[verbatim,quote,relative=2]
297 Articulations and fingerings are usually placed automatically, but
298 you can specify a direction by replacing the dash (@code{-}) with
299 @code{^} (up) or @code{_} (down). You can also use multiple
300 articulations on the same note. However, in most cases it is best
301 to let LilyPond determine the articulation directions.
303 @lilypond[verbatim,quote,relative=2]
304 c_-^1 d^. f^4_2-> e^-_+
326 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
329 @notation{Dynamic} signs are made by adding the markings (with a
330 backslash) to the note:
332 @lilypond[verbatim,quote,relative=2]
337 @notation{Crescendi} and @notation{decrescendi} are started with
338 the commands @code{\<} and @code{\>}. The next dynamics sign, for
339 example @code{\f}, will end the (de)crescendo, or the command
340 @code{\!} can be used:
342 @lilypond[verbatim,quote,relative=2]
348 Notation Reference: @ruser{Articulations and ornamentations},
349 @ruser{Fingering instructions}, @ruser{Dynamics}.
353 @subsection Adding text
362 Text may be added to your scores:
364 @lilypond[verbatim,quote,relative=2]
368 Extra formatting may be added with the @code{\markup} command:
370 @lilypond[verbatim,quote,relative=2]
371 c1^\markup{ \bold espr}
373 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
379 Notation Reference: @ruser{Writing text}.
382 @node Automatic and manual beams
383 @subsection Automatic and manual beams
386 @cindex automatic beams
388 @cindex beams, automatic
389 @cindex beams, manual
390 @cindex beams, by hand
395 @funindex \autoBeamOff
396 @funindex autoBeamOff
397 @funindex \autoBeamOn
400 Music Glossary: @rglos{beam}.
402 All @notation{beams} are drawn automatically:
404 @lilypond[verbatim,quote,relative=2]
405 a8 ais d ees r d c16 b a8
408 If you do not like the automatic beams, they may be overridden
409 manually. To correct just an occasional beam mark the first note
410 to be beamed with @code{[} and the last one with @code{]}.
412 @lilypond[verbatim,quote,relative=2]
413 a8[ ais] d[ ees r d] a b
416 If you want to turn off automatic beaming entirely or for an
417 extended section of music, use the command @code{\autoBeamOff}
418 to turn off automatic beaming and @code{\autoBeamOn} to turn it
421 @lilypond[verbatim,quote,relative=2]
430 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
433 @node Advanced rhythmic commands
434 @subsection Advanced rhythmic commands
436 @subheading Partial measure
440 @cindex partial measure
445 Music Glossary: @rglos{anacrusis}.
447 A pickup (or @notation{anacrusis}) is entered with the keyword
448 @code{\partial}. It is followed by a duration: @code{\partial 4}
449 is a quarter note pickup and @code{\partial 8} an eighth note.
451 @lilypond[verbatim,quote,relative=2]
464 Music Glossary: @rglos{note value}, @rglos{triplet}.
466 @notation{Tuplets} are made with the @code{\times} keyword. It
467 takes two arguments: a fraction and a piece of music. The
468 duration of the piece of music is multiplied by the fraction.
469 Triplets make notes occupy 2/3 of their notated duration, so a
470 @notation{triplet} has 2/3 as its fraction
472 @lilypond[verbatim,quote,relative=2]
473 \times 2/3 { f8 g a }
475 \times 2/3 { f,8 g16[ a g a] }
479 @subheading Grace notes
487 @funindex \acciaccatura
488 @funindex acciaccatura
489 @funindex \appoggiatura
490 @funindex acciaccatura
492 Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
493 @rglos{appoggiatura}.
495 @notation{Grace notes} are created with the @code{\grace} command,
496 although they can also be created by prefixing a music expression
497 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
499 @lilypond[verbatim,quote,relative=2]
500 c2 \grace { a32[ b] } c2
501 c2 \appoggiatura b16 c2
502 c2 \acciaccatura b16 c2
507 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
511 @node Multiple notes at once
512 @section Multiple notes at once
514 This section introduces having more than one note at the same
515 time: multiple instruments, multiple staves for a single
516 instrument (i.e. piano), and chords.
518 Polyphony in music refers to having more than one voice occurring
519 in a piece of music. Polyphony in LilyPond refers to having more
520 than one voice on the same staff.
523 * Music expressions explained::
526 * Combining notes into chords::
527 * Single staff polyphony::
531 @node Music expressions explained
532 @subsection Music expressions explained
534 @cindex music expression
535 @cindex expression, music
536 @cindex compound music expression
537 @cindex music expression, compound
539 In LilyPond input files, music is represented by @emph{music
540 expressions}. A single note is a music expression:
542 @lilypond[verbatim,quote,relative=2]
546 Enclosing a note in braces creates a @emph{compound music
547 expression}. Here we have created a compound music expression
550 @lilypond[verbatim,quote,relative=2]
554 Putting a group of music expressions (e.g. notes) in braces means
555 that they are in sequence (i.e. each one follows the previous
556 one). The result is another music expression:
558 @lilypond[verbatim,quote,relative=2]
562 @subheading Analogy: mathematical expressions
564 This mechanism is similar to mathematical formulas: a big formula
565 is created by composing small formulas. Such formulas are called
566 expressions, and they can contain other expressions, so you can
567 make arbitrarily complex and large expressions. For example,
576 ((1 + 2) * 3) / (4 * 5)
579 This is a sequence of expressions, where each expression is
580 contained in the next (larger) one. The simplest expressions are
581 numbers, and larger ones are made by combining expressions with
582 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
583 Like mathematical expressions, music expressions can be nested
584 arbitrarily deep, which is necessary for complex music like
588 @subheading Simultaneous music expressions: multiple staves
590 @cindex multiple staves
591 @cindex staves, multiple
593 @cindex combining expressions in parallel
594 @cindex parallel expressions
595 @cindex expressions, parallel
596 @cindex relative notes and simultaneous music
597 @cindex relative notes and parallel expressions
598 @cindex simultaneous music and relative notes
599 @cindex parallel expressions and relative notes
605 Music Glossary: @rglos{polyphony}.
607 This technique is useful for @notation{polyphonic} music. To
608 enter music with more voices or more staves, we combine
609 expressions in parallel. To indicate that two voices should play
610 at the same time, simply enter a simultaneous combination of music
611 expressions. A @q{simultaneous} music expression is formed by
612 enclosing expressions inside @code{<<} and @code{>>}. In the
613 following example, three sequences (all containing two separate
614 notes) are combined simultaneously:
616 @lilypond[verbatim,quote]
626 Note that we have indented each level of the input with a
627 different amount of space. LilyPond does not care how much (or
628 little) space there is at the beginning of a line, but indenting
629 LilyPond code like this makes it much easier for humans to read.
631 @warning{each note is relative to the previous note in
632 the input, not relative to the @code{c''} in the initial
633 @code{@bs{}relative} command.}
636 @subheading Simultaneous music expressions: single staff
638 To determine the number of staves in a piece, LilyPond looks at
639 the beginning of the first expression. If there is a single note,
640 there is one staff; if there is a simultaneous expression, there
641 is more than one staff. The following example shows a complex
642 expression, but as it begins with a single note it will be set
643 out on a single staff.
645 @lilypond[verbatim,quote]
648 << { e f } { c <<b d>> } >>
652 @node Multiple staves
653 @subsection Multiple staves
655 @cindex multiple staves
656 @cindex staves, multiple
658 @cindex context, notation
659 @cindex notation context
671 LilyPond input files are constructed out of music expressions, as
672 we saw in @ref{Music expressions explained}. If the score begins
673 with simultaneous music expressions, LilyPond creates multiples
674 staves. However, it is easier to see what happens if we create
675 each staff explicitly.
677 To print more than one staff, each piece of music that makes up a
678 staff is marked by adding @code{\new Staff} before it. These
679 @code{Staff} elements are then combined in parallel with @code{<<}
682 @lilypond[verbatim,quote]
685 \new Staff { \clef treble c }
686 \new Staff { \clef bass c,, }
691 The command @code{\new} introduces a @q{notation context.} A
692 notation context is an environment in which musical events (like
693 notes or @code{\clef} commands) are interpreted. For simple
694 pieces, such notation contexts are created automatically. For
695 more complex pieces, it is best to mark contexts explicitly.
697 There are several types of contexts. @code{Score}, @code{Staff},
698 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
699 lyric texts and @code{ChordNames} prints chord names.
701 In terms of syntax, prepending @code{\new} to a music expression
702 creates a bigger music expression. In this way it resembles the
703 minus sign in mathematics. The formula @math{(4+5)} is an
704 expression, so @math{-(4+5)} is a bigger expression.
706 Time signatures entered in one staff affects all other staves by
707 default. On the other hand, the key signature of one staff does
708 @emph{not} affect other staves. This different default behavior
709 is because scores with transposing instruments are more common
710 than polyrhythmic scores.
712 @lilypond[verbatim,quote]
715 \new Staff { \clef treble \key d \major \time 3/4 c }
716 \new Staff { \clef bass c,, }
725 @subsection Staff groups
739 Music Glossary: @rglos{brace}.
741 Piano music is typeset in two staves connected by a
743 Printing such a staff is similar to the polyphonic example in
744 @ref{Multiple staves}. However, now this entire expression is
745 inserted inside a @code{PianoStaff}:
754 Here is a small example:
756 @lilypond[verbatim,quote]
759 \new Staff { \time 2/4 c4 e g g, }
760 \new Staff { \clef bass c,, c' e c }
765 Other staff groupings are introduced with @code{\new GrandStaff},
766 suitable for orchestral scores, and @w{@code{\new ChoirStaff}},
767 suitable for vocal scores. These staff groups each form another
768 type of context, one that generates the brace at the left end of
769 every system and also controls the extent of bar lines.
773 Notation Reference: @ruser{Keyboard and other multi-staff
775 @ruser{Displaying staves}.
778 @node Combining notes into chords
779 @subsection Combining notes into chords
782 @cindex note durations in chords
788 Music Glossary: @rglos{chord}.
790 We saw earlier how notes can be combined into @notation{chords} by
791 indicating they are simultaneous by enclosing them in double angle
792 brackets. However, the normal way of indicating a chord is to
793 surround the pitches with @emph{single} angle brackets. Note that
794 all the notes in a chord must have the same duration, and that the
795 duration is placed after the closing bracket.
797 @lilypond[verbatim,quote,relative=2]
801 Think of chords as almost equivalent to single notes:
802 almost everything you can attach to a single note can be attached
803 to a chord, and everything must go @emph{outside} the angle
804 brackets. For example, you can combine markings like beams and
805 ties with chords. They must be placed outside the angle brackets.
807 @lilypond[verbatim,quote,relative=2]
808 r4 <c e g>8[ <c f a>]~ <c f a>2
809 r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
813 @node Single staff polyphony
814 @subsection Single staff polyphony
817 @cindex multiple voices
818 @cindex voices, more on one staff
819 @cindex single staff polyphony
823 @funindex << ... \\ ... >>
828 Polyphonic music in lilypond, while not difficult, uses concepts
829 that we haven't discussed yet, so we're not going to introduce
830 them here. Instead, the following sections introduce these concepts
831 and explain them thoroughly.
834 Learning Manual: @ref{Voices contain music}.
836 Notation Reference: @ruser{Simultaneous notes}.
841 This section introduces vocal music and simple song sheets.
844 * Setting simple songs::
845 * Aligning lyrics to a melody::
846 * Lyrics to multiple staves::
850 @node Setting simple songs
851 @subsection Setting simple songs
859 Music Glossary: @rglos{lyrics}.
861 Here is the start of the melody to a nursery
862 rhyme, @notation{Girls and boys come out to play}:
864 @lilypond[verbatim,quote]
872 The @notation{lyrics} can be set to these notes, combining both
873 with the @code{\addlyrics} keyword. Lyrics are entered by
874 separating each syllable with a space.
876 @lilypond[verbatim,quote]
884 Girls and boys come out to play,
889 Note the curly brackets delimiting both the music and the lyrics.
890 It is essential that the final syllable is separated from the
891 terminating curly bracket by a space or a newline, or it will be
892 assumed to be part of the syllable, giving rise to an obscure
893 error, see @rprogram{Apparent error in ../ly/init.ly}.
895 Note also the double angle brackets @w{@code{<< ... >>}} around the
896 whole piece to show that the music and lyrics are to occur at the
899 @node Aligning lyrics to a melody
900 @subsection Aligning lyrics to a melody
903 @cindex extender line
906 @cindex lyrics, aligning
907 @cindex aligning lyrics
908 @cindex lyrics, multi-syllable words
909 @cindex words with multiple syllables in lyrics
911 Music Glossary: @rglos{melisma}, @rglos{extender line}.
913 The next line in the nursery rhyme is @notation{The moon doth
914 shine as bright as day}. Let's extend it:
916 @lilypond[verbatim,quote]
922 g8 a4 b8 c b a d4 b8 g4.
925 Girls and boys come out to play,
926 The moon doth shine as bright as day;
931 We see the extra lyrics do not align properly with the notes. The
932 word @notation{shine} should be sung on two notes, not one. This
933 is called a @notation{melisma}, a single syllable sung to more
934 than one note. There are several ways to spread a syllable over
935 multiple notes, the simplest being to add a slur across them, for
936 details, see @ref{Ties and slurs}:
938 @lilypond[verbatim,quote]
944 g8 a4 b8 c( b) a d4 b8 g4.
947 Girls and boys come out to play,
948 The moon doth shine as bright as day;
953 The words now line up correctly with the notes, but the automatic
954 beaming for the notes above @notation{shine as} does not look right.
955 We can correct this by inserting manual beaming commands to override
956 the automatic beaming here, for details, see @ref{Automatic and
959 @lilypond[verbatim,quote]
965 g8 a4 b8 c([ b]) a d4 b8 g4.
968 Girls and boys come out to play,
969 The moon doth shine as bright as day;
974 As an alternative to using slurs, the melismata may be indicated
975 in just the lyrics by using an underscore @code{_} for each note
976 that should be included in the melisma:
978 @lilypond[verbatim,quote]
984 g8 a4 b8 c[ b] a d4 b8 g4.
987 Girls and boys come out to play,
988 The moon doth shine _ as bright as day;
993 If a syllable extends over several notes or a single very long
994 note an @notation{extender line} is usually drawn from the
995 syllable extending under all the notes for that syllable. It is
996 entered as two underscores @code{__}. Here is an example from the
997 first three bars of @notation{Dido's Lament}, from Purcell's
998 @notation{Dido and Æneas}:
1000 @lilypond[verbatim,quote]
1006 b c4.( bes8 a4. g8 fis4.) g8 fis1
1010 am laid __ in earth,
1015 None of the examples so far have involved words containing more
1016 than one syllable. Such words are usually split one syllable to a
1017 note, with hyphens between syllables. Such hyphens are entered as
1018 two dashes, resulting in a centered hyphen between the syllables.
1019 Here is an example showing this and everything we have learned so
1020 far about aligning lyrics to notes.
1022 @c no ragged-right here because otherwise the hyphens get lost,
1023 @c but the example is long enough to avoid looking strange.
1024 @lilypond[verbatim,quote,noragged-right]
1030 d4 g4 g a8( b) g4 g4
1034 A -- way in a __ man -- ger,
1035 no __ crib for a bed, __
1040 Some lyrics, especially those in Italian, require the opposite:
1041 setting more than one syllable to a single note. This is
1042 achieved by linking the syllables together with a single
1043 underscore @code{_} (with no spaces), or enclosing them in quotes.
1044 Here's an example from Rossini's @notation{Figaro}, where
1045 @notation{al} has to be sung on the same note as the @notation{go} of
1046 @notation{Largo} in Figaro's aria @notation{Largo al factotum}:
1048 @c no ragged-right here because otherwise the hyphens get lost,
1049 @c but the example is long enough to avoid looking strange.
1050 @lilypond[verbatim,quote,noragged-right]
1056 c4.~ c8 d b c([ d]) b c d b c
1059 Lar -- go_al fac -- to -- tum del -- la cit -- tÃ
1066 Notation Reference: @ruser{Vocal music}.
1069 @node Lyrics to multiple staves
1070 @subsection Lyrics to multiple staves
1072 @cindex lyrics and multiple staves
1073 @cindex multiple staves and lyrics
1075 The simple approach using @code{\addlyrics} can be used for
1076 placing lyrics under more than one staff. Here is an
1077 example from Handel's @notation{Judas Maccabæus}:
1079 @lilypond[verbatim,quote]
1085 c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
1088 Let flee -- cy flocks the hills a -- dorn, __
1094 r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
1097 Let flee -- cy flocks the hills a -- dorn,
1102 Scores any more complex than this simple example are better
1103 produced by separating out the score structure from the notes and
1104 lyrics with variables. These are discussed in @ref{Organizing
1105 pieces with variables}.
1109 Notation Reference: @ruser{Vocal music}.
1113 @section Final touches
1115 This is the final section of the tutorial; it demonstrates how to
1116 add the final touches to simple pieces, and provides an
1117 introduction to the rest of the manual.
1120 * Organizing pieces with variables::
1123 * Absolute note names::
1124 * After the tutorial::
1128 @node Organizing pieces with variables
1129 @subsection Organizing pieces with variables
1132 @cindex variables, defining
1135 @cindex assigning variables
1136 @cindex using variables
1137 @cindex variables, using
1138 @cindex variables, characters allowed in
1139 @cindex characters allowed in variables
1141 When all of the elements discussed earlier are combined to produce
1142 larger files, the music expressions get a lot bigger. In
1143 polyphonic music with many staves, the input files can become very
1144 confusing. We can reduce this confusion by using
1147 With variables (also known as identifiers or macros), we can break
1148 up complex music expressions. A variable is assigned as
1152 namedMusic = @{ @dots{} @}
1155 The contents of the music expression @code{namedMusic} can be used
1156 later by placing a backslash in front of the name
1157 (@code{\namedMusic}, just like a normal LilyPond command).
1159 @lilypond[verbatim,quote]
1160 violin = \new Staff {
1165 cello = \new Staff {
1180 The name of a variable must have alphabetic characters only, no
1181 numbers, underscores, or dashes.
1183 Variables must be defined @emph{before} the main music
1184 expression, but may be used as many times as required anywhere after
1185 they have been defined. They may even be used in a later definition
1186 of another variable, giving a way of shortening the input if a
1187 section of music is repeated many times.
1189 @lilypond[verbatim,quote]
1190 tripletA = \times 2/3 { c,8 e g }
1191 barA = { \tripletA \tripletA \tripletA \tripletA }
1198 Variables may be used for many other types of objects in
1199 the input. For example,
1204 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1207 Depending on its contents, the variable can be used in different
1208 places. The following example uses the above variables:
1221 @node Version number
1222 @subsection Version number
1226 @cindex version number
1228 @cindex future upgrades
1229 @cindex updating files
1230 @cindex files, updating
1234 @funindex convert-ly
1236 The @code{\version} statement records the version of LilyPond that
1237 was used to write the file:
1240 \version @w{"@version{}"}
1244 By convention, this is placed at the top of your LilyPond file.
1246 These annotations make future upgrades of LilyPond go more
1247 smoothly. Changes in the syntax are handled with a special
1248 program, @command{convert-ly}, and it uses @code{\version} to
1249 determine what rules to apply. For details, see
1250 @rprogram{Updating files with convert-ly}.
1254 @subsection Adding titles
1258 @cindex header block
1263 The title, composer, opus number, and similar information are
1264 entered in the @code{\header} block. This exists outside of the
1265 main music expression; the @code{\header} block is usually placed
1266 underneath the version number.
1269 \version @w{"@version{}"}
1277 @dots{} music @dots{}
1281 When the file is processed, the title and composer are printed
1282 above the music. More information on titling can be found in
1283 @ruser{Creating titles}.
1286 @node Absolute note names
1287 @subsection Absolute note names
1290 @cindex note names, absolute
1291 @cindex absolute mode
1292 @cindex absolute values for pitches
1293 @cindex pitches, absolute values
1294 @cindex absolute note names
1296 So far we have always used @code{\relative} to define pitches.
1297 This is the easiest way to enter most music, but another way of
1298 defining pitches exists: absolute mode.
1300 If you omit the @code{\relative}, LilyPond treats all pitches as
1301 absolute values. A @code{c'} will always mean middle C, a
1302 @code{b} will always mean the note one step below middle C, and a
1303 @code{g,} will always mean the note on the bottom staff of the
1306 @lilypond[verbatim,quote]
1314 Here is a four-octave scale:
1316 @lilypond[verbatim,quote]
1331 As you can see, writing a melody in the treble clef involves a lot
1332 of quote @code{'} marks. Consider this fragment from Mozart:
1334 @lilypond[verbatim,quote]
1338 cis''8. d''16 cis''8 e''4 e''8
1339 b'8. cis''16 b'8 d''4 d''8
1343 All these quotes makes the input less readable and they are a source
1344 of errors. With @code{\relative}, the previous example is much
1345 easier to read and type:
1347 @lilypond[verbatim,quote]
1351 cis8. d16 cis8 e4 e8
1356 If you make a mistake with an octave mark (@code{'} or @code{,})
1357 while working in @code{\relative} mode, it is very obvious -- many
1358 notes will be in the wrong octave. When working in absolute mode,
1359 a single mistake will not be as visible, and will not be as easy
1362 However, absolute mode is useful for music which has large
1363 intervals, and is extremely useful for computer-generated LilyPond
1368 @node After the tutorial
1369 @subsection After the tutorial
1371 After finishing the tutorial, you should probably try writing a
1372 piece or two. Start by adding notes to one of the
1373 @ref{Templates}. If you need any notation that was not covered in
1374 the tutorial, look at the Notation Reference, starting with
1375 @ruser{Musical notation}. If you want to write for an instrument
1376 ensemble that is not covered in the templates, take a look at
1377 @ref{Extending the templates}.
1379 Once you have written a few short pieces, read the rest of the
1380 Learning Manual (chapters 3-5). There's nothing wrong with
1381 reading it now, of course! However, the rest of the Learning
1382 Manual assumes that you are familiar with LilyPond input. You may
1383 wish to skim these chapters right now, and come back to them after
1384 you have more experience.
1386 In this tutorial and in the rest of the Learning Manual, there is a
1387 paragraph @strong{See also} at the end of each section, which contains
1388 cross-references to other sections: you should not follow these
1389 cross-references at first reading; when you have read all of the
1390 Learning Manual, you may want to read some sections again and follow
1391 cross-references for further reading.
1393 If you have not done so already, @emph{please} read
1395 @c @ref{About the documentation}.
1396 There is a lot of information about LilyPond, so
1397 newcomers often do not know where they should look for help. If
1398 you spend five minutes reading that section carefully, you might
1399 save yourself hours of frustration looking in the wrong places!