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. For details, see the Contributors'
8 Guide, node Updating translation committishes..
14 Tutorial guidelines: (different from policy.txt!)
15 - unless you have a really good reason, use either
16 @lilypond[verbatim,quote]
18 @lilypond[verbatim,quote,relative=2]
20 Don't use any other relative=X commands.
22 - use "aes" and "ees" instead of "as" and "es". I know it's not
23 correct Dutch naming, but let's not confuse people with this
24 until we get to the Basic notation chapter.
26 - Add "Music Glossary: @rglos{foo}" to the *top* of the relevant
27 portions of the tutorial.
33 @chapter Common notation
35 This chapter explains how to create beautiful printed music
36 containing common musical notation, following the material in
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 @warning{New users are often confused by these -- please read the
67 warning at the bottom of this page, especially if you are not
68 familiar with music theory!}
70 @subheading Accidentals
73 @cindex accidentals and key signatures
86 Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
87 @rglos{double flat}, @rglos{accidental}.
89 A @notation{sharp} pitch is made by adding @code{is} to the name,
90 and a @notation{flat} pitch by adding @code{es}. As you might
91 expect, a @notation{double sharp} or @notation{double flat} is
92 made by adding @code{isis} or @code{eses}. This syntax is derived
93 from note naming conventions in Nordic and Germanic languages,
94 like German and Dutch. To use other names for
95 @notation{accidentals}, see @ruser{Note names in other languages}.
97 @lilypond[verbatim,quote,relative=2]
101 @cindex key signature, setting
102 @subheading Key signatures
104 @cindex key signature
107 @cindex accidentals and key signature
108 @cindex content vs. layout
109 @cindex layout vs. content
118 Music Glossary: @rglos{key signature}, @rglos{major},
121 The @notation{key signature} is set with the command @code{\key}
122 followed by a pitch and @code{\major} or @code{\minor}.
124 @lilypond[verbatim,quote,relative=2]
133 @subheading Warning: key signatures and pitches
135 Music Glossary: @rglos{accidental}, @rglos{key signature},
136 @rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
137 @rglos{transposition}.
139 To determine whether to print an @notation{accidental}, LilyPond
140 examines the pitches and the @notation{key signature}. The key
141 signature only affects the @emph{printed} accidentals, not the
142 note's @notation{pitch}! This is a feature that often causes
143 confusion to newcomers, so let us explain it in more detail.
145 LilyPond makes a sharp distinction between musical content and
146 layout. The alteration (@notation{flat}, @notation{natural sign} or
147 @notation{sharp}) of a note is part of the pitch, and is therefore
148 musical content. Whether an accidental (a @emph{printed} flat,
149 natural or sharp sign) is printed in front of the corresponding
150 note is a question of layout. Layout is something that follows
151 rules, so accidentals are printed automatically according to those
152 rules. The pitches in your music are works of art, so they will
153 not be added automatically, and you must enter what you want to
158 @lilypond[verbatim,quote,relative=2]
164 No note has a printed accidental, but you must still add
165 @code{is} and type @code{cis} and @code{fis} in the input file.
167 The code @code{b} does not mean @qq{print a black dot just on
168 the middle line of the staff.} Rather, it means @qq{there is a
169 note with pitch B-natural.} In the key of A-flat major, it
170 @emph{does} get an accidental:
172 @lilypond[verbatim,quote,relative=2]
177 If the above seems confusing, consider this: if you were playing a
178 piano, which key would you hit? If you would press a black key,
179 then you @emph{must} add @code{-is} or @code{-es} to the note
182 Adding all alterations explicitly might require a little more
183 effort when typing, but the advantage is that
184 @notation{transposing} is easier, and accidentals can be printed
185 according to different conventions. For some examples of how
186 accidentals can be printed according to different rules, see
187 @ruser{Automatic accidentals}.
191 Notation Reference: @ruser{Note names in other languages},
192 @ruser{Accidentals}, @ruser{Automatic accidentals},
193 @ruser{Key signature}.
195 Music Glossary: @rglos{Pitch names}.
199 @subsection Ties and slurs
203 @cindex slur, phrasing
204 @cindex phrasing slur
213 Music Glossary: @rglos{tie}.
215 A @notation{tie} is created by appending a tilde @code{~} to the
216 first note being tied.
218 @lilypond[verbatim,quote,relative=2]
226 Music Glossary: @rglos{slur}.
228 A @notation{slur} is a curve drawn across many notes. The
229 starting note and ending note are marked with @code{(} and
230 @code{)} respectively.
232 @lilypond[verbatim,quote,relative=2]
233 d4( c16) cis( d e c cis d) e( d4)
236 @subheading Phrasing slurs
238 Music Glossary: @rglos{slur}, @rglos{phrasing}.
240 Slurs to indicate longer @notation{phrasing} can be entered with
241 @code{\(} and @code{\)}. You can have both @notation{slurs}
242 and phrasing slurs at the same time, but you cannot have
243 simultaneous slurs or simultaneous phrasing slurs.
245 @lilypond[verbatim,quote,relative=2]
246 a8(\( ais b c) cis2 b'2 a4 cis,\)
251 @cindex slurs versus ties
252 @subheading Warnings: slurs vs. ties
254 Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}.
256 A @notation{slur} looks like a @notation{tie}, but it has a
257 different meaning. A tie simply makes the first note longer, and
258 can only be used on pairs of notes with the same pitch. Slurs
259 indicate the @notation{articulation} of notes, and can be used on
260 larger groups of notes. Slurs and ties can be nested.
262 @lilypond[verbatim,quote,relative=2]
263 c2~( c8 fis fis4 ~ fis2 g2)
268 Notation Reference: @ruser{Ties}, @ruser{Slurs},
269 @ruser{Phrasing slurs}.
272 @node Articulation and dynamics
273 @subsection Articulation and dynamics
276 @subheading Articulations
282 Music Glossary: @rglos{articulation}.
284 Common @notation{articulations} can be added to a note using a
285 dash @code{-} and a single character:
287 @lilypond[verbatim,quote,relative=2]
288 c-. c-- c-> c-^ c-+ c-_
291 @subheading Fingerings
298 Music Glossary: @rglos{fingering}.
300 Similarly, @notation{fingering} indications can be added to a note
301 using a dash (@code{-}) and the digit to be printed:
303 @lilypond[verbatim,quote,relative=2]
307 Articulations and fingerings are usually placed automatically, but
308 you can specify a direction by replacing the dash (@code{-}) with
309 @code{^} (up) or @code{_} (down). You can also use multiple
310 articulations on the same note. However, in most cases it is best
311 to let LilyPond determine the articulation directions.
313 @lilypond[verbatim,quote,relative=2]
314 c_-^1 d^. f^4_2-> e^-_+
336 Music Glossary: @rglos{dynamics}, @rglos{crescendo},
339 @notation{Dynamic} signs are made by adding the markings (with a
340 backslash) to the note:
342 @lilypond[verbatim,quote,relative=2]
347 @notation{Crescendi} and @notation{decrescendi} are started with
348 the commands @code{\<} and @code{\>}. The next dynamics sign, for
349 example @code{\f}, will end the (de)crescendo, or the command
350 @code{\!} can be used:
352 @lilypond[verbatim,quote,relative=2]
358 Notation Reference: @ruser{Articulations and ornamentations},
359 @ruser{Fingering instructions}, @ruser{Dynamics}.
363 @subsection Adding text
372 Text may be added to your scores:
374 @lilypond[verbatim,quote,relative=2]
378 Extra formatting may be added with the @code{\markup} command:
380 @lilypond[verbatim,quote,relative=2]
381 c1^\markup{ \bold espr}
383 \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
389 Notation Reference: @ruser{Writing text}.
392 @node Automatic and manual beams
393 @subsection Automatic and manual beams
396 @cindex automatic beams
398 @cindex beams, automatic
399 @cindex beams, manual
400 @cindex beams, by hand
405 @funindex \autoBeamOff
406 @funindex autoBeamOff
407 @funindex \autoBeamOn
410 Music Glossary: @rglos{beam}.
412 All @notation{beams} are drawn automatically:
414 @lilypond[verbatim,quote,relative=2]
415 a8 ais d ees r d c16 b a8
418 If you do not like the automatic beams, they may be overridden
419 manually. To correct just an occasional beam mark the first note
420 to be beamed with @code{[} and the last one with @code{]}.
422 @lilypond[verbatim,quote,relative=2]
423 a8[ ais] d[ ees r d] a b
426 If you want to turn off automatic beaming entirely or for an
427 extended section of music, use the command @code{\autoBeamOff}
428 to turn off automatic beaming and @code{\autoBeamOn} to turn it
431 @lilypond[verbatim,quote,relative=2]
440 Notation Reference: @ruser{Automatic beams}, @ruser{Manual beams}.
443 @node Advanced rhythmic commands
444 @subsection Advanced rhythmic commands
446 @subheading Partial measure
450 @cindex partial measure
455 Music Glossary: @rglos{anacrusis}.
457 A pickup (or @notation{anacrusis}) is entered with the keyword
458 @code{\partial}. It is followed by a duration: @code{\partial 4}
459 is a quarter note pickup and @code{\partial 8} an eighth note.
461 @lilypond[verbatim,quote,relative=2]
474 Music Glossary: @rglos{note value}, @rglos{triplet}.
476 @notation{Tuplets} are made with the @code{\times} keyword. It
477 takes two arguments: a fraction and a piece of music. The
478 duration of the piece of music is multiplied by the fraction.
479 Triplets make notes occupy 2/3 of their notated duration, so a
480 @notation{triplet} has 2/3 as its fraction
482 @lilypond[verbatim,quote,relative=2]
483 \times 2/3 { f8 g a }
485 \times 2/3 { f,8 g16[ a g a] }
489 @subheading Grace notes
497 @funindex \acciaccatura
498 @funindex acciaccatura
499 @funindex \appoggiatura
500 @funindex acciaccatura
502 Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},
503 @rglos{appoggiatura}.
505 @notation{Grace notes} are created with the @code{\grace} command,
506 although they can also be created by prefixing a music expression
507 with the keyword @code{\appoggiatura} or @code{\acciaccatura}:
509 @lilypond[verbatim,quote,relative=2]
510 c2 \grace { a32[ b] } c2
511 c2 \appoggiatura b16 c2
512 c2 \acciaccatura b16 c2
517 Notation Reference: @ruser{Grace notes}, @ruser{Tuplets},
521 @node Multiple notes at once
522 @section Multiple notes at once
524 This section introduces having more than one note at the same
525 time: multiple instruments, multiple staves for a single
526 instrument (i.e. piano), and chords.
528 Polyphony in music refers to having more than one voice occurring
529 in a piece of music. Polyphony in LilyPond refers to having more
530 than one voice on the same staff.
533 * Music expressions explained::
536 * Combining notes into chords::
537 * Single staff polyphony::
541 @node Music expressions explained
542 @subsection Music expressions explained
544 @cindex music expression
545 @cindex expression, music
546 @cindex compound music expression
547 @cindex music expression, compound
549 In LilyPond input files, music is represented by @emph{music
550 expressions}. A single note is a music expression:
552 @lilypond[verbatim,quote,relative=2]
556 Enclosing a note in braces creates a @emph{compound music
557 expression}. Here we have created a compound music expression
560 @lilypond[verbatim,quote,relative=2]
564 Putting a group of music expressions (e.g. notes) in braces means
565 that they are in sequence (i.e. each one follows the previous
566 one). The result is another music expression:
568 @lilypond[verbatim,quote,relative=2]
572 @subheading Analogy: mathematical expressions
574 This mechanism is similar to mathematical formulas: a big formula
575 is created by composing small formulas. Such formulas are called
576 expressions, and they can contain other expressions, so you can
577 make arbitrarily complex and large expressions. For example,
586 ((1 + 2) * 3) / (4 * 5)
589 This is a sequence of expressions, where each expression is
590 contained in the next (larger) one. The simplest expressions are
591 numbers, and larger ones are made by combining expressions with
592 operators (like @code{+}, @code{*} and @code{/}) and parentheses.
593 Like mathematical expressions, music expressions can be nested
594 arbitrarily deep, which is necessary for complex music like
598 @subheading Simultaneous music expressions: multiple staves
600 @cindex multiple staves
601 @cindex staves, multiple
603 @cindex combining expressions in parallel
604 @cindex parallel expressions
605 @cindex expressions, parallel
606 @cindex relative notes and simultaneous music
607 @cindex relative notes and parallel expressions
608 @cindex simultaneous music and relative notes
609 @cindex parallel expressions and relative notes
615 Music Glossary: @rglos{polyphony}.
617 This technique is useful for @notation{polyphonic} music. To
618 enter music with more voices or more staves, we combine
619 expressions in parallel. To indicate that two voices should play
620 at the same time, simply enter a simultaneous combination of music
621 expressions. A @q{simultaneous} music expression is formed by
622 enclosing expressions inside @code{<<} and @code{>>}. In the
623 following example, three sequences (all containing two separate
624 notes) are combined simultaneously:
626 @lilypond[verbatim,quote]
636 Note that we have indented each level of the input with a
637 different amount of space. LilyPond does not care how much (or
638 little) space there is at the beginning of a line, but indenting
639 LilyPond code like this makes it much easier for humans to read.
641 @warning{each note is relative to the previous note in
642 the input, not relative to the @code{c''} in the initial
643 @code{@bs{}relative} command.}
646 @subheading Simultaneous music expressions: single staff
648 To determine the number of staves in a piece, LilyPond looks at
649 the beginning of the first expression. If there is a single note,
650 there is one staff; if there is a simultaneous expression, there
651 is more than one staff. The following example shows a complex
652 expression, but as it begins with a single note it will be set
653 out on a single staff.
655 @lilypond[verbatim,quote]
658 << { e f } { c <<b d>> } >>
662 @node Multiple staves
663 @subsection Multiple staves
665 @cindex multiple staves
666 @cindex staves, multiple
668 @cindex context, notation
669 @cindex notation context
681 LilyPond input files are constructed out of music expressions, as
682 we saw in @ref{Music expressions explained}. If the score begins
683 with simultaneous music expressions, LilyPond creates multiples
684 staves. However, it is easier to see what happens if we create
685 each staff explicitly.
687 To print more than one staff, each piece of music that makes up a
688 staff is marked by adding @code{\new Staff} before it. These
689 @code{Staff} elements are then combined in parallel with @code{<<}
692 @lilypond[verbatim,quote]
695 \new Staff { \clef treble c }
696 \new Staff { \clef bass c,, }
701 The command @code{\new} introduces a @q{notation context.} A
702 notation context is an environment in which musical events (like
703 notes or @code{\clef} commands) are interpreted. For simple
704 pieces, such notation contexts are created automatically. For
705 more complex pieces, it is best to mark contexts explicitly.
707 There are several types of contexts. @code{Score}, @code{Staff},
708 and @code{Voice} handle melodic notation, while @code{Lyrics} sets
709 lyric texts and @code{ChordNames} prints chord names.
711 In terms of syntax, prepending @code{\new} to a music expression
712 creates a bigger music expression. In this way it resembles the
713 minus sign in mathematics. The formula @math{(4+5)} is an
714 expression, so @math{-(4+5)} is a bigger expression.
716 Time signatures entered in one staff affect all other staves by
717 default. On the other hand, the key signature of one staff does
718 @emph{not} affect other staves. This different default behavior
719 is because scores with transposing instruments are more common
720 than polyrhythmic scores.
722 @lilypond[verbatim,quote]
725 \new Staff { \clef treble \key d \major \time 3/4 c }
726 \new Staff { \clef bass c,, }
735 @subsection Staff groups
749 Music Glossary: @rglos{brace}.
751 Piano music is typeset in two staves connected by a
753 Printing such a staff is similar to the polyphonic example in
754 @ref{Multiple staves}. However, now this entire expression is
755 inserted inside a @code{PianoStaff}:
764 Here is a small example:
766 @lilypond[verbatim,quote]
769 \new Staff { \time 2/4 c4 e g g, }
770 \new Staff { \clef bass c,, c' e c }
775 Other staff groupings are introduced with @code{\new GrandStaff},
776 suitable for orchestral scores, and @w{@code{\new ChoirStaff}},
777 suitable for vocal scores. These staff groups each form another
778 type of context, one that generates the brace at the left end of
779 every system and also controls the extent of bar lines.
783 Notation Reference: @ruser{Keyboard and other multi-staff
785 @ruser{Displaying staves}.
788 @node Combining notes into chords
789 @subsection Combining notes into chords
792 @cindex note durations in chords
798 Music Glossary: @rglos{chord}.
800 We saw earlier how notes can be combined into @notation{chords} by
801 indicating they are simultaneous by enclosing them in double angle
802 brackets. However, the normal way of indicating a chord is to
803 surround the pitches with @emph{single} angle brackets. Note that
804 all the notes in a chord must have the same duration, and that the
805 duration is placed after the closing bracket.
807 @lilypond[verbatim,quote,relative=2]
811 Think of chords as almost equivalent to single notes:
812 almost everything you can attach to a single note can be attached
813 to a chord, and everything must go @emph{outside} the angle
814 brackets. For example, you can combine markings like beams and
815 ties with chords. They must be placed outside the angle brackets.
817 @lilypond[verbatim,quote,relative=2]
818 r4 <c e g>8[ <c f a>]~ <c f a>2
819 r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
823 @node Single staff polyphony
824 @subsection Single staff polyphony
827 @cindex multiple voices
828 @cindex voices, more on one staff
829 @cindex single staff polyphony
833 @funindex << ... \\ ... >>
838 Polyphonic music in lilypond, while not difficult, uses concepts
839 that we haven't discussed yet, so we're not going to introduce
840 them here. Instead, the following sections introduce these concepts
841 and explain them thoroughly.
844 Learning Manual: @ref{Voices contain music}.
846 Notation Reference: @ruser{Simultaneous notes}.
851 This section introduces vocal music and simple song sheets.
854 * Setting simple songs::
855 * Aligning lyrics to a melody::
856 * Lyrics to multiple staves::
860 @node Setting simple songs
861 @subsection Setting simple songs
869 Music Glossary: @rglos{lyrics}.
871 Here is the start of the melody to a nursery
872 rhyme, @notation{Girls and boys come out to play}:
874 @lilypond[verbatim,quote]
882 The @notation{lyrics} can be set to these notes, combining both
883 with the @code{\addlyrics} keyword. Lyrics are entered by
884 separating each syllable with a space.
886 @lilypond[verbatim,quote]
894 Girls and boys come out to play,
899 Note the curly brackets delimiting both the music and the lyrics.
900 It is essential that the final syllable is separated from the
901 terminating curly bracket by a space or a newline, or it will be
902 assumed to be part of the syllable, giving rise to an obscure
903 error, see @rprogram{Apparent error in ../ly/init.ly}.
905 Note also the double angle brackets @w{@code{<< ... >>}} around the
906 whole piece to show that the music and lyrics are to occur at the
909 @node Aligning lyrics to a melody
910 @subsection Aligning lyrics to a melody
913 @cindex extender line
916 @cindex lyrics, aligning
917 @cindex aligning lyrics
918 @cindex lyrics, multi-syllable words
919 @cindex words with multiple syllables in lyrics
921 Music Glossary: @rglos{melisma}, @rglos{extender line}.
923 The next line in the nursery rhyme is @notation{The moon doth
924 shine as bright as day}. Let's extend it:
926 @lilypond[verbatim,quote]
932 g8 a4 b8 c b a d4 b8 g4.
935 Girls and boys come out to play,
936 The moon doth shine as bright as day;
941 We see the extra lyrics do not align properly with the notes. The
942 word @notation{shine} should be sung on two notes, not one. This
943 is called a @notation{melisma}, a single syllable sung to more
944 than one note. There are several ways to spread a syllable over
945 multiple notes, the simplest being to add a slur across them, for
946 details, see @ref{Ties and slurs}:
948 @lilypond[verbatim,quote]
954 g8 a4 b8 c( b) a d4 b8 g4.
957 Girls and boys come out to play,
958 The moon doth shine as bright as day;
963 The words now line up correctly with the notes, but the automatic
964 beaming for the notes above @notation{shine as} does not look right.
965 We can correct this by inserting manual beaming commands to override
966 the automatic beaming here, for details, see @ref{Automatic and
969 @lilypond[verbatim,quote]
975 g8 a4 b8 c([ b]) a d4 b8 g4.
978 Girls and boys come out to play,
979 The moon doth shine as bright as day;
984 As an alternative to using slurs, the melismata may be indicated
985 in just the lyrics by using an underscore @code{_} for each note
986 that should be included in the melisma:
988 @lilypond[verbatim,quote]
994 g8 a4 b8 c[ b] a d4 b8 g4.
997 Girls and boys come out to play,
998 The moon doth shine _ as bright as day;
1003 If a syllable extends over several notes or a single very long
1004 note an @notation{extender line} is usually drawn from the
1005 syllable extending under all the notes for that syllable. It is
1006 entered as two underscores @code{__}. Here is an example from the
1007 first three bars of @notation{Dido's Lament}, from Purcell's
1008 @notation{Dido and Æneas}:
1010 @lilypond[verbatim,quote]
1016 b c4.( bes8 a4. g8 fis4.) g8 fis1
1020 am laid __ in earth,
1025 None of the examples so far have involved words containing more
1026 than one syllable. Such words are usually split one syllable to a
1027 note, with hyphens between syllables. Such hyphens are entered as
1028 two dashes, resulting in a centered hyphen between the syllables.
1029 Here is an example showing this and everything we have learned so
1030 far about aligning lyrics to notes.
1032 @c no ragged-right here because otherwise the hyphens get lost,
1033 @c but the example is long enough to avoid looking strange.
1034 @lilypond[verbatim,quote,noragged-right]
1040 d4 g4 g a8( b) g4 g4
1044 A -- way in a __ man -- ger,
1045 no __ crib for a bed, __
1050 Some lyrics, especially those in Italian, require the opposite:
1051 setting more than one syllable to a single note. This is
1052 achieved by linking the syllables together with a single
1053 underscore @code{_} (with no spaces), or enclosing them in quotes.
1054 Here's an example from Rossini's @notation{Figaro}, where
1055 @notation{al} has to be sung on the same note as the @notation{go} of
1056 @notation{Largo} in Figaro's aria @notation{Largo al factotum}:
1058 @c no ragged-right here because otherwise the hyphens get lost,
1059 @c but the example is long enough to avoid looking strange.
1060 @lilypond[verbatim,quote,noragged-right]
1066 c4.~ c8 d b c([ d]) b c d b c
1069 Lar -- go_al fac -- to -- tum del -- la cit -- tÃ
1076 Notation Reference: @ruser{Vocal music}.
1079 @node Lyrics to multiple staves
1080 @subsection Lyrics to multiple staves
1082 @cindex lyrics and multiple staves
1083 @cindex multiple staves and lyrics
1085 The simple approach using @code{\addlyrics} can be used for
1086 placing lyrics under more than one staff. Here is an
1087 example from Handel's @notation{Judas Maccabæus}:
1089 @lilypond[verbatim,quote]
1095 c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
1098 Let flee -- cy flocks the hills a -- dorn, __
1104 r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
1107 Let flee -- cy flocks the hills a -- dorn,
1112 Scores any more complex than this simple example are better
1113 produced by separating out the score structure from the notes and
1114 lyrics with variables. These are discussed in @ref{Organizing
1115 pieces with variables}.
1119 Notation Reference: @ruser{Vocal music}.
1123 @section Final touches
1125 This is the final section of the tutorial; it demonstrates how to
1126 add the final touches to simple pieces, and provides an
1127 introduction to the rest of the manual.
1130 * Organizing pieces with variables::
1132 * Absolute note names::
1133 * After the tutorial::
1137 @node Organizing pieces with variables
1138 @subsection Organizing pieces with variables
1141 @cindex variables, defining
1144 @cindex assigning variables
1145 @cindex using variables
1146 @cindex variables, using
1147 @cindex variables, characters allowed in
1148 @cindex characters allowed in variables
1150 When all of the elements discussed earlier are combined to produce
1151 larger files, the music expressions get a lot bigger. In
1152 polyphonic music with many staves, the input files can become very
1153 confusing. We can reduce this confusion by using
1156 With variables (also known as identifiers or macros), we can break
1157 up complex music expressions. A variable is assigned as
1161 namedMusic = @{ @dots{} @}
1164 The contents of the music expression @code{namedMusic} can be used
1165 later by placing a backslash in front of the name
1166 (@code{\namedMusic}, just like a normal LilyPond command).
1168 @lilypond[verbatim,quote]
1169 violin = \new Staff {
1174 cello = \new Staff {
1189 The name of a variable must have alphabetic characters only, no
1190 numbers, underscores, or dashes.
1192 Variables must be defined @emph{before} the main music
1193 expression, but may be used as many times as required anywhere after
1194 they have been defined. They may even be used in a later definition
1195 of another variable, giving a way of shortening the input if a
1196 section of music is repeated many times.
1198 @lilypond[verbatim,quote]
1199 tripletA = \times 2/3 { c,8 e g }
1200 barA = { \tripletA \tripletA \tripletA \tripletA }
1207 Variables may be used for many other types of objects in
1208 the input. For example,
1213 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1216 Depending on its contents, the variable can be used in different
1217 places. The following example uses the above variables:
1231 @subsection Adding titles
1235 @cindex header block
1240 The title, composer, opus number, and similar information are
1241 entered in the @code{\header} block. This exists outside of the
1242 main music expression; the @code{\header} block is usually placed
1243 underneath the version number.
1246 \version @w{"@version{}"}
1254 @dots{} music @dots{}
1258 When the file is processed, the title and composer are printed
1259 above the music. More information on titling can be found in
1260 @ruser{Creating titles}.
1263 @node Absolute note names
1264 @subsection Absolute note names
1267 @cindex note names, absolute
1268 @cindex absolute mode
1269 @cindex absolute values for pitches
1270 @cindex pitches, absolute values
1271 @cindex absolute note names
1273 So far we have always used @code{\relative} to define pitches.
1274 This is the easiest way to enter most music, but another way of
1275 defining pitches exists: absolute mode.
1277 If you omit the @code{\relative}, LilyPond treats all pitches as
1278 absolute values. A @code{c'} will always mean middle C, a
1279 @code{b} will always mean the note one step below middle C, and a
1280 @code{g,} will always mean the note on the bottom staff of the
1283 @lilypond[verbatim,quote]
1291 Here is a four-octave scale:
1293 @lilypond[verbatim,quote]
1308 As you can see, writing a melody in the treble clef involves a lot
1309 of quote @code{'} marks. Consider this fragment from Mozart:
1311 @lilypond[verbatim,quote]
1315 cis''8. d''16 cis''8 e''4 e''8
1316 b'8. cis''16 b'8 d''4 d''8
1320 All these quotes makes the input less readable and they are a source
1321 of errors. With @code{\relative}, the previous example is much
1322 easier to read and type:
1324 @lilypond[verbatim,quote]
1328 cis8. d16 cis8 e4 e8
1333 If you make a mistake with an octave mark (@code{'} or @code{,})
1334 while working in @code{\relative} mode, it is very obvious -- many
1335 notes will be in the wrong octave. When working in absolute mode,
1336 a single mistake will not be as visible, and will not be as easy
1339 However, absolute mode is useful for music which has large
1340 intervals, and is extremely useful for computer-generated LilyPond
1345 @node After the tutorial
1346 @subsection After the tutorial
1348 After finishing the tutorial, you should probably try writing a
1349 piece or two. Start by adding notes to one of the
1350 @ref{Templates}. If you need any notation that was not covered in
1351 the tutorial, look at the Notation Reference, starting with
1352 @ruser{Musical notation}. If you want to write for an instrument
1353 ensemble that is not covered in the templates, take a look at
1354 @ref{Extending the templates}.
1356 Once you have written a few short pieces, read the rest of the
1357 Learning Manual (chapters 3-5). There's nothing wrong with
1358 reading it now, of course! However, the rest of the Learning
1359 Manual assumes that you are familiar with LilyPond input. You may
1360 wish to skim these chapters right now, and come back to them after
1361 you have more experience.
1363 In this tutorial and in the rest of the Learning Manual, there is a
1364 paragraph @strong{See also} at the end of each section, which contains
1365 cross-references to other sections: you should not follow these
1366 cross-references at first reading; when you have read all of the
1367 Learning Manual, you may want to read some sections again and follow
1368 cross-references for further reading.
1370 If you have not done so already, @emph{please} read @ref{Overview
1371 of manuals}. There is a lot of information about LilyPond, so
1372 newcomers often do not know where they should look for help. If
1373 you spend five minutes reading that section carefully, you might
1374 save yourself hours of frustration looking in the wrong places!