4 @c A menu is needed before every deeper *section nesting of @nodes
5 @c Run M-x texinfo-all-menus-update
6 @c to automagically fill in these menus
7 @c before saving changes
15 Rhythm staff (clef, x-notehead)
16 \partcombine: -> orchestral part-HOWTO.
18 postscript, scheme output?
19 (links to?) using/existance of ly2dvi, lilypond-book
23 @c .{Reference Manual}
25 @node Reference Manual
26 @chapter Reference Manual
28 This document describes GNU LilyPond and its input format. This document
29 has been revised for LilyPond 1.3.125
58 The purpose of LilyPond is explained informally by the term `music
59 typesetter'. This is not a fully correct name: not only does the
60 program print musical symbols, it also makes esthetic decisions. All
61 symbols and their placement is @emph{generated} from a high-level
62 musical description. In other words, LilyPond would be best described
63 by `music compiler' or `music to notation compiler'.
65 Internally, LilyPond is written in a mixture of Scheme and C++. Most of
66 the algorithms and low-level routines are written in C++, but these low
67 level components are glued together using Scheme data
68 structures. LilyPond is linked to GUILE, GNU's Scheme library for
71 When lilypond is run to typeset sheet music, the following happens:
74 @item GUILE Initialization: various scheme files are read
75 @item parsing: first standard .ly initialization files are read, and
76 then the user @file{.ly} file is read.
77 @item interpretation: the music in the file is processed "in playing
78 order", i.e. in the same order as your eyes scan sheet music, and in the
79 same order that you hear the notes play.
82 in this step, the results of the interpretation, a typesetting
83 specification, is solved.
85 @item the visible results ("virtual ink") is written to the output file.
88 These stages, involve data of a specific type: during parsing,
89 @strong{Music} objects are created. During the interpretation,
90 @strong{context} is constructed, and with this context af network of
91 @strong{graphical objects} (``grobs'') is created. The grobs contain
92 unknown variables, and the network forms a set of equations. After
93 solving the equations and filling in these variables, the printed output
94 (in the form of @strong{molecules}) is written to an output file.
96 These threemanship of tasks (parsing, translating, typesetting) and
97 data-structures (music, context, graphical objects) permeates the entire
98 design of the program. This manual is ordered in terms of user
99 tasks. With each concept will be explained to which of the three parts
102 LilyPond input can be classified into three types:
104 @item musical expressions: a musical expression is some combination of
106 @item output definitions: recipes for translating those musical
107 expressions into performances (MIDI) or graphics (eg. PostScript).
109 @item declarations: by declaring and naming musical expressions, you
110 can enter and edit them in manageable chunks.
115 @c . {Modifying music}
116 @node Modifying music
117 @section Modifying music
118 @cindex Modifying music
120 FIXME: more verbose titling:
124 Repeating music expressions?
134 Apply allows a Scheme-function to operate directly on the internal
135 representation of music.
137 \apply #@var{func} @var{music}
139 The function takes two arguments, being a function and an musical
140 argument for that function. The function should return a music
143 This example replaces the text string of a script. It also shows a dump
144 of the music it processes.
146 #(define (testfunc x)
147 (if (equal? (ly-get-mus-property x 'text) "foo")
148 (ly-set-mus-property x 'text "bar"))
150 (ly-set-mus-property x 'elements
151 (map testfunc (ly-get-mus-property x 'elements)))
156 \apply #testfunc { c4_"foo" }
160 For more information on what is possible, see the @ref{Tricks} and the
161 automatically generated documentation.
171 @cindex @code{\repeat}
173 In order to specify repeats, use the @code{\repeat}
174 keyword. Since repeats look and sound differently when played or
175 printed, there are a few different variants of repeats.
179 Repeated music is fully written (played) out. Useful for MIDI
183 This is the normal notation: Repeats are not written out, but
184 alternative endings (voltas) are printed, left to right.
187 Alternative endings are written stacked. Which is unfortunately not
188 practical for anything right now.
196 * Manual repeat commands::
198 * Tremolo subdivision::
202 @subsection Repeat syntax
204 The syntax for repeats is
207 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
210 If you have alternative endings, you may add
212 @cindex @code{\alternative}
214 \alternative @code{@{} @var{alternative1}
216 @var{alternative3} @dots{} @code{@}}
219 where each @var{alternative} is a Music expression.
221 Normal notation repeats are used like this:
225 @lilypond[fragment,verbatim]
227 \repeat volta 2 { c'4 d' e' f' }
228 \repeat volta 2 { f' e' d' c' }
232 With alternative endings:
236 @lilypond[fragment,verbatim]
238 \repeat volta 2 {c'4 d' e' f'}
239 \alternative { {d'2 d'} {f' f} }
243 Folded repeats look like this:@footnote{Folded repeats offer little
244 more over simultaneous music. However, it is to be expected that
245 more functionality -- especially for the MIDI backend -- will be
246 implemented at some point in the future.}
250 @lilypond[fragment,verbatim]
252 \repeat fold 2 {c'4 d' e' f'}
253 \alternative { {d'2 d'} {f' f} }
259 If you don't give enough alternatives for all of the repeats, then
260 the first alternative is assumed to be repeated often enough to equal
261 the specified number of repeats.
264 @lilypond[fragment,verbatim]
268 \repeat volta 3 { e | c2 d2 | e2 f2 | }
269 \alternative { { g4 g g } { a | a a a a | b2. } }
277 As you can see, LilyPond doesn't remember the timing information, nor
278 are slurs or ties repeated. We hope to fix this after 1.4.
280 It is possible to nest @code{\repeat}, although it probably is only
281 meaningful for nested repeats.
283 @node Manual repeat commands
284 @subsection Manual repeat commands
286 @cindex @code{repeatCommands}
288 The property @code{repeatCommands} can be used to control the layout of
289 repeats. Its value is a Scheme list of repeat commands, where each repeat
297 @item (volta . @var{text})
298 Print a volta bracket saying @var{text}.
300 Stop a running volta bracket
303 @lilypond[verbatim, fragment]
305 \property Score.repeatCommands = #'((volta "93") end-repeat)
307 \property Score.repeatCommands = #'((volta #f))
312 @node Tremolo repeats
313 @subsection Tremolo repeats
314 @cindex tremolo beams
316 To place tremolo marks between notes, use @code{\repeat} with tremolo
318 @lilypond[verbatim,center]
320 \context Voice \notes\relative c' {
321 \repeat "tremolo" 8 { c16 d16 }
322 \repeat "tremolo" 4 { c16 d16 }
323 \repeat "tremolo" 2 { c16 d16 }
324 \repeat "tremolo" 4 c16
327 linewidth = 40*\staffspace;
332 @node Tremolo subdivision
333 @subsection Tremolo subdivision
334 @cindex tremolo marks
335 @cindex @code{tremoloFlags}
337 Tremolo marks can be printed on a single note by adding
338 `@code{:}[@var{length}]' after the note. The length must be at least 8.
339 A @var{length} value of 8 gives one line across the note stem. If the
340 length is omitted, then the last value is used, or the value of the
341 @code{tremoloFlags} property if there was no last value.
343 @lilypond[verbatim,fragment,center]
347 Tremolos in this style do not carry over into the MIDI output.
349 Using this mechanism pays off when you entering many tremolos, since the
350 default argument saves a lot of typing.
361 * Defining pitch names::
370 @subsection Notes mode
374 @cindex @code{\notes}
375 Note mode is introduced by the keyword
376 @code{\notes}. In Note mode, words can only
377 contain alphabetic characters. If @code{word} is encountered,
378 LilyPond first checks for a notename of @code{word}. If no
379 notename is found, then @code{word} is treated as a string.
381 Since combinations of numbers and dots are used for indicating
382 durations, it is not possible to enter real numbers in this mode.
391 @cindex Note specification
393 @cindex entering notes
395 The verbose syntax for pitch specification is
397 @cindex @code{\pitch}
399 \pitch @var{scmpitch}
402 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
404 In Note and Chord mode, pitches may be designated by names. The default
405 names are the Dutch note names. The notes are specified by the letters
406 @code{c} through @code{b}, where @code{c} is an octave below middle C
407 and the letters span the octave above that C. In Dutch,
408 @cindex note names, Dutch
409 a sharp is formed by adding @code{-is} to the end of a pitch name. A
410 flat is formed by adding @code{-es}. Double sharps and double flats are
411 obtained by adding @code{-isis} or @code{-eses}. @code{aes} and
412 @code{ees} are contracted to @code{as} and @code{es} in Dutch, but both
413 forms will be accepted.
415 LilyPond has predefined sets of notenames for various other languages.
416 To use them, simply include the language specific init file. For
417 example: @code{\include "english.ly"}. The available language files and
418 the names they define are:
421 Note Names sharp flat
422 nederlands.ly c d e f g a bes b -is -es
423 english.ly c d e f g a bf b -s/-sharp -f/-flat
424 deutsch.ly c d e f g a b h -is -es
425 norsk.ly c d e f g a b h -iss/-is -ess/-es
426 svenska.ly c d e f g a b h -iss -ess
427 italiano.ly do re mi fa sol la sib si -d -b
428 catalan.ly do re mi fa sol la sib si -d/-s -b
437 The optional octave specification takes the form of a series of
438 single quote (`@code{'}') characters or a series of comma
439 (`@code{,}') characters. Each @code{'} raises the pitch by one
440 octave; each @code{,} lowers the pitch by an octave.
442 @lilypond[fragment,verbatim,center]
443 c' d' e' f' g' a' b' c''
446 @lilypond[fragment,verbatim,center]
447 cis' dis' eis' fis' gis' ais' bis'
450 @lilypond[fragment,verbatim,center]
451 ces' des' es' fes' ges' as' bes'
454 @lilypond[fragment,verbatim,center]
455 cisis' eisis' gisis' aisis' beses'
458 @lilypond[fragment,verbatim,center]
459 ceses' eses' geses' ases' beses'
463 @c . {Defining pitch names}
464 @node Defining pitch names
465 @subsection Defining pitch names
467 @cindex defining pitch names
468 @cindex pitch names, defining
470 Note names and chord modifiers can be customised for nationalities. The
471 syntax is as follows.
473 @cindex @code{\pitchnames}
474 @cindex @code{\chordmodifiers}
476 \pitchnames @var{scheme-alist}
477 \chordmodifiers @var{scheme-alist}
480 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
481 specific examples how to do this. Some national note names have been
482 provided, among others: Norwegian, Swedish, German, Italian, Catalan,
483 French, Dutch and English.
488 @subsection Durations
492 @cindex @code{\duration}
494 The syntax for an verbose duration specification is
496 \duration @var{scmduration}
499 In Note, Chord, and Lyrics mode, durations may be designated by numbers
500 and dots: durations are entered as their reciprocal values. For notes
501 longer than a whole note, use identifiers.
507 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
509 r1 r2 r4 r8 r16 r32 r64 r64
515 \notes \relative c'' {
516 a\longa a\breve \autoBeamOff
517 a1 a2 a4 a8 a16 a32 a64 a64
519 r1 r2 r4 r8 r16 r32 r64 r64
524 \remove "Clef_engraver";
525 \remove "Staff_symbol_engraver";
526 \remove "Time_signature_engraver";
527 \consists "Pitch_squash_engraver";
534 As you can see, the longa is not printed. To get a longa note head, you
535 have to use a different style of note heads. See [TODO].
537 If the duration is omitted then it is set equal to the previous duration
538 entered. At the start of parsing there is no previous duration, so then
539 a quarter note is assumed. The duration can be followed by a dot
540 (`@code{.}') to obtain dotted note lengths.
543 @lilypond[fragment,verbatim,center]
549 You can alter the length of duration by writing `@code{*}@var{fraction}'
550 after it. This will not affect the appearance of note heads or rests.
556 A note specification has the form
559 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
563 LilyPond will determine what accidentals to typeset depending on the key
564 and context, so alteration refer to what note is heard, not to whether
565 accidentals are printed. A reminder accidental
566 @cindex reminder accidental
568 can be forced by adding an exclamation mark @code{!} after the pitch.
569 A cautionary accidental,
570 @cindex cautionary accidental
572 i.e., an accidental within parentheses can be obtained by adding the
573 question mark `@code{?}' after the pitch.
575 @lilypond[fragment,verbatim,center]
576 cis' d' e' cis' c'? d' e' c'!
585 Rests are entered like notes, with note name `@code{r}'.
586 There is also a note name
587 `@code{s}', which produces a space of the specified
598 \skip @var{duration} @code{;}
602 Skips the amount of time specified by @var{duration}. If no other
603 music is played, a gap will be left for the skipped time with no
604 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
605 this has the same effect as the spacer rest.
609 @c . {Music notation}
611 @section Music notation
612 @cindex Music notation
626 @code{\key} @var{pitch} @var{type} @code{;}
628 @cindex @code{\minor}
629 @cindex @code{\major}
630 @cindex @code{\minor}
631 @cindex @code{\ionian}
632 @cindex @code{\locrian}
633 @cindex @code{\aeolian}
634 @cindex @code{\mixolydian}
635 @cindex @code{\lydian}
636 @cindex @code{\phrygian}
637 @cindex @code{\dorian}
639 Change the key signature. @var{type} should be @code{\major} or
640 @code{\minor} to get @var{pitch}-major or @var{pitch}-minor,
641 respectively. The second argument is optional; the default is major
642 keys. The @var{\context} argument can also be given as an integer,
643 which tells the number of semitones that should be added to the pitch
644 given in the subsequent @code{\key} commands to get the corresponding
645 major key, e.g., @code{\minor} is defined as 3. The standard mode names
646 @code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian},
647 @code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined.
651 @subsubsection Clef changes
654 \clef @var{clefname} @code{;}
660 \property Staff.clefGlyph = @var{symbol associated with clefname}
661 \property Staff.clefPosition = @var{clef Y-position for clefname}
662 \property Staff.clefOctavation = @var{extra pitch of clefname}
665 Supported clef-names include
670 @c . {Time signature}
672 @subsection Time signature
673 @cindex Time signature
678 \time @var{numerator}@code{/}@var{denominator} @code{;}
681 A short-cut for doing
683 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
686 See the documentation of @code{timeSignatureFraction}
690 @subsubsection Partial
694 @cindex partial measure
695 @cindex measure, partial
696 @cindex shorten measures
697 @cindex @code{\partial}
699 \partial @var{duration} @code{;}
705 \property Score.measurePosition = @var{length of duration}
709 See the documentation of @code{measurePosition}.
717 [todo : collisiosn, rest-collisinos, voiceX identifiers, how to
718 which contexts to instantiate.]
722 @cindex @code{\shiftOff}
723 @item @code{\shiftOff}
724 Disable horizontal shifting of note heads that collide.
726 @cindex @code{\shiftOn}
727 @item @code{\shiftOn}
728 Enable note heads that collide with other note heads to be
729 shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
730 set different shift values.
732 @cindex @code{\stemBoth}
733 @item @code{\stemBoth}
734 Allow stems, beams, and slurs to point either upwards or
735 downwards, decided automatically by LilyPond.
737 @cindex @code{\stemDown}
738 @item @code{\stemDown}
739 Force stems, beams, and slurs to point down.
741 @cindex @code{\stemUp}
743 Force stems, beams and slurs to point up.
767 @c . {Automatic beams}
768 @subsubsection Automatic beams
771 @cindex automatic beam generation
773 @cindex @code{Voice.noAutoBeaming}
775 LilyPond will group flagged notes and generate beams autmatically, where
778 This feature can be disabled by setting the @code{Voice.noAutoBeaming}
779 property to true, which you may find necessary for the melody that goes
780 with lyrics, eg. Automatic beaming can easily be overridden for
781 specific cases by specifying explicit beams. This is discussed in the
786 @cindex @code{Voice.autoBeamSettings}
787 @cindex @code{(end * * * *)}
788 @cindex @code{(begin * * * *)}
790 A large number of Voice properties are used to decide how to generate
791 beams. Their default values appear in @file{scm/auto-beam.scm}. In
792 general, beams can begin anywhere, but their ending location is
793 significant. Beams can end on a beat, or at durations specified by the
794 properties in @code{Voice.autoBeamSettings}. To end beams every quarter
795 note, for example, you could set the property @code{(end * * * *)} to
796 @code{(make-moment 1 4)}. To end beams at every three eighth notes you
797 would set it to @code{(make-moment 1 8)}. The same syntax can be used
798 to specify beam starting points using @code{(begin * * * *)}, eg:
801 \property Voice.autoBeamSettings \override
802 #'(end * * * *) = #(make-moment 1 4)
803 \property Voice.autoBeamSettings \override
804 #'(begin * * * *) = #(make-moment 1 8)
808 To allow different settings for different time signatures, instead of
809 the first two asterisks @code{* *} you can specify a time signature; use
810 @code{(end N M * *)} to restrict the definition to
811 `@var{N}@code{/}@var{M}' time. For example, to specify beams ending
812 only for 6/8 time you would use the property @code{(end 6 8 * *)}.
814 To allow different endings for notes of different durations, instead of
815 th last two asterisks you can specify a duration; use @code{(end * * N
816 M)} to restrict the definition to beams that contain notes of
817 `@var{N}@code{/}@var{M}' duration.
819 For example, to specify beam endings for beams that contain 32nd notes,
820 you would use @code{(end * * 1 32)}.
825 @cindex Automatic beams
826 @subsubsection Manual beams
827 @cindex beams, manual
831 In some cases it may be necessary to override LilyPond's automatic
832 beaming algorithm. For example, the auto beamer will not beam over
833 rests or bar lines, so if you want that, specify the begin and end point
834 manually using @code{[} and @code{]}:
837 @lilypond[fragment,relative,verbatim]
839 r4 [r8 g'' a r8] r8 [g | a] r8
844 @cindex @code{stemLeftBeamCount}
846 If you have specific wishes for the number of beams, you can fully
847 control the number of beams through the properties
848 y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.
850 @lilypond[fragment,relative,verbatim]
853 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
857 @cindex @code{stemRightBeamCount}
860 @c . {Adjusting beams}
861 @unnumberedsubsubsec Adjusting beams
862 @cindex Adjusting beams
883 A slur connects chords and is used to indicate legato. Slurs avoid
884 crossing stems. A slur is started with @code{(} and stopped with
885 @code{)}. The starting @code{(} appears to the right of the first note
886 in the slur. The terminal @code{)} appears to the left of the last note
887 in the slur. This makes it possible to put a note in slurs from both
890 @lilypond[fragment,verbatim,center]
891 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
894 @c . {Adjusting slurs}
895 @unnumberedsubsubsec Adjusting slurs
898 @node Slur attachments
899 @subsubsection Slur attachments
901 The ending of a slur should whenever possible be attached to a note
902 head. Only in some instances where beams are involved, LilyPond may
903 attach a slur to a stem end. In some cases, you may want to override
904 LilyPond's decision, e.g., to attach the slur to the stem end. This can
905 be done through @code{Voice.Slur}'s grob-property @code{attachment}:
909 @lilypond[fragment,relative,verbatim]
910 \property Voice.Slur \set #'direction = #1
911 \property Voice.Stem \set #'length = #5.5
913 \property Voice.Slur \set #'attachment = #'(stem . stem)
918 Similarly, slurs can be attached to note heads even when beams are
922 @lilypond[fragment,relative,verbatim]
923 \property Voice.Slur \set #'direction = #1
924 \property Voice.Slur \set #'attachment = #'(head . head)
925 g''16()g()g()g()d'()d()d()d
929 If a slur would strike through a stem or beam, LilyPond will move the
930 slur away vertically (upward or downward). In some cases, this may
931 cause ugly slurs that you may want to correct:
934 @lilypond[fragment,relative,verbatim]
935 \property Voice.Stem \set #'direction = #1
936 \property Voice.Slur \set #'direction = #1
938 \property Voice.Slur \set #'attachment = #'(stem . stem)
943 LilyPond will increase the curvature of a slur trying to stay free of
944 note heads and stems. However, if the curvature would increase too much,
945 the slur will be reverted to its default shape. This decision is based
946 on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some
947 cases, you may find ugly slurs beautiful, and tell LilyPond so by
948 increasing the @code{beautiful} value:
950 [hoe gedefd?? wat betekent beautiful = X?]
955 \notes \context PianoStaff <
957 \context Staff=up { s1 * 6/4 }
958 \context Staff=down <
960 \autochange Staff \context Voice
962 d,8( a' d f a d f d a f d )a
970 Slur \override #'beautiful = #5.0
971 Slur \override #'direction = #1
972 Stem \override #'direction = #-1
973 autoBeamSettings \override #'(end * * * *)
978 VerticalAlignment \override #'threshold = #'(5 . 5)
985 @cindex Adusting slurs
991 @subsection Phrasing slur
992 @cindex phrasing slur
993 @cindex phrasing mark
995 A phrasing slur (or phrasing mark) connects chords and is used to
996 indicate a musical sentence. Phrasing slurs avoid crossing stems. A
997 phrasing slur is started with @code{\(} and stopped with @code{\)}. The
998 starting @code{\(} appears to the right of the first note in the
999 phrasing slur. The terminal @code{\)} appears to the left of the last
1000 note in the phrasing slur.
1002 @lilypond[fragment,verbatim,center,relative]
1003 \time 6/4; c''\((d)e f(e)\)d
1015 A tie connects two adjacent note heads of the same pitch. When used
1016 with chords, it connects all of the note heads whose pitches match.
1017 Ties are indicated using the tilde symbol `@code{~}'.
1018 If you try to tie together chords which have no common pitches, a
1019 warning message will appear and no ties will be created.
1021 @lilypond[fragment,verbatim,center]
1022 e' ~ e' <c' e' g'> ~ <c' e' g'>
1030 @subsubsection Tuplets
1034 Tuplets are made out of a music expression by multiplying their duration
1037 @cindex @code{\times}
1039 \times @var{fraction} @var{musicexpr}
1042 The duration of @var{musicexpr} will be multiplied by the fraction.
1043 In print, the fraction's denominator will be printed over the notes,
1044 optionally with a bracket. The most common tuplet is the triplet in
1045 which 3 notes have the length of 2, so the notes are 2/3 of
1046 their written length:
1048 @lilypond[fragment,verbatim,center]
1049 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1052 [todo: document tupletSpannerDuration]
1058 @subsubsection Text spanner
1059 @cindex Text spanner
1063 @subsubsection Ottava
1065 @unnumberedsubsubsec Ottava
1067 [move to trick. Not a supported feature.]
1069 @lilypond[fragment,relative,verbatim]
1071 \property Voice.TextSpanner \set #'type = #'dotted-line
1072 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1073 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1074 \property Staff.centralCPosition = #-13
1075 a\spanrequest \start "text" b c a \spanrequest \stop "text"
1080 @c . {Span requests}
1082 @subsubsection Span requests
1083 @cindex Span requests
1085 @cindex @code{\spanrequest}
1088 \spanrequest @var{startstop} @var{type}
1090 @cindex @code{\start}
1091 @cindex @code{\stop}
1093 Define a spanning request. The @var{startstop} parameter is either -1
1094 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
1095 describes what should be started. Supported types are @code{crescendo},
1096 @code{decrescendo}, @code{beam}, @code{slur}. [FIXME: many more] This
1097 is an internal command. Users should use the shorthands which are
1098 defined in the initialization file @file{spanners.ly}.
1100 You can attach a (general) span request to a note using
1102 @lilypond[fragment,verbatim,center]
1103 c'4-\spanrequest \start "slur"
1104 c'4-\spanrequest \stop "slur"
1107 The slur syntax with parentheses is a shorthand for this.
1112 @subsection Ornaments
1121 @subsubsection Articulation
1122 @cindex Articulation
1124 @cindex articulations
1128 A variety of symbols can appear above and below notes to indicate
1129 different characteristics of the performance. These symbols can be
1130 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1131 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1132 forced to appear above or below the note by writing
1133 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1134 respectively. Here is a chart showing symbols above notes, with the
1135 name of the corresponding symbol appearing underneath.
1141 \property Score.LyricSyllable \override #'font-family =
1143 \property Score.LyricSyllable \override #'font-shape = #'upright
1144 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1145 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1146 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1147 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1148 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1149 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1150 c''-\thumb c''-\segno c''-\coda
1152 \context Lyrics \lyrics {
1153 accent__ marcato__ staccatissimo__ fermata
1154 stopped__ staccato__ tenuto__ upbow
1155 downbow__ lheel__ rheel__ ltoe
1156 rtoe__ turn__ open__ flageolet
1157 reverseturn__ trill__ prall__ mordent
1158 prallprall__ prallmordent__ uprall__ downprall
1159 thumb__ segno__ coda
1163 linewidth = 5.875\in;
1172 @subsubsection Text scripts
1173 @cindex Text scripts
1177 In addition, it is possible to place arbitrary strings of text or
1178 @TeX{} above or below notes by using a string instead of an
1179 identifier: @code{c^"text"}. Fingerings
1180 can be placed by simply using digits. All of these note ornaments
1181 appear in the printed output but have no effect on the MIDI rendering of
1185 @unnumberedsubsubsec Fingerings
1188 To save typing, fingering instructions (digits 0 to 9 are
1189 supported) and single characters shorthands exist for a few
1194 \notes \context Voice {
1195 \property Voice.TextScript \set #'font-family = #'typewriter
1196 \property Voice.TextScript \set #'font-shape = #'upright
1202 c''4-^_"c-\\^{ }" s4
1209 linewidth = 5.875 \in;
1217 @cindex @code{\textscript}
1221 \textscript @var{text} @var{style}
1224 Defines a text to be printed over or under a note. @var{style} is a
1225 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1226 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1228 You can attach a general textscript request using this syntax:
1233 c4-\textscript "6" "finger"
1234 c4-\textscript "foo" "normal"
1239 This is equivalent to @code{c4-6 c4-"foo"}.
1241 @cindex @code{\script}
1250 Prints a symbol above or below a note. The argument is a string which
1251 points into the script-alias table defined in @file{scm/script.scm}.
1252 Usually the @code{\script} keyword is not used directly. Various
1253 helpful identifier definitions appear in @file{script.ly}.
1255 For information on how to add scripts, consult @file{scm/script.scm}.
1262 @subsection Grace notes
1271 @cindex @code{\grace}
1274 @cindex @code{graceAlignPosition}
1277 \grace @var{musicexpr}
1280 A grace note expression has duration 0; the next real note is
1281 assumed to be the main note.
1283 You cannot have the grace note after the main note, in terms of
1284 duration, and main notes, but you can typeset the grace notes to the
1285 right of the main note using the property
1286 @code{graceAlignPosition}.
1287 @cindex @code{flagStyle}
1289 When grace music is interpreted, a score-within-a-score is set up:
1290 @var{musicexpr} has its own time bookkeeping, and you could (for
1291 example) have a separate time signature within grace notes. While in
1292 this score-within-a-score, you can create notes, beams, slurs, etc.
1293 Unbeamed eighth notes and shorter by default have a slash through the
1294 stem. This behavior can be controlled with the
1295 @code{flagStyle} property.
1298 @lilypond[fragment,verbatim]
1300 \grace c8 c4 \grace { [c16 c16] } c4
1301 \grace { \property Grace.flagStyle = "" c16 } c4
1308 At present, nesting @code{\grace} notes is not supported. The following
1309 may cause run-time errors:
1311 @code{\grace @{ \grace c32 c16 @} c4}
1313 Since the meaning of such a construct is unclear, we don't consider
1314 this a loss. Similarly, juxtaposing two @code{\grace} sections is
1315 syntactically valid, but makes no sense and may cause runtime errors.
1317 Ending a staff or score with grace notes may also generate a run-time
1318 error, since there will be no main note to attach the grace notes to.
1320 The present implementation is not robust and generally kludgy. We expect
1321 it to change after LilyPond 1.4. Syntax changes might also be
1334 * Crescendo and Decrescendo::
1343 @subsubsection Glissando
1346 @cindex @code{\glissando}
1348 A glissando line can be requested by attaching a @code{\glissando} to a
1352 @lilypond[fragment,relative,verbatim]
1357 Printing of an additional text (such as @emph{gliss.}) must be done
1364 @subsubsection Dynamics
1377 @cindex @code{\ffff}
1391 Dynamic marks are specified by using an identifier after a note:
1392 @code{c4-\ff}. The available dynamic marks are:
1393 @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f},
1394 @code{\ff}, @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf},
1395 @code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1397 @c . {Crescendo and Decrescendo}
1398 @node Crescendo and Decrescendo
1399 @subsubsection Crescendo and Decrescendo
1401 @cindex Crescendo and Decrescendo
1405 @cindex @code{\decr}
1406 @cindex @code{\rced}
1413 A crescendo mark is started with @code{\cr} and terminated with
1414 @code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
1415 started with @code{\decr} and terminated with @code{\rced}. There are
1416 also shorthands for these marks. A crescendo can be started with
1417 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1418 can be terminated with @code{\!}. Note that @code{\!} must go before
1419 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1420 after the last note. Because these marks are bound to notes, if you
1421 want to get several marks during one note, you must use spacer notes.
1423 @lilypond[fragment,verbatim,center]
1424 c'' \< \! c'' d'' \decr e'' \rced
1425 < f''1 { s4 \< \! s2 \> \! s4 } >
1428 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1429 is an example how to do it:
1431 @lilypond[fragment,relative,verbatim]
1433 \property Voice.crescendoText = "cresc."
1434 \property Voice.crescendoSpanner = #'dashed-line
1443 @subsubsection Bar lines
1447 @cindex measure lines
1454 This is a short-cut for doing
1456 \property Score.whichBar = @var{bartype}
1459 You are encouraged to use @code{\repeat} for repetitions. See
1460 @ref{Repeats}, and the documentation of @code{whichBar} in
1461 @ref{(lilypond-internals)LilyPond context properties}.
1468 @subsubsection Breath marks
1469 @cindex Breath marks
1475 @subsection Bar check
1479 @cindex @code{barCheckNoSynchronize}
1483 Whenever a bar check is encountered during interpretation, a warning
1484 message is issued if it doesn't fall at a measure boundary. This can
1485 help you find errors in the input. Depending on the value of
1486 @code{barCheckNoSynchronize}, the beginning of the measure will be
1487 relocated, so this can also be used to shorten measures.
1489 A bar check is entered using the bar symbol, @code{|}
1500 @section Piano music
1502 * Automatic staff changes::
1503 * Manual staff switches::
1510 @c . {Automatic staff changes}
1511 @node Automatic staff changes
1512 @subsection Automatic staff changes
1513 @cindex Automatic staff changes
1517 @node Manual staff switches
1518 @subsection Manual staff switches
1520 @cindex manual staff switches
1521 @cindex staff switch, manual
1523 @cindex @code{\translator}
1525 \translator @var{contexttype} = @var{name}
1528 A music expression indicating that the context which is a direct
1529 child of the a context of type @var{contexttype} should be shifted to
1530 a context of type @var{contexttype} and the specified name.
1532 Usually this is used to switch staffs in Piano music, e.g.
1535 \translator Staff = top @var{Music}
1549 @subsection Arpeggio
1552 @cindex broken arpeggio
1553 @cindex @code{\arpeggio}
1555 You can specify an arpeggio sign on a chord by attaching an
1556 @code{\arpeggio} to a note of the chord.
1560 @lilypond[fragment,relative,verbatim]
1561 \context Voice <c'\arpeggio e g c>
1565 When an arpeggio crosses staffs in piano music, you attach an arpeggio
1566 to the chords in both staffs, and set
1567 @code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios
1571 @lilypond[fragment,relative,verbatim]
1572 \context PianoStaff <
1573 \property PianoStaff.connectArpeggios = ##t
1574 \context Voice = one { <c''\arpeggio e g c> }
1575 \context Voice = other { \clef bass; <c,,\arpeggio e g>}
1582 @c . {Follow Thread}
1584 @subsection Follow Thread
1585 @cindex follow thread
1586 @cindex staff switching
1589 [todo: different name, eg. voice line ? ]
1591 @cindex @code{followThread}
1593 Whenever a voice switches to another staff a line connecting the notes
1594 can be printed automatically. This is enabled if the property
1595 @code{PianoStaff.followThread} is set to true:
1598 @lilypond[fragment,relative,verbatim]
1599 \context PianoStaff <
1600 \property PianoStaff.followThread = ##t
1601 \context Staff \context Voice {
1603 \translator Staff=two
1606 \context Staff=two {\clef bass; \skip 1*2;}
1620 * Automatic syllable durations::
1625 @subsection Lyrics mode
1629 @cindex @code{\lyrics}
1631 Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
1632 rules that make it easy to include punctuation and diacritical marks in
1633 words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
1634 format or a standard encoding without needing quotes. The precise
1635 definition of this mode is ludicrous, and this will remain so until the
1636 authors of LilyPond acquire a deeper understanding of character
1637 encoding, or someone else steps up to fix this.
1639 A word in Lyrics mode begins with: an alphabetic character, @code{_},
1640 @code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
1641 through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
1642 any 8-bit character with ASCII code over 127, or a two-character
1643 combination of a backslash followed by one of @code{`}, @code{'},
1644 @code{"}, or @code{^}.
1646 Subsequent characters of a word can be any character that is not a digit
1647 and not white space. One important consequence of this is that a word
1648 can end with `@code{@}}', which may be confusing. However, LilyPond will
1649 issue a warning. Any @code{_} character which appears in an unquoted
1650 word is converted to a space. This provides a mechanism for introducing
1651 spaces into words without using quotes. Quoted words can also be used
1652 in Lyrics mode to specify words that cannot be written with the above
1653 rules. Here are some examples. Not all of these words are printable by
1658 2B_||_!2B % not a word because it starts with a digit
1659 ``Hello'' % not a word because it starts with `
1660 _ _ _ _ % 4 words, each one a space
1663 Since combinations of numbers and dots are used for indicating
1664 durations, you can not enter real numbers in this mode.
1666 @cindex lyrics expressions
1668 Syllables are entered like notes, with pitches replaced by text. For
1669 example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each
1670 with quarter note duration. Note that the hyphen has no special
1671 meaning for lyrics, and does not introduce special symbols. See
1672 section @ref{Lexical modes} for a description of what is interpreted as
1675 Spaces can be introduced into a lyric either by using quotes
1676 (@code{"}) or by using an underscore without quotes: @code{He_could4
1677 not4}. All unquoted underscores are converted to spaces. Printing
1678 lyrics is discussed in the next section.
1681 @c . {Printing lyrics}
1682 @node Printing lyrics
1683 @subsection Printing lyrics
1687 Lyric syllables must be interpreted within a @code{Lyrics} context for
1688 printing them. Here is a full example:
1694 \notes \transpose c'' {
1696 e f g2 | e4 f g2 \bar "|.";
1698 \context Lyrics \lyrics {
1699 Va-4 der Ja- cob Va- der Ja- cob
1700 Slaapt gij nog?2 Slaapt4 gij nog?2
1712 @cindex lyric extender
1714 You may want a continuous line after the syllables to show melismata.
1715 To achieve this effect, add a @code{__} lyric as a separate word
1716 after the lyric to be extended. This will create an extender, a line
1717 that extends over the entire duration of the lyric. This line will
1718 run all the way to the start of the next lyric, so you may want to
1719 shorten it by using a blank lyric (using @code{_}).
1726 \notes \relative c'' {
1727 a4 () b () c () d | c () d () b () a | c () d () b () a
1729 \context Lyrics \lyrics {
1730 foo1 __ | bar2. __ _4 | baz1 __
1738 @cindex Lyric hyphen
1740 If you want to have hyphens centered between syllables (rather than
1741 attached to the end of the first syllable) you can use the special
1742 `@code{-}@code{-}' lyric as a separate word between syllables. This
1743 will result in a hyphen which length varies depending on the space
1744 between syllables, and which will be centered between the syllables.
1752 \notes \transpose c'' {
1754 e f g2 | e4 f g2 \bar "|.";
1756 \context Lyrics \lyrics {
1757 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1758 Slaapt gij nog?2 | Slaapt4 gij nog?2
1767 @c . {Automatic syllable durations}
1768 @node Automatic syllable durations
1769 @subsection Automatic syllable durations
1770 @cindex Automatic syllable durations
1773 [explain automatic phrasing]
1774 @cindex automatic lyric durations
1775 @cindex @code{\addlyrics}
1777 If you have lyrics that are set to a melody, you can import the rhythm
1778 of that melody into the lyrics using @code{\addlyrics}. The syntax for
1781 \addlyrics @var{musicexpr1 musicexpr2}
1784 This means that both @var{musicexpr1} and @var{musicexpr2} are
1785 interpreted, but that every non-command atomic music expression
1786 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1787 of @var{musicexpr1}.
1788 @cindex @code{automaticMelismata}
1790 If the property @code{automaticMelismata} is set in the
1791 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1795 @lilypond[verbatim,fragment]
1798 \property Voice.automaticMelismata = ##t
1799 c8 () cis d8. e16 f2
1801 \context Lyrics \lyrics {
1806 You should use a single rhythm melody, and single rhythm lyrics (a
1807 constant duration is the obvious choice). If you do not, you will get
1808 undesired effects when using multiple stanzas:
1811 @lilypond[verbatim,fragment]
1814 c8 () cis d8. e16 f2
1816 \context Lyrics \lyrics
1823 It is valid (but probably not very useful) to use notes instead of
1824 lyrics for @var{musicexpr2}.
1833 [chords vs. simultaneous music]
1837 * Entering named chords::
1838 * Printing named chords::
1843 @subsection Chords mode
1846 Chord mode is introduced by the keyword
1847 @code{\chords}. It is similar to Note mode, but
1848 words are also looked up in a chord modifier table (containing
1849 @code{maj}, @code{dim}, etc).
1851 Since combinations of numbers and dots are used for indicating
1852 durations, you can not enter real numbers in this mode. Dashes
1853 and carets are used to indicate chord additions and subtractions,
1854 so scripts can not be entered in Chord mode.
1856 @c . {Entering named chords}
1857 @node Entering named chords
1858 @subsection Entering named chords
1859 @cindex Chords names
1861 Chord names are a way to generate simultaneous music expressions that
1862 correspond with traditional chord names. It can only be used in
1863 Chord mode (see section @ref{Lexical modes}).
1867 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1870 @var{tonic} should be the tonic note of the chord, and @var{duration}
1871 is the chord duration in the usual notation. There are two kinds of
1872 modifiers. One type is @emph{chord additions}, which are obtained by
1873 listing intervals separated by dots. An interval is written by its
1874 number with an optional @code{+} or @code{-} to indicate raising or
1875 lowering by half a step. Chord additions has two effects: It adds
1876 the specified interval and all lower odd numbered intervals to the
1877 chord, and it may lower or raise the specified interval. Intervals
1878 must be separated by a dot (@code{.}).
1881 Throughout these examples, chords have been shifted around the staff
1882 using @code{\transpose}.
1887 @lilypond[fragment,verbatim]
1891 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1903 The second type of modifier that may appear after the @code{:} is a
1904 named modifier. Named modifiers are listed in the file
1905 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
1906 @code{min} which lower the 3rd half a step, `@code{aug}' which
1907 raises the 5th, `@code{dim}' which lowers the 5th,
1908 `@code{maj}' which adds a raised 7th, and `@code{sus}'
1909 which replaces the 5th with a 4th.
1913 @lilypond[fragment,verbatim]
1916 c1:m c:min7 c:maj c:aug c:dim c:sus
1924 Chord subtractions are used to eliminate notes from a chord. The
1925 notes to be subtracted are listed after a @code{^} character,
1928 @lilypond[fragment,verbatim,center]
1937 Chord inversions can be specified by appending `@code{/}' and
1938 the name of a single note to a chord. This has the effect of
1939 lowering the specified note by an octave so it becomes the lowest
1940 note in the chord. If the specified note is not in the chord, a
1941 warning will be printed.
1943 @lilypond[fragment,verbatim,center]
1953 Bass notes can be added by `@code{/+}' and
1954 the name of a single note to a chord. This has the effect of
1955 adding the specified note to the chord, lowered by an octave,
1956 so it becomes the lowest note in the chord.
1958 @lilypond[fragment,verbatim,center]
1967 The most interesting application is printing chord names, which is
1968 explained in the next subsection.
1970 You should not combine @code{\relative} with named chords. [FIXME]
1972 @c . {Printing named chords}
1973 @node Printing named chords
1974 @subsection Printing named chords
1980 @cindex printing chord names
1983 @cindex @code{ChordNames}
1984 @cindex @code{ChordNameVoice}
1986 For displaying printed chord names, use the @code{ChordNames} and
1987 @code{ChordNameVoice} contexts. The chords may be entered either using
1988 the notation described above, or directly using simultaneous music.
1993 \chords {a1 b c} <d f g> <e g b>
1997 \context ChordNamesVoice \scheme
1998 \context Staff \transpose c'' \scheme
2000 \paper { linewidth = -1.; }
2005 You can make the chord changes stand out more by setting property
2006 @code{ChordNames.chordChanges} to true. This will only display chord
2007 names when there's a change in the chords scheme, but always display the
2008 chord name after a line break:
2014 c1:m \break c:m c:m c:m d
2019 \context ChordNames \scheme
2020 \context Staff \transpose c'' \scheme
2023 linewidth = 40 * \staffspace;
2035 LilyPond examines chords specified as lists of notes to determine a
2036 name to give the chord. LilyPond will not try to
2037 identify chord inversions or added base, which may result in strange
2038 chord names when chords are entered as a list of pitches:
2041 @lilypond[verbatim,center]
2050 \context ChordNamesVoice \scheme
2051 \context Staff \scheme
2053 \paper { linewidth = -1.; }
2058 To specify chord inversions, append @code{/<notename>}. To specify an
2059 added bass note, append @code{/+<notename}:
2062 @lilypond[verbatim,center]
2069 \context ChordNames \scheme
2070 \context Staff \transpose c'' \scheme
2072 \paper { linewidth = -1.; }
2077 The chord names that LilyPond should print are fully customizable. The
2078 code to print chord names is written in Scheme. It can be found in
2079 @file{scm/chord-name.scm}. Chord names are based on Banter style
2080 naming, which is unambiguous and has a logical structure. Typical
2081 American style chord names are implemented as a variation on Banter
2082 names, they can be selected by setting property @code{ChordName.style}
2087 \include "english.ly"
2092 df:m5- % Diminished triad
2093 c:5^3 % Root-fifth chord
2094 c:4^3 % Suspended fourth triad
2095 c:5+ % Augmented triad
2097 c:m5-.7- % Diminished seventh
2098 c:7+ % Major seventh
2099 c:7.4^3 % Dominant seventh suspended fourth
2100 c:5+.7 % Augmented dominant seventh
2101 c:m5-.7 % "Half" diminished seventh
2102 c:5-.7 % Dominant seventh flat fifth
2103 c:5-.7+ % Major seventh flat fifth
2104 c:m7+ % Minor-major seventh
2105 c:m7 % Minor seventh
2106 c:7 % Dominant seventh
2109 c:9^7 % Major triad w/added ninth
2110 c:6.9^7 % Six/Nine chord
2111 c:9 % Dominant ninth
2112 c:7+.9 % Major ninth
2113 c:m7.9 % Minor ninth
2118 \context ChordNames \scheme
2119 \context Staff \transpose c'' \scheme
2124 ChordName \override #'word-space = #1
2125 ChordName \override #'style = #'american
2132 Similarly, Jazz style chord names are implemented as a variation on
2133 American style names:
2139 c:6 % 6 = major triad with added sixth
2140 c:maj % triangle = maj
2145 c:m % m = minor triad
2146 c:m.6 % m6 = minor triad with added sixth
2147 c:m.7+ % m triangle = minor major seventh chord
2155 c:7.5+ % +7 = augmented dominant
2156 c:7.5- % 7b5 = hard diminished dominant
2163 c:13.9-^11 % 7(b9,13)
2164 c:13.9+^11 % 7(#9,13)
2166 c:13-.9-^11 % 7(b9,b13)
2167 c:13-.9+^11 % 7(#9,b13)
2169 % half diminished chords
2170 c:m5-.7 % slashed o = m7b5
2171 c:9.3-.5- % o/7(pure 9)
2174 c:m5-.7- % o = diminished seventh chord
2179 \context ChordNames \scheme
2180 \context Staff \transpose c'' \scheme
2185 ChordName \override #'word-space = #1
2186 ChordName \override #'style = #'jazz
2194 @section Writing parts
2200 * Multi measure rests::
2211 tranposing midi property.
2215 @c . {Rehearsal marks}
2216 @node Rehearsal marks
2217 @subsection Rehearsal marks
2218 @cindex Rehearsal marks
2220 @cindex @code{\mark}
2223 \mark @var{unsigned};
2224 @cindex @code{Mark_engraver}
2228 Prints a mark over or under the staff.
2230 [TODO: automatic increments]
2233 @subsection Transpose
2235 @cindex transposition of pitches
2236 @cindex @code{\transpose}
2238 A music expression can be transposed with @code{\transpose}. The syntax
2241 \transpose @var{pitch} @var{musicexpr}
2244 This means that middle C in @var{musicexpr} is transposed to
2247 @code{\transpose} distinguishes between enharmonic pitches: both
2248 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2249 a tone. The first version will print sharps and the second version
2253 @lilypond[fragment,verbatim]
2256 { \key e \major; c d e f }
2258 \transpose des'' { \key e \major; c d e f }
2259 \transpose cis'' { \key e \major; c d e f }
2265 If you want to use both @code{\transpose} and @code{\relative}, then
2266 you must use @code{\transpose} first. @code{\relative} will have no
2267 effect music that appears inside a @code{\transpose}.
2270 @c . {Multi measure rests}
2271 @node Multi measure rests
2272 @subsection Multi measure rests
2273 @cindex Multi measure rests
2277 Multi measure rests are entered using `@code{R}'. It is specifically
2278 meant for entering parts: the rest can expand to fill a score with
2279 rests, or it can be printed as a single multimeasure rest This expansion
2280 is controlled by the property @code{Score.skipBars}. If this is set to true,
2281 Lily will not expand empty measures, and the appropriate number is added
2284 @lilypond[fragment,verbatim]
2285 \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2288 Currently, there is no way to condense multiple rests into a single
2291 @cindex condensing rests
2296 @section Page layout
2310 @subsection Paper block
2313 The most important output definition is the @code{\paper} block, for
2314 music notation. The syntax is
2317 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2320 where each of the items is one of
2323 @item An assignment. The assignment must be terminated by a
2326 @item A context definition. See section @ref{Context definitions} for
2327 more information on context definitions.
2329 @item \stylesheet declaration. Its syntax is
2331 \stylesheet @var{alist}
2334 See @file{font.scm} for details of @var{alist}.
2337 @c . {Paper variables}
2338 @node Paper variables
2339 @subsection Paper variables
2340 @cindex Paper variables
2342 The paper block has some variables you may want to use or change:
2345 @cindex @code{indent}
2347 The indentation of the first line of music.
2348 @cindex @code{staffspace}
2350 @item @code{staffspace}
2351 The distance between two staff lines, calculated from the center
2352 of the lines. You should use either this or @code{stafflinethickness}
2353 as a unit for distances you modify.
2355 @cindex @code{linewidth}
2356 @item @code{linewidth}
2357 Sets the width of the lines.
2359 If set to a negative value, a single
2360 unjustified line is produced.
2362 @cindex @code{textheight}
2364 @item @code{textheight}
2365 Sets the total height of the music on each page. Only used by
2367 @cindex @code{interscoreline}
2369 @item @code{interscoreline}
2370 Sets the spacing between the score lines. Defaults to 16 pt.
2371 @cindex @code{interscorelinefill}
2373 @item @code{interscorelinefill}
2374 If set to a positive number, the distance between the score
2375 lines will stretch in order to fill the full page. In that
2376 case @code{interscoreline} specifies the minimum spacing.
2378 @cindex @code{stafflinethickness}
2380 @item @code{stafflinethickness}
2381 Determines the thickness of staff lines, and also acts as a scaling
2382 parameter for other line thicknesses.
2389 @subsection Font size
2392 The Feta font provides musical symbols at six different sizes. These
2393 fonts are 11 point, 13 point, 16 point, 20 point,
2394 23 point, and 26 point. The point size of a font is the
2395 height of the five lines in a staff when displayed in the font.
2397 Definitions for these sizes are the files @file{paperSZ.ly}, where
2398 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
2399 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
2400 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
2401 @code{paperTwentysix} are defined respectively. The default
2402 @code{\paper} block is also set.
2404 The font definitions are generated using a Scheme function. For more
2405 details, see the file @file{font.scm}.
2411 @subsection Paper size
2416 @cindex @code{papersize}
2418 To change the paper size, you must first set the
2419 @code{papersize} variable at top level. Set it to
2420 the strings @code{a4}, @code{letter}, or @code{legal}. After this
2421 specification, you must set the font as described above. If you want
2422 the default font, then use the 20 point font. The new paper size will
2423 not take effect if the font is not loaded and selected afterwards.
2427 \include "paper16.ly"
2431 \paper @{ \paperSixteen @}
2435 The file "paper16.ly" will now include a file named @file{a4.ly}, which
2436 will set the paper variables @code{hsize} and @code{vsize} (used by
2447 @subsection Line break
2450 @cindex breaking lines
2452 Line breaks are normally computed automatically. They are chosen such
2453 that the resulting spacing has low variation, and looks neither cramped
2456 Occasionally you might want to override the automatic breaks; you can do
2457 this by specifying @code{\break}. This will force a line break at this
2458 point. Do remember that line breaks can only occur at places where there
2459 are barlines. If you want to have a line break where there is no
2460 barline, you can force a barline by entering @code{\bar "";}.
2462 Similarly, @code{\noBreak} forbids a line break at a certain point.
2464 @cindex @code{\penalty}
2466 The @code{\break} and @code{\noBreak} commands are defined in terms of
2467 the penalty command:
2469 \penalty @var{int} @code{;}
2472 This imposes encourages or discourages LilyPond to make a line break
2475 @strong{Warning} do not use @code{\penalty} directly. It is rather
2476 kludgy, and slated for rewriting.
2480 @subsection Page break
2483 @cindex breaking pages
2486 Page breaks are normally computed by @TeX{}, so they are not under direct
2487 control. However, you can insert a commands into the @file{.tex} output to
2488 instruct @TeX{} where to break pages. For more details, see the
2489 example file @file{input/test/between-systems.ly}
2504 * MIDI instrument names::
2510 @subsection MIDI block
2514 The MIDI block is analogous to the paper block, but it is somewhat
2515 simpler. The @code{\midi} block can contain:
2519 @item a @code{\tempo} definition
2520 @item context definitions
2523 Assignments in the @code{\midi} block are not allowed.
2527 @cindex context definition
2529 Context definitions follow precisely the same syntax as within the
2530 \paper block. Translation modules for sound are called performers.
2531 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2534 @c . {MIDI instrument names}
2535 @node MIDI instrument names
2536 @subsection MIDI instrument names
2537 @cindex instrument names
2538 @cindex @code{Staff.midiInstrument}
2539 @cindex @code{Staff.instrument}
2541 The MIDI instrument name is set by the @code{Staff.midiInstrument}
2542 property or, if that property is not set, the @code{Staff.instrument}
2543 property. The instrument name should be chosen from the following list.
2544 If the selected string does not exactly match, then LilyPond uses the
2547 [FIXME: to appendix ]
2551 "acoustic grand" "contrabass" "lead 7 (fifths)"
2552 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2553 "electric grand" "pizzicato strings" "pad 1 (new age)"
2554 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2555 "electric piano 1" "timpani" "pad 3 (polysynth)"
2556 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2557 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2558 "clav" "synthstrings 1" "pad 6 (metallic)"
2559 "celesta" "synthstrings 2" "pad 7 (halo)"
2560 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2561 "music box" "voice oohs" "fx 1 (rain)"
2562 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2563 "marimba" "orchestra hit" "fx 3 (crystal)"
2564 "xylophone" "trumpet" "fx 4 (atmosphere)"
2565 "tubular bells" "trombone" "fx 5 (brightness)"
2566 "dulcimer" "tuba" "fx 6 (goblins)"
2567 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2568 "percussive organ" "french horn" "fx 8 (sci-fi)"
2569 "rock organ" "brass section" "sitar"
2570 "church organ" "synthbrass 1" "banjo"
2571 "reed organ" "synthbrass 2" "shamisen"
2572 "accordion" "soprano sax" "koto"
2573 "harmonica" "alto sax" "kalimba"
2574 "concertina" "tenor sax" "bagpipe"
2575 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2576 "acoustic guitar (steel)" "oboe" "shanai"
2577 "electric guitar (jazz)" "english horn" "tinkle bell"
2578 "electric guitar (clean)" "bassoon" "agogo"
2579 "electric guitar (muted)" "clarinet" "steel drums"
2580 "overdriven guitar" "piccolo" "woodblock"
2581 "distorted guitar" "flute" "taiko drum"
2582 "guitar harmonics" "recorder" "melodic tom"
2583 "acoustic bass" "pan flute" "synth drum"
2584 "electric bass (finger)" "blown bottle" "reverse cymbal"
2585 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2586 "fretless bass" "whistle" "breath noise"
2587 "slap bass 1" "ocarina" "seashore"
2588 "slap bass 2" "lead 1 (square)" "bird tweet"
2589 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2590 "synth bass 2" "lead 3 (calliope)" "helicopter"
2591 "violin" "lead 4 (chiff)" "applause"
2592 "viola" "lead 5 (charang)" "gunshot"
2593 "cello" "lead 6 (voice)"
2604 @cindex beats per minute
2605 @cindex metronome marking
2607 @cindex @code{\tempo}
2609 \tempo @var{duration} = @var{perminute} @code{;}
2612 Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
2613 output with 76 quarter notes per minute.
2621 @section Music entry
2632 @subsection Relative
2634 @cindex relative octave specification
2636 Octaves are specified by adding @code{'} and @code{,} to pitch names.
2637 When you copy existing music, it is easy to accidentally put a pitch in
2638 the wrong octave and hard to find such an error. To prevent these
2639 errors, LilyPond features octave entry.
2641 @cindex @code{\relative}
2643 \relative @var{startpitch} @var{musicexpr}
2646 The octave of notes that appear in @var{musicexpr} are calculated as
2647 follows: If no octave changing marks are used, the basic interval
2648 between this and the last note is always taken to be a fourth or less.
2649 The octave changing marks @code{'} and @code{,} can then
2650 be added to raise or lower the pitch by an extra octave. Upon entering
2651 relative mode, an absolute starting pitch must be specified that will
2652 act as the predecessor of the first note of @var{musicexpr}.
2654 This distance is determined without regarding accidentals: a
2655 @code{fisis} following a @code{ceses} will be put above the
2658 Entering scales is straightforward in relative mode.
2660 @lilypond[fragment,verbatim,center]
2662 g a b c d e f g g, g
2666 And octave changing marks are used for intervals greater than a fourth.
2668 @lilypond[fragment,verbatim,center]
2670 c g c f, c' a, e'' }
2673 If the preceding item is a chord, the first note of the chord is used
2674 to determine the first note of the next chord. But other notes
2675 within the second chord are determined by looking at the immediately
2678 @lilypond[fragment,verbatim,center]
2685 @cindex @code{\notes}
2687 The pitch after the @code{\relative} contains a notename. To parse
2688 the pitch as a notename, you have to be in note mode, so there must
2689 be a surrounding @code{\notes} keyword (which is not
2692 The relative conversion will not affect @code{\transpose} or
2693 @code{\relative} sections in its argument. If you want to use
2694 relative within transposed music, you must place an additional
2695 @code{\relative} inside the @code{\transpose}.
2698 @c . {Point and click}
2699 @node Point and click
2700 @subsection Point and click
2709 * Selecting contexts::
2710 * Context definitions::
2711 * Notation Contexts::
2714 @c . {Music expressions}
2715 @node Selecting contexts
2716 @subsection Selecting contexts
2718 @cindex @code{\context}
2719 @cindex context selection
2722 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
2725 Interpret @var{musicexpr} within a context of type @var{contexttype}.
2726 If the context does not exist, it will be created. The new context
2727 can optionally be given a name.
2731 @c . {Context definitions}
2732 @node Context definitions
2733 @subsection Context definitions
2735 @cindex context definition
2736 @cindex translator definition
2737 @cindex engraver hacking
2740 A notation contexts is defined by the following information
2745 @item The LilyPond modules that do the actual conversion of music to
2746 notation. Each module is a so-called
2751 @item How these modules should cooperate, i.e. which ``cooperation
2752 module'' should be used. This cooperation module is a special
2755 @item What other contexts the context can contain,
2757 @item What properties are defined.
2760 A context definition has this syntax:
2764 \translator @code{@{}
2765 @var{translatorinit} @var{translatormodifierlist}
2769 @var{translatorinit} can be an identifier or
2771 \type @var{typename} @code{;}
2773 where @var{typename} is one of
2776 @cindex @code{Engraver_group_engraver}
2777 @item @code{Engraver_group_engraver}
2778 The standard cooperation engraver.
2779 @cindex @code{Score_engraver}
2781 @item @code{Score_engraver}
2782 This is cooperation module that should be in the top level context.
2783 @cindex @code{Grace_engraver_group}
2785 @item @code{Grace_engraver_group}
2786 This is a special cooperation module (resembling
2787 @code{Score_engraver}) that is used to created an embedded
2791 @var{translatormodifierlist} is a list of items where each item is
2795 @item @code{\consists} @var{engravername} @code{;}
2796 Add @var{engravername} to the list of modules in this context.
2797 The order of engravers added with @code{\consists} is
2800 @item @code{\consistsend} @var{engravername} @code{;}
2801 Analogous to @code{\consists}, but makes sure that
2802 @var{engravername} is always added to the end of the list of
2805 Some engraver types need to be at the end of the list; this
2806 insures they are put there, and stay there, if a user adds or
2807 removes engravers. This command is usually not needed for
2810 @item @code{\accepts} @var{contextname} @code{;}
2811 Add @var{contextname} to the list of context this context can
2812 contain. The first listed context is the context to create by
2815 @item @code{\denies}. The opposite of @code{\accepts}. Added for
2816 completeness, but is never used in practice.
2819 @item @code{\remove} @var{engravername} @code{;}
2820 Remove a previously added (with @code{\consists}) engraver.
2822 @item @code{\name} @var{contextname} @code{;}
2823 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2824 the name is not specified, the translator won't do anything.
2826 @item @var{propname} @code{=} @var{value} @code{;}
2827 A property assignment.
2830 In the @code{\paper} block, it is also possible to define translator
2831 identifiers. Like other block identifiers, the identifier can only
2832 be used as the very first item of a translator. In order to define
2833 such an identifier outside of @code{\score}, you must do
2839 foo = \translator @{ @dots{} @}
2846 \translator @{ \foo @dots{} @}
2854 @cindex paper types, engravers, and pre-defined translators
2856 Some pre-defined identifiers can simplify modification of
2857 translators. The pre-defined identifiers are:
2860 @cindex @code{StaffContext}
2861 @item @code{StaffContext}
2862 Default Staff context.
2863 @cindex @code{RhythmicStaffContext}
2865 @item @code{RhythmicStaffContext}
2866 Default RhythmicStaff context.
2867 @cindex @code{VoiceContext}
2869 @item @code{VoiceContext}
2870 Default Voice context.
2871 @cindex @code{ScoreContext}
2873 @item @code{ScoreContext}
2874 Default Score context.
2876 @cindex @code{HaraKiriStaffContext}
2878 @item @code{HaraKiriStaffContext}
2879 Staff context that does not print if it only contains rests.
2880 Useful for orchestral scores.@footnote{Harakiri, also called
2881 Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
2885 Using these pre-defined values, you can remove or add items to the
2894 \remove Some_engraver;
2895 \consists Different_engraver;
2905 @c . {Notation Contexts}
2906 @node Notation Contexts
2907 @subsection Notation Contexts
2909 @cindex notation contexts
2911 Notation contexts are objects that only exist during a run of
2912 LilyPond. During the interpretation phase of LilyPond, the Music
2913 expression contained in a @code{\score} block is interpreted in time
2914 order. This is the order in which humans read, play, and write
2917 A context is an object that holds the reading state of the
2918 expression; it contains information like
2921 @item What notes are playing at this point?
2922 @item What symbols will be printed at this point?
2923 @item In what style will they printed?
2924 @item What is the current key signature, time signature, point within
2928 Contexts are grouped hierarchically: A @code{Voice} context is
2929 contained in a @code{Staff} context (because a staff can contain
2930 multiple voices at any point), a @code{Staff} context is contained in
2931 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
2932 these can all contain multiple staffs).
2934 Contexts associated with sheet music output are called @emph{notation
2935 contexts}, those for sound output are called performance contexts.
2937 Contexts are created either manually or automatically. Initially, the
2938 top level music expression is interpreted by the top level context (the
2939 @code{Score} context). When a atomic music expression (i.e. a note, a
2940 rest, etc.), a nested set of contexts is created that can process these
2941 atomic expressions, as in this example:
2944 \score @{ \notes @{ c4 @} @}
2947 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
2948 context. When the note @code{c4} itself is interpreted, a set of
2949 contexts is needed that will accept notes. The default for this is a
2950 @code{Voice} context, contained in a @code{Staff} context. Creation of
2951 these contexts results in the staff being printed.
2955 You can also create contexts manually, and you probably have to do so
2956 if you want to typeset complicated multiple part material. If a
2957 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
2958 during the interpretation phase, the @var{musicexpr} argument will be
2959 interpreted with a context of type @var{name}. If you specify a name,
2960 the specific context with that name is searched.
2964 If a context of the specified type and name can not be found, a new
2965 one is created. For example,
2971 \notes \relative c'' {
2972 c4 <d4 \context Staff = "another" e4> f
2979 In this example, the @code{c} and @code{d} are printed on the
2980 default staff. For the @code{e}, a context Staff called
2981 @code{another} is specified; since that does not exist, a new
2982 context is created. Within @code{another}, a (default) Voice context
2983 is created for the @code{e4}. When all music referring to a
2984 context is finished, the context is ended as well. So after the
2985 third quarter, @code{another} is removed.
2987 Almost all music expressions inherit their interpretation context
2988 from their parent. In other words, suppose that the syntax for a
2993 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
2996 When the interpretation of this music expression starts, the context
2997 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
3000 Lastly, you may wonder, why this:
3006 \notes \relative c'' @{
3014 doesn't result in this:
3019 \notes \relative c'' {
3026 For the @code{c4}, a default @code{Staff} (with a contained
3027 @code{Voice}) context is created. After the @code{c4} ends, no
3028 music refers to this default staff, so it would be ended, with the
3029 result shown. To prevent this inconvenient behavior, the context to
3030 which the sequential music refers is adjusted during the
3031 interpretation. So after the @code{c4} ends, the context of the
3032 sequential music is also the default @code{Voice} context.
3033 The @code{d4} gets interpreted in the same context
3036 Properties that are set in one context are inherited by all of the
3037 contained contexts. This means that a property valid for the
3038 @code{Voice} context can be set in the @code{Score} context (for
3039 example) and thus take effect in all @code{Voice} contexts.
3041 Properties can be preset within the @code{\translator} block
3042 corresponding to the appropriate context. In this case, the syntax
3046 @var{propname} @code{=} @var{value}
3049 This assignment happens before interpretation starts, so a
3050 @code{\property} expression will override any predefined settings.
3052 The property settings are used during the interpretation phase. They
3053 are read by the LilyPond modules where interpretation contexts are
3054 built of. These modules are called @emph{translators}. Translators for
3055 notation are called @emph{engravers}, and translators for sound are
3056 called @emph{performers}.
3060 @c . {Syntactic details}
3061 @node Syntactic details
3062 @section Syntactic details
3063 @cindex Syntactic details
3067 * Music expressions::
3076 @subsection Top level
3079 This section describes what you may enter at top level.
3082 @unnumberedsubsec Score definition
3083 @cindex score definition
3085 The output is generated combining a music expression with an output
3086 definition. A score block has the following syntax:
3089 \score @{ @var{musicexpr} @var{outputdefs} @}
3092 @var{outputdefs} are zero or more output definitions. If no output
3093 definition is supplied, the default @code{\paper} block will be added.
3097 @subsubsection Score
3101 @subsubsection Paper
3109 @subsubsection Header
3111 @cindex @code{\header}
3116 \header @{ @var{key1} = @var{val1};
3117 @cindex @code{ly2dvi}
3118 @var{key2} = @var{val2}; @dots{} @}
3122 A header describes the file's contents. It can also appear in a
3123 @code{\score} block. Tools like @code{ly2dvi} can use this
3124 information for generating titles. Key values that are used by
3125 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
3126 metre, arranger, piece and tagline.
3128 It is customary to put the @code{\header} at the top of the file.
3130 @subsubsection Default output
3132 A @code{\midi} or @code{\paper} block at top-level sets the default
3134 paper block for all scores that lack an explicit paper block.
3138 @subsection Identifiers
3141 All of the information in a LilyPond input file, is represented as a
3142 Scheme value. In addition to normal Scheme data types (such as pair,
3143 number, boolean, etc.), LilyPond has a number of specialized data types,
3150 @item Translator_def
3154 @item Music_output_def
3155 @item Moment (rational number)
3158 LilyPond also includes some transient object types. Objects of these
3159 types are built during a LilyPond run, and do not `exist' per se within
3160 your input file. These objects are created as a result of your input
3161 file, so you can include commands in the input to manipulate them,
3162 during a lilypond run.
3165 @item Grob: short for Graphical object. See @ref{Grobs}.
3166 @item Molecule: device-independent page output object,
3167 including dimensions. Produced by some Grob functions
3169 @item Translator: object that produces audio objects or Grobs. This is
3170 not yet user accessible.
3171 @item Font_metric: object representing a font. (See @ref{Font metrics})
3176 @node Music expressions
3177 @subsection Music expressions
3179 @cindex music expressions
3181 Music in LilyPond is entered as a music expression. Notes, rests, lyric
3182 syllables are music expressions, and you can combine music expressions
3183 to form new ones, for example by enclosing a list of expressions in
3184 @code{\sequential @{ @}} or @code{< >}. In this example, a compound
3185 expression is formed out of the quarter note @code{c} and a quarter note
3189 \sequential @{ c4 d4 @}
3192 @cindex Sequential music
3193 @cindex @code{\sequential}
3194 @cindex sequential music
3197 @cindex Simultaneous music
3198 @cindex @code{\simultaneous}
3200 The two basic compound music expressions are simultaneous and
3204 \sequential @code{@{} @var{musicexprlist} @code{@}}
3205 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
3207 For both, there is a shorthand:
3209 @code{@{} @var{musicexprlist} @code{@}}
3213 @code{<} @var{musicexprlist} @code{>}
3215 for simultaneous music.
3216 Other compound music expressions include
3219 \transpose @var{pitch} @var{expr}
3220 \apply @var{func} @var{expr}
3221 \context @var{type} = @var{id} @var{expr}
3222 \times @var{fraction} @var{expr}
3225 In principle, the way in which you nest sequential and simultaneous to
3226 produce music is not relevant. In the following example, three chords
3227 are expressed in two different ways:
3229 @lilypond[fragment,verbatim,center]
3230 \notes \context Voice {
3231 <a c'> <b d' > <c' e'>
3232 < { a b c' } { c' d' e' } >
3236 However, in some cases, LilyPond will also try to choose contexts, and
3237 use the structure of the music expression to do so. This can have
3238 undesired effects: for example, LilyPond will create a separate staff
3239 for each note if you start a @code{\score} with a chord:
3240 @lilypond[verbatim,center]
3248 The solution is to explicitly instantiate the context you desire.
3249 In this case this is typically a Voice context
3250 @lilypond[verbatim,center]
3252 \notes\context Voice <c''4 e''>
3258 If you use @code{\context Staff} you will get separate stems for each
3259 note head, leading to collisions, so don't use that.
3265 @subsection Assignments
3268 Identifiers allow objects to be assigned to names during the parse
3269 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
3270 and to refer to an identifier, you preceed its name with a backslash:
3271 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
3272 the input-types listed above. Identifier assignments can appear at top
3273 level in the LilyPond file, but also in @code{\paper} blocks.
3275 Semicolons are forbidden after top level assignments, but mandatory in
3276 other places. The rules about semicolons and assignments are very
3277 confusing, but when LilyPond input evolves more towards Scheme, we hope
3278 that this problem will grow smaller.
3280 An identifier can be created with any string for its name, but you will
3281 only be able to refer to identifiers whose names begin with a letter,
3282 being entirely alphabetical. It is impossible to refer to an identifier
3283 whose name is the same as the name of a keyword.
3285 The right hand side of an identifier assignment is parsed completely
3286 before the assignment is done, so it is allowed to redefine an
3287 identifier in terms of its old value, e.g.
3293 When an identifier is referenced, the information it points to is
3294 copied. For this reason, an identifier reference must always be the
3295 first item in a block.
3299 \paperIdent % wrong and invalid
3303 \paperIdent % correct
3307 @c . {Lexical details}
3308 @node Lexical details
3309 @subsection Lexical details
3310 @cindex Lexical details
3315 @subsubsection Comments
3321 A one line comment is introduced by a @code{%} character.
3322 Block comments are started by @code{%@{} and ended by @code{%@}}.
3323 They cannot be nested.
3325 @c . {Direct Scheme}
3326 @subsubsection Direct Scheme
3329 @cindex Scheme, in-line code
3332 LilyPond contains a Scheme interpreter (the GUILE library) for
3333 internal use. In some places Scheme expressions also form valid syntax:
3334 whereever it is allowed,
3338 evaluates the specified Scheme code. If this is used at toplevel, then
3339 the result is discarded. Example:
3341 \property Staff.TestObject \override #'foobar = #(+ 1 2)
3344 @code{\override} expects two Scheme expressions, so there are two Scheme
3345 expressions. The first one is a symbol (@code{foobar}), the second one
3346 an integer (namely, 3).
3348 Scheme is a full-blown programming language, and a full discussion is
3349 outside the scope of this document. Interested readers are referred to
3350 the website @uref{http://www.schemers.org/} for more information on
3355 @subsubsection Keywords
3359 Keywords start with a backslash, followed by a number of lower case
3360 alphabetic characters. These are all the keywords.
3363 apply arpeggio autochange spanrequest commandspanrequest
3364 simultaneous sequential accepts alternative bar breathe
3365 char chordmodifiers chords clef cm consists consistsend
3366 context denies duration dynamicscript elementdescriptions
3367 font grace header in lyrics key mark pitch
3368 time times midi mm name pitchnames notes outputproperty
3369 override set revert partial paper penalty property pt
3370 relative remove repeat addlyrics partcombine score
3371 script stylesheet skip textscript tempo translator
3376 @subsubsection Integers
3384 Formed from an optional minus sign followed by digits. Arithmetic
3385 operations cannot be done with integers, and integers cannot be mixed
3389 @subsubsection Reals
3390 @cindex real numbers
3396 Formed from an optional minus sign and a sequence of digits followed
3397 by a @emph{required} decimal point and an optional exponent such as
3398 @code{-1.2e3}. Reals can be built up using the usual operations:
3399 `@code{+}', `@code{-}', `@code{*}', and
3400 `@code{/}', with parentheses for grouping.
3408 A real constant can be followed by one of the dimension keywords:
3409 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
3410 points, inches and centimeters, respectively. This converts the number
3411 to a real that is the internal representation of dimensions.
3415 @subsubsection Strings
3419 Begins and ends with the @code{"} character. To include a @code{"}
3420 character in a string write @code{\"}. Various other backslash
3421 sequences have special interpretations as in the C language. A string
3422 that contains no spaces can be written without the quotes. See
3423 @ref{Lexical modes} for details on unquoted strings; their
3424 interpretation varies depending on the situation. Strings can be
3425 concatenated with the @code{+} operator.
3427 The tokenizer accepts the following commands. They have no grammatical
3428 function, hence they can appear anywhere in the input.
3432 @subsubsection Main input
3435 @cindex @code{\maininput}
3437 The @code{\maininput} command is used in init files to signal that the
3438 user file must be read. This command cannot be used in a user file.
3440 @c . {File inclusion}
3441 @subsubsection Main input
3444 @subsubsection File inclusion
3445 @cindex @code{\include}
3447 \include @var{filename}
3450 Include @var{filename}. The argument @var{filename} may be a quoted string (an
3451 unquoted string will not work here!) or a string identifier. The full
3452 filename including the @file{.ly} extension must be given,
3454 @subsubsection Version information
3455 @cindex @code{\version}
3457 \version @var{string} ;
3460 Specify the version of LilyPond that a file was written for. The
3461 argument is a version string in quotes, for example @code{"1.2.0"}.
3462 This is used to detect invalid input, and to aid
3463 @code{convert-ly} a tool that automatically upgrades input files. See
3464 See @ref{convert-ly} for more information on @code{convert-ly}.
3470 @subsubsection Defining pitch names
3471 @cindex Lexical modes
3472 @cindex definining pitch names
3473 @cindex pitch names, definining
3475 @cindex chord modifier names
3477 A @code{\paper} block at top level sets the default paper block. A
3478 @code{\midi} block at top level works similarly.
3481 @subsubsection Assignments
3485 Identifier assignments may appear at top level. @ref{Assignments}
3489 @c . {Direct scheme}
3490 @subsubsection Direct scheme
3491 @cindex Direct scheme
3493 Scheme statements maybe issued to produce interesting side-effects.
3496 @c . {Lexical modes}
3498 @subsection Lexical modes
3499 @cindex Lexical modes
3502 @cindex @code{\notes}
3503 @cindex @code{\chords}
3504 @cindex @code{\lyrics}
3506 To simplify entering notes, lyrics, and chords, LilyPond has three
3507 special input modes on top of the default mode: note, lyrics and chords
3508 mode. These input modes change the way that normal, unquoted words are
3509 interpreted: for example, the word @code{cis} may be interpreted as a
3510 C-sharp, as a lyric syllable `cis' or as a C-sharp major triad
3513 A mode switch is entered as a compound music expressions
3515 @code{\notes} @var{musicexpr}
3516 @code{\chords} @var{musicexpr}
3517 @code{\lyrics} @var{musicexpr}.
3520 In each of these cases, these expressions do not add anything to the
3521 meaning of their arguments. They are just a way to indicate that the
3522 arguments should be parsed in indicated mode. The modes are treated in
3523 more detail in the sections @ref{Note entry}, @ref{Lyrics} and
3526 You may nest different input modes.
3530 @subsection Ambiguities
3535 The grammar contains a number of ambiguities. We hope to resolve them at
3539 @item The assignment
3545 can be interpreted as making a string identifier @code{\foo}
3546 containing @code{"bar"}, or a music identifier @code{\foo}
3547 containing the syllable `bar'.
3549 @item The assignment
3555 can be interpreted as making an integer identifier
3556 containing -6, or a Request identifier containing the
3557 fingering `6' (with neutral direction).
3559 @item If you do a nested repeat like
3571 then it is ambiguous to which @code{\repeat} the
3572 @code{\alternative} belongs. This is the classic if-then-else
3573 dilemma. It may be solved by using braces.
3575 @item (an as yet unidentified ambiguity :-)
3590 @unnumberedsubsec Translation property
3592 [todo: add \set/\override/\revert]
3595 @cindex @code{\property}
3597 \property @var{contextname}.@var{propname} = @var{value}
3600 Sets the @var{propname} property of the context @var{contextname} to
3601 the specified @var{value}. All three arguments are strings.
3602 Depending on the context, it may be necessary to quote the strings or
3603 to leave space on both sides of the dot.
3606 @cindex output properties
3607 @unnumberedsubsec Output properties
3609 These allow you to tweak what is happening in the back-end
3610 directly. If you want to control every detail of the output
3611 formatting, this is the feature to use. The downside to this is that
3612 you need to know exactly how the backend works. Example:
3615 @lilypond[fragment,verbatim]
3617 \context Staff \outputproperty
3618 #(make-type-checker 'note-head-interface)
3619 #'extra-offset = #'(0.5 . 0.75)
3623 This selects all note heads occurring at current staff level, and sets
3624 the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting them
3627 Use of this feature is entirely on your own risk: if you use this, the
3628 result will depend very heavily on the implementation of the backend,
3629 which we change regularly and unscrupulously.
3632 Don't move the finger 2, only text "m.d." ...
3634 #(define (make-text-checker text)
3635 (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
3638 \notes\relative c''' {
3639 \property Voice.Stem \set #'direction = #1
3640 \outputproperty #(make-text-checker "m.d.")
3641 #'extra-offset = #'(-3.5 . -4.5)
3644 \paper { linewidth = -1.; }
3652 @c .{Local emacs vars}
3655 @c minor-mode: font-lock
3656 @c minor-mode: outline
3657 @c outline-layout: (-1 : 0)
3658 @c outline-use-mode-specific-leader: "@c \."
3659 @c outline-primary-bullet: "{"
3660 @c outline-stylish-prefixes: nil
3661 @c outline-override-protect: t