3 @c A menu is needed before every deeper *section nesting of @nodes
4 @c Run M-x texinfo-all-menus-update
5 @c to automagically fill in these menus
6 @c before saving changes
14 Rhythm staff (clef, x-notehead)
15 \partcombine: -> orchestral part-HOWTO.
17 postscript, scheme output?
18 (links to?) using/existance of ly2dvi, lilypond-book
22 @c .{Reference Manual}
24 @node Reference Manual
25 @chapter Reference Manual
27 This document describes GNU LilyPond and its input format. This document
28 has been revised for LilyPond 1.3.125
57 The purpose of LilyPond is explained informally by the term `music
58 typesetter'. This is not a fully correct name: not only does the
59 program print musical symbols, it also makes esthetic decisions. All
60 symbols and their placement is @emph{generated} from a high-level
61 musical description. In other words, LilyPond would be best described
62 by `music compiler' or `music to notation compiler'.
64 Internally, LilyPond is written in a mixture of Scheme and C++. Most of
65 the algorithms and low-level routines are written in C++, but these low
66 level components are glued together using Scheme data
67 structures. LilyPond is linked to GUILE, GNU's Scheme library for
70 When lilypond is run to typeset sheet music, the following happens:
73 @item GUILE Initialization: various scheme files are read
74 @item parsing: first standard .ly initialization files are read, and
75 then the user @file{.ly} file is read.
76 @item interpretation: the music in the file is processed "in playing
77 order", i.e. in the same order as your eyes scan sheet music, and in the
78 same order that you hear the notes play.
81 in this step, the results of the interpretation, a typesetting
82 specification, is solved.
84 @item the visible results ("virtual ink") is written to the output file.
87 These stages, involve data of a specific type: during parsing,
88 @strong{Music} objects are created. During the interpretation,
89 @strong{context} is constructed, and with this context af network of
90 @strong{graphical objects} (``grobs'') is created. The grobs contain
91 unknown variables, and the network forms a set of equations. After
92 solving the equations and filling in these variables, the printed output
93 (in the form of @strong{molecules}) is written to an output file.
95 These threemanship of tasks (parsing, translating, typesetting) and
96 data-structures (music, context, graphical objects) permeates the entire
97 design of the program. This manual is ordered in terms of user
98 tasks. With each concept will be explained to which of the three parts
101 LilyPond input can be classified into three types:
103 @item musical expressions: a musical expression is some combination of
105 @item output definitions: recipes for translating those musical
106 expressions into performances (MIDI) or graphics (eg. PostScript).
108 @item declarations: by declaring and naming musical expressions, you
109 can enter and edit them in manageable chunks.
113 @c . {Music constructs}
114 @node Music constructs
115 @section Music constructs
116 @cindex Music constructs
118 * Music expressions::
120 * Simultaneous music::
121 * Compound music expressions::
124 @c . {Music expressions}
125 @node Music expressions
126 @subsection Music expressions
128 @cindex music expressions
130 Music in LilyPond is entered as a music expression. Notes, rests, lyric
131 syllables are music expressions (the atomic expressions), and you can
132 combine music expressions to form new ones. This example forms a
133 compound expressions out of the quarter @code{c} note and a @code{d}
137 \sequential @{ c4 d4 @}
140 The meaning of this compound expression is to play the @code{c}
141 first, and then the @code{d} (as opposed to playing them
142 simultaneously, for instance).
144 @c . {Sequential music}
145 @node Sequential music
146 @subsection Sequential music
147 @cindex Sequential music
148 @cindex @code{\sequential}
149 @cindex sequential music
152 \sequential @code{@{} @var{musicexprlist} @code{@}}
155 This means that list should be played or written in sequence, i.e.,
156 the second after the first, the third after the second. The duration
157 of sequential music is the the sum of the durations of the elements.
158 There is a shorthand, which leaves out the keyword:
164 @code{@{} @var{musicexprlist} @code{@}}
167 @c . {Simultaneous music}
168 @node Simultaneous music
169 @subsection Simultaneous music
170 @cindex Simultaneous music
171 @cindex @code{\simultaneous}
174 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
177 It constructs a music expression where all of its arguments start at
178 the same moment. The duration is the maximum of the durations of the
179 elements. The following shorthand is a common idiom:
182 @code{<} @var{musicexprlist} @code{>}
185 If you try to use a chord as the first thing in your score, you might
186 get multiple staffs instead of a chord.
188 @lilypond[verbatim,center]
197 This happens because the chord is interpreted by a score context.
198 Each time a note is encountered a default Voice context (along with a
199 Staff context) is created. The solution is to explicitly instantiate
202 @lilypond[verbatim,center]
204 \notes\context Voice <c''4 e''>
211 @c . {Compound music expressions}
212 @node Compound music expressions
213 @subsection Compound music expressions
215 @cindex Compound music expressions
217 Music expressions are compound data structures. You can nest music
218 expressions any way you like. This simple example shows how three
219 chords can be expressed in two different ways:
221 @lilypond[fragment,verbatim,center]
222 \notes \context Staff {
223 <a c'> <b d' > <c' e'>
224 < { a b c' } { c' d' e' } >
229 @cindex @code{\context}
230 @cindex context selection
233 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
236 Interpret @var{musicexpr} within a context of type @var{contexttype}.
237 If the context does not exist, it will be created. The new context
238 can optionally be given a name.
241 @c . {Modifying music}
242 @node Modifying music
243 @section Modifying music
244 @cindex Modifying music
246 FIXME: more verbose titling:
250 Repeating music expressions?
258 @subsection Transpose
260 @cindex transposition of pitches
261 @cindex @code{\transpose}
263 A music expression can be transposed with @code{\transpose}. The syntax
266 \transpose @var{pitch} @var{musicexpr}
269 This means that middle C in @var{musicexpr} is transposed to
272 @code{\transpose} distinguishes between enharmonic pitches: both
273 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
274 a tone. The first version will print sharps and the second version
278 @lilypond[fragment,verbatim]
281 { \key e \major; c d e f }
283 \transpose des'' { \key e \major; c d e f }
284 \transpose cis'' { \key e \major; c d e f }
290 If you want to use both @code{\transpose} and @code{\relative}, then
291 you must use @code{\transpose} first. @code{\relative} will have no
292 effect music that appears inside a @code{\transpose}.
298 Apply allows a Scheme-function to operate directly on the internal
299 representation of music.
301 \apply #@var{func} @var{music}
303 The function takes two arguments, being a function and an musical
304 argument for that function. The function should return a music
307 This example replaces the text string of a script. It also shows a dump
308 of the music it processes.
310 #(define (testfunc x)
311 (if (equal? (ly-get-mus-property x 'text) "foo")
312 (ly-set-mus-property x 'text "bar"))
314 (ly-set-mus-property x 'elements
315 (map testfunc (ly-get-mus-property x 'elements)))
320 \apply #testfunc { c4_"foo" }
324 For more information on what is possible, see the @ref{Tricks} and the
325 automatically generated documentation.
335 @cindex @code{\repeat}
337 In order to specify repeats, use the @code{\repeat}
338 keyword. Since repeats look and sound differently when played or
339 printed, there are a few different variants of repeats.
343 Repeated music is fully written (played) out. Useful for MIDI
347 This is the normal notation: Repeats are not written out, but
348 alternative endings (voltas) are printed, left to right.
351 Alternative endings are written stacked. Which is unfortunately not
352 practical for anything right now.
360 * Manual repeat commands::
362 * Tremolo subdivision::
366 @subsection Repeat syntax
368 The syntax for repeats is
371 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
374 If you have alternative endings, you may add
376 @cindex @code{\alternative}
378 \alternative @code{@{} @var{alternative1}
380 @var{alternative3} @dots{} @code{@}}
383 where each @var{alternative} is a Music expression.
385 Normal notation repeats are used like this:
389 @lilypond[fragment,verbatim]
391 \repeat volta 2 { c'4 d' e' f' }
392 \repeat volta 2 { f' e' d' c' }
396 With alternative endings:
400 @lilypond[fragment,verbatim]
402 \repeat volta 2 {c'4 d' e' f'}
403 \alternative { {d'2 d'} {f' f} }
407 Folded repeats look like this:@footnote{Folded repeats offer little
408 more over simultaneous music. However, it is to be expected that
409 more functionality -- especially for the MIDI backend -- will be
410 implemented at some point in the future.}
414 @lilypond[fragment,verbatim]
416 \repeat fold 2 {c'4 d' e' f'}
417 \alternative { {d'2 d'} {f' f} }
423 If you don't give enough alternatives for all of the repeats, then
424 the first alternative is assumed to be repeated often enough to equal
425 the specified number of repeats.
428 @lilypond[fragment,verbatim]
432 \repeat volta 3 { e | c2 d2 | e2 f2 | }
433 \alternative { { g4 g g } { a | a a a a | b2. } }
441 As you can see, LilyPond doesn't remember the timing information, nor
442 are slurs or ties repeated. We hope to fix this after 1.4.
444 It is possible to nest @code{\repeat}, although it probably is only
445 meaningful for nested repeats.
447 @node Manual repeat commands
448 @subsection Manual repeat commands
450 @cindex @code{repeatCommands}
452 The property @code{repeatCommands} can be used to control the layout of
453 repeats. Its value is a Scheme list of repeat commands, where each repeat
462 @item (volta . @var{text})
463 Print a volta bracket saying @var{text}.
466 @lilypond[verbatim, fragment]
468 \property Score.repeatCommands = #'((volta "93") end-repeat)
470 \property Score.repeatCommands = #'((volta #f))
475 @node Tremolo repeats
476 @subsection Tremolo repeats
477 @cindex tremolo beams
479 To place tremolo marks between notes, use @code{\repeat} with tremolo
481 @lilypond[verbatim,center]
483 \context Voice \notes\relative c' {
484 \repeat "tremolo" 8 { c16 d16 }
485 \repeat "tremolo" 4 { c16 d16 }
486 \repeat "tremolo" 2 { c16 d16 }
487 \repeat "tremolo" 4 c16
490 linewidth = 40*\staffspace;
495 @node Tremolo subdivision
496 @subsection Tremolo subdivision
497 @cindex tremolo marks
498 @cindex @code{tremoloFlags}
500 Tremolo marks can be printed on a single note by adding
501 `@code{:}[@var{length}]' after the note. The length must be at least 8.
502 A @var{length} value of 8 gives one line across the note stem. If the
503 length is omitted, then the last value is used, or the value of the
504 @code{tremoloFlags} property if there was no last value.
506 @lilypond[verbatim,fragment,center]
510 Tremolos in this style do not carry over into the MIDI output.
512 Using this mechanism pays off when you entering many tremolos, since the
513 default argument saves a lot of typing.
524 * Defining pitch names::
528 * Multi measure rests::
534 @subsection Notes mode
538 @cindex @code{\notes}
539 Note mode is introduced by the keyword
540 @code{\notes}. In Note mode, words can only
541 contain alphabetic characters. If @code{word} is encountered,
542 LilyPond first checks for a notename of @code{word}. If no
543 notename is found, then @code{word} is treated as a string.
545 Since combinations of numbers and dots are used for indicating
546 durations, it is not possible to enter real numbers in this mode.
555 @cindex Note specification
557 @cindex entering notes
559 The verbose syntax for pitch specification is
561 @cindex @code{\pitch}
563 \pitch @var{scmpitch}
566 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
568 In Note and Chord mode, pitches may be designated by names. The default
569 names are the Dutch note names. The notes are specified by the letters
570 @code{c} through @code{b}, where @code{c} is an octave below middle C
571 and the letters span the octave above that C. In Dutch,
572 @cindex note names, Dutch
573 a sharp is formed by adding @code{-is} to the end of a pitch name. A
574 flat is formed by adding @code{-es}. Double sharps and double flats are
575 obtained by adding @code{-isis} or @code{-eses}. @code{aes} and
576 @code{ees} are contracted to @code{as} and @code{es} in Dutch, but both
577 forms will be accepted.
579 LilyPond has predefined sets of notenames for various other languages.
580 To use them, simply include the language specific init file. For
581 example: @code{\include "english.ly"}. The available language files and
582 the names they define are:
585 Note Names sharp flat
586 nederlands.ly c d e f g a bes b -is -es
587 english.ly c d e f g a bf b -s/-sharp -f/-flat
588 deutsch.ly c d e f g a b h -is -es
589 norsk.ly c d e f g a b h -iss/-is -ess/-es
590 svenska.ly c d e f g a b h -iss -ess
591 italiano.ly do re mi fa sol la sib si -d -b
592 catalan.ly do re mi fa sol la sib si -d/-s -b
601 The optional octave specification takes the form of a series of
602 single quote (`@code{'}') characters or a series of comma
603 (`@code{,}') characters. Each @code{'} raises the pitch by one
604 octave; each @code{,} lowers the pitch by an octave.
606 @lilypond[fragment,verbatim,center]
607 c' d' e' f' g' a' b' c''
610 @lilypond[fragment,verbatim,center]
611 cis' dis' eis' fis' gis' ais' bis'
614 @lilypond[fragment,verbatim,center]
615 ces' des' es' fes' ges' as' bes'
618 @lilypond[fragment,verbatim,center]
619 cisis' eisis' gisis' aisis' beses'
622 @lilypond[fragment,verbatim,center]
623 ceses' eses' geses' ases' beses'
627 @c . {Defining pitch names}
628 @node Defining pitch names
629 @subsection Defining pitch names
631 @cindex defining pitch names
632 @cindex pitch names, defining
634 Note names and chord modifiers can be customised for nationalities. The
635 syntax is as follows.
637 @cindex @code{\pitchnames}
638 @cindex @code{\chordmodifiers}
640 \pitchnames @var{scheme-alist}
641 \chordmodifiers @var{scheme-alist}
644 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
645 specific examples how to do this. Some national note names have been
646 provided, among others: Norwegian, Swedish, German, Italian, Catalan,
647 French, Dutch and English.
652 @subsection Durations
656 @cindex @code{\duration}
658 The syntax for an verbose duration specification is
660 \duration @var{scmduration}
663 In Note, Chord, and Lyrics mode, durations may be designated by numbers
664 and dots: durations are entered as their reciprocal values. For notes
665 longer than a whole note, use identifiers.
671 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
673 r1 r2 r4 r8 r16 r32 r64 r64
679 \notes \relative c'' {
680 a\longa a\breve \autoBeamOff
681 a1 a2 a4 a8 a16 a32 a64 a64
683 r1 r2 r4 r8 r16 r32 r64 r64
688 \remove "Clef_engraver";
689 \remove "Staff_symbol_engraver";
690 \remove "Time_signature_engraver";
691 \consists "Pitch_squash_engraver";
698 As you can see, the longa is not printed. To get a longa note head, you
699 have to use a different style of note heads. See [TODO].
701 If the duration is omitted then it is set equal to the previous duration
702 entered. At the start of parsing there is no previous duration, so then
703 a quarter note is assumed. The duration can be followed by a dot
704 (`@code{.}') to obtain dotted note lengths.
707 @lilypond[fragment,verbatim,center]
713 You can alter the length of duration by writing `@code{*}@var{fraction}'
714 after it. This will not affect the appearance of note heads or rests.
720 A note specification has the form
723 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
727 LilyPond will determine what accidentals to typeset depending on the key
728 and context, so alteration refer to what note is heard, not to whether
729 accidentals are printed. A reminder accidental
730 @cindex reminder accidental
732 can be forced by adding an exclamation mark @code{!} after the pitch.
733 A cautionary accidental,
734 @cindex cautionary accidental
736 i.e., an accidental within parentheses can be obtained by adding the
737 question mark `@code{?}' after the pitch.
739 @lilypond[fragment,verbatim,center]
740 cis' d' e' cis' c'? d' e' c'!
751 Rests are entered like notes, with note name `@code{r}'.
752 There is also a note name
753 `@code{s}', which produces a space of the specified
757 @c . {Multi measure rests}
758 @node Multi measure rests
759 @subsection Multi measure rests
760 @cindex Multi measure rests
764 [todo: moveme to orchestral-part section?]
766 Multi measure rests are entered using `@code{R}'. It is specifically
767 meant for entering parts: the rest can expand to fill a score with
768 rests, or it can be printed as a single multimeasure rest This expansion
769 is controlled by the property @code{Score.skipBars}. If this is set to true,
770 Lily will not expand empty measures, and the appropriate number is added
773 @lilypond[fragment,verbatim]
774 \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
777 Currently, there is no way to condense multiple rests into a single
780 @cindex condensing rests
789 \skip @var{duration} @code{;}
793 Skips the amount of time specified by @var{duration}. If no other
794 music is played, a gap will be left for the skipped time with no
795 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
796 this has the same effect as the spacer rest.
800 @c . {Music notation}
802 @section Music notation
803 @cindex Music notation
817 @code{\key} @var{pitch} @var{type} @code{;}
819 @cindex @code{\minor}
820 @cindex @code{\major}
821 @cindex @code{\minor}
822 @cindex @code{\ionian}
823 @cindex @code{\locrian}
824 @cindex @code{\aeolian}
825 @cindex @code{\mixolydian}
826 @cindex @code{\lydian}
827 @cindex @code{\phrygian}
828 @cindex @code{\dorian}
830 Change the key signature. @var{type} should be @code{\major} or
831 @code{\minor} to get @var{pitch}-major or @var{pitch}-minor,
832 respectively. The second argument is optional; the default is major
833 keys. The @var{\context} argument can also be given as an integer,
834 which tells the number of semitones that should be added to the pitch
835 given in the subsequent @code{\key} commands to get the corresponding
836 major key, e.g., @code{\minor} is defined as 3. The standard mode names
837 @code{\ionian}, @code{\locrian}, @code{\aeolian}, @code{\mixolydian},
838 @code{\lydian}, @code{\phrygian}, and @code{\dorian} are also defined.
842 @subsubsection Clef changes
845 \clef @var{clefname} @code{;}
851 \property Staff.clefGlyph = @var{symbol associated with clefname}
852 \property Staff.clefPosition = @var{clef Y-position for clefname}
853 \property Staff.clefOctavation = @var{extra pitch of clefname}
856 Supported clef-names include
861 @c . {Time signature}
863 @subsection Time signature
864 @cindex Time signature
869 \time @var{numerator}@code{/}@var{denominator} @code{;}
872 A short-cut for doing
874 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
877 See the documentation of @code{timeSignatureFraction}
881 @subsubsection Partial
885 @cindex partial measure
886 @cindex measure, partial
887 @cindex shorten measures
888 @cindex @code{\partial}
890 \partial @var{duration} @code{;}
896 \property Score.measurePosition = @var{length of duration}
900 See the documentation of @code{measurePosition}.
908 [todo : collisiosn, rest-collisinos, voiceX identifiers, how to
909 which contexts to instantiate.]
913 @cindex @code{\shiftOff}
914 @item @code{\shiftOff}
915 Disable horizontal shifting of note heads that collide.
917 @cindex @code{\shiftOn}
918 @item @code{\shiftOn}
919 Enable note heads that collide with other note heads to be
920 shifted horiztonally. Also @code{\shiftOnn} and @code{\shiftOnnn}
921 set different shift values.
923 @cindex @code{\stemBoth}
924 @item @code{\stemBoth}
925 Allow stems, beams, and slurs to point either upwards or
926 downwards, decided automatically by LilyPond.
928 @cindex @code{\stemDown}
929 @item @code{\stemDown}
930 Force stems, beams, and slurs to point down.
932 @cindex @code{\stemUp}
934 Force stems, beams and slurs to point up.
958 @c . {Automatic beams}
959 @subsubsection Automatic beams
962 @cindex automatic beam generation
964 @cindex @code{Voice.noAutoBeaming}
966 LilyPond will group flagged notes and generate beams autmatically, where
969 This feature can be disabled by setting the @code{Voice.noAutoBeaming}
970 property to true, which you may find necessary for the melody that goes
971 with lyrics, eg. Automatic beaming can easily be overridden for
972 specific cases by specifying explicit beams. This is discussed in the
977 @cindex @code{Voice.autoBeamSettings}
978 @cindex @code{(end * * * *)}
979 @cindex @code{(begin * * * *)}
981 A large number of Voice properties are used to decide how to generate
982 beams. Their default values appear in @file{scm/auto-beam.scm}. In
983 general, beams can begin anywhere, but their ending location is
984 significant. Beams can end on a beat, or at durations specified by the
985 properties in @code{Voice.autoBeamSettings}. To end beams every quarter
986 note, for example, you could set the property @code{(end * * * *)} to
987 @code{(make-moment 1 4)}. To end beams at every three eighth notes you
988 would set it to @code{(make-moment 1 8)}. The same syntax can be used
989 to specify beam starting points using @code{(begin * * * *)}, eg:
992 \property Voice.autoBeamSettings \override
993 #'(end * * * *) = #(make-moment 1 4)
994 \property Voice.autoBeamSettings \override
995 #'(begin * * * *) = #(make-moment 1 8)
999 To allow different settings for different time signatures, instead of
1000 the first two asterisks @code{* *} you can specify a time signature; use
1001 @code{(end N M * *)} to restrict the definition to
1002 `@var{N}@code{/}@var{M}' time. For example, to specify beams ending
1003 only for 6/8 time you would use the property @code{(end 6 8 * *)}.
1005 To allow different endings for notes of different durations, instead of
1006 th last two asterisks you can specify a duration; use @code{(end * * N
1007 M)} to restrict the definition to beams that contain notes of
1008 `@var{N}@code{/}@var{M}' duration.
1010 For example, to specify beam endings for beams that contain 32nd notes,
1011 you would use @code{(end * * 1 32)}.
1016 @cindex Automatic beams
1017 @subsubsection Manual beams
1018 @cindex beams, manual
1022 In some cases it may be necessary to override LilyPond's automatic
1023 beaming algorithm. For example, the auto beamer will not beam over
1024 rests or bar lines, so if you want that, specify the begin and end point
1025 manually using @code{[} and @code{]}:
1028 @lilypond[fragment,relative,verbatim]
1030 r4 [r8 g'' a r8] r8 [g | a] r8
1035 @cindex @code{stemLeftBeamCount}
1037 If you have specific wishes for the number of beams, you can fully
1038 control the number of beams through the properties
1039 y@code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}.
1041 @lilypond[fragment,relative,verbatim]
1044 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
1048 @cindex @code{stemRightBeamCount}
1051 @c . {Adjusting beams}
1052 @unnumberedsubsubsec Adjusting beams
1053 @cindex Adjusting beams
1066 * Slur attachments::
1074 Slurs connects chords and try to avoid crossing stems. A slur is
1075 started with @code{(} and stopped with @code{)}. The
1076 starting @code{(} appears to the right of the first note in
1077 the slur. The terminal @code{)} appears to the left of the
1078 first note in the slur. This makes it possible to put a note in
1079 slurs from both sides:
1081 @lilypond[fragment,verbatim,center]
1082 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1085 @c . {Adjusting slurs}
1086 @unnumberedsubsubsec Adjusting slurs
1089 @node Slur attachments
1090 @subsubsection Slur attachments
1092 The ending of a slur should whenever possible be attached to a note
1093 head. Only in some instances where beams are involved, LilyPond may
1094 attach a slur to a stem end. In some cases, you may want to override
1095 LilyPond's decision, e.g., to attach the slur to the stem end. This can
1096 be done through @code{Voice.Slur}'s grob-property @code{attachment}:
1100 @lilypond[fragment,relative,verbatim]
1101 \property Voice.Slur \set #'direction = #1
1102 \property Voice.Stem \set #'length = #5.5
1104 \property Voice.Slur \set #'attachment = #'(stem . stem)
1109 Similarly, slurs can be attached to note heads even when beams are
1113 @lilypond[fragment,relative,verbatim]
1114 \property Voice.Slur \set #'direction = #1
1115 \property Voice.Slur \set #'attachment = #'(head . head)
1116 g''16()g()g()g()d'()d()d()d
1120 If a slur would strike through a stem or beam, LilyPond will move the
1121 slur away vertically (upward or downward). In some cases, this may
1122 cause ugly slurs that you may want to correct:
1125 @lilypond[fragment,relative,verbatim]
1126 \property Voice.Stem \set #'direction = #1
1127 \property Voice.Slur \set #'direction = #1
1129 \property Voice.Slur \set #'attachment = #'(stem . stem)
1134 LilyPond will increase the curvature of a slur trying to stay free of
1135 note heads and stems. However, if the curvature would increase too much,
1136 the slur will be reverted to its default shape. This decision is based
1137 on @code{Voice.Slur}'s grob-property @code{beautiful} value. In some
1138 cases, you may find ugly slurs beautiful, and tell LilyPond so by
1139 increasing the @code{beautiful} value:
1141 [hoe gedefd?? wat betekent beautiful = X?]
1146 \notes \context PianoStaff <
1148 \context Staff=up { s1 * 6/4 }
1149 \context Staff=down <
1151 \autochange Staff \context Voice
1152 \notes \relative c {
1153 d,8( a' d f a d f d a f d )a
1161 Slur \override #'beautiful = #5.0
1162 Slur \override #'direction = #1
1163 Stem \override #'direction = #-1
1164 autoBeamSettings \override #'(end * * * *)
1165 = #(make-moment 1 2)
1169 VerticalAlignment \override #'threshold = #'(5 . 5)
1176 @cindex Adusting slurs
1188 A tie connects two adjacent note heads of the same pitch. When used
1189 with chords, it connects all of the note heads whose pitches match.
1190 Ties are indicated using the tilde symbol `@code{~}'.
1191 If you try to tie together chords which have no common pitches, a
1192 warning message will appear and no ties will be created.
1194 @lilypond[fragment,verbatim,center]
1195 e' ~ e' <c' e' g'> ~ <c' e' g'>
1203 @subsubsection Tuplets
1207 Tuplets are made out of a music expression by multiplying their duration
1210 @cindex @code{\times}
1212 \times @var{fraction} @var{musicexpr}
1215 The duration of @var{musicexpr} will be multiplied by the fraction.
1216 In print, the fraction's denominator will be printed over the notes,
1217 optionally with a bracket. The most common tuplet is the triplet in
1218 which 3 notes have the length of 2, so the notes are 2/3 of
1219 their written length:
1221 @lilypond[fragment,verbatim,center]
1222 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1225 [todo: document tupletSpannerDuration]
1231 @subsubsection Text spanner
1232 @cindex Text spanner
1236 @subsubsection Ottava
1238 @unnumberedsubsubsec Ottava
1240 [move to trick. Not a supported feature.]
1242 @lilypond[fragment,relative,verbatim]
1244 \property Voice.TextSpanner \set #'type = #'dotted-line
1245 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1246 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1247 \property Staff.centralCPosition = #-13
1248 a\spanrequest \start "text" b c a \spanrequest \stop "text"
1253 @c . {Span requests}
1255 @subsubsection Span requests
1256 @cindex Span requests
1258 @cindex @code{\spanrequest}
1261 \spanrequest @var{startstop} @var{type}
1263 @cindex @code{\start}
1264 @cindex @code{\stop}
1266 Define a spanning request. The @var{startstop} parameter is either -1
1267 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
1268 describes what should be started. Supported types are @code{crescendo},
1269 @code{decrescendo}, @code{beam}, @code{slur}. [FIXME: many more] This
1270 is an internal command. Users should use the shorthands which are
1271 defined in the initialization file @file{spanners.ly}.
1273 You can attach a (general) span request to a note using
1275 @lilypond[fragment,verbatim,center]
1276 c'4-\spanrequest \start "slur"
1277 c'4-\spanrequest \stop "slur"
1280 The slur syntax with parentheses is a shorthand for this.
1285 @subsection Ornaments
1294 @subsubsection Articulation
1295 @cindex Articulation
1297 @cindex articulations
1301 A variety of symbols can appear above and below notes to indicate
1302 different characteristics of the performance. These symbols can be
1303 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1304 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1305 forced to appear above or below the note by writing
1306 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1307 respectively. Here is a chart showing symbols above notes, with the
1308 name of the corresponding symbol appearing underneath.
1314 \property Score.LyricSyllable \override #'font-family =
1316 \property Score.LyricSyllable \override #'font-shape = #'upright
1317 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1318 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1319 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1320 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1321 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1322 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1323 c''-\thumb c''-\segno c''-\coda
1325 \context Lyrics \lyrics {
1326 accent__ marcato__ staccatissimo__ fermata
1327 stopped__ staccato__ tenuto__ upbow
1328 downbow__ lheel__ rheel__ ltoe
1329 rtoe__ turn__ open__ flageolet
1330 reverseturn__ trill__ prall__ mordent
1331 prallprall__ prallmordent__ uprall__ downprall
1332 thumb__ segno__ coda
1336 linewidth = 5.875\in;
1345 @subsubsection Text scripts
1346 @cindex Text scripts
1350 In addition, it is possible to place arbitrary strings of text or
1351 @TeX{} above or below notes by using a string instead of an
1352 identifier: @code{c^"text"}. Fingerings
1353 can be placed by simply using digits. All of these note ornaments
1354 appear in the printed output but have no effect on the MIDI rendering of
1358 @unnumberedsubsubsec Fingerings
1361 To save typing, fingering instructions (digits 0 to 9 are
1362 supported) and single characters shorthands exist for a few
1367 \notes \context Voice {
1368 \property Voice.TextScript \set #'font-family = #'typewriter
1369 \property Voice.TextScript \set #'font-shape = #'upright
1375 c''4-^_"c-\\^{ }" s4
1382 linewidth = 5.875 \in;
1390 @cindex @code{\textscript}
1394 \textscript @var{text} @var{style}
1397 Defines a text to be printed over or under a note. @var{style} is a
1398 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1399 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1401 You can attach a general textscript request using this syntax:
1406 c4-\textscript "6" "finger"
1407 c4-\textscript "foo" "normal"
1412 This is equivalent to @code{c4-6 c4-"foo"}.
1414 @cindex @code{\script}
1423 Prints a symbol above or below a note. The argument is a string which
1424 points into the script-alias table defined in @file{scm/script.scm}.
1425 Usually the @code{\script} keyword is not used directly. Various
1426 helpful identifier definitions appear in @file{script.ly}.
1428 For information on how to add scripts, consult @file{scm/script.scm}.
1435 @subsection Grace notes
1444 @cindex @code{\grace}
1447 @cindex @code{graceAlignPosition}
1450 \grace @var{musicexpr}
1453 A grace note expression has duration 0; the next real note is
1454 assumed to be the main note.
1456 You cannot have the grace note after the main note, in terms of
1457 duration, and main notes, but you can typeset the grace notes to the
1458 right of the main note using the property
1459 @code{graceAlignPosition}.
1460 @cindex @code{flagStyle}
1462 When grace music is interpreted, a score-within-a-score is set up:
1463 @var{musicexpr} has its own time bookkeeping, and you could (for
1464 example) have a separate time signature within grace notes. While in
1465 this score-within-a-score, you can create notes, beams, slurs, etc.
1466 Unbeamed eighth notes and shorter by default have a slash through the
1467 stem. This behavior can be controlled with the
1468 @code{flagStyle} property.
1471 @lilypond[fragment,verbatim]
1473 \grace c8 c4 \grace { [c16 c16] } c4
1474 \grace { \property Grace.flagStyle = "" c16 } c4
1481 At present, nesting @code{\grace} notes is not supported. The following
1482 may cause run-time errors:
1484 @code{\grace @{ \grace c32 c16 @} c4}
1486 Since the meaning of such a construct is unclear, we don't consider
1487 this a loss. Similarly, juxtaposing two @code{\grace} sections is
1488 syntactically valid, but makes no sense and may cause runtime errors.
1490 Ending a staff or score with grace notes may also generate a run-time
1491 error, since there will be no main note to attach the grace notes to.
1493 The present implementation is not robust and generally kludgy. We expect
1494 it to change after LilyPond 1.4. Syntax changes might also be
1507 * Crescendo and Decrescendo::
1517 @subsubsection Glissando
1520 @cindex @code{\glissando}
1522 A glissando line can be requested by attaching a @code{\glissando} to a
1526 @lilypond[fragment,relative,verbatim]
1531 Printing of an additional text (such as @emph{gliss.}) must be done
1538 @subsubsection Dynamics
1551 @cindex @code{\ffff}
1565 Dynamic marks are specified by using an identifier after a note:
1566 @code{c4-\ff}. The available dynamic marks are:
1567 @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f},
1568 @code{\ff}, @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf},
1569 @code{\sff}, @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1571 @c . {Crescendo and Decrescendo}
1572 @node Crescendo and Decrescendo
1573 @subsubsection Crescendo and Decrescendo
1575 @cindex Crescendo and Decrescendo
1579 @cindex @code{\decr}
1580 @cindex @code{\rced}
1587 A crescendo mark is started with @code{\cr} and terminated with
1588 @code{\rc}, the textual reverse of @code{cr}. A decrescendo mark is
1589 started with @code{\decr} and terminated with @code{\rced}. There are
1590 also shorthands for these marks. A crescendo can be started with
1591 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1592 can be terminated with @code{\!}. Note that @code{\!} must go before
1593 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1594 after the last note. Because these marks are bound to notes, if you
1595 want to get several marks during one note, you must use spacer notes.
1597 @lilypond[fragment,verbatim,center]
1598 c'' \< \! c'' d'' \decr e'' \rced
1599 < f''1 { s4 \< \! s2 \> \! s4 } >
1602 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1603 is an example how to do it:
1605 @lilypond[fragment,relative,verbatim]
1607 \property Voice.crescendoText = "cresc."
1608 \property Voice.crescendoSpanner = #'dashed-line
1617 @subsubsection Bar lines
1621 @cindex measure lines
1628 This is a short-cut for doing
1630 \property Score.whichBar = @var{bartype}
1633 You are encouraged to use @code{\repeat} for repetitions. See
1634 @ref{Repeats}, and the documentation of @code{whichBar} in
1635 @ref{(lilypond-internals)LilyPond context properties}.
1642 @subsubsection Breath marks
1643 @cindex Breath marks
1645 @c . {Rehearsal marks}
1646 @node Rehearsal marks
1647 @subsubsection Rehearsal marks
1648 @cindex Rehearsal marks
1650 @cindex @code{\mark}
1653 \mark @var{unsigned};
1654 @cindex @code{Mark_engraver}
1658 Prints a mark over or under the staff.
1663 @subsection Bar check
1667 @cindex @code{barCheckNoSynchronize}
1671 Whenever a bar check is encountered during interpretation, a warning
1672 message is issued if it doesn't fall at a measure boundary. This can
1673 help you find errors in the input. Depending on the value of
1674 @code{barCheckNoSynchronize}, the beginning of the measure will be
1675 relocated, so this can also be used to shorten measures.
1677 A bar check is entered using the bar symbol, @code{|}
1688 @section Piano music
1690 * Automatic staff changes::
1691 * Manual staff switches::
1698 @c . {Automatic staff changes}
1699 @node Automatic staff changes
1700 @subsection Automatic staff changes
1701 @cindex Automatic staff changes
1705 @node Manual staff switches
1706 @subsection Manual staff switches
1708 @cindex manual staff switches
1709 @cindex staff switch, manual
1711 @cindex @code{\translator}
1713 \translator @var{contexttype} = @var{name}
1716 A music expression indicating that the context which is a direct
1717 child of the a context of type @var{contexttype} should be shifted to
1718 a context of type @var{contexttype} and the specified name.
1720 Usually this is used to switch staffs in Piano music, e.g.
1723 \translator Staff = top @var{Music}
1737 @subsection Arpeggio
1740 @cindex broken arpeggio
1741 @cindex @code{\arpeggio}
1743 You can specify an arpeggio sign on a chord by attaching an
1744 @code{\arpeggio} to a note of the chord.
1748 @lilypond[fragment,relative,verbatim]
1749 \context Voice <c'\arpeggio e g c>
1753 When an arpeggio crosses staffs in piano music, you attach an arpeggio
1754 to the chords in both staffs, and set
1755 @code{PianoStaff.connectArpeggios}. LilyPond will connect the arpeggios
1759 @lilypond[fragment,relative,verbatim]
1760 \context PianoStaff <
1761 \property PianoStaff.connectArpeggios = ##t
1762 \context Voice = one { <c''\arpeggio e g c> }
1763 \context Voice = other { \clef bass; <c,,\arpeggio e g>}
1770 @c . {Follow Thread}
1772 @subsection Follow Thread
1773 @cindex follow thread
1774 @cindex staff switching
1777 [todo: different name, eg. voice line ? ]
1779 @cindex @code{followThread}
1781 Whenever a voice switches to another staff a line connecting the notes
1782 can be printed automatically. This is enabled if the property
1783 @code{PianoStaff.followThread} is set to true:
1786 @lilypond[fragment,relative,verbatim]
1787 \context PianoStaff <
1788 \property PianoStaff.followThread = ##t
1789 \context Staff \context Voice {
1791 \translator Staff=two
1794 \context Staff=two {\clef bass; \skip 1*2;}
1814 * Automatic syllable durations::
1819 @subsection Lyrics mode
1823 @cindex @code{\lyrics}
1825 Lyrics mode is introduced by the keyword @code{\lyrics}. This mode has
1826 rules that make it easy to include punctuation and diacritical marks in
1827 words: The purpose of Lyrics mode is that you can enter lyrics in @TeX{}
1828 format or a standard encoding without needing quotes. The precise
1829 definition of this mode is ludicrous, and this will remain so until the
1830 authors of LilyPond acquire a deeper understanding of character
1831 encoding, or someone else steps up to fix this.
1833 A word in Lyrics mode begins with: an alphabetic character, @code{_},
1834 @code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
1835 through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
1836 any 8-bit character with ASCII code over 127, or a two-character
1837 combination of a backslash followed by one of @code{`}, @code{'},
1838 @code{"}, or @code{^}.
1840 Subsequent characters of a word can be any character that is not a digit
1841 and not white space. One important consequence of this is that a word
1842 can end with `@code{@}}', which may be confusing. However, LilyPond will
1843 issue a warning. Any @code{_} character which appears in an unquoted
1844 word is converted to a space. This provides a mechanism for introducing
1845 spaces into words without using quotes. Quoted words can also be used
1846 in Lyrics mode to specify words that cannot be written with the above
1847 rules. Here are some examples. Not all of these words are printable by
1852 2B_||_!2B % not a word because it starts with a digit
1853 ``Hello'' % not a word because it starts with `
1854 _ _ _ _ % 4 words, each one a space
1857 Since combinations of numbers and dots are used for indicating
1858 durations, you can not enter real numbers in this mode.
1860 @cindex lyrics expressions
1862 Syllables are entered like notes, with pitches replaced by text. For
1863 example, @code{Twin-4 kle4 twin-4 kle4} enters four syllables, each
1864 with quarter note duration. Note that the hyphen has no special
1865 meaning for lyrics, and does not introduce special symbols. See
1866 section @ref{Lexical modes} for a description of what is interpreted as
1869 Spaces can be introduced into a lyric either by using quotes
1870 (@code{"}) or by using an underscore without quotes: @code{He_could4
1871 not4}. All unquoted underscores are converted to spaces. Printing
1872 lyrics is discussed in the next section.
1875 @c . {Printing lyrics}
1876 @node Printing lyrics
1877 @subsection Printing lyrics
1881 Lyric syllables must be interpreted within a @code{Lyrics} context for
1882 printing them. Here is a full example:
1888 \notes \transpose c'' {
1890 e f g2 | e4 f g2 \bar "|.";
1892 \context Lyrics \lyrics {
1893 Va-4 der Ja- cob Va- der Ja- cob
1894 Slaapt gij nog?2 Slaapt4 gij nog?2
1906 @cindex lyric extender
1908 You may want a continuous line after the syllables to show melismata.
1909 To achieve this effect, add a @code{__} lyric as a separate word
1910 after the lyric to be extended. This will create an extender, a line
1911 that extends over the entire duration of the lyric. This line will
1912 run all the way to the start of the next lyric, so you may want to
1913 shorten it by using a blank lyric (using @code{_}).
1920 \notes \relative c'' {
1921 a4 () b () c () d | c () d () b () a | c () d () b () a
1923 \context Lyrics \lyrics {
1924 foo1 __ | bar2. __ _4 | baz1 __
1932 @cindex Lyric hyphen
1934 If you want to have hyphens centered between syllables (rather than
1935 attached to the end of the first syllable) you can use the special
1936 `@code{-}@code{-}' lyric as a separate word between syllables. This
1937 will result in a hyphen which length varies depending on the space
1938 between syllables, and which will be centered between the syllables.
1946 \notes \transpose c'' {
1948 e f g2 | e4 f g2 \bar "|.";
1950 \context Lyrics \lyrics {
1951 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1952 Slaapt gij nog?2 | Slaapt4 gij nog?2
1961 @c . {Automatic syllable durations}
1962 @node Automatic syllable durations
1963 @subsection Automatic syllable durations
1964 @cindex Automatic syllable durations
1967 [explain automatic phrasing]
1968 @cindex automatic lyric durations
1969 @cindex @code{\addlyrics}
1971 If you have lyrics that are set to a melody, you can import the rhythm
1972 of that melody into the lyrics using @code{\addlyrics}. The syntax for
1975 \addlyrics @var{musicexpr1 musicexpr2}
1978 This means that both @var{musicexpr1} and @var{musicexpr2} are
1979 interpreted, but that every non-command atomic music expression
1980 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1981 of @var{musicexpr1}.
1982 @cindex @code{automaticMelismata}
1984 If the property @code{automaticMelismata} is set in the
1985 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1989 @lilypond[verbatim,fragment]
1992 \property Voice.automaticMelismata = ##t
1993 c8 () cis d8. e16 f2
1995 \context Lyrics \lyrics {
2000 You should use a single rhythm melody, and single rhythm lyrics (a
2001 constant duration is the obvious choice). If you do not, you will get
2002 undesired effects when using multiple stanzas:
2005 @lilypond[verbatim,fragment]
2008 c8 () cis d8. e16 f2
2010 \context Lyrics \lyrics
2017 It is valid (but probably not very useful) to use notes instead of
2018 lyrics for @var{musicexpr2}.
2027 [chords vs. simultaneous music]
2031 * Entering named chords::
2032 * Printing named chords::
2037 @subsection Chords mode
2040 Chord mode is introduced by the keyword
2041 @code{\chords}. It is similar to Note mode, but
2042 words are also looked up in a chord modifier table (containing
2043 @code{maj}, @code{dim}, etc).
2045 Since combinations of numbers and dots are used for indicating
2046 durations, you can not enter real numbers in this mode. Dashes
2047 and carets are used to indicate chord additions and subtractions,
2048 so scripts can not be entered in Chord mode.
2050 @c . {Entering named chords}
2051 @node Entering named chords
2052 @subsection Entering named chords
2053 @cindex Chords names
2055 Chord names are a way to generate simultaneous music expressions that
2056 correspond with traditional chord names. It can only be used in
2057 Chord mode (see section @ref{Lexical modes}).
2061 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2064 @var{tonic} should be the tonic note of the chord, and @var{duration}
2065 is the chord duration in the usual notation. There are two kinds of
2066 modifiers. One type is @emph{chord additions}, which are obtained by
2067 listing intervals separated by dots. An interval is written by its
2068 number with an optional @code{+} or @code{-} to indicate raising or
2069 lowering by half a step. Chord additions has two effects: It adds
2070 the specified interval and all lower odd numbered intervals to the
2071 chord, and it may lower or raise the specified interval. Intervals
2072 must be separated by a dot (@code{.}).
2075 Throughout these examples, chords have been shifted around the staff
2076 using @code{\transpose}.
2081 @lilypond[fragment,verbatim]
2085 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
2097 The second type of modifier that may appear after the @code{:} is a
2098 named modifier. Named modifiers are listed in the file
2099 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2100 @code{min} which lower the 3rd half a step, `@code{aug}' which
2101 raises the 5th, `@code{dim}' which lowers the 5th,
2102 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2103 which replaces the 5th with a 4th.
2107 @lilypond[fragment,verbatim]
2110 c1:m c:min7 c:maj c:aug c:dim c:sus
2118 Chord subtractions are used to eliminate notes from a chord. The
2119 notes to be subtracted are listed after a @code{^} character,
2122 @lilypond[fragment,verbatim,center]
2131 Chord inversions can be specified by appending `@code{/}' and
2132 the name of a single note to a chord. This has the effect of
2133 lowering the specified note by an octave so it becomes the lowest
2134 note in the chord. If the specified note is not in the chord, a
2135 warning will be printed.
2137 @lilypond[fragment,verbatim,center]
2147 Bass notes can be added by `@code{/+}' and
2148 the name of a single note to a chord. This has the effect of
2149 adding the specified note to the chord, lowered by an octave,
2150 so it becomes the lowest note in the chord.
2152 @lilypond[fragment,verbatim,center]
2161 The most interesting application is printing chord names, which is
2162 explained in the next subsection.
2164 You should not combine @code{\relative} with named chords. [FIXME]
2166 @c . {Printing named chords}
2167 @node Printing named chords
2168 @subsection Printing named chords
2174 @cindex printing chord names
2177 @cindex @code{ChordNames}
2178 @cindex @code{ChordNameVoice}
2180 For displaying printed chord names, use the @code{ChordNames} and
2181 @code{ChordNameVoice} contexts. The chords may be entered either using
2182 the notation described above, or directly using simultaneous music.
2187 \chords {a1 b c} <d f g> <e g b>
2191 \context ChordNamesVoice \scheme
2192 \context Staff \transpose c'' \scheme
2194 \paper { linewidth = -1.; }
2199 You can make the chord changes stand out more by setting property
2200 @code{ChordNames.chordChanges} to true. This will only display chord
2201 names when there's a change in the chords scheme, but always display the
2202 chord name after a line break:
2208 c1:m \break c:m c:m c:m d
2213 \context ChordNames \scheme
2214 \context Staff \transpose c'' \scheme
2217 linewidth = 40 * \staffspace;
2229 LilyPond examines chords specified as lists of notes to determine a
2230 name to give the chord. LilyPond will not try to
2231 identify chord inversions or added base, which may result in strange
2232 chord names when chords are entered as a list of pitches:
2235 @lilypond[verbatim,center]
2244 \context ChordNamesVoice \scheme
2245 \context Staff \scheme
2247 \paper { linewidth = -1.; }
2252 To specify chord inversions, append @code{/<notename>}. To specify an
2253 added bass note, append @code{/+<notename}:
2256 @lilypond[verbatim,center]
2263 \context ChordNames \scheme
2264 \context Staff \transpose c'' \scheme
2266 \paper { linewidth = -1.; }
2271 The chord names that LilyPond should print are fully customizable. The
2272 code to print chord names is written in Scheme. It can be found in
2273 @file{scm/chord-name.scm}. Chord names are based on Banter style
2274 naming, which is unambiguous and has a logical structure. Typical
2275 American style chord names are implemented as a variation on Banter
2276 names, they can be selected by setting property @code{ChordName.style}
2281 \include "english.ly"
2286 df:m5- % Diminished triad
2287 c:5^3 % Root-fifth chord
2288 c:4^3 % Suspended fourth triad
2289 c:5+ % Augmented triad
2291 c:m5-.7- % Diminished seventh
2292 c:7+ % Major seventh
2293 c:7.4^3 % Dominant seventh suspended fourth
2294 c:5+.7 % Augmented dominant seventh
2295 c:m5-.7 % "Half" diminished seventh
2296 c:5-.7 % Dominant seventh flat fifth
2297 c:5-.7+ % Major seventh flat fifth
2298 c:m7+ % Minor-major seventh
2299 c:m7 % Minor seventh
2300 c:7 % Dominant seventh
2303 c:9^7 % Major triad w/added ninth
2304 c:6.9^7 % Six/Nine chord
2305 c:9 % Dominant ninth
2306 c:7+.9 % Major ninth
2307 c:m7.9 % Minor ninth
2312 \context ChordNames \scheme
2313 \context Staff \transpose c'' \scheme
2318 ChordName \override #'word-space = #1
2319 ChordName \override #'style = #'american
2326 Similarly, Jazz style chord names are implemented as a variation on
2327 American style names:
2333 c:6 % 6 = major triad with added sixth
2334 c:maj % triangle = maj
2339 c:m % m = minor triad
2340 c:m.6 % m6 = minor triad with added sixth
2341 c:m.7+ % m triangle = minor major seventh chord
2349 c:7.5+ % +7 = augmented dominant
2350 c:7.5- % 7b5 = hard diminished dominant
2357 c:13.9-^11 % 7(b9,13)
2358 c:13.9+^11 % 7(#9,13)
2360 c:13-.9-^11 % 7(b9,b13)
2361 c:13-.9+^11 % 7(#9,b13)
2363 % half diminished chords
2364 c:m5-.7 % slashed o = m7b5
2365 c:9.3-.5- % o/7(pure 9)
2368 c:m5-.7- % o = diminished seventh chord
2373 \context ChordNames \scheme
2374 \context Staff \transpose c'' \scheme
2379 ChordName \override #'word-space = #1
2380 ChordName \override #'style = #'jazz
2392 @section Page layout
2406 @subsection Paper block
2409 The most important output definition is the @code{\paper} block, for
2410 music notation. The syntax is
2413 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2416 where each of the items is one of
2419 @item An assignment. The assignment must be terminated by a
2422 @item A context definition. See section @ref{Context definitions} for
2423 more information on context definitions.
2425 @item \stylesheet declaration. Its syntax is
2427 \stylesheet @var{alist}
2430 See @file{font.scm} for details of @var{alist}.
2433 @c . {Paper variables}
2434 @node Paper variables
2435 @subsection Paper variables
2436 @cindex Paper variables
2438 The paper block has some variables you may want to use or change:
2441 @cindex @code{indent}
2443 The indentation of the first line of music.
2444 @cindex @code{staffspace}
2446 @item @code{staffspace}
2447 The distance between two staff lines, calculated from the center
2448 of the lines. You should use either this or @code{stafflinethickness}
2449 as a unit for distances you modify.
2451 @cindex @code{linewidth}
2452 @item @code{linewidth}
2453 Sets the width of the lines.
2455 If set to a negative value, a single
2456 unjustified line is produced.
2458 @cindex @code{textheight}
2460 @item @code{textheight}
2461 Sets the total height of the music on each page. Only used by
2463 @cindex @code{interscoreline}
2465 @item @code{interscoreline}
2466 Sets the spacing between the score lines. Defaults to 16 pt.
2467 @cindex @code{interscorelinefill}
2469 @item @code{interscorelinefill}
2470 If set to a positive number, the distance between the score
2471 lines will stretch in order to fill the full page. In that
2472 case @code{interscoreline} specifies the minimum spacing.
2474 @cindex @code{stafflinethickness}
2476 @item @code{stafflinethickness}
2477 Determines the thickness of staff lines, and also acts as a scaling
2478 parameter for other line thicknesses.
2485 @subsection Font size
2488 The Feta font provides musical symbols at six different sizes. These
2489 fonts are 11 point, 13 point, 16 point, 20 point,
2490 23 point, and 26 point. The point size of a font is the
2491 height of the five lines in a staff when displayed in the font.
2493 Definitions for these sizes are the files @file{paperSZ.ly}, where
2494 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
2495 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
2496 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
2497 @code{paperTwentysix} are defined respectively. The default
2498 @code{\paper} block is also set.
2500 The font definitions are generated using a Scheme function. For more
2501 details, see the file @file{font.scm}.
2507 @subsection Paper size
2512 @cindex @code{papersize}
2514 To change the paper size, you must first set the
2515 @code{papersize} variable at top level. Set it to
2516 the strings @code{a4}, @code{letter}, or @code{legal}. After this
2517 specification, you must set the font as described above. If you want
2518 the default font, then use the 20 point font. The new paper size will
2519 not take effect if the font is not loaded and selected afterwards.
2523 \include "paper16.ly"
2527 \paper @{ \paperSixteen @}
2531 The file "paper16.ly" will now include a file named @file{a4.ly}, which
2532 will set the paper variables @code{hsize} and @code{vsize} (used by
2543 @subsection Line break
2546 @cindex breaking lines
2548 Line breaks are normally computed automatically. They are chosen such
2549 that the resulting spacing has low variation, and looks neither cramped
2552 Occasionally you might want to override the automatic breaks; you can do
2553 this by specifying @code{\break}. This will force a line break at this
2554 point. Do remember that line breaks can only occur at places where there
2555 are barlines. If you want to have a line break where there is no
2556 barline, you can force a barline by entering @code{\bar "";}.
2558 Similarly, @code{\noBreak} forbids a line break at a certain point.
2560 @cindex @code{\penalty}
2562 The @code{\break} and @code{\noBreak} commands are defined in terms of
2563 the penalty command:
2565 \penalty @var{int} @code{;}
2568 This imposes encourages or discourages LilyPond to make a line break
2571 @strong{Warning} do not use @code{\penalty} directly. It is rather
2572 kludgy, and slated for rewriting.
2576 @subsection Page break
2579 @cindex breaking pages
2582 Page breaks are normally computed by @TeX{}, so they are not under direct
2583 control. However, you can insert a commands into the @file{.tex} output to
2584 instruct @TeX{} where to break pages. For more details, see the
2585 example file @file{input/test/between-systems.ly}
2600 * MIDI instrument names::
2606 @subsection MIDI block
2610 The MIDI block is analogous to the paper block, but it is somewhat
2611 simpler. The @code{\midi} block can contain:
2615 @item a @code{\tempo} definition
2616 @item context definitions
2619 Assignments in the @code{\midi} block are not allowed.
2623 @cindex context definition
2625 Context definitions follow precisely the same syntax as within the
2626 \paper block. Translation modules for sound are called performers.
2627 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2630 @c . {MIDI instrument names}
2631 @node MIDI instrument names
2632 @subsection MIDI instrument names
2633 @cindex instrument names
2634 @cindex @code{Staff.midiInstrument}
2635 @cindex @code{Staff.instrument}
2637 The MIDI instrument name is set by the @code{Staff.midiInstrument}
2638 property or, if that property is not set, the @code{Staff.instrument}
2639 property. The instrument name should be chosen from the following list.
2640 If the selected string does not exactly match, then LilyPond uses the
2643 [FIXME: to appendix ]
2647 "acoustic grand" "contrabass" "lead 7 (fifths)"
2648 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2649 "electric grand" "pizzicato strings" "pad 1 (new age)"
2650 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2651 "electric piano 1" "timpani" "pad 3 (polysynth)"
2652 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2653 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2654 "clav" "synthstrings 1" "pad 6 (metallic)"
2655 "celesta" "synthstrings 2" "pad 7 (halo)"
2656 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2657 "music box" "voice oohs" "fx 1 (rain)"
2658 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2659 "marimba" "orchestra hit" "fx 3 (crystal)"
2660 "xylophone" "trumpet" "fx 4 (atmosphere)"
2661 "tubular bells" "trombone" "fx 5 (brightness)"
2662 "dulcimer" "tuba" "fx 6 (goblins)"
2663 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2664 "percussive organ" "french horn" "fx 8 (sci-fi)"
2665 "rock organ" "brass section" "sitar"
2666 "church organ" "synthbrass 1" "banjo"
2667 "reed organ" "synthbrass 2" "shamisen"
2668 "accordion" "soprano sax" "koto"
2669 "harmonica" "alto sax" "kalimba"
2670 "concertina" "tenor sax" "bagpipe"
2671 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2672 "acoustic guitar (steel)" "oboe" "shanai"
2673 "electric guitar (jazz)" "english horn" "tinkle bell"
2674 "electric guitar (clean)" "bassoon" "agogo"
2675 "electric guitar (muted)" "clarinet" "steel drums"
2676 "overdriven guitar" "piccolo" "woodblock"
2677 "distorted guitar" "flute" "taiko drum"
2678 "guitar harmonics" "recorder" "melodic tom"
2679 "acoustic bass" "pan flute" "synth drum"
2680 "electric bass (finger)" "blown bottle" "reverse cymbal"
2681 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2682 "fretless bass" "whistle" "breath noise"
2683 "slap bass 1" "ocarina" "seashore"
2684 "slap bass 2" "lead 1 (square)" "bird tweet"
2685 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2686 "synth bass 2" "lead 3 (calliope)" "helicopter"
2687 "violin" "lead 4 (chiff)" "applause"
2688 "viola" "lead 5 (charang)" "gunshot"
2689 "cello" "lead 6 (voice)"
2700 @cindex beats per minute
2701 @cindex metronome marking
2703 @cindex @code{\tempo}
2705 \tempo @var{duration} = @var{perminute} @code{;}
2708 Used to specify the tempo. For example, @code{\tempo 4 = 76;} requests
2709 output with 76 quarter notes per minute.
2717 @section Music entry
2728 @subsection Relative
2730 @cindex relative octave specification
2732 Octaves are specified by adding @code{'} and @code{,} to pitch names.
2733 When you copy existing music, it is easy to accidentally put a pitch in
2734 the wrong octave and hard to find such an error. To prevent these
2735 errors, LilyPond features octave entry.
2737 @cindex @code{\relative}
2739 \relative @var{startpitch} @var{musicexpr}
2742 The octave of notes that appear in @var{musicexpr} are calculated as
2743 follows: If no octave changing marks are used, the basic interval
2744 between this and the last note is always taken to be a fourth or less.
2745 The octave changing marks @code{'} and @code{,} can then
2746 be added to raise or lower the pitch by an extra octave. Upon entering
2747 relative mode, an absolute starting pitch must be specified that will
2748 act as the predecessor of the first note of @var{musicexpr}.
2750 This distance is determined without regarding accidentals: a
2751 @code{fisis} following a @code{ceses} will be put above the
2754 Entering scales is straightforward in relative mode.
2756 @lilypond[fragment,verbatim,center]
2758 g a b c d e f g g, g
2762 And octave changing marks are used for intervals greater than a fourth.
2764 @lilypond[fragment,verbatim,center]
2766 c g c f, c' a, e'' }
2769 If the preceding item is a chord, the first note of the chord is used
2770 to determine the first note of the next chord. But other notes
2771 within the second chord are determined by looking at the immediately
2774 @lilypond[fragment,verbatim,center]
2781 @cindex @code{\notes}
2783 The pitch after the @code{\relative} contains a notename. To parse
2784 the pitch as a notename, you have to be in note mode, so there must
2785 be a surrounding @code{\notes} keyword (which is not
2788 The relative conversion will not affect @code{\transpose} or
2789 @code{\relative} sections in its argument. If you want to use
2790 relative within transposed music, you must place an additional
2791 @code{\relative} inside the @code{\transpose}.
2794 @c . {Point and click}
2795 @node Point and click
2796 @subsection Point and click
2805 * Context definitions::
2806 * Notation Contexts::
2809 [rewrite this entirely]
2811 @c . {Context definitions}
2812 @node Context definitions
2813 @subsection Context definitions
2815 @cindex context definition
2816 @cindex translator definition
2817 @cindex engraver hacking
2820 A notation contexts is defined by the following information
2825 @item The LilyPond modules that do the actual conversion of music to
2826 notation. Each module is a so-called
2831 @item How these modules should cooperate, i.e. which ``cooperation
2832 module'' should be used. This cooperation module is a special
2835 @item What other contexts the context can contain,
2837 @item What properties are defined.
2840 A context definition has this syntax:
2844 \translator @code{@{}
2845 @var{translatorinit} @var{translatormodifierlist}
2849 @var{translatorinit} can be an identifier or
2851 \type @var{typename} @code{;}
2853 where @var{typename} is one of
2856 @cindex @code{Engraver_group_engraver}
2857 @item @code{Engraver_group_engraver}
2858 The standard cooperation engraver.
2859 @cindex @code{Score_engraver}
2861 @item @code{Score_engraver}
2862 This is cooperation module that should be in the top level context.
2863 @cindex @code{Grace_engraver_group}
2865 @item @code{Grace_engraver_group}
2866 This is a special cooperation module (resembling
2867 @code{Score_engraver}) that is used to created an embedded
2871 @var{translatormodifierlist} is a list of items where each item is
2875 @item @code{\consists} @var{engravername} @code{;}
2876 Add @var{engravername} to the list of modules in this context.
2877 The order of engravers added with @code{\consists} is
2880 @item @code{\consistsend} @var{engravername} @code{;}
2881 Analogous to @code{\consists}, but makes sure that
2882 @var{engravername} is always added to the end of the list of
2885 Some engraver types need to be at the end of the list; this
2886 insures they are put there, and stay there, if a user adds or
2887 removes engravers. This command is usually not needed for
2890 @item @code{\accepts} @var{contextname} @code{;}
2891 Add @var{contextname} to the list of context this context can
2892 contain. The first listed context is the context to create by
2895 @item @code{\denies}. The opposite of @code{\accepts}. Added for
2896 completeness, but is never used in practice.
2899 @item @code{\remove} @var{engravername} @code{;}
2900 Remove a previously added (with @code{\consists}) engraver.
2902 @item @code{\name} @var{contextname} @code{;}
2903 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2904 the name is not specified, the translator won't do anything.
2906 @item @var{propname} @code{=} @var{value} @code{;}
2907 A property assignment.
2910 In the @code{\paper} block, it is also possible to define translator
2911 identifiers. Like other block identifiers, the identifier can only
2912 be used as the very first item of a translator. In order to define
2913 such an identifier outside of @code{\score}, you must do
2919 foo = \translator @{ @dots{} @}
2926 \translator @{ \foo @dots{} @}
2934 @cindex paper types, engravers, and pre-defined translators
2936 Some pre-defined identifiers can simplify modification of
2937 translators. The pre-defined identifiers are:
2940 @cindex @code{StaffContext}
2941 @item @code{StaffContext}
2942 Default Staff context.
2943 @cindex @code{RhythmicStaffContext}
2945 @item @code{RhythmicStaffContext}
2946 Default RhythmicStaff context.
2947 @cindex @code{VoiceContext}
2949 @item @code{VoiceContext}
2950 Default Voice context.
2951 @cindex @code{ScoreContext}
2953 @item @code{ScoreContext}
2954 Default Score context.
2956 @cindex @code{HaraKiriStaffContext}
2958 @item @code{HaraKiriStaffContext}
2959 Staff context that does not print if it only contains rests.
2960 Useful for orchestral scores.@footnote{Harakiri, also called
2961 Seppuku, is the ritual suicide of the Japanese Samourai warriors.}
2965 Using these pre-defined values, you can remove or add items to the
2974 \remove Some_engraver;
2975 \consists Different_engraver;
2985 @c . {Notation Contexts}
2986 @node Notation Contexts
2987 @subsection Notation Contexts
2989 @cindex notation contexts
2991 Notation contexts are objects that only exist during a run of
2992 LilyPond. During the interpretation phase of LilyPond, the Music
2993 expression contained in a @code{\score} block is interpreted in time
2994 order. This is the order in which humans read, play, and write
2997 A context is an object that holds the reading state of the
2998 expression; it contains information like
3001 @item What notes are playing at this point?
3002 @item What symbols will be printed at this point?
3003 @item In what style will they printed?
3004 @item What is the current key signature, time signature, point within
3008 Contexts are grouped hierarchically: A @code{Voice} context is
3009 contained in a @code{Staff} context (because a staff can contain
3010 multiple voices at any point), a @code{Staff} context is contained in
3011 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
3012 these can all contain multiple staffs).
3014 Contexts associated with sheet music output are called @emph{notation
3015 contexts}, those for sound output are called performance contexts.
3017 Contexts are created either manually or automatically. Initially, the
3018 top level music expression is interpreted by the top level context (the
3019 @code{Score} context). When a atomic music expression (i.e. a note, a
3020 rest, etc.), a nested set of contexts is created that can process these
3021 atomic expressions, as in this example:
3024 \score @{ \notes @{ c4 @} @}
3027 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
3028 context. When the note @code{c4} itself is interpreted, a set of
3029 contexts is needed that will accept notes. The default for this is a
3030 @code{Voice} context, contained in a @code{Staff} context. Creation of
3031 these contexts results in the staff being printed.
3035 You can also create contexts manually, and you probably have to do so
3036 if you want to typeset complicated multiple part material. If a
3037 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
3038 during the interpretation phase, the @var{musicexpr} argument will be
3039 interpreted with a context of type @var{name}. If you specify a name,
3040 the specific context with that name is searched.
3044 If a context of the specified type and name can not be found, a new
3045 one is created. For example,
3051 \notes \relative c'' {
3052 c4 <d4 \context Staff = "another" e4> f
3059 In this example, the @code{c} and @code{d} are printed on the
3060 default staff. For the @code{e}, a context Staff called
3061 @code{another} is specified; since that does not exist, a new
3062 context is created. Within @code{another}, a (default) Voice context
3063 is created for the @code{e4}. When all music referring to a
3064 context is finished, the context is ended as well. So after the
3065 third quarter, @code{another} is removed.
3067 Almost all music expressions inherit their interpretation context
3068 from their parent. In other words, suppose that the syntax for a
3073 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
3076 When the interpretation of this music expression starts, the context
3077 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
3080 Lastly, you may wonder, why this:
3086 \notes \relative c'' @{
3094 doesn't result in this:
3099 \notes \relative c'' {
3106 For the @code{c4}, a default @code{Staff} (with a contained
3107 @code{Voice}) context is created. After the @code{c4} ends, no
3108 music refers to this default staff, so it would be ended, with the
3109 result shown. To prevent this inconvenient behavior, the context to
3110 which the sequential music refers is adjusted during the
3111 interpretation. So after the @code{c4} ends, the context of the
3112 sequential music is also the default @code{Voice} context.
3113 The @code{d4} gets interpreted in the same context
3116 Properties that are set in one context are inherited by all of the
3117 contained contexts. This means that a property valid for the
3118 @code{Voice} context can be set in the @code{Score} context (for
3119 example) and thus take effect in all @code{Voice} contexts.
3121 Properties can be preset within the @code{\translator} block
3122 corresponding to the appropriate context. In this case, the syntax
3126 @var{propname} @code{=} @var{value}
3129 This assignment happens before interpretation starts, so a
3130 @code{\property} expression will override any predefined settings.
3132 The property settings are used during the interpretation phase. They
3133 are read by the LilyPond modules where interpretation contexts are
3134 built of. These modules are called @emph{translators}. Translators for
3135 notation are called @emph{engravers}, and translators for sound are
3136 called @emph{performers}.
3140 @c . {Syntactic details}
3141 @node Syntactic details
3142 @section Syntactic details
3143 @cindex Syntactic details
3155 @subsection Top level
3158 This section describes what you may enter at top level.
3161 @unnumberedsubsec Score definition
3162 @cindex score definition
3164 The output is generated combining a music expression with an output
3165 definition. A score block has the following syntax:
3168 \score @{ @var{musicexpr} @var{outputdefs} @}
3171 @var{outputdefs} are zero or more output definitions. If no output
3172 definition is supplied, the default @code{\paper} block will be added.
3176 @subsubsection Score
3180 @subsubsection Paper
3188 @subsubsection Header
3190 @cindex @code{\header}
3195 \header @{ @var{key1} = @var{val1};
3196 @cindex @code{ly2dvi}
3197 @var{key2} = @var{val2}; @dots{} @}
3201 A header describes the file's contents. It can also appear in a
3202 @code{\score} block. Tools like @code{ly2dvi} can use this
3203 information for generating titles. Key values that are used by
3204 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
3205 metre, arranger, piece and tagline.
3207 It is customary to put the @code{\header} at the top of the file.
3209 @subsubsection Default output
3211 A @code{\midi} or @code{\paper} block at top-level sets the default
3213 paper block for all scores that lack an explicit paper block.
3217 @subsection Identifiers
3220 All of the information in a LilyPond input file, is represented as a
3221 Scheme value. In addition to normal Scheme data types (such as pair,
3222 number, boolean, etc.), LilyPond has a number of specialized data types,
3229 @item Translator_def
3233 @item Music_output_def
3234 @item Moment (rational number)
3237 LilyPond also includes some transient object types. Objects of these
3238 types are built during a LilyPond run, and do not `exist' per se within
3239 your input file. These objects are created as a result of your input
3240 file, so you can include commands in the input to manipulate them,
3241 during a lilypond run.
3244 @item Grob: short for Graphical object. See @ref{Grobs}.
3245 @item Molecule: device-independent page output object,
3246 including dimensions. Produced by some Grob functions
3248 @item Translator: object that produces audio objects or Grobs. This is
3249 not yet user accessible.
3250 @item Font_metric: object representing a font. (See @ref{Font metrics})
3257 @subsection Assignments
3260 Identifiers allow objects to be assigned to names during the parse
3261 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
3262 and to refer to an identifier, you preceed its name with a backslash:
3263 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
3264 the input-types listed above. Identifier assignments can appear at top
3265 level in the LilyPond file, but also in @code{\paper} blocks.
3267 Semicolons are forbidden after top level assignments, but mandatory in
3268 other places. The rules about semicolons and assignments are very
3269 confusing, but when LilyPond input evolves more towards Scheme, we hope
3270 that this problem will grow smaller.
3272 An identifier can be created with any string for its name, but you will
3273 only be able to refer to identifiers whose names begin with a letter,
3274 being entirely alphabetical. It is impossible to refer to an identifier
3275 whose name is the same as the name of a keyword.
3277 The right hand side of an identifier assignment is parsed completely
3278 before the assignment is done, so it is allowed to redefine an
3279 identifier in terms of its old value, e.g.
3285 When an identifier is referenced, the information it points to is
3286 copied. For this reason, an identifier reference must always be the
3287 first item in a block.
3291 \paperIdent % wrong and invalid
3295 \paperIdent % correct
3299 @c . {Lexical details}
3300 @node Lexical details
3301 @subsection Lexical details
3302 @cindex Lexical details
3307 @subsubsection Comments
3313 A one line comment is introduced by a @code{%} character.
3314 Block comments are started by @code{%@{} and ended by @code{%@}}.
3315 They cannot be nested.
3317 @c . {Direct Scheme}
3318 @subsubsection Direct Scheme
3321 @cindex Scheme, in-line code
3324 LilyPond contains a Scheme interpreter (the GUILE library) for
3325 internal use. In some places Scheme expressions also form valid syntax:
3326 whereever it is allowed,
3330 evaluates the specified Scheme code. If this is used at toplevel, then
3331 the result is discarded. Example:
3333 \property Staff.TestObject \override #'foobar = #(+ 1 2)
3336 @code{\override} expects two Scheme expressions, so there are two Scheme
3337 expressions. The first one is a symbol (@code{foobar}), the second one
3338 an integer (namely, 3).
3340 Scheme is a full-blown programming language, and a full discussion is
3341 outside the scope of this document. Interested readers are referred to
3342 the website @uref{http://www.schemers.org/} for more information on
3347 @subsubsection Keywords
3351 Keywords start with a backslash, followed by a number of lower case
3352 alphabetic characters. These are all the keywords.
3355 apply arpeggio autochange spanrequest commandspanrequest
3356 simultaneous sequential accepts alternative bar breathe
3357 char chordmodifiers chords clef cm consists consistsend
3358 context denies duration dynamicscript elementdescriptions
3359 font grace header in lyrics key mark pitch
3360 time times midi mm name pitchnames notes outputproperty
3361 override set revert partial paper penalty property pt
3362 relative remove repeat addlyrics partcombine score
3363 script stylesheet skip textscript tempo translator
3368 @subsubsection Integers
3376 Formed from an optional minus sign followed by digits. Arithmetic
3377 operations cannot be done with integers, and integers cannot be mixed
3381 @subsubsection Reals
3382 @cindex real numbers
3388 Formed from an optional minus sign and a sequence of digits followed
3389 by a @emph{required} decimal point and an optional exponent such as
3390 @code{-1.2e3}. Reals can be built up using the usual operations:
3391 `@code{+}', `@code{-}', `@code{*}', and
3392 `@code{/}', with parentheses for grouping.
3400 A real constant can be followed by one of the dimension keywords:
3401 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
3402 points, inches and centimeters, respectively. This converts the number
3403 to a real that is the internal representation of dimensions.
3407 @subsubsection Strings
3411 Begins and ends with the @code{"} character. To include a @code{"}
3412 character in a string write @code{\"}. Various other backslash
3413 sequences have special interpretations as in the C language. A string
3414 that contains no spaces can be written without the quotes. See
3415 @ref{Lexical modes} for details on unquoted strings; their
3416 interpretation varies depending on the situation. Strings can be
3417 concatenated with the @code{+} operator.
3419 The tokenizer accepts the following commands. They have no grammatical
3420 function, hence they can appear anywhere in the input.
3424 @subsubsection Main input
3427 @cindex @code{\maininput}
3429 The @code{\maininput} command is used in init files to signal that the
3430 user file must be read. This command cannot be used in a user file.
3432 @c . {File inclusion}
3433 @subsubsection Main input
3436 @subsubsection File inclusion
3437 @cindex @code{\include}
3439 \include @var{filename}
3442 Include @var{filename}. The argument @var{filename} may be a quoted string (an
3443 unquoted string will not work here!) or a string identifier. The full
3444 filename including the @file{.ly} extension must be given,
3446 @subsubsection Version information
3447 @cindex @code{\version}
3449 \version @var{string} ;
3452 Specify the version of LilyPond that a file was written for. The
3453 argument is a version string in quotes, for example @code{"1.2.0"}.
3454 This is used to detect invalid input, and to aid
3455 @code{convert-ly} a tool that automatically upgrades input files. See
3456 See @ref{convert-ly} for more information on @code{convert-ly}.
3462 @subsubsection Defining pitch names
3463 @cindex Lexical modes
3464 @cindex definining pitch names
3465 @cindex pitch names, definining
3467 @cindex chord modifier names
3469 A @code{\paper} block at top level sets the default paper block. A
3470 @code{\midi} block at top level works similarly.
3473 @subsubsection Assignments
3477 Identifier assignments may appear at top level. @ref{Assignments}
3481 @c . {Direct scheme}
3482 @subsubsection Direct scheme
3483 @cindex Direct scheme
3485 Scheme statements maybe issued to produce interesting side-effects.
3488 @c . {Lexical modes}
3490 @subsection Lexical modes
3491 @cindex Lexical modes
3494 @cindex @code{\notes}
3495 @cindex @code{\chords}
3496 @cindex @code{\lyrics}
3498 To simplify entering notes, lyrics, and chords, LilyPond has three
3499 special input modes on top of the default mode: note, lyrics and chords
3500 mode. These input modes change the way that normal, unquoted words are
3501 interpreted: for example, the word @code{cis} may be interpreted as a
3502 C-sharp, as a lyric syllable `cis' or as a C-sharp major triad
3505 A mode switch is entered as a compound music expressions
3507 @code{\notes} @var{musicexpr}
3508 @code{\chords} @var{musicexpr}
3509 @code{\lyrics} @var{musicexpr}.
3512 In each of these cases, these expressions do not add anything to the
3513 meaning of their arguments. They are just a way to indicate that the
3514 arguments should be parsed in indicated mode. The modes are treated in
3515 more detail in the sections @ref{Note entry}, @ref{Lyrics} and
3518 You may nest different input modes.
3522 @subsection Ambiguities
3527 The grammar contains a number of ambiguities. We hope to resolve them at
3531 @item The assignment
3537 can be interpreted as making a string identifier @code{\foo}
3538 containing @code{"bar"}, or a music identifier @code{\foo}
3539 containing the syllable `bar'.
3541 @item The assignment
3547 can be interpreted as making an integer identifier
3548 containing -6, or a Request identifier containing the
3549 fingering `6' (with neutral direction).
3551 @item If you do a nested repeat like
3563 then it is ambiguous to which @code{\repeat} the
3564 @code{\alternative} belongs. This is the classic if-then-else
3565 dilemma. It may be solved by using braces.
3567 @item (an as yet unidentified ambiguity :-)
3582 @unnumberedsubsec Translation property
3584 [todo: add \set/\override/\revert]
3587 @cindex @code{\property}
3589 \property @var{contextname}.@var{propname} = @var{value}
3592 Sets the @var{propname} property of the context @var{contextname} to
3593 the specified @var{value}. All three arguments are strings.
3594 Depending on the context, it may be necessary to quote the strings or
3595 to leave space on both sides of the dot.
3598 @cindex output properties
3599 @unnumberedsubsec Output properties
3601 These allow you to tweak what is happening in the back-end
3602 directly. If you want to control every detail of the output
3603 formatting, this is the feature to use. The downside to this is that
3604 you need to know exactly how the backend works. Example:
3607 @lilypond[fragment,verbatim]
3609 \context Staff \outputproperty
3610 #(make-type-checker 'note-head-interface)
3611 #'extra-offset = #'(0.5 . 0.75)
3615 This selects all note heads occurring at current staff level, and sets
3616 the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting them
3619 Use of this feature is entirely on your own risk: if you use this, the
3620 result will depend very heavily on the implementation of the backend,
3621 which we change regularly and unscrupulously.
3624 Don't move the finger 2, only text "m.d." ...
3626 #(define (make-text-checker text)
3627 (lambda (grob) (equal? text (ly-get-elt-property grob 'text))))
3630 \notes\relative c''' {
3631 \property Voice.Stem \set #'direction = #1
3632 \outputproperty #(make-text-checker "m.d.")
3633 #'extra-offset = #'(-3.5 . -4.5)
3636 \paper { linewidth = -1.; }
3644 @c .{Local emacs vars}
3647 @c minor-mode: font-lock
3648 @c minor-mode: outline
3649 @c outline-layout: (-1 : 0)
3650 @c outline-use-mode-specific-leader: "@c \."
3651 @c outline-primary-bullet: "{"
3652 @c outline-stylish-prefixes: nil
3653 @c outline-override-protect: t