1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
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.
12 - unless you have a really good reason, use either
13 @l ilypond[quote,ragged-right,verbatim]
15 @l ilypond[quote,ragged-right,verbatim,fragment,relative=2]
17 Don't use any other relative=X commands (make it a non-fragment
18 example), and don't use fragment without relative=2.
22 - discuss subheading vs. unnumberedsubsection
28 @c old info that will probably be removed.
30 @c * more details about running lilypond; error messages,
31 @c compiling/viewing (emacs?)
32 @c * where to go from First steps+More basics?
34 @c wherever possible, do not include index entries here; the
35 @c index should point to stuff in the reference manual. -gp
37 @c Your first LilyPond score in 10 minutes?
42 This tutorial starts with an introduction to the LilyPond music
43 language and how to produce printed music. After this first contact we
44 will explain how to create common musical notation.
47 Many people learn programs by trying and fiddling around with the
48 program. This is also possible with LilyPond. If you click on a
49 picture in the HTML version of this manual, you will see the exact
50 LilyPond input that was used to generate that image.
53 @lilypond[fragment,quote,ragged-right,relative=2]
54 c-\markup { \bold \huge { Click here. } }
57 By cutting and pasting everything from the @qq{Start cut-&-pastable-section}
58 to the end of the file, you have a
59 starting template for experiments. If you like learning in this way,
60 you will probably want to print out or bookmark the
61 @ref{Cheat sheet}, which is a table listing of the most common
62 commands for quick reference.
66 * First steps (compiling a file)::
68 * Working on text files::
69 * How to read the manual::
70 * Accidentals and key signatures::
72 * Automatic and manual beams::
74 * Music expressions explained::
76 * Adding articulation marks to notes::
77 * Combining notes into chords::
78 * Advanced rhythmic commands::
79 * Commenting input files::
83 * Single staff polyphony::
85 * Organizing larger pieces::
86 * An orchestral part::
87 * After the tutorial::
91 @node First steps (compiling a file)
92 @section First steps (compiling a file)
94 The first example demonstrates how to start working with LilyPond. To
95 create sheet music, we write a text file that specifies the
96 notation. For example, if we write
105 the result looks like this
107 @lilypond[quote,ragged-right]
113 @strong{Warning:} Every piece of LilyPond input needs to have @strong{@{ curly
114 braces @}} placed around the input. The braces should be also be
115 surrounded by a space unless they are at the beginning or end of a
116 line to avoid ambiguities. These may be omitted in some examples in this
117 manual, but don't forget them in your own music!
119 @cindex Case sensitive
120 In addition, LilyPond input is @strong{case sensitive}. @code{ @{ c d e @} }
121 is valid input; @code{ @{ C D E @} } will produce an error message.
125 @unnumberedsubsec Entering music and viewing output
127 In this section we will explain what commands to run
128 and how to view or print the output.
130 @unnumberedsubsubsec MacOS X
132 If you double click LilyPond.app, it will open with an example
133 file. Save it, for example, to @file{test.ly} on your Desktop, and
134 then process it with the menu command @samp{Compile > Typeset File}.
135 The resulting PDF file will be displayed on your screen.
137 Be warned that the first time you ever run lilypond will take a minute
138 or two because all of the system fonts have to be analyzed first.
140 For future use of LilyPond, you should begin by selecting "New"
143 @unnumberedsubsubsec Windows
145 On Windows, start up a text-editor@footnote{Any simple or
146 programmer-oriented editor with UTF-8 support will do, for example
147 Notepad. Do not use a word processor, since these insert formatting
148 codes that will confuse LilyPond.} and enter
156 Save it on the desktop as @file{test.ly} and make sure that it is not
157 called @file{test.ly.TXT}. Double clicking @file{test.ly} will process
158 the file and show the resulting PDF file.
161 @unnumberedsubsubsec Unix
163 Begin by opening a terminal window and starting a text editor. For
164 example, you could open an xterm and execute
165 @code{joe}@footnote{There are macro files for VIM addicts, and there
166 is a @code{LilyPond-mode} for Emacs addicts. If they have not been
167 installed already, refer to the file @file{INSTALL.txt}. These
168 easiest editing environment is @file{LilyPondTool}. See
169 @ref{Editor support} for more information.}. In your
170 text editor, enter the following input and save the file as
180 To process @file{test.ly}, proceed as follows
187 You will see something resembling
194 Interpreting music... [1]
195 Preprocessing graphical objects...
196 Calculating line breaks... [2]
197 Layout output to `test.ps'...
198 Converting to `test.pdf'...
202 @cindex Viewing music
205 The result is the file @file{test.pdf} which you can print or view
206 with the standard facilities of your operating system.@footnote{If
207 your system does not have any tools installed, you can try
208 @uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely
209 available package for viewing and printing PDF and PostScript files.}
212 @node Simple notation
213 @section Simple notation
215 LilyPond will add some notation elements automatically. In the next
216 example, we have only specified four pitches, but LilyPond has
217 added a clef, time signature, and rhythms.
219 @lilypond[quote,ragged-right,verbatim]
226 This behavior may be altered, but in most cases these automatic values
230 @unnumberedsubsec Pitches
232 The easiest way to enter notes is by using @code{\relative} mode. In
233 this mode, the @rglos{interval} between the previous note and the
234 current note is assumed to be within a @rglos{fourth}. We begin by
235 entering the most elementary piece of music, a @rglos{scale}.
237 @lilypond[quote,ragged-right,verbatim]
244 The initial note is @rglos{middle C}. Each successive note
245 is within a fourth of the previous note -- in other words, the first
246 @samp{c} is the closest C to middle C. This is followed by the closest
247 D to the previous note. We can create melodies which have larger intervals:
249 @lilypond[quote,ragged-right,verbatim]
257 As you may notice, this example does not start on middle C. The first
258 note -- the @samp{d} -- is the closest D to middle C.
260 To add intervals that are larger than a fourth, we can raise the octave
261 by adding a single quote @code{'} (or apostrophe) to the note name. We can
262 lower the octave by adding a comma @code{,} to the note name.
264 @lilypond[quote,ragged-right,verbatim]
272 To change a note by two (or more!) octaves, we use multiple @code{''} or
273 @code{,,} -- but be careful that you use two single quotes @code{''} and
274 not one double quote @code{"}@tie{}! The initial value in
275 @code{\relative c'} may also be modified like this.
278 @unnumberedsubsec Durations (rhythms)
280 The @rglos{duration} of a note is specified by a number after the note
281 name. @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note},
282 @samp{4} for a @rglos{quarter note} and so on. Beams are added
285 @lilypond[quote,ragged-right,verbatim]
289 a16 a a a a32 a a a a64 a a a a a a a a2
294 If you do not specify a duration, the previous duration is used
295 for the next note. The duration of the first note defaults to a quarter.
297 To create @rglos{dotted notes}, add a dot @samp{.} to the duration number.
299 @lilypond[quote,ragged-right,verbatim]
307 @unnumberedsubsec Rests
309 A @rglos{rest} is entered just like a note with the name @samp{r}:
311 @lilypond[quote,ragged-right,verbatim]
319 @unnumberedsubsec Time signature
321 The @rglos{time signature}) can be set with the @code{\time} command:
323 @lilypond[quote,ragged-right,verbatim]
335 @unnumberedsubsec Clef
337 The @rglos{clef} can be set using the @code{\clef} command:
339 @lilypond[quote,ragged-right,verbatim]
353 @unnumberedsubsec All together
355 Here is a small example showing all these elements together:
357 @lilypond[quote,ragged-right,verbatim]
366 @c I don't think these are useful, but I haven't completely made
367 @c up my mind whether to completely remove them or not.
369 For more information on
373 @i tem Entering pitches and durations
375 @r ef{Pitches}, and @r ef{Durations}.
380 @i tem Time signatures and other timing commands
381 see @r ef{Time signature}.
387 @node Working on text files
388 @section Working on text files
390 LilyPond input files are treated like files in most programming languages:
391 they are case sensitive, white-space insensitive, and expressions are
392 formed with curly braces @{ @}.
394 If the previous sentence sounds like nonsense, don't worry! We'll explain
395 what all these terms mean:
399 @cindex Case sensitive
400 @item @strong{Case sensitive}:
401 it matters whether you enter a letter
402 in lower case (i.e. @code{a, b, s, t}) or upper case (i.e.
403 @code{A, B, S, T}). Notes are lower case: @code{ @{ c d e @} }
404 is valid input; @code{ @{ C D E @} } will produce an error message.
406 @item @strong{Whitespace insensitive}:
407 it does not matter how many
408 spaces (or new lines) you add. @code{ @{ c d e @}} means the same thing
409 as @code{ @{ c @ @ @ @ @ d e @} } and
417 Of course, the previous example is hard to read. A good rule of thumb
418 is to indent code blocks with either a tab or two spaces:
425 @item @strong{Expressions:}
426 Every piece of LilyPond input needs to have
427 @strong{@{ curly braces @}} placed around the input. These braces tell
428 LilyPond that the input is a single music expression, just like
429 parenthesis @samp{()} in mathematics. The braces should
430 be surrounded by a space unless they are at the beginning or end of a
431 line to avoid ambiguities.
433 A function (such as @code{\relative @{ @}} ) also counts as a single
438 There are more tips for constructing input files in
439 @ref{Suggestions for writing LilyPond files}.
441 @c End of current re-write; more material coming in a few days. -gp
444 @node How to read the manual
445 @section How to read the manual
447 As we saw in @ref{Working on text files}, LilyPond input must be
448 surrounded by @{ @} marks or a @code{\relative c'' @{ ... @}}. For the
449 rest of this manual, most examples will omit this.
451 If you are reading the HTML documentation and wish to see the exact
452 exact LilyPond code that was used to create the example, simply click
453 on the picture. If you are not reading the HTML version, you could
454 copy and paste the displayed input, but you @strong{must} add the
455 @code{\relative c'' @{ @}} like this:
459 ... example goes here...
463 Why omit the braces? Most examples
464 in this manual can be inserted into the middle of a longer piece of
465 music. For these examples, it does not make sense to add
466 @code{\relative c'' @{ @}} -- you should not place a @code{\relative}
467 inside another @code{\relative}, so you would not be able to copy
468 a small documentation example and paste it inside a longer piece
472 @node Accidentals and key signatures
473 @section Accidentals and key signatures
475 @unnumberedsubsec Accidentals
477 A @rglos{sharp} pitch is made by adding @samp{is} to
478 the name, and a @rglos{flat} pitch by adding @samp{es}. As
479 you might expect, a @rglos{double sharp} or @rglos{double flat} is
480 made by adding @samp{isis} or @samp{eses}@footnote{This syntax
481 derived from note naming conventions in Nordic and Germanic languages,
482 like German and Dutch. To use other names for accidentals, see
483 @ref{Note names in other languages}.}
485 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
486 cis1 ees fisis, aeses
489 @cindex key signature, setting
490 @unnumberedsubsec Key signatures
492 The key signature is set with the command @code{\key} followed by
493 a pitch and @code{\major} or @code{\minor}.
495 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
504 @unnumberedsubsec Warning: key signatures and pitches
506 To determine whether to print an accidental, LilyPond examines the
507 pitches and the key signature. The key signature only effects
508 the @emph{printed} accidentals, not the actual pitches! This is a
509 feature that often causes confusion to newcomers, so let us explain it
512 LilyPond makes a sharp distinction between musical content and
513 layout. The alteration (flat, natural or sharp) of a note is part of
514 the pitch, and is therefore musical content. Whether an accidental (a
515 @emph{printed} flat, natural or sharp sign) is printed in front of the
516 corresponding note is a question of layout. Layout is something that
517 follows rules, so accidentals are printed automatically according to
518 those rules. The pitches in your music are works of art, so they will
519 not be added automatically, and you must enter what you want to hear.
523 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
529 No note has a printed accidental, but you must still add the @samp{is} to
530 @code{cis} and @code{fis}.
532 The code @samp{e} does not mean @qq{print a black dot just below the
533 first line of the staff.} Rather, it means: @qq{there is a note with
534 pitch E-natural.} In the key of A-flat major, it @emph{does} get an
537 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
542 Adding all alterations explicitly might require a little more effort
543 when typing, but the advantage is that transposing is easier, and
544 accidentals can be printed according to different conventions. See
545 @ref{Automatic accidentals} for some examples how accidentals can be printed
546 according to different rules.
549 For more information on
554 see @r ef{Automatic accidentals}.
557 see @r ef{Key signature}.
565 @section Ties and slurs
568 @unnumberedsubsec Ties
569 A @rglos{tie} is created by appending a tilde @samp{~} to the first
572 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
577 @c For more information on Ties see @ref{Ties}.
580 @unnumberedsubsec Slurs
582 A @rglos{slur} is a curve drawn across many notes. The starting note
583 and ending note are marked with @samp{(} and @samp{)} respectively.
585 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
586 d4( c16) cis( d e c cis d) e( d4)
589 @cindex slurs, phrasing
590 @cindex phrasing slurs
591 @unnumberedsubsec Phrasing slurs
593 @cindex phrasing slurs
594 Slurs to indicate longer phrasing can be entered with @code{\(} and
595 @code{\)}. You can have both legato slurs and phrasing slurs at the
596 same time, but you cannot have simultaneous slurs or simultaneous
599 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
600 a8(\( ais b c) cis2 b'2 a4 cis,\)
605 @cindex slurs versus ties
606 @unnumberedsubsec Warnings: slurs vs. ties
608 A slur looks like a @rglos{tie}, but it has a different meaning. A
609 tie simply makes the first note longer, and can only be used on
610 pairs of notes with the same pitch. Slurs indicate the articulations
611 of notes, and can be used on larger groups of notes. Slurs and ties
614 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
615 c2~( c8 fis fis4 ~ fis2 g2)
621 @node Automatic and manual beams
622 @section Automatic and manual beams
624 @cindex beams, by hand
625 All @rglos{beam}s are drawn automatically
627 @lilypond[quote,fragment,relative=2,verbatim]
632 If you do not like where beams are put, they can be entered by
633 hand. Mark the first note to be beamed with @samp{[} and the last one
636 @lilypond[quote,fragment,relative=2,verbatim]
640 For more information on beams, see @ref{Manual beams}.
643 Here are key signatures, accidentals and ties in action
645 @lilypond[fragment,quote,noindent,line-width=50\staff-space,verbatim]
652 fis4 fis8 fis8 eis4 a8 gis~
661 There are some interesting points to note in this example. Bar lines
662 and beams are drawn automatically. Line breaks are calculated
663 automatically; it does not matter where the line breaks are in the
664 source file. Finally, the order in which time, key, and clef changes
665 are entered is not relevant: in the printout, these are ordered
666 according to standard notation conventions.
671 @section Octave entry
674 @c Tim wants to move this quotes example just before the: quotes-do not-work
675 @c score, but we'd need to remove quotes from the other two (key and
678 @c better to have this just before the `octaves are bad' snipped
679 @c but we'd need to remove the ', from \key and tie
680 To raise a note by an octave, add a high quote @samp{'} (apostrophe) to
681 the note name, to lower a note one octave, add a @q{low quote} @samp{,}
682 (comma). Middle C is @code{c'}
684 @lilypond[quote,notime,fragment,verbatim]
685 c'4 c'' c''' \clef bass c c,
688 An example of the use of quotes is in the following Mozart fragment
690 @lilypond[quote,ragged-right,fragment,verbatim]
693 cis''8. d''16 cis''8 e''4 e''8
694 b'8. cis''16 b'8 d''4 d''8
698 This example shows that music in a high register needs lots of quotes.
699 This makes the input less readable, and it is a source of errors. The
700 solution is to use @q{relative octave} mode. This is the
701 most convenient way to copy existing music.
703 In relative mode, a note without octavation quotes (i.e., the @samp{'}
704 or @samp{,} after a note) is chosen so that it is closest to the
705 previous one. For example, @samp{c f} goes up while @samp{c g} goes
708 To use relative mode, add @code{\relative} before the piece of
709 music. The first note is taken relative to the middle C
710 @c no , for this sentence
715 @lilypond[quote,notime,fragment,verbatim]
722 Since most music has small intervals, pieces can be written almost
723 without octavation quotes in relative mode. The previous example is
726 @lilypond[quote,ragged-right,verbatim]
730 cis'8. d16 cis8 e4 e8
735 @c needed better, maybe even redundant explanation
736 @c added another example below.
737 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
738 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
739 Larger intervals are made by adding octavation quotes.
741 @lilypond[quote,notime,verbatim,fragment]
747 In summary, quotes or commas no longer determine the absolute height
748 of a note in @code{\relative} mode. Rather, the height of a note is
749 relative to the previous one, and changing the octave of a single note
750 shifts all following notes an octave up or down.
752 For more information on relative octaves see @ref{Relative octaves},
753 and @ref{Octave check}.
756 @node Music expressions explained
757 @section Music expressions explained
760 In input files, music is represent by so-called @emph{music
761 expression}s. We have already seen some in the previous examples;
762 a single note is a music expression
764 @lilypond[fragment,quote,verbatim,relative=3]
768 Enclosing a group of notes in braces creates a new music
771 @lilypond[fragment,quote,verbatim,relative=3]
775 Putting a bunch of music expressions (e.g., notes) in braces, means that
776 they should be played in sequence. The result again is a music
777 expression, which can be grouped with other expressions sequentially.
778 Here, the expression from the previous example is combined with two
781 @lilypond[fragment,quote,verbatim,relative=3]
785 This technique is useful for non-monophonic music. To enter music
786 with more voices or more staves, we also combine expressions in
787 parallel. Two voices that should play at the same time, are entered
788 as a simultaneous combination of two sequences. A @q{simultaneous}
789 music expression is formed by enclosing expressions in @code{<<} and
790 @code{>>}. In the following example, three sequences (all containing
791 two separate notes) are combined simultaneously
793 @lilypond[fragment,quote,verbatim,relative=3]
801 This mechanism is similar to mathematical
802 formulas: a big formula is created by composing small formulas. Such
803 formulas are called expressions, and their definition is recursive, so
804 you can make arbitrarily complex and large expressions. For example,
813 ((1 + 2) * 3) / (4 * 5)
817 @cindex music expression
818 This is a sequence of expressions, where each expression is contained
819 in the next (larger) one. The simplest expressions are numbers, and larger
820 ones are made by combining expressions with operators (like @samp{+},
821 @samp{*} and @samp{/}) and parentheses. Like mathematical expressions,
822 music expressions can be nested arbitrarily deep, which is necessary
823 for complex music like polyphonic scores.
825 Note that this example only has one staff, whereas
826 the previous example had three separate staves. That is because this
827 example begins with a single note. To determine the number of staves,
828 LilyPond looks at the first element. If it is a single note, there is one
829 staff; if there is a simultaneous expression, there is more than one staff.
831 @lilypond[fragment,quote,verbatim,relative=2]
834 << { e f } { c <<b d>> } >>
838 Music files with deep nesting can be confusing to enter and
839 maintain. One convention that helps against this confusion is
840 indenting. When entering a file with deep nesting of braces and
841 angles, it is customary to use an indent that indicates the nesting
842 level. Formatting music like this eases reading and helps you insert
843 the right number of closing braces at the end of an expression. For
857 Some editors have special support for entering LilyPond, and can help
858 indenting source files. See @ref{Editor support} for more information.
863 To print more than one staff, each piece of music that makes up a
864 staff is marked by adding @code{\new Staff} before it. These
865 @code{Staff} elements are then combined in parallel with @code{<<} and
866 @code{>>}, as demonstrated here
868 @lilypond[quote,fragment,verbatim]
870 \new Staff { \clef treble c'' }
871 \new Staff { \clef bass c }
876 The command @code{\new} introduces a @q{notation context.} A notation
877 context is an environment in which musical events (like notes or
878 @code{\clef} commands) are interpreted. For simple pieces, such
879 notation contexts are created automatically. For more complex pieces, it
880 is best to mark contexts explicitly. This ensures that each fragment
883 There are several types of contexts. @code{Staff}, @code{Voice} and
884 @code{Score} handle melodic notation, while @code{Lyrics} sets lyric
885 texts and @code{ChordNames} prints chord names.
887 In terms of syntax, prepending @code{\new} to a music expression
888 creates a bigger music expression. In this way it resembles the minus
889 sign in mathematics. The formula @math{(4+5)} is an expression, so
890 @math{-(4+5)} is a bigger expression.
892 We can now typeset a melody with two staves
894 @c TODO: (c) status of this Paul McCartney (?) song (let's all stand together)
896 @lilypond[fragment,quote,verbatim,ragged-right]
913 For more information on contexts see the description in
914 @ref{Interpretation contexts}.
918 @node Adding articulation marks to notes
919 @section Adding articulation marks to notes
925 Common accents can be added to a note using a dash (@samp{-}) and a
928 @lilypond[fragment,quote,verbatim,relative=2]
929 c-. c-- c-> c-^ c-+ c-_
933 Similarly, fingering indications can be added to a note using a dash
934 (@samp{-}) and the digit to be printed
936 @lilypond[fragment,quote,verbatim,relative=2]
940 Articulations and fingerings are usually placed automatically, but you
941 can specify a direction using @samp{^} (up) or @samp{_} (down). You can
942 also use multiple articulations on the same note. In most cases, however,
943 it is best to let LilyPond determine the articulation directions.
945 @lilypond[fragment,quote,verbatim,relative=2]
946 c_-^1 d^. f^4_2-> e^-_+
949 Dynamic signs are made by adding the markings (with a backslash) to
952 @lilypond[fragment,quote,verbatim,relative=2]
960 Crescendi and decrescendi are started with the commands @code{\<} and
961 @code{\>}. An ending dynamic, for example @code{\f}, will finish the
962 (de)crescendo, or the command @code{\!} can be used
964 @lilypond[fragment,quote,verbatim,relative=2]
971 For more information on
976 see @ref{Fingering instructions}.
978 see @ref{Articulations}.
982 see @ref{Phrasing slurs}.
989 @node Combining notes into chords
990 @section Combining notes into chords
993 Chords can be made by surrounding pitches with angle brackets.
994 Angle brackets are the symbols @samp{<} and @samp{>}.
996 @lilypond[quote,relative=1,fragment,verbatim]
1001 You can combine markings like beams and ties with chords. They must
1002 be placed outside the angled brackets
1004 @lilypond[quote,relative=1,fragment,verbatim]
1005 r4 <c e g>8[ <c f a>]~ <c f a>
1009 r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)
1012 @lilypond[quote,relative=1,fragment]
1014 r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)
1018 @node Advanced rhythmic commands
1019 @section Advanced rhythmic commands
1023 @cindex partial measure
1024 A pickup is entered with the keyword @code{\partial}. It
1025 is followed by a duration: @code{\partial 4} is a quarter note upstep
1026 and @code{\partial 8} an eighth note
1028 @lilypond[quote,relative=2,verbatim,fragment]
1035 Tuplets are made with the @code{\times} keyword. It takes two
1036 arguments: a fraction and a piece of music. The duration of the piece
1037 of music is multiplied by the fraction. Triplets make notes occupy
1038 2/3 of their notated duration, so a triplet has 2/3 as its fraction
1040 @lilypond[quote,relative=1,verbatim,fragment]
1041 \times 2/3 { f8 g a }
1042 \times 2/3 { c r c }
1046 @cindex acciaccatura
1047 Grace notes are also made by prefixing a music expression with the
1048 keyword @code{\appoggiatura} or @code{\acciaccatura}
1049 @cindex appoggiatura
1050 @cindex acciaccatura
1052 @lilypond[quote,relative=2,verbatim,fragment]
1053 c4 \appoggiatura b16 c4
1054 c4 \acciaccatura b16 c4
1059 For more information on
1064 see @ref{Grace notes},
1068 see @ref{Partial measures}.
1073 @node Commenting input files
1074 @section Commenting input files
1077 @cindex line comment
1078 @cindex block comment
1079 A comment is a remark for the human reader of the music input; it is
1080 ignored while parsing, so it has no effect on the printed output.
1081 There are two types of comments. The percent symbol @samp{%}
1082 introduces a line comment; after @samp{%} the rest of the line is
1083 ignored. A block comment marks a whole section of music
1084 input. Anything that is enclosed in @code{%@{} and @code{%@}} is
1085 ignored. The following fragment shows possible uses for comments
1088 % notes for twinkle twinkle follow
1092 This line, and the notes below
1093 are ignored, since they are in a
1100 @c TODO post-2.6 reorg
1101 @c This is good info, but I wouldn't call it a comment. IMO it should
1102 @c be moved somewhere else.
1106 There is a special statement that is a kind of comment. The @code{\version}
1107 statement marks for which version of LilyPond the file was written.
1108 To mark a file for version 2.10.1, use
1115 These annotations make future upgrades of LilyPond go more
1116 smoothly. Changes in the syntax are handled with a special program,
1117 @file{convert-ly} (see @ref{Updating files with convert-ly}), and it uses
1118 @code{\version} to determine what rules to apply.
1121 @node Printing lyrics
1122 @section Printing lyrics
1125 @c TODO: (c) status of the Queen fragment.
1129 Lyrics are entered by separating each syllable with a space
1132 I want to break free
1137 @lilypond[quote,verbatim,fragment,ragged-right]
1139 r4 c \times 2/3 { f g g }
1140 \times 2/3 { g4( a2) }
1144 The lyrics can be set to these notes, combining both with the
1145 @code{\addlyrics} keyword
1147 @lilypond[quote,verbatim,fragment,ragged-right]
1150 r4 c \times 2/3 { f g g }
1151 \times 2/3 { g4( a2) }
1153 \addlyrics { I want to break free }
1158 @cindex extender line
1160 This melody ends on a @rglos{melisma}, a single syllable (@q{free})
1161 sung to more than one note. This is indicated with an @emph{extender
1162 line}. It is entered as two underscores, i.e.,
1165 @{ I want to break free __ @}
1168 @lilypond[fragment,quote,ragged-right]
1171 r4 c \times 2/3 { f g g }
1172 \times 2/3 { g4( a2) }
1174 \addlyrics { I want to break free __ }
1178 Similarly, hyphens between words can be entered as two dashes,
1179 resulting in a centered hyphen between two syllables
1185 @c no ragged-right here, because otherwise the hypens get lost.
1186 @lilypond[fragment,quote]
1192 \addlyrics { A -- le gri -- a }
1196 More options, like putting multiple lines of lyrics below a melody are
1197 discussed in @ref{Vocal music}.
1201 @section A lead sheet
1207 @c TODO: revise this, \chords { } is shorter and more intuitive.
1209 In popular music, it is common to denote accompaniment with chord names.
1210 Such chords can be entered like notes,
1212 @lilypond[quote,verbatim,ragged-right]
1213 \chordmode { c2 f4. g8 }
1217 Now each pitch is read as the root of a chord instead of a note.
1218 This mode is switched on with @code{\chordmode}
1220 Other chords can be created by adding modifiers after a colon. The
1221 following example shows a few common modifiers
1223 @lilypond[quote,verbatim,ragged-right]
1224 \chordmode { c2 f4:m g4:maj7 gis1:dim7 }
1227 For lead sheets, chords are not printed on staves, but as names on a
1228 line for themselves. This is achieved by using @code{\chords} instead
1229 of @code{\chordmode}. This uses the same syntax as @code{\chordmode},
1230 but renders the notes in a @code{ChordNames} context, with the
1233 @lilypond[quote,verbatim,ragged-right]
1234 \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
1238 When put together, chord names, lyrics and a melody form
1239 a lead sheet, for example,
1243 \chords @{ @emph{chords} @}
1245 \addlyrics @{ @emph{the text} @}
1250 @lilypond[quote,ragged-right]
1252 \chords { r2 c:sus4 f }
1254 r4 c' \times 2/3 { f g g }
1255 \times 2/3 { g4( a2) }
1257 \addlyrics { I want to break free __ }
1261 A complete list of modifiers and other options for layout can be found
1266 @section Adding titles
1268 Bibliographic information is entered in a separate block, the
1269 @code{\header} block. The name of the piece, its composer, etc., are
1270 entered as an assignment, within @code{\header
1271 @{@tie{}@dots{}@tie{}@}}. The @code{\header} block is usually put at
1272 the top of the file. For example,
1277 composer = "Igor Stravinsky"
1284 When the file is processed, the title and composer are printed above
1285 the music. More information on titling can be found in @ref{Creating
1289 @node Single staff polyphony
1290 @section Single staff polyphony
1293 @cindex multiple voices
1294 @cindex voices, more -- on a staff
1295 When different melodic lines are combined on a single staff they are
1296 printed as polyphonic voices; each voice has its own stems, slurs and
1297 beams, and the top voice has the stems up, while the bottom voice has
1300 Entering such parts is done by entering each voice as a sequence (with
1301 @code{@{...@}}), and combining these simultaneously, separating the
1302 voices with @code{\\}
1304 @lilypond[quote,verbatim,relative=2,fragment]
1305 << { a4 g2 f4~ f4 } \\
1309 For polyphonic music typesetting, spacer rests can also be convenient;
1310 these are rests that do not print. They are useful for filling up
1311 voices that temporarily do not play. Here is the same example with a
1312 spacer rest (@samp{s}) instead of a normal rest (@samp{r}),
1314 @lilypond[quote,verbatim,relative=2,fragment]
1315 << { a4 g2 f4~ f4 } \\
1320 Again, these expressions can be nested arbitrarily
1322 @lilypond[quote,fragment,verbatim,relative=2,fragment]
1330 { <c g>1 ~ <c g>4 } \\
1336 More features of polyphonic typesetting are described in this manual
1337 in section @ref{Basic polyphony}.
1341 @section Piano staves
1343 @cindex staff switch, manual
1344 @cindex cross staff voice, manual
1345 Piano music is typeset in two staves connected by a brace. Printing
1346 such a staff is similar to the polyphonic example in @ref{More staves},
1349 << \new Staff @{ @dots{} @}
1350 \new Staff @{ @dots{} @} >>
1354 but now this entire expression must be interpreted as a
1358 \new PianoStaff << \new Staff @dots{} >>
1361 Here is a small example
1363 @lilypond[quote,verbatim,relative=1,fragment]
1365 \new Staff { \time 2/4 c4 c g' g }
1366 \new Staff { \clef bass c,, c' e c }
1370 More information on formatting piano music is given in @ref{Piano music}.
1373 @node Organizing larger pieces
1374 @section Organizing larger pieces
1376 When all of the elements discussed earlier are combined to produce
1377 larger files, the @code{\score} blocks get a lot bigger because the
1378 music expressions are longer, and, in the case of polyphonic music,
1379 more deeply nested. Such large expressions can become unwieldy.
1381 By using variables, also known as identifiers, it is possible to break
1382 up complex music expressions. An identifier is assigned as follows
1385 namedMusic = @{ @dots{} @}
1389 The contents of the music expression @code{namedMusic}, can be used
1390 later by preceding the name with a backslash, i.e., @code{\namedMusic}.
1391 In the next example, a two-note motive is repeated two times by using
1392 variable substitution
1394 @lilypond[quote,ragged-right,verbatim,nofragment]
1398 { \seufzer \seufzer }
1401 The name of an identifier should have alphabetic characters only: no
1402 numbers, underscores, or dashes. The assignment should be outside of
1405 It is possible to use variables for many other types of objects in the
1411 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1414 Depending on its contents, the identifier can be used in different
1415 places. The following example uses the above variables
1425 More information on the possible uses of identifiers is given in the
1426 technical manual, in @ref{Input variables and Scheme}.
1427 @c fixme: the ref is too technical.
1430 @node An orchestral part
1431 @section An orchestral part
1433 In orchestral music, all notes are printed twice. Once in a part for
1434 the musicians, and once in a full score for the conductor. Identifiers can
1435 be used to avoid double work. The music is entered once, and stored in
1436 a variable. The contents of that variable is then used to generate
1437 both the part and the full score.
1439 It is convenient to define the notes in a special file. For example,
1440 suppose that the file @file{horn-music.ly} contains the following part
1441 of a horn/@/bassoon duo
1444 hornNotes = \relative c @{
1451 Then, an individual part is made by putting the following in a file
1454 \include "horn-music.ly"
1456 instrument = "Horn in F"
1460 \transpose f c' \hornNotes
1467 \include "horn-music.ly"
1471 substitutes the contents of @file{horn-music.ly} at this position in
1472 the file, so @code{hornNotes} is defined afterwards. The command
1473 @code{\transpose f@tie{}c'} indicates that the argument, being
1474 @code{\hornNotes}, should be transposed by a fifth upwards. Sounding
1475 @samp{f} is denoted by notated @code{c'}, which corresponds with the
1476 tuning of a normal French Horn in@tie{}F. The transposition can be seen
1477 in the following output
1479 @lilypond[quote,ragged-right]
1480 \transpose f c' \relative c {
1486 In ensemble pieces, one of the voices often does not play for many
1487 measures. This is denoted by a special rest, the multi-measure
1488 rest. It is entered with a capital @samp{R} followed by a duration
1489 (@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
1490 etc.). By multiplying the
1491 duration, longer rests can be constructed. For example, this rest
1492 takes 3@tie{}measures in 2/4 time
1498 When printing the part, multi-rests
1499 must be condensed. This is done by setting a run-time variable
1502 \set Score.skipBars = ##t
1506 This command sets the property @code{skipBars} in the
1507 @code{Score} context to true (@code{##t}). Prepending the rest and
1508 this option to the music above, leads to the following result
1510 @lilypond[quote,ragged-right]
1511 \transpose f c' \relative c {
1513 \set Score.skipBars = ##t
1520 The score is made by combining all of the music together. Assuming
1521 that the other voice is in @code{bassoonNotes} in the file
1522 @file{bassoon-music.ly}, a score is made with
1525 \include "bassoon-music.ly"
1526 \include "horn-music.ly"
1529 \new Staff \hornNotes
1530 \new Staff \bassoonNotes
1537 @lilypond[quote,ragged-right]
1545 r4 d,8 f | gis4 c | b bes |
1546 a8 e f4 | g d | gis f
1551 More in-depth information on preparing parts and scores can be found
1552 in the notation manual; see @ref{Orchestral music}.
1554 Setting run-time variables (@q{properties}) is discussed in
1555 @ref{Changing context properties on the fly}.
1558 @node After the tutorial
1559 @section After the tutorial
1561 After finishing the tutorial, you should probably try writing a
1562 piece or two. Start with one of the @ref{Example templates} and
1563 add notes. If you need any notation that was not covered in the
1564 tutorial, look at the Notation Reference, starting with
1565 @ref{Basic notation}. If you want to write for an instrument
1566 ensemble which is not covered in the @ref{Example templates},
1567 take a look at @ref{Extending the templates}.
1569 Once you have written a few short pieces, read the rest of
1570 the Learning Manual (chapters 3-5). There's nothing wrong
1571 with reading them now, of course! However, the rest of the
1572 Learning Manual assumes that you are familiar with
1573 LilyPond input. You may wish to skim these chapters right
1574 now, and come back to them after you have more experience.