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 @warning{New users are often confused by these -- please read the
66 warning at the bottom of this page, especially if you are not
67 familiar with music theory!}
69 @subheading Accidentals
72 @cindex accidentals and key signatures
85 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
86 @rglos{double flat}, @rglos{accidental}.
88 A @notation{sharp} pitch is made by adding @code{is} to the name,
89 and a @notation{flat} pitch by adding @code{es}. As you might
90 expect, a @notation{double sharp} or @notation{double flat} is
91 made by adding @code{isis} or @code{eses}. This syntax is derived
92 from note naming conventions in Nordic and Germanic languages,
93 like German and Dutch. To use other names for
94 @notation{accidentals}, see @ruser{Note names in other languages}.
96 @lilypond[verbatim,quote,relative=2]
100 @cindex key signature, setting
101 @subheading Key signatures
103 @cindex key signature
106 @cindex accidentals and key signature
107 @cindex content vs. layout
108 @cindex layout vs. content
117 Music Glossary: @rglos{key signature}, @rglos{major},
120 The @notation{key signature} is set with the command @code{\key}
121 followed by a pitch and @code{\major} or @code{\minor}.
123 @lilypond[verbatim,quote,relative=2]
132 @subheading Warning: key signatures and pitches
134 Music Glossary: @rglos{accidental}, @rglos{key signature},
135 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
136 @rglos{transposition}.
138 To determine whether to print an @notation{accidental}, LilyPond
139 examines the pitches and the @notation{key signature}. The key
140 signature only affects the @emph{printed} accidentals, not the
141 note's @notation{pitch}! This is a feature that often causes
142 confusion to newcomers, so let us explain it in more detail.
144 LilyPond makes a sharp distinction between musical content and
145 layout. The alteration (@notation{flat}, @notation{natural sign} or
146 @notation{sharp}) of a note is part of the pitch, and is therefore
147 musical content. Whether an accidental (a @emph{printed} flat,
148 natural or sharp sign) is printed in front of the corresponding
149 note is a question of layout. Layout is something that follows
150 rules, so accidentals are printed automatically according to those
151 rules. The pitches in your music are works of art, so they will
152 not be added automatically, and you must enter what you want to
157 @lilypond[verbatim,quote,relative=2]
163 No note has a printed accidental, but you must still add
164 @code{is} and type @code{cis} and @code{fis} in the input file.
166 The code @code{b} does not mean @qq{print a black dot just on
167 the middle line of the staff.} Rather, it means @qq{there is a
168 note with pitch B-natural.} In the key of A-flat major, it
169 @emph{does} get an accidental:
171 @lilypond[verbatim,quote,relative=2]
176 If the above seems confusing, consider this: if you were playing a
177 piano, which key would you hit? If you would press a black key,
178 then you @emph{must} add @code{-is} or @code{-es} to the note
181 Adding all alterations explicitly might require a little more
182 effort when typing, but the advantage is that
183 @notation{transposing} is easier, and accidentals can be printed
184 according to different conventions. For some examples of how
185 accidentals can be printed according to different rules, see
186 @ruser{Automatic accidentals}.
190 Notation Reference: @ruser{Note names in other languages},
191 @ruser{Accidentals}, @ruser{Automatic accidentals},
192 @ruser{Key signature}.
194 Music Glossary: @rglos{Pitch names}.
198 @subsection Ties and slurs
202 @cindex slur, phrasing
203 @cindex phrasing slur
212 Music Glossary: @rglos{tie}.
214 A @notation{tie} is created by appending a tilde @code{~} to the
215 first note being tied.
217 @lilypond[verbatim,quote,relative=2]
225 Music Glossary: @rglos{slur}.
227 A @notation{slur} is a curve drawn across many notes. The
228 starting note and ending note are marked with @code{(} and
229 @code{)} respectively.
231 @lilypond[verbatim,quote,relative=2]
232 d4( c16) cis( d e c cis d) e( d4)
235 @subheading Phrasing slurs
237 Music Glossary: @rglos{slur}, @rglos{phrasing}.
239 Slurs to indicate longer @notation{phrasing} can be entered with
240 @code{\(} and @code{\)}. You can have both @notation{slurs}
241 and phrasing slurs at the same time, but you cannot have
242 simultaneous slurs or simultaneous phrasing slurs.
244 @lilypond[verbatim,quote,relative=2]
245 a8(\( ais b c) cis2 b'2 a4 cis,\)
250 @cindex slurs versus ties
251 @subheading Warnings: slurs vs. ties
253 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
255 A @notation{slur} looks like a @notation{tie}, but it has a
256 different meaning. A tie simply makes the first note longer, and
257 can only be used on pairs of notes with the same pitch. Slurs
258 indicate the @notation{articulation} of notes, and can be used on
259 larger groups of notes. Slurs and ties can be nested.
261 @lilypond[verbatim,quote,relative=2]
262 c2~( c8 fis fis4 ~ fis2 g2)
267 Notation Reference: @ruser{Ties}, @ruser{Slurs},
268 @ruser{Phrasing slurs}.
271 @node Articulation and dynamics
272 @subsection Articulation and dynamics
275 @subheading Articulations
281 Music Glossary: @rglos{articulation}.
283 Common @notation{articulations} can be added to a note using a
284 dash @code{-} and a single character:
286 @lilypond[verbatim,quote,relative=2]
287 c-. c-- c-> c-^ c-+ c-_
290 @subheading Fingerings
297 Music Glossary: @rglos{fingering}.
299 Similarly, @notation{fingering} indications can be added to a note
300 using a dash (@code{-}) and the digit to be printed:
302 @lilypond[verbatim,quote,relative=2]
306 Articulations and fingerings are usually placed automatically, but
307 you can specify a direction by replacing the dash (@code{-}) with
308 @code{^} (up) or @code{_} (down). You can also use multiple
309 articulations on the same note. However, in most cases it is best
310 to let LilyPond determine the articulation directions.
312 @lilypond[verbatim,quote,relative=2]
313 c_-^1 d^. f^4_2-> e^-_+
335 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
338 @notation{Dynamic} signs are made by adding the markings (with a
339 backslash) to the note:
341 @lilypond[verbatim,quote,relative=2]
346 @notation{Crescendi} and @notation{decrescendi} are started with
347 the commands @code{\<} and @code{\>}. The next dynamics sign, for
348 example @code{\f}, will end the (de)crescendo, or the command
349 @code{\!} can be used:
351 @lilypond[verbatim,quote,relative=2]
357 Notation Reference: @ruser{Articulations and ornamentations},
358 @ruser{Fingering instructions}, @ruser{Dynamics}.
362 @subsection Adding text
371 Text may be added to your scores:
373 @lilypond[verbatim,quote,relative=2]
377 Extra formatting may be added with the @code{\markup} command:
379 @lilypond[verbatim,quote,relative=2]
380 c1^\markup{ \bold espr}
382 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
388 Notation Reference: @ruser{Writing text}.
391 @node Automatic and manual beams
392 @subsection Automatic and manual beams
395 @cindex automatic beams
397 @cindex beams, automatic
398 @cindex beams, manual
399 @cindex beams, by hand
404 @funindex \autoBeamOff
405 @funindex autoBeamOff
406 @funindex \autoBeamOn
409 Music Glossary: @rglos{beam}.
411 All @notation{beams} are drawn automatically:
413 @lilypond[verbatim,quote,relative=2]
414 a8 ais d ees r d c16 b a8
417 If you do not like the automatic beams, they may be overridden
418 manually. To correct just an occasional beam mark the first note
419 to be beamed with @code{[} and the last one with @code{]}.
421 @lilypond[verbatim,quote,relative=2]
422 a8[ ais] d[ ees r d] a b
425 If you want to turn off automatic beaming entirely or for an
426 extended section of music, use the command @code{\autoBeamOff}
427 to turn off automatic beaming and @code{\autoBeamOn} to turn it
430 @lilypond[verbatim,quote,relative=2]
439 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
442 @node Advanced rhythmic commands
443 @subsection Advanced rhythmic commands
445 @subheading Partial measure
449 @cindex partial measure
454 Music Glossary: @rglos{anacrusis}.
456 A pickup (or @notation{anacrusis}) is entered with the keyword
457 @code{\partial}. It is followed by a duration: @code{\partial 4}
458 is a quarter note pickup and @code{\partial 8} an eighth note.
460 @lilypond[verbatim,quote,relative=2]
473 Music Glossary: @rglos{note value}, @rglos{triplet}.
475 @notation{Tuplets} are made with the @code{\times} keyword. It
476 takes two arguments: a fraction and a piece of music. The
477 duration of the piece of music is multiplied by the fraction.
478 Triplets make notes occupy 2/3 of their notated duration, so a
479 @notation{triplet} has 2/3 as its fraction
481 @lilypond[verbatim,quote,relative=2]
482 \times 2/3 { f8 g a }
484 \times 2/3 { f,8 g16[ a g a] }
488 @subheading Grace notes
496 @funindex \acciaccatura
497 @funindex acciaccatura
498 @funindex \appoggiatura
499 @funindex acciaccatura
501 Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
502 @rglos{appoggiatura}.
504 @notation{Grace notes} are created with the @code{\grace} command,
505 although they can also be created by prefixing a music expression
506 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
508 @lilypond[verbatim,quote,relative=2]
509 c2 \grace { a32[ b] } c2
510 c2 \appoggiatura b16 c2
511 c2 \acciaccatura b16 c2
516 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
520 @node Multiple notes at once
521 @section Multiple notes at once
523 This section introduces having more than one note at the same
524 time: multiple instruments, multiple staves for a single
525 instrument (i.e. piano), and chords.
527 Polyphony in music refers to having more than one voice occurring
528 in a piece of music. Polyphony in LilyPond refers to having more
529 than one voice on the same staff.
532 * Music expressions explained::
535 * Combining notes into chords::
536 * Single staff polyphony::
540 @node Music expressions explained
541 @subsection Music expressions explained
543 @cindex music expression
544 @cindex expression, music
545 @cindex compound music expression
546 @cindex music expression, compound
548 In LilyPond input files, music is represented by @emph{music
549 expressions}. A single note is a music expression:
551 @lilypond[verbatim,quote,relative=2]
555 Enclosing a note in braces creates a @emph{compound music
556 expression}. Here we have created a compound music expression
559 @lilypond[verbatim,quote,relative=2]
563 Putting a group of music expressions (e.g. notes) in braces means
564 that they are in sequence (i.e. each one follows the previous
565 one). The result is another music expression:
567 @lilypond[verbatim,quote,relative=2]
571 @subheading Analogy: mathematical expressions
573 This mechanism is similar to mathematical formulas: a big formula
574 is created by composing small formulas. Such formulas are called
575 expressions, and they can contain other expressions, so you can
576 make arbitrarily complex and large expressions. For example,
585 ((1 + 2) * 3) / (4 * 5)
588 This is a sequence of expressions, where each expression is
589 contained in the next (larger) one. The simplest expressions are
590 numbers, and larger ones are made by combining expressions with
591 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
592 Like mathematical expressions, music expressions can be nested
593 arbitrarily deep, which is necessary for complex music like
597 @subheading Simultaneous music expressions: multiple staves
599 @cindex multiple staves
600 @cindex staves, multiple
602 @cindex combining expressions in parallel
603 @cindex parallel expressions
604 @cindex expressions, parallel
605 @cindex relative notes and simultaneous music
606 @cindex relative notes and parallel expressions
607 @cindex simultaneous music and relative notes
608 @cindex parallel expressions and relative notes
614 Music Glossary: @rglos{polyphony}.
616 This technique is useful for @notation{polyphonic} music. To
617 enter music with more voices or more staves, we combine
618 expressions in parallel. To indicate that two voices should play
619 at the same time, simply enter a simultaneous combination of music
620 expressions. A @q{simultaneous} music expression is formed by
621 enclosing expressions inside @code{<<} and @code{>>}. In the
622 following example, three sequences (all containing two separate
623 notes) are combined simultaneously:
625 @lilypond[verbatim,quote]
635 Note that we have indented each level of the input with a
636 different amount of space. LilyPond does not care how much (or
637 little) space there is at the beginning of a line, but indenting
638 LilyPond code like this makes it much easier for humans to read.
640 @warning{each note is relative to the previous note in
641 the input, not relative to the @code{c''} in the initial
642 @code{@bs{}relative} command.}
645 @subheading Simultaneous music expressions: single staff
647 To determine the number of staves in a piece, LilyPond looks at
648 the beginning of the first expression. If there is a single note,
649 there is one staff; if there is a simultaneous expression, there
650 is more than one staff. The following example shows a complex
651 expression, but as it begins with a single note it will be set
652 out on a single staff.
654 @lilypond[verbatim,quote]
657 << { e f } { c <<b d>> } >>
661 @node Multiple staves
662 @subsection Multiple staves
664 @cindex multiple staves
665 @cindex staves, multiple
667 @cindex context, notation
668 @cindex notation context
680 LilyPond input files are constructed out of music expressions, as
681 we saw in @ref{Music expressions explained}. If the score begins
682 with simultaneous music expressions, LilyPond creates multiples
683 staves. However, it is easier to see what happens if we create
684 each staff explicitly.
686 To print more than one staff, each piece of music that makes up a
687 staff is marked by adding @code{\new Staff} before it. These
688 @code{Staff} elements are then combined in parallel with @code{<<}
691 @lilypond[verbatim,quote]
694 \new Staff { \clef treble c }
695 \new Staff { \clef bass c,, }
700 The command @code{\new} introduces a @q{notation context.} A
701 notation context is an environment in which musical events (like
702 notes or @code{\clef} commands) are interpreted. For simple
703 pieces, such notation contexts are created automatically. For
704 more complex pieces, it is best to mark contexts explicitly.
706 There are several types of contexts. @code{Score}, @code{Staff},
707 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
708 lyric texts and @code{ChordNames} prints chord names.
710 In terms of syntax, prepending @code{\new} to a music expression
711 creates a bigger music expression. In this way it resembles the
712 minus sign in mathematics. The formula @math{(4+5)} is an
713 expression, so @math{-(4+5)} is a bigger expression.
715 Time signatures entered in one staff affect all other staves by
716 default. On the other hand, the key signature of one staff does
717 @emph{not} affect other staves. This different default behavior
718 is because scores with transposing instruments are more common
719 than polyrhythmic scores.
721 @lilypond[verbatim,quote]
724 \new Staff { \clef treble \key d \major \time 3/4 c }
725 \new Staff { \clef bass c,, }
734 @subsection Staff groups
748 Music Glossary: @rglos{brace}.
750 Piano music is typeset in two staves connected by a
752 Printing such a staff is similar to the polyphonic example in
753 @ref{Multiple staves}. However, now this entire expression is
754 inserted inside a @code{PianoStaff}:
763 Here is a small example:
765 @lilypond[verbatim,quote]
768 \new Staff { \time 2/4 c4 e g g, }
769 \new Staff { \clef bass c,, c' e c }
774 Other staff groupings are introduced with @code{\new GrandStaff},
775 suitable for orchestral scores, and @w{@code{\new ChoirStaff}},
776 suitable for vocal scores. These staff groups each form another
777 type of context, one that generates the brace at the left end of
778 every system and also controls the extent of bar lines.
782 Notation Reference: @ruser{Keyboard and other multi-staff
784 @ruser{Displaying staves}.
787 @node Combining notes into chords
788 @subsection Combining notes into chords
791 @cindex note durations in chords
797 Music Glossary: @rglos{chord}.
799 We saw earlier how notes can be combined into @notation{chords} by
800 indicating they are simultaneous by enclosing them in double angle
801 brackets. However, the normal way of indicating a chord is to
802 surround the pitches with @emph{single} angle brackets. Note that
803 all the notes in a chord must have the same duration, and that the
804 duration is placed after the closing bracket.
806 @lilypond[verbatim,quote,relative=2]
810 Think of chords as almost equivalent to single notes:
811 almost everything you can attach to a single note can be attached
812 to a chord, and everything must go @emph{outside} the angle
813 brackets. For example, you can combine markings like beams and
814 ties with chords. They must be placed outside the angle brackets.
816 @lilypond[verbatim,quote,relative=2]
817 r4 <c e g>8[ <c f a>]~ <c f a>2
818 r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
822 @node Single staff polyphony
823 @subsection Single staff polyphony
826 @cindex multiple voices
827 @cindex voices, more on one staff
828 @cindex single staff polyphony
832 @funindex << ... \\ ... >>
837 Polyphonic music in lilypond, while not difficult, uses concepts
838 that we haven't discussed yet, so we're not going to introduce
839 them here. Instead, the following sections introduce these concepts
840 and explain them thoroughly.
843 Learning Manual: @ref{Voices contain music}.
845 Notation Reference: @ruser{Simultaneous notes}.
850 This section introduces vocal music and simple song sheets.
853 * Setting simple songs::
854 * Aligning lyrics to a melody::
855 * Lyrics to multiple staves::
859 @node Setting simple songs
860 @subsection Setting simple songs
868 Music Glossary: @rglos{lyrics}.
870 Here is the start of the melody to a nursery
871 rhyme, @notation{Girls and boys come out to play}:
873 @lilypond[verbatim,quote]
881 The @notation{lyrics} can be set to these notes, combining both
882 with the @code{\addlyrics} keyword. Lyrics are entered by
883 separating each syllable with a space.
885 @lilypond[verbatim,quote]
893 Girls and boys come out to play,
898 Note the curly brackets delimiting both the music and the lyrics.
899 It is essential that the final syllable is separated from the
900 terminating curly bracket by a space or a newline, or it will be
901 assumed to be part of the syllable, giving rise to an obscure
902 error, see @rprogram{Apparent error in ../ly/init.ly}.
904 Note also the double angle brackets @w{@code{<< ... >>}} around the
905 whole piece to show that the music and lyrics are to occur at the
908 @node Aligning lyrics to a melody
909 @subsection Aligning lyrics to a melody
912 @cindex extender line
915 @cindex lyrics, aligning
916 @cindex aligning lyrics
917 @cindex lyrics, multi-syllable words
918 @cindex words with multiple syllables in lyrics
920 Music Glossary: @rglos{melisma}, @rglos{extender line}.
922 The next line in the nursery rhyme is @notation{The moon doth
923 shine as bright as day}. Let's extend it:
925 @lilypond[verbatim,quote]
931 g8 a4 b8 c b a d4 b8 g4.
934 Girls and boys come out to play,
935 The moon doth shine as bright as day;
940 We see the extra lyrics do not align properly with the notes. The
941 word @notation{shine} should be sung on two notes, not one. This
942 is called a @notation{melisma}, a single syllable sung to more
943 than one note. There are several ways to spread a syllable over
944 multiple notes, the simplest being to add a slur across them, for
945 details, see @ref{Ties and slurs}:
947 @lilypond[verbatim,quote]
953 g8 a4 b8 c( b) a d4 b8 g4.
956 Girls and boys come out to play,
957 The moon doth shine as bright as day;
962 The words now line up correctly with the notes, but the automatic
963 beaming for the notes above @notation{shine as} does not look right.
964 We can correct this by inserting manual beaming commands to override
965 the automatic beaming here, for details, see @ref{Automatic and
968 @lilypond[verbatim,quote]
974 g8 a4 b8 c([ b]) a d4 b8 g4.
977 Girls and boys come out to play,
978 The moon doth shine as bright as day;
983 As an alternative to using slurs, the melismata may be indicated
984 in just the lyrics by using an underscore @code{_} for each note
985 that should be included in the melisma:
987 @lilypond[verbatim,quote]
993 g8 a4 b8 c[ b] a d4 b8 g4.
996 Girls and boys come out to play,
997 The moon doth shine _ as bright as day;
1002 If a syllable extends over several notes or a single very long
1003 note an @notation{extender line} is usually drawn from the
1004 syllable extending under all the notes for that syllable. It is
1005 entered as two underscores @code{__}. Here is an example from the
1006 first three bars of @notation{Dido's Lament}, from Purcell's
1007 @notation{Dido and Æneas}:
1009 @lilypond[verbatim,quote]
1015 b c4.( bes8 a4. g8 fis4.) g8 fis1
1019 am laid __ in earth,
1024 None of the examples so far have involved words containing more
1025 than one syllable. Such words are usually split one syllable to a
1026 note, with hyphens between syllables. Such hyphens are entered as
1027 two dashes, resulting in a centered hyphen between the syllables.
1028 Here is an example showing this and everything we have learned so
1029 far about aligning lyrics to notes.
1031 @c no ragged-right here because otherwise the hyphens get lost,
1032 @c but the example is long enough to avoid looking strange.
1033 @lilypond[verbatim,quote,noragged-right]
1039 d4 g4 g a8( b) g4 g4
1043 A -- way in a __ man -- ger,
1044 no __ crib for a bed, __
1049 Some lyrics, especially those in Italian, require the opposite:
1050 setting more than one syllable to a single note. This is
1051 achieved by linking the syllables together with a single
1052 underscore @code{_} (with no spaces), or enclosing them in quotes.
1053 Here's an example from Rossini's @notation{Figaro}, where
1054 @notation{al} has to be sung on the same note as the @notation{go} of
1055 @notation{Largo} in Figaro's aria @notation{Largo al factotum}:
1057 @c no ragged-right here because otherwise the hyphens get lost,
1058 @c but the example is long enough to avoid looking strange.
1059 @lilypond[verbatim,quote,noragged-right]
1065 c4.~ c8 d b c([ d]) b c d b c
1068 Lar -- go_al fac -- to -- tum del -- la cit -- tÃ
1075 Notation Reference: @ruser{Vocal music}.
1078 @node Lyrics to multiple staves
1079 @subsection Lyrics to multiple staves
1081 @cindex lyrics and multiple staves
1082 @cindex multiple staves and lyrics
1084 The simple approach using @code{\addlyrics} can be used for
1085 placing lyrics under more than one staff. Here is an
1086 example from Handel's @notation{Judas Maccabæus}:
1088 @lilypond[verbatim,quote]
1094 c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
1097 Let flee -- cy flocks the hills a -- dorn, __
1103 r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
1106 Let flee -- cy flocks the hills a -- dorn,
1111 Scores any more complex than this simple example are better
1112 produced by separating out the score structure from the notes and
1113 lyrics with variables. These are discussed in @ref{Organizing
1114 pieces with variables}.
1118 Notation Reference: @ruser{Vocal music}.
1122 @section Final touches
1124 This is the final section of the tutorial; it demonstrates how to
1125 add the final touches to simple pieces, and provides an
1126 introduction to the rest of the manual.
1129 * Organizing pieces with variables::
1131 * Absolute note names::
1132 * After the tutorial::
1136 @node Organizing pieces with variables
1137 @subsection Organizing pieces with variables
1140 @cindex variables, defining
1143 @cindex assigning variables
1144 @cindex using variables
1145 @cindex variables, using
1146 @cindex variables, characters allowed in
1147 @cindex characters allowed in variables
1149 When all of the elements discussed earlier are combined to produce
1150 larger files, the music expressions get a lot bigger. In
1151 polyphonic music with many staves, the input files can become very
1152 confusing. We can reduce this confusion by using
1155 With variables (also known as identifiers or macros), we can break
1156 up complex music expressions. A variable is assigned as
1160 namedMusic = @{ @dots{} @}
1163 The contents of the music expression @code{namedMusic} can be used
1164 later by placing a backslash in front of the name
1165 (@code{\namedMusic}, just like a normal LilyPond command).
1167 @lilypond[verbatim,quote]
1168 violin = \new Staff {
1173 cello = \new Staff {
1188 The name of a variable must have alphabetic characters only, no
1189 numbers, underscores, or dashes.
1191 Variables must be defined @emph{before} the main music
1192 expression, but may be used as many times as required anywhere after
1193 they have been defined. They may even be used in a later definition
1194 of another variable, giving a way of shortening the input if a
1195 section of music is repeated many times.
1197 @lilypond[verbatim,quote]
1198 tripletA = \times 2/3 { c,8 e g }
1199 barA = { \tripletA \tripletA \tripletA \tripletA }
1206 Variables may be used for many other types of objects in
1207 the input. For example,
1212 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1215 Depending on its contents, the variable can be used in different
1216 places. The following example uses the above variables:
1230 @subsection Adding titles
1234 @cindex header block
1239 The title, composer, opus number, and similar information are
1240 entered in the @code{\header} block. This exists outside of the
1241 main music expression; the @code{\header} block is usually placed
1242 underneath the version number.
1245 \version @w{"@version{}"}
1253 @dots{} music @dots{}
1257 When the file is processed, the title and composer are printed
1258 above the music. More information on titling can be found in
1259 @ruser{Creating titles}.
1262 @node Absolute note names
1263 @subsection Absolute note names
1266 @cindex note names, absolute
1267 @cindex absolute mode
1268 @cindex absolute values for pitches
1269 @cindex pitches, absolute values
1270 @cindex absolute note names
1272 So far we have always used @code{\relative} to define pitches.
1273 This is the easiest way to enter most music, but another way of
1274 defining pitches exists: absolute mode.
1276 If you omit the @code{\relative}, LilyPond treats all pitches as
1277 absolute values. A @code{c'} will always mean middle C, a
1278 @code{b} will always mean the note one step below middle C, and a
1279 @code{g,} will always mean the note on the bottom staff of the
1282 @lilypond[verbatim,quote]
1290 Here is a four-octave scale:
1292 @lilypond[verbatim,quote]
1307 As you can see, writing a melody in the treble clef involves a lot
1308 of quote @code{'} marks. Consider this fragment from Mozart:
1310 @lilypond[verbatim,quote]
1314 cis''8. d''16 cis''8 e''4 e''8
1315 b'8. cis''16 b'8 d''4 d''8
1319 All these quotes makes the input less readable and they are a source
1320 of errors. With @code{\relative}, the previous example is much
1321 easier to read and type:
1323 @lilypond[verbatim,quote]
1327 cis8. d16 cis8 e4 e8
1332 If you make a mistake with an octave mark (@code{'} or @code{,})
1333 while working in @code{\relative} mode, it is very obvious -- many
1334 notes will be in the wrong octave. When working in absolute mode,
1335 a single mistake will not be as visible, and will not be as easy
1338 However, absolute mode is useful for music which has large
1339 intervals, and is extremely useful for computer-generated LilyPond
1344 @node After the tutorial
1345 @subsection After the tutorial
1347 After finishing the tutorial, you should probably try writing a
1348 piece or two. Start by adding notes to one of the
1349 @ref{Templates}. If you need any notation that was not covered in
1350 the tutorial, look at the Notation Reference, starting with
1351 @ruser{Musical notation}. If you want to write for an instrument
1352 ensemble that is not covered in the templates, take a look at
1353 @ref{Extending the templates}.
1355 Once you have written a few short pieces, read the rest of the
1356 Learning Manual (chapters 3-5). There's nothing wrong with
1357 reading it now, of course! However, the rest of the Learning
1358 Manual assumes that you are familiar with LilyPond input. You may
1359 wish to skim these chapters right now, and come back to them after
1360 you have more experience.
1362 In this tutorial and in the rest of the Learning Manual, there is a
1363 paragraph @strong{See also} at the end of each section, which contains
1364 cross-references to other sections: you should not follow these
1365 cross-references at first reading; when you have read all of the
1366 Learning Manual, you may want to read some sections again and follow
1367 cross-references for further reading.
1369 If you have not done so already, @emph{please} read @ref{Overview
1370 of manuals}. There is a lot of information about LilyPond, so
1371 newcomers often do not know where they should look for help. If
1372 you spend five minutes reading that section carefully, you might
1373 save yourself hours of frustration looking in the wrong places!