4 @c A menu is needed before every deeper *section nesting of @node's; run
5 @c M-x texinfo-all-menus-update
6 @c to automagically fill in these menus before saving changes
15 @c .{Reference Manual}
17 @node Reference Manual
18 @chapter Reference Manual
21 <!--- @@WEB-TITLE@@=Reference Manual --->
24 This document describes GNU LilyPond and its input format. The last
25 revision of this document was made for LilyPond 1.4.1. It supposes a
26 passing familiarity with how LilyPond input works. New users are
27 encouraged to study the tutorial first.
29 The reference manual is ordered according to different tasks.
30 More details on the property setting mechanisms and context handling is
31 provided in @ref{Tuning output} and @ref{Interpretation context}. The
32 syntactical details are described at the end of the manual.
54 * Skipping corrected music::
55 * Interpretation context::
65 The purpose of LilyPond is explained informally by the term `music
66 typesetter'. This is not a fully correct name: not only does the
67 program print musical symbols, it also makes aesthetic decisions.
68 Symbols and their placements are @emph{generated} from a high-level
69 musical description. In other words, LilyPond would be best described
70 by `music compiler' or `music to notation compiler'.
72 LilyPond is linked to GUILE, GNU's Scheme library for extension
73 programming. The Scheme library provides the glue that holds together
74 the low-level routines and separate modules which are written in C++.
76 When lilypond is run to typeset sheet music, the following happens:
78 @item GUILE Initialization: various scheme files are read
79 @item parsing: first standard @code{ly} initialization files are read, and
80 then the user @file{ly} file is read.
81 @item interpretation: the music in the file is processed ``in playing
82 order'', i.e. the order that you use to read sheet music, or the
83 order in which notes are played. The result of this step is a typesetting
87 The typesetting specification is solved: positions and formatting is
90 @item the visible results ("virtual ink") are written to the output file.
93 During these stages different types of data play the the main role:
94 during parsing, @strong{Music} objects are created. During the
95 interpretation, @strong{contexts} are constructed, and with these contexts
96 a network of @strong{graphical objects} (``grobs'') is created. These
97 grobs contain unknown variables, and the network forms a set of
98 equations. After solving the equations and filling in these variables,
99 the printed output (in the form of @strong{molecules}) is written to an
102 These threemanship of tasks (parsing, translating, typesetting) and
103 data-structures (music, context, graphical objects) permeates the entire
104 design of the program.
111 The most basic forms of music are notes. We discuss how you enter them
112 here. Notes on their own don't form valid input, but for the sake of
113 brevity we omit obligatory lint such as @code{\score} blocks and
114 @code{\paper} declarations.
125 * Defining pitch names::
126 * Easy Notation note heads ::
133 A note specification has the form
136 @var{pitch}[!][?][@var{duration}]
139 The alteration refers to what note is heard, not to whether an
140 accidental is printed. This is done depending on the key and context.
141 A reminder accidental
142 @cindex reminder accidental
144 can be forced by adding an exclamation mark @code{!} after the pitch. A
145 cautionary accidental,
146 @cindex cautionary accidental
147 @cindex parenthesized accidental
148 i.e., an accidental within parentheses can be obtained by adding the
149 question mark `@code{?}' after the pitch.
151 @lilypond[fragment,verbatim,center]
152 cis' d' e' cis' c'? d' e' c'!
161 @cindex Note specification
163 @cindex entering notes
165 The verbose syntax for pitch specification is
167 @cindex @code{\pitch}
169 \pitch @var{scmpitch}
172 @var{scmpitch} is a pitch scheme object, see @ref{Pitch data type}.
174 In Note and Chord mode, pitches may be designated by names. The default
175 names are the Dutch note names. The notes are specified by the letters
176 @code{a} through @code{g} (where the octave is formed by notes ranging
177 from @code{c} to @code{b}). The pitch @code{c} is an octave below
178 middle C and the letters span the octave above that C.
180 @cindex note names, Dutch
182 In Dutch, a sharp is formed by adding @code{-is} to the end of a pitch
183 name and a flat is formed by adding @code{-es}. Double sharps and double
184 flats are obtained by adding @code{-isis} or @code{-eses}. @code{aes}
185 and @code{ees} are contracted to @code{as} and @code{es} in Dutch, but
186 both forms are accepted.
188 LilyPond has predefined sets of note names for various other languages.
189 To use them, simply include the language specific init file. For
190 example: @code{\include "english.ly"}. The available language files and
191 the names they define are:
194 Note Names sharp flat
195 nederlands.ly c d e f g a bes b -is -es
196 english.ly c d e f g a bf b -s/-sharp -f/-flat
197 deutsch.ly c d e f g a b h -is -es
198 norsk.ly c d e f g a b h -iss/-is -ess/-es
199 svenska.ly c d e f g a b h -iss -ess
200 italiano.ly do re mi fa sol la sib si -d -b
201 catalan.ly do re mi fa sol la sib si -d/-s -b
209 The optional octave specification takes the form of a series of
210 single quote (`@code{'}') characters or a series of comma
211 (`@code{,}') characters. Each @code{'} raises the pitch by one
212 octave; each @code{,} lowers the pitch by an octave.
214 @lilypond[fragment,verbatim,center]
215 c' c'' es' g' as' gisis' ais'
223 Rests are entered like notes, with note name `@code{r}'. The grob is
224 @code{Rest}. Whole bar rests centered in the bar are specified using
225 @code{R}, see @ref{Multi measure rests}.
240 Skips the amount of time specified by @var{duration}. If no other music
241 is played, a gap will be left for the skipped time without any notes
242 printed. The shorthand is only available in Note and Chord mode.
246 @subsection Durations
250 @cindex @code{\duration}
252 The syntax for a verbose duration specification is
254 \duration @var{scmduration}
256 Here, @var{scmduration} is a Scheme object of type @code{Duration}. See
257 @ref{Duration} for more information.
260 In Note, Chord, and Lyrics mode, durations may be designated by numbers
261 and dots: durations are entered as their reciprocal values. For notes
262 longer than a whole you must use identifiers.
266 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
268 r1 r2 r4 r8 r16 r32 r64 r64
274 \notes \relative c'' {
276 a1 a2 a4 a8 a16 a32 a64 a64
278 r1 r2 r4 r8 r16 r32 r64 r64
283 \remove "Clef_engraver"
284 \remove "Staff_symbol_engraver"
285 \remove "Time_signature_engraver"
286 \consists "Pitch_squash_engraver"
292 To get a longa note head, you have to use mensural note heads. This
293 is accomplished by setting the @code{style} property of the
294 NoteHead grob to @code{mensural}. There is also a note head style
295 @code{baroque} which gives mensural note heads for @code{\longa} and
296 @code{\breve} but standard note heads for shorter notes.
298 @lilypond[fragment,singleline,verbatim]
299 \property Voice.NoteHead \set #'style = #'mensural
303 If the duration is omitted then it is set to the previous duration
304 entered. At the start of parsing a quarter note is assumed. The
305 duration can be followed by dots (`@code{.}') to obtain dotted note
309 @lilypond[fragment,verbatim,center]
315 You can alter the length of duration by a fraction @var{N/M} by
316 appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
317 will not affect the appearance of the notes or rests produced.
329 A tie connects two adjacent note heads of the same pitch. When used
330 with chords, it connects all the note heads whose pitches match.
331 Ties are indicated using the tilde symbol `@code{~}'. If you try to tie
332 together chords which have no common pitches then no ties will be
335 @lilypond[fragment,verbatim,center]
336 e' ~ e' <c' e' g'> ~ <c' e' g'>
339 If you dislike the amount of ties created for a chord, you set
340 @code{Voice.sparseTies} to true, resulting in a smaller number of
342 @lilypond[fragment,verbatim,center]
343 \property Voice.sparseTies = ##t
344 <c' e' g'> ~ <c' e' g'>
347 In its meaning a tie is just a way of extending a note duration, similar
348 to the augmentation dot: the following example are two ways of notating
349 exactly the same concept.
351 @lilypond[fragment, singleline]
352 \time 3/4 c'2. c'2 ~ c'4
355 The name of the tie grob is @code{Voice.Tie}.
359 At present, the tie is implemented as a separate thing, temporally
360 located in between the notes. There is also no way to convert
361 between tied notes, dotted notes and plain notes.
363 Tieing only a subset of the note heads of a chord is not supported in a
364 simple way. It can be achieved by moving the tie-engraver into the Thread
365 context and turning on and off ties per Thread.
373 @cindex @code{\times}
375 Tuplets are made out of a music expression by multiplying all duration
378 @cindex @code{\times}
380 \times @var{fraction} @var{musicexpr}
383 The duration of @var{musicexpr} will be multiplied by the fraction.
384 In print, the fraction's denominator will be printed over the notes,
385 optionally with a bracket. The most common tuplet is the triplet in
386 which 3 notes have the length of 2, so the notes are 2/3 of
387 their written length:
389 @lilypond[fragment,verbatim,center]
390 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
393 The property @code{tupletSpannerDuration} specifies how long each bracket
394 should last. With this, you can make lots of tuplets while typing
395 @code{\times} only once, thus saving typing work.
397 @lilypond[fragment, relative, singleline, verbatim]
398 \property Voice.tupletSpannerDuration = #(make-moment 1 4)
399 \times 2/3 { c'8 c c c c c }
402 The format of the number is determined by the property
403 @code{tupletNumberFormatFunction}. The default prints only the
404 denominator, but if you set it to the Scheme function
405 @code{fraction-tuplet-formatter}, Lilypond will print @var{num}:@var{den}
408 The typesetting of brackets and numbers is controlled by the properties
409 @code{tuplet-bracket-visibility} and @code{tuplet-number-visibility}.
411 @lilypond[fragment, relative, singleline, verbatim]
412 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##t
413 \times 2/3{c'8 d e} \times 2/3{d4 e8}
414 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = #'if-no-beam
415 \times 2/3{c d e} \times 2/3{d4 e8}
416 \property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##f
417 \times 2/3{c d e} \times 2/3{d4 e8}
418 \property Voice.TupletBracket \set #'tuplet-number-visibility = ##f
419 \times 2/3{c d e} \times 2/3{d4 e8}
420 \property Voice.TupletBracket \set #'tuplet-number-visibility = #'if-no-beam
421 \times 2/3{c d e} \times 2/3{d4 e8}
424 @cindex @code{tupletNumberFormatFunction}
425 @cindex tuplet formatting
427 Tuplet brackets are printed as @code{TupletBracket} grobs
429 @c . {Defining pitch names}
430 @node Defining pitch names
431 @subsection Defining pitch names
433 @cindex defining pitch names
434 @cindex pitch names, defining
436 Note names and chord modifiers can be customized for nationalities. The
437 syntax is as follows.
439 @cindex @code{\pitchnames}
440 @cindex @code{\chordmodifiers}
442 \pitchnames @var{scheme-alist}
443 \chordmodifiers @var{scheme-alist}
446 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
447 specific examples on how to do this.
450 @node Easy Notation note heads
451 @subsection Easy Notation note heads
453 @cindex easy notation
456 A entirely different type of note head is the "easyplay" note head: a
457 note head that includes a note name. It is used in some publications by
458 Hal-Leonard Inc. music publishers.
460 @lilypond[singleline,verbatim]
461 \include "paper23.ly"
463 \notes { c'2 e'4 f' | g'1 }
464 \paper { \translator { \EasyNotation } }
468 Note that @code{EasyNotation} overrides a @code{Score} context. You
469 probably will want to print it with magnification to make it more
470 readable, see @ref{Output scaling}.
476 If you view the result with Xdvi, then staff lines will show through the
477 letters. Printing the postscript file obtained either by using dvips or
478 the @code{-f ps} option of lilypond produces the correct result.
483 @section Staff notation
485 @cindex Staff notation
497 @subsection Key signature
502 Setting or changing the key signature is done with the @code{\key}
505 @code{\key} @var{pitch} @var{type}
508 @cindex @code{\minor}
509 @cindex @code{\major}
510 @cindex @code{\minor}
511 @cindex @code{\ionian}
512 @cindex @code{\locrian}
513 @cindex @code{\aeolian}
514 @cindex @code{\mixolydian}
515 @cindex @code{\lydian}
516 @cindex @code{\phrygian}
517 @cindex @code{\dorian}
519 Here, @var{type} should be @code{\major} or @code{\minor} to get
520 @var{pitch}-major or @var{pitch}-minor, respectively.
521 The standard mode names @code{\ionian},
522 @code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
523 @code{\phrygian}, and @code{\dorian} are also defined.
525 This command sets the context property @code{Staff.keySignature}.
526 Non-standard key signatures can be specified by setting this property
527 directly, see the generated documentation for @rgrob{KeySignature}.
529 The printed signature is a @code{KeySignature} grob.
531 @cindex @code{keySignature}
538 The clef can be set or changed with the @code{\clef} command.
546 \property Staff.clefGlyph = @var{glyph associated with clefname}
547 \property Staff.clefPosition = @var{clef Y-position for clefname}
548 \property Staff.centralCPosition = @var{position for central C}
549 \property Staff.clefOctavation = @var{extra transposition of clefname}
552 Any change in these properties creates a clef (a @code{Clef} grob).
554 Supported clef-names include
556 @c Moved standard clefs to the top /MB
558 @item treble, violin, G, G2
567 G clef on 1st line, so-called French violin clef
582 By adding @code{_8} or @code{^8} to the clef name, the clef is
583 transposed one octave down or up, respectively.
585 Supported associated glyphs (for @code{Staff.clefGlyph}) are:
594 @item clefs-vaticana_do
595 Editio Vaticana style do clef
596 @item clefs-vaticana_fa
597 Editio Vaticana style fa clef
598 @item clefs-medicaea_do
599 Editio Medicaea style do clef
600 @item clefs-medicaea_fa
601 Editio Medicaea style fa clef
602 @item clefs-mensural1_c
603 modern style mensural C clef
604 @item clefs-mensural2_c
605 historic style small mensural C clef
606 @item clefs-mensural3_c
607 historic style big mensural C clef
608 @item clefs-mensural1_f
609 historic style traditional mensural F clef
610 @item clefs-mensural2_f
611 historic style new mensural F clef
612 @item clefs-mensural_g
613 historic style mensural G clef
614 @item clefs-hufnagel_do
615 historic style hufnagel do clef
616 @item clefs-hufnagel_fa
617 historic style hufnagel fa clef
618 @item clefs-hufnagel_do_fa
619 historic style hufnagel combined do/fa clef
620 @item clefs-percussion
621 modern style percussion clef
624 @emph{Modern style} means ``as is typeset in current editions.''
625 @emph{Historic style} means ``as was typeset or written in contemporary
626 historic editions''. @emph{Editio XXX style} means ``as is/was printed in
629 @cindex Vaticana, Editio
630 @cindex Medicaea, Editio
631 @cindex hufnagel clefs
634 @c . {Time signature}
636 @subsection Time signature
637 @cindex Time signature
641 The time signature is set or changed by the @code{\time}
644 \time @var{n}@code{/}@var{d}
646 Internally, this is a shortcut for doing
648 \property Score.timeSignatureFraction = #'(@var{n} . @var{d})
649 \property Score.beatLength = #(make-moment 1 @var{d})
650 \property Score.measureLength = #(make-moment @var{n} @var{d})
653 These properties @code{timeSignatureFraction} determine where bar lines
654 should be inserted, and how automatic beams should be
657 Changing the value of @code{timeSignatureFraction} also causes a
658 fraction to be printed. This grob is @code{TimeSignature}.
660 The actual symbol that's printed can be customized with the style
662 @lilypond[fragment, verbatim, singleline]
664 \property Staff.TimeSignature \override #'style = #'C
666 \property Staff.TimeSignature \override #'style = #'()
668 \property Staff.TimeSignature \override #'style = #'C
672 There are many more options for the layout of this grob. They are
673 selected through the @code{style} grob property.
675 @c FIXME: this isn't documented except in example?
677 @file{input/test/time.ly} for examples.
684 @cindex partial measure
685 @cindex measure, partial
686 @cindex shorten measures
687 @cindex @code{\partial}
689 Partial measures, for example in upbeats, are entered using the
690 @code{\partial} command:
692 \partial @var{duration}
695 Internally, this is a shortcut for
698 \property Score.measurePosition = -@var{length of duration}
702 The property @code{measurePosition} contains a rational number
703 indicating how much of the measure has passed at this point.
706 @node Unmetered music
707 @subsection Unmetered music
709 Bar lines and bar numbers are calculated automatically. For unmetered
710 music (e.g. cadenzas), this is not desirable. The property
711 @code{Score.timing} can be used to switch off this automatic timing
713 @lilypond[fragment,relative,singleline,verbatim]
715 \property Score.timing = ##f
717 \property Score.timing = ##t
721 The identifiers @code{\cadenzaOn} and @code{\cadenzaOff} can be used as
728 @subsection Bar lines
732 @cindex measure lines
739 This is a shortcut for doing
741 \property Score.whichBar = @var{bartype}
743 The following bar types are available
745 @lilypond[fragment, relative, singleline, verbatim]
758 You are encouraged to use @code{\repeat} for repetitions. See
762 @cindex Bar_line_engraver
764 @cindex repeatCommands
765 @cindex defaultBarType
767 Whenever @code{whichBar} is set to a string, a bar line of that type is
768 created. @code{whichBar} is usually set automatically: at the start of
769 a measure it is set to @code{defaultBarType}. The contents of
770 @code{repeatCommands} is used to override default measure bars.
772 @code{whichBar} can also be set directly, using @code{\property} or
773 @code{\bar }. These settings take precedence over the automatic
774 @code{whichBar} settings.
776 @code{BarLine} grobs are created by the @code{Bar_engraver}.
783 Polyphonic parts, i.e. parts with more than one voice on a staff can be
784 typeset with LilyPond. To use this, instantiate a separate Voice
785 context for each part, and assign a stem direction to each part.
786 @lilypond[fragment,verbatim]
788 < \context Voice = VA { \stemUp b'4 a' g' f' e' }
789 \context Voice = VB { \stemDown g'4 g' g' g' g' } >
792 When there are more than two voices on a staff, you must also indicate
793 which voice should moved horizontally in case of a collision. This can
794 be done with the identifiers @code{\shiftOff}, @code{\shiftOn},
795 @code{\shiftOnn}, etc. (which sets the grob property @code{horizontal-shift}
796 in @code{NoteColumn}).
798 @lilypond[fragment, verbatim]
799 \context Staff \notes\relative c''<
806 \context Voice=three {
807 \shiftOnn \stemUp ais
809 \context Voice=four {
810 \shiftOnnn \stemUp fis
815 The most convenient way is to use the identifiers @code{\voiceOne}
816 through @code{\voiceFour}, which also set slur and tie directions in the
819 @lilypond[singleline, verbatim]
821 \context Staff < \context Voice = VA { \voiceOne cis2 b }
822 \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 }
823 \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } >
826 Normally, note heads with a different number of dots are not merged, but
827 if you set the grob property @code{merge-differently-dotted}, they are:
829 @lilypond[verbatim,fragment,singleline]
831 \context Voice = VA { \voiceOne
833 \property Staff.NoteCollision \override #'merge-differently-dotted = ##t
836 \context Voice = VB { \voiceTwo [g'8. f16] [g'8. f'16] }
840 LilyPond also vertically shifts rests that are opposite of a stem.
842 @lilypond[singleline,verbatim]
844 \context Voice { \stemUp c''4 }
845 \context Voice =VB { r4 }
849 Note head collisions (horizontal shifting of note heads) are handled by
850 the @code{NoteCollision} grob. @code{RestCollision} handles vertical
853 @cindex @code{NoteCollision}
854 @cindex @code{RestCollision}
859 Resolving collisions is a very intricate subject, and LilyPond only
860 handles a few situations. When it can not cope, you are advised to use
861 @code{force-hshift} of the NoteColumn grob and @code{staff-position} of
862 the Rest grob to override typesetting decisions.
867 Beams are used to group short notes into chunks that are aligned with
868 the metrum. LilyPond guesses where beams should be inserted. If you're
869 not satisfied with the automatic beaming, you can specify which patterns
870 to beam automatically. In specific cases, you can also enter the beams
874 @c . {Automatic beams}
875 @subsection Automatic beams
877 @cindex @code{Voice.autoBeamSettings}
878 @cindex @code{(end * * * *)}
879 @cindex @code{(begin * * * *)}
882 In normal time signatures, automatic beams can start on any note but can
883 only end in a few positions within the measure: beams can end on a beat,
884 or at durations specified by the properties in
885 @code{Voice.autoBeamSettings}. The defaults for @code{autoBeamSettings}
886 are defined in @file{scm/auto-beam.scm}.
888 The value of @code{autoBeamSettings} is changed using
889 @code{\override} and unset using @code{\revert}:
891 \property Voice.autoBeamSettings \override #'(@var{BE} @var{P} @var{Q} @var{N} @var{M}) = @var{dur}
892 \property Voice.autoBeamSettings \revert #'(@var{BE} @var{P} @var{Q} @var{N} @var{M})
894 Here, @var{BE} is the symbol @code{begin} or @code{end}. It determines
895 whether the rule applies to begin or end-points. The quantity
896 @var{P}/@var{Q} refers to the length of the beamed notes (and `@code{*
897 *}' designates notes of any length), @var{N}/@var{M} refers to a time
898 signature (wildcards, `@code{* *}' may be entered to designate all time
901 For example, if you want automatic beams to end on every quarter note,
902 you can use the following:
904 \property Voice.autoBeamSettings \override
905 #'(end * * * *) = #(make-moment 1 4)
907 Since the duration of a quarter note is 1/4 of a whole note, it is
908 entered as @code{(make-moment 1 4)}.
910 The same syntax can be used to specify beam starting points. In this
911 example, automatic beams can only end on a dotted quarter note.
913 \property Voice.autoBeamSettings \override
914 #'(end * * * *) = #(make-moment 3 8)
916 In 4/4 time signature, this means that automatic beams could end only on
917 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
918 3/8 has passed within the measure).
920 You can also restrict rules to specific time signatures. A rule that
921 should only be applied in @var{N}/@var{M} time signature is formed by
922 replacing the second asterisks by @var{N} and @var{M}. For example, a
923 rule for 6/8 time exclusively looks like
925 \property Voice.autoBeamSettings \override
926 #'(begin * * 6 8) = ...
929 If you want a rule to apply to certain types of beams, you can use the
930 first pair of asterisks. Beams are classified according to the shortest
931 note they contain. For a beam ending rule that only applies to beams
932 with 32nd notes (and no shorter notes), you would use @code{(end 1
936 @c Automatic beams can not be put on the last note in a score.
938 If a score ends while an automatic beam has not been ended and is still
939 accepting notes, this last beam will not be typeset at all.
941 @cindex automatic beam generation
943 @cindex @code{Voice.noAutoBeaming}
945 Automatic beaming is on by default, but can be switched off by setting
946 @code{Voice.noAutoBeaming} to true. You you may find this necessary for
947 a melody that goes with lyrics.
951 It is not possible to specify beaming parameters for beams with mixed
952 durations, that differ from the beaming parameters of all separate
953 durations, i.e., you'll have to specify manual beams to get:
954 @lilypond[fragment,singleline,relative]
955 \property Voice.autoBeamSettings
956 \override #'(end * * * *) = #(make-moment 3 8)
957 \time 12/8 c'8 c c c16 c c c c c [c c c c] c8 c c4
960 It is not possible to specify beaming parameters that act differently in
961 different parts of a measure. This means that it is not possible to use
962 automatic beaming in irregular meters such as @code{5/8}.
965 @cindex Automatic beams
966 @subsection Manual beams
967 @cindex beams, manual
971 In some cases it may be necessary to override LilyPond's automatic
972 beaming algorithm. For example, the auto beamer will not beam over
973 rests or bar lines, If you want that, specify the begin and end point
974 manually using a @code{[} before the first beamed note and a @code{]}
977 @lilypond[fragment,relative,verbatim]
979 r4 [r8 g' a r8] r8 [g | a] r8
982 Whenever an manual beam is busy, the automatic beamer will not produce
985 @cindex @code{stemLeftBeamCount}
987 Normally, beaming patterns within a beam are determined automatically.
988 When this mechanism fouls up, the properties
989 @code{Voice.stemLeftBeamCount} and @code{Voice.stemRightBeamCount}. can
990 be used to control the beam subdivision on a stem. If you set either
991 property, it's value will be used only once, and then it is erased.
993 @lilypond[fragment,relative,verbatim]
996 [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a]
999 @cindex @code{stemRightBeamCount}
1001 The beam symbol (grob @code{Voice.Beam}, both for automatic and manual
1002 beams) can be tweaked through grob-properties @code{height} and
1003 @code{staff-position}. These specify vertical location and vertical
1004 span. Both are measured in half staff-spaces, @code{staff-position=0}
1005 corresponds to the middle staff line.
1008 Set @code{height} to zero, to get horizontal beams:
1010 @lilypond[fragment,relative,verbatim]
1011 \property Voice.Beam \set #'direction = #1
1012 \property Voice.Beam \set #'height = #0
1016 Here's how you'd specify a weird looking beam that instead of being
1017 horizontal, falls two staff spaces:
1019 @lilypond[fragment,relative,verbatim]
1020 \property Voice.Beam \set #'staff-position = #4
1021 \property Voice.Beam \set #'height = #-4
1024 @cindex @code{default-neutral-direction}
1026 @node Expressive marks
1027 @section Expressive marks
1042 A slur indicates that notes are to be played bound or @emph{legato}.
1043 They are entered using parentheses:
1045 @lilypond[fragment,verbatim,center]
1046 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1050 Slurs avoid crossing stems, and are generally attached to note heads.
1051 However, in some situations with beams, slurs may be attached to stem
1052 ends. If you want to override this layout you can do this through the
1053 @code{Voice.Slur}'s grob-property @code{attachment}. It's value is a
1054 pair of symbols, specifying the attachment type of the left and right end points.
1056 @lilypond[fragment,relative,verbatim]
1057 \property Voice.Slur \set #'direction = #1
1058 \property Voice.Stem \set #'length = #5.5
1060 \property Voice.Slur \set #'attachment = #'(stem . stem)
1064 If a slur would strike through a stem or beam, the slur will be moved
1065 away upward or downward. If this happens, attaching the slur to the
1066 stems might look better:
1068 @lilypond[fragment,relative,verbatim]
1069 \property Voice.Stem \set #'direction = #1
1070 \property Voice.Slur \set #'direction = #1
1072 \property Voice.Slur \set #'attachment = #'(stem . stem)
1077 Similarly, the curvature of a slur is adjusted to stay clear of note
1078 heads and stems. When that would increase the curvature too much, the
1079 slur is reverted to its default shape. The threshold for this decision
1080 is in @code{Voice.Slur}'s grob-property @code{beautiful}. It is loosely
1081 related to the enclosed area between the slur and the notes. Usually,
1082 the default setting works well, but in some cases you may prefer a
1083 curved slur when LilyPond decides for a vertically moved one. You can
1084 indicate this preference by increasing the @code{beautiful} value:
1086 @lilypond[verbatim,singleline,relative]
1087 \property Voice.Beam \override #'direction = #-1
1088 \property Voice.Slur \override #'direction = #1
1089 c16( a' f' a a f a, )c,
1090 c( a' f' a a f d, )c
1091 \property Voice.Slur \override #'beautiful = #5.0
1092 c( a' f' a a f d, )c
1097 @code{beautiful} is an arbitrary parameter in the slur formatter.
1098 Useful values can only be determined by trial and error.
1100 @cindex Adjusting slurs
1102 @node Phrasing slurs
1103 @subsection Phrasing slurs
1105 @cindex phrasing slurs
1106 @cindex phrasing marks
1108 A phrasing slur (or phrasing mark) connects chords and is used to
1109 indicate a musical sentence. It is started using @code{\(} and @code{\)}
1112 @lilypond[fragment,verbatim,center,relative]
1113 \time 6/4 c' \( ( d ) e f ( e ) \) d
1116 Typographically, the phrasing slur behaves almost exactly like a normal
1117 slur. The grob associated with it is @code{Voice.PhrasingSlur}.
1120 @subsection Breath marks
1122 Breath marks are entered using @code{\breathe}. The result is a
1123 @code{Voice.BreathingSign} grob.
1125 @lilypond[fragment,relative]
1134 Currently, only tick marks are supported, not comma style breath marks.
1141 @cindex beats per minute
1142 @cindex metronome marking
1144 Metronome settings can be entered as follows:
1146 @cindex @code{\tempo}
1148 \tempo @var{duration} = @var{perminute}
1151 For example, @code{\tempo 4 = 76} requests output with 76 quarter notes
1156 The tempo setting is not printed, but is only used in the MIDI
1157 output. You can trick lily into producing a metronome mark,
1158 though. Details are in @ref{Text markup}.
1163 @subsection Text spanners
1164 @cindex Text spanners
1166 Some textual indications, e.g. rallentando or accelerando, often extend
1167 over many measures. This is indicated by following the text with a
1168 dotted line. You can create such texts using text spanners. The syntax
1171 \spanrequest \start "text"
1172 \spanrequest \stop "text"
1174 LilyPond will respond by creating a @code{Voice.TextSpanner} grob. The
1175 string to be printed, as well as the style is set through grob
1178 An application---or rather, a hack---is to fake octavation indications.
1179 @lilypond[fragment,relative,verbatim]
1180 \relative c' { a''' b c a
1181 \property Voice.TextSpanner \set #'type = #'dotted-line
1182 \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5)
1183 \property Voice.TextSpanner \set #'edge-text = #'("8va " . "")
1184 \property Staff.centralCPosition = #-13
1185 a\spanrequest \start "text" b c a \spanrequest \stop "text" }
1203 @subsection Articulations
1204 @cindex Articulations
1206 @cindex articulations
1210 A variety of symbols can appear above and below notes to indicate
1211 different characteristics of the performance. These symbols can be
1212 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1213 are defined in @file{script.ly}. Symbols can be forced to appear above
1214 or below the note by writing `@var{note}@code{^\}@var{name}' and
1215 `@var{note}@code{_\}@var{name}' respectively. Here is a chart showing
1216 symbols on notes, with the name of the corresponding symbol appearing
1222 \property Score.LyricSyllable \override #'font-family =#'typewriter
1223 \property Score.LyricSyllable \override #'font-shape = #'upright
1224 \context Staff \notes {
1225 c''-\accent c''-\marcato c''-\staccatissimo c''^\fermata
1226 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1227 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1228 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1229 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1230 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1231 c''-\upmordent c''-\downmordent c''-\pralldown c''-\prallup
1232 c''-\lineprall c''-\thumb c''-\segno c''-\coda
1234 \context Lyrics \lyrics {
1235 accent__ marcato__ staccatissimo__ fermata
1236 stopped__ staccato__ tenuto__ upbow
1237 downbow__ lheel__ rheel__ ltoe
1238 rtoe__ turn__ open__ flageolet
1239 reverseturn__ trill__ prall__ mordent
1240 prallprall__ prallmordent__ uprall__ downprall
1241 upmordent__ downmordent__ pralldown__ prallup__
1242 lineprall__ thumb__ segno__ coda
1246 linewidth = 5.875\in
1252 To save typing work, some shorthands are available:
1253 @lilypond[singleline]
1255 \notes \context Voice {
1256 \property Voice.TextScript \set #'font-family = #'typewriter
1257 \property Voice.TextScript \set #'font-shape = #'upright
1263 c''4-^_"c-\\^{ }" s4
1270 Fingering instructions can also be entered in this shorthand.
1271 @lilypond[verbatim, singleline, fragment]
1272 c'4-1 c'4-2 c'4-3 c'4-4
1276 @cindex @code{\script}
1281 You can add scripts by editing @file{scm/script.scm}. This file contains
1282 a table, listing script definitions and aliases. The following syntax
1283 accesses a script definition from the table:
1289 Usually the @code{\script} keyword is not used directly. Various
1290 helpful identifier definitions appear in @file{script.ly}.
1292 Grobs for these objects are @code{Script} and @code{Fingering}.
1296 All of these note ornaments appear in the printed output but have no
1297 effect on the MIDI rendering of the music.
1299 Unfortunately, there is no support for adding fingering instructions or
1300 ornaments to individual note heads. Some hacks exist, though. See
1301 @file{input/test/script-horizontal.ly}.
1306 @subsection Text scripts
1307 @cindex Text scripts
1309 In addition, it is possible to place arbitrary strings of text or markup
1310 text (see @ref{Text markup}) above or below notes by using a string:
1313 By default, these indications do not influence the note spacing, but
1314 if @code{Voice.textNonEmpty} is set to true the widths will be taken
1315 into account. The identifier @code{\fatText} is defined in the standard
1317 @lilypond[fragment,singleline,verbatim]
1318 \relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
1321 Text scripts are created in form of @code{Voice.TextScript} grobs.
1323 @ref{Text markup} describes how to change the font or access
1324 special symbols in text scripts.
1328 @subsection Grace notes
1337 @cindex @code{\grace}
1340 @cindex @code{graceAlignPosition}
1342 Grace notes are ornaments that are written out, but do not take up any
1343 logical time in a measure. LilyPond has limited support for grace notes.
1344 The syntax is as follows.
1346 \grace @var{musicexpr}
1349 When grace music is interpreted, a score-within-a-score is set up:
1350 @var{musicexpr} has its own time bookkeeping, and you could (for
1351 example) have a separate time signature within the grace notes. While in
1352 this score-within-a-score, you can create notes, beams, slurs, etc.
1353 Unbeamed eighth notes and shorter by default have a slash through the
1356 @lilypond[fragment,verbatim]
1358 \grace c8 c4 \grace { [c16 c16] } c4
1360 \property Voice.Stem \override #'flag-style = #'()
1362 \property Voice.Stem \revert #'flag-style
1368 A grace note expression has duration 0; the next real note is assumed to
1369 be the main note. If you want the note to appear after the main note,
1370 set @code{Voice.graceAlignPosition} to @code{1}.
1374 At present, slurs or ties from the grace notes to the following notes
1375 are not supported. Also, nesting @code{\grace} notes is not
1376 supported. The following may cause run-time errors:
1378 @code{\grace @{ \grace c32 c16 @} c4}
1380 Since the meaning of such a construct is unclear, we don't consider this
1381 a loss. Similarly, juxtaposing two @code{\grace} sections is
1382 syntactically valid, but makes no sense and may cause runtime errors.
1383 Ending a staff or score with grace notes may also generate a run-time
1384 error, since there will be no main note to attach the grace notes to.
1386 The present implementation of grace notes is not robust and generally
1387 kludgey. We expect it to change after LilyPond 1.4. Syntax changes might
1388 also be implemented.
1399 @subsection Glissando
1402 @cindex @code{\glissando}
1404 A glissando line (grob @code{Voice.Glissando}) can be requested by attaching a
1405 @code{\glissando} to a note:
1407 @lilypond[fragment,relative,verbatim]
1413 Printing of an additional text (such as @emph{gliss.}) must be done
1420 @subsection Dynamics
1433 @cindex @code{\ffff}
1443 Absolute dynamic marks are specified using an identifier after a
1444 note: @code{c4-\ff}. The available dynamic marks are: @code{\ppp},
1445 @code{\pp}, @code{\p}, @code{\mp}, @code{\mf}, @code{\f}, @code{\ff},
1446 @code{\fff}, @code{\fff}, @code{\fp}, @code{\sf}, @code{\sff},
1447 @code{\sp}, @code{\spp}, @code{\sfz}, and @code{\rfz}.
1449 @lilypond[verbatim,singleline,fragment,relative]
1450 c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff
1456 @cindex @code{\decr}
1457 @cindex @code{\rced}
1463 A crescendo mark is started with @code{\cr} and terminated with
1464 @code{\rc} (the textual reverse of @code{cr}). A decrescendo mark is
1465 started with @code{\decr} and terminated with @code{\rced}. There are
1466 also shorthands for these marks. A crescendo can be started with
1467 @code{\<} and a decrescendo can be started with @code{\>}. Either one
1468 can be terminated with @code{\!}. Note that @code{\!} must go before
1469 the last note of the dynamic mark whereas @code{\rc} and @code{\rced} go
1470 after the last note. Because these marks are bound to notes, if you
1471 want several marks during one note, you have to use spacer notes.
1473 @lilypond[fragment,verbatim,center]
1474 c'' \< \! c'' d'' \decr e'' \rced
1475 < f''1 { s4 s4 \< \! s4 \> \! s4 } >
1478 You can also use a text saying @emph{cresc.} instead of hairpins. Here
1479 is an example how to do it:
1484 @lilypond[fragment,relative,verbatim]
1486 \property Voice.crescendoText = "cresc."
1487 \property Voice.crescendoSpanner = #'dashed-line
1492 For everyday use, we recommend the identifiers @code{\cresc},
1493 @code{endcresc}, @code{\dim} and @code{\enddim}.
1497 Dynamics are grobs of @code{Voice.DynamicText} and
1498 @code{Voice.Hairpin}. They are put together on
1499 @code{Voice.DynamicLineSpanner} to align them vertically.
1508 @cindex @code{\repeat}
1510 To specify repeats, use the @code{\repeat} keyword. Since repeats
1511 should work differently when played or printed, there are a few
1512 different variants of repeats.
1516 Repeated music is fully written (played) out. Useful for MIDI
1517 output, and entering repetitive music.
1520 This is the normal notation: Repeats are not written out, but
1521 alternative endings (voltas) are printed, left to right.
1524 Alternative endings are written stacked. This has limited use but may be
1525 used to typeset two lines of lyrics in songs with repeats, see
1526 @file{input/star-spangled-banner.ly}.
1532 Make beat or measure repeats. These look like percent signs.
1538 * Manual repeat commands::
1540 * Tremolo subdivisions::
1545 @subsection Repeat syntax
1547 The syntax for repeats is
1550 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1553 If you have alternative endings, you may add
1554 @cindex @code{\alternative}
1556 \alternative @code{@{} @var{alternative1}
1558 @var{alternative3} @dots{} @code{@}}
1560 where each @var{alternative} is a music expression.
1562 Normal notation repeats are used like this:
1563 @lilypond[fragment,verbatim]
1565 \repeat volta 2 { c'4 d' e' f' }
1566 \repeat volta 2 { f' e' d' c' }
1569 With alternative endings:
1570 @lilypond[fragment,verbatim]
1572 \repeat volta 2 {c'4 d' e' f'}
1573 \alternative { {d'2 d'} {f' f} }
1576 Folded repeats look like this:
1579 @lilypond[fragment,verbatim]
1581 \repeat fold 2 {c'4 d' e' f'}
1582 \alternative { {d'2 d'} {f' f} }
1586 If you don't give enough alternatives for all of the repeats, then
1587 the first alternative is assumed to be repeated often enough to equal
1588 the specified number of repeats.
1590 @lilypond[fragment,verbatim]
1594 \repeat volta 4 { e | c2 d2 | e2 f2 | }
1595 \alternative { { g4 g g } { a | a a a a | b2. } }
1602 Notice that timing information is not remembered at the start of an
1603 alternative, so you have to reset timing information after a repeat,
1604 e.g. using a bar-check (See @ref{Bar check}), setting
1605 @code{Score.measurePosition} or entering @code{\partial}. Slurs or ties
1606 are also not repeated.
1608 It is possible to nest @code{\repeat}s, although this probably is only
1609 meaningful for unfolded repeats.
1611 Folded repeats offer little more over simultaneous music. However, it
1612 is to be expected that more functionality -- especially for the MIDI
1613 backend -- will be implemented at some point in the future.
1615 Volta repeats are printed over all staves in a score. You must turn them
1616 off explicitly, for example by doing
1618 \property Staff.VoltaBracket = \turnOff
1620 in all but the top staff.
1622 @node Manual repeat commands
1623 @subsection Manual repeat commands
1625 @cindex @code{repeatCommands}
1627 The property @code{repeatCommands} can be used to control the layout of
1628 repeats. Its value is a Scheme list of repeat commands, where each repeat
1636 @item (volta . @var{text})
1637 Print a volta bracket saying @var{text}.
1639 Stop a running volta bracket
1642 @lilypond[verbatim, fragment]
1644 \property Score.repeatCommands = #'((volta "93") end-repeat)
1646 \property Score.repeatCommands = #'((volta #f))
1651 Repeats brackets are @code{Staff.VoltaBracket} grobs.
1653 @node Tremolo repeats
1654 @subsection Tremolo repeats
1655 @cindex tremolo beams
1657 To place tremolo marks between notes, use @code{\repeat} with tremolo
1659 @lilypond[verbatim,center,singleline]
1661 \context Voice \notes\relative c' {
1662 \repeat "tremolo" 8 { c16 d16 }
1663 \repeat "tremolo" 4 { c16 d16 }
1664 \repeat "tremolo" 2 { c16 d16 }
1665 \repeat "tremolo" 4 c16
1670 Tremolo beams are @code{Voice.Beam} grobs. Single stem tremolos are
1671 @code{Voice.StemTremolo}.
1676 At present, the spacing between tremolo beams is not regular, since the
1677 spacing engine does not notice that not all notes are printed.
1679 @node Tremolo subdivisions
1680 @subsection Tremolo subdivisions
1681 @cindex tremolo marks
1682 @cindex @code{tremoloFlags}
1684 Tremolo marks can be printed on a single note by adding
1685 `@code{:}[@var{length}]' after the note. The length must be at least 8.
1686 A @var{length} value of 8 gives one line across the note stem. If the
1687 length is omitted, then then the last value (stored in
1688 @code{Voice.tremoloFlags}) is used.
1690 @lilypond[verbatim,fragment,center]
1691 c'2:8 c':32 | c': c': |
1697 Tremolos in this style do not carry over into the MIDI output.
1700 @node Measure repeats
1701 @subsection Measure repeats
1703 @cindex percent repeats
1704 @cindex measure repeats
1706 In the @code{percent} style, a note pattern can be repeated. It is
1707 printed once, and then the pattern is replaced with a special sign.
1708 Patterns of a one and two measures are replaced by percent-like signs,
1709 patterns that divide the measure length are replaced by slashes.
1711 @lilypond[verbatim,singleline]
1712 \context Voice { \repeat "percent" 4 { c'4 }
1713 \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 }
1717 The signs are represented by these grobs: @code{Voice.RepeatSlash} and
1718 @code{Voice.PercentRepeat} and @code{Voice.DoublePercentRepeat}.
1722 You can not nest percent repeats, e.g. by filling in the first measure
1723 with slashes, and repeating that measure with percents.
1725 @node Rhythmic music
1726 @section Rhythmic music
1733 @node Rhythmic staves
1734 @subsection Rhythmic staves
1736 Sometimes you might want to show only the rhythm of a melody. This can
1737 be done with the rhythmic staff. All pitches of notes on such a staff
1738 are squashed, and the staff itself looks has a single staff line:
1740 @lilypond[fragment,relative,verbatim]
1741 \context RhythmicStaff {
1743 c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
1750 @section Piano music
1752 Piano music is an odd type of notation. Piano staves are two normal
1753 staves coupled with a brace. The staves are largely independent, but
1754 sometimes voices can cross between the two staves. The
1755 @code{PianoStaff} is especially built to handle this cross-staffing
1756 behavior. In this section we discuss the @code{PianoStaff} and some
1757 other pianistic peculiarities.
1760 * Automatic staff changes::
1761 * Manual staff switches::
1764 * Voice follower lines::
1768 @c . {Automatic staff changes}
1769 @node Automatic staff changes
1770 @subsection Automatic staff changes
1771 @cindex Automatic staff changes
1773 Voices can switch automatically between the top and the bottom
1774 staff. The syntax for this is
1776 \autochange @var{contexttype} @var{musicexp}
1778 This will switch the interpretation context of @var{musicexp} between a
1779 @var{contexttype} named @code{up} and @code{down}. Typically, you use
1780 @code{Staff} for @var{contexttype}. The autochanger switches on basis
1781 of pitch (central C is the turning point), and it looks ahead skipping
1782 over rests to switch rests in advance.
1784 @lilypond[verbatim,singleline]
1785 \score { \notes \context PianoStaff <
1786 \context Staff = "up" {
1787 \autochange Staff \context Voice = VA < \relative c' {
1788 g4 a b c d r4 a g } > }
1789 \context Staff = "down" {
1795 Note how spacer rests are used to prevent the bottom staff from
1796 terminating too soon.
1799 @node Manual staff switches
1800 @subsection Manual staff switches
1802 @cindex manual staff switches
1803 @cindex staff switch, manual
1805 Voices can be switched between staves manually, using the following command:
1807 \translator Staff = @var{staffname} @var{music}
1809 The string @var{staffname} is the name of the staff. It switches the
1810 current voice from its current staff to the Staff called
1811 @var{staffname}. Typically @var{staffname} is @code{"up"} or
1814 The formal definition of this construct is obtuse, but for the sake of
1815 completeness we give it here.
1816 @cindex @code{\translator}
1818 \translator @var{contexttype} = @var{name}
1820 Formally, this construct is a music expression indicating
1821 that the context which is a direct child of the context of type
1822 @var{contexttype} should be shifted to a context of type
1823 @var{contexttype} and the specified name.
1831 Piano pedal instruction can be expressed using
1832 @code{\sustainDown}, @code{\sustainUp}, @code{\unaCorda},
1833 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp}.
1835 These identifiers are shorthands for spanner commands of the types
1836 @code{Sustain}, @code{UnaCorda} and @code{Sostenuto}:
1838 @lilypond[fragment,verbatim]
1839 c''4 \spanrequest \start "Sustain" c''4
1840 c''4 \spanrequest \stop "Sustain"
1843 The symbols that are printed can be modified by setting
1844 @code{pedal@var{X}Strings}, where @var{X} is one of the pedal
1845 types. Refer to the generated documentation of @rgrob{PianoPedal} for
1851 Currently, brackets are not supported, only text markings (i.e. `*Ped'
1857 @subsection Arpeggio
1860 @cindex broken arpeggio
1861 @cindex @code{\arpeggio}
1863 You can specify an arpeggio sign on a chord by attaching an
1864 @code{\arpeggio} to a note of the chord.
1867 @lilypond[fragment,relative,verbatim]
1868 \context Voice <c\arpeggio e g c>
1871 When an arpeggio crosses staves in piano music, you attach an arpeggio
1872 to the chords in both staves, and set
1873 @code{PianoStaff.connectArpeggios}.
1875 @lilypond[fragment,relative,verbatim]
1876 \context PianoStaff <
1877 \property PianoStaff.connectArpeggios = ##t
1878 \context Voice = one { <c'\arpeggio e g c> }
1879 \context Voice = other { \clef bass <c,,\arpeggio e g>}
1883 This command creates @code{Voice.Arpeggio} grobs. Cross staff arpeggios
1884 are @code{PianoStaff.Arpeggio}.
1888 It is not possible to mix connected arpeggios and unconnected arpeggios
1893 @node Voice follower lines
1894 @subsection Voice follower lines
1896 @cindex follow voice
1897 @cindex staff switching
1900 @cindex @code{followVoice}
1902 Whenever a voice switches to another staff a line connecting the notes
1903 can be printed automatically. This is enabled if the property
1904 @code{PianoStaff.followVoice} is set to true:
1906 @lilypond[fragment,relative,verbatim]
1907 \context PianoStaff <
1908 \property PianoStaff.followVoice = ##t
1909 \context Staff \context Voice {
1911 \translator Staff=two
1914 \context Staff=two {\clef bass \skip 1*2 }
1918 The associated grob is @code{Voice.VoiceFollower}.
1928 * Automatic syllable durations::
1934 @subsection Lyrics mode
1937 To print lyrics, you must first make a music expression from the lyric
1938 text. That music expression can be printed by selecting an appropriate
1942 @cindex @code{\lyrics}
1944 You can enter lyrics in a special input mode of LilyPond. This mode is
1945 called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
1946 The purpose of this mode is that you can enter lyrics as plain text,
1947 punctuation and accents without any hassle.
1949 Syllables are entered like notes, with pitches replaced by text. For
1950 example, @code{Twin- kle twin- kle} enters four syllables. Note that
1951 the hyphen has no special meaning for lyrics, and does not introduce
1954 Spaces can be introduced into a lyric either by using quotes:
1955 @code{"He could"4 not4} or by using an underscore without quotes:
1956 @code{He_could4 not4}. All unquoted underscores are converted to
1959 The precise definition of this mode can be found in @ref{Lyrics mode
1962 @c . {Printing lyrics}
1963 @node Printing lyrics
1964 @subsection Printing lyrics
1967 Lyrics are printed by interpreting them in the @code{Lyrics} context.
1969 @c Maybe more pedagogical to avoid \addlyrics in this first example? /MB
1971 @lilypond[verbatim,singleline]
1972 \addlyrics \notes \relative c' {
1974 \property Staff.automaticMelismata = ##t
1975 d'2 c4 b16 ( a g a b a b ) c a2
1976 b2 c4 b8 ( a16 g ) a4 g2 }
1977 \context Lyrics \lyrics {
1979 share the soft -- ware; }
1983 Notes and syllable durations are matched automatically. This is
1984 accomplished using @code{\addlyrics}, which is documented in
1985 @ref{Automatic syllable durations}. Setting @code{automaticMelismata} in
1986 the melody staff will cause slurs to be interpreted as melismata.
1988 The Lyric syllables are @code{LyricsVoice.LyricSyllable} grobs.
1991 @cindex lyric extender
1994 As you can see, extender lines are entered as @code{__}. This will
1995 create an extender, a line that extends over the entire duration of the
1996 lyric. This line will run all the way to the start of the next lyric,
1997 so you may want to shorten it by using a blank lyric (using @code{_}).
1998 The grob for this symbol is @code{LyricsVoice.LyricExtender}.
2003 If you want to have hyphens centered between syllables (rather than
2004 attached to the end of the first syllable) you can use the special
2005 `@code{-}@code{-}' lyric as a separate word between syllables. This
2006 will result in a hyphen whose length varies depending on the space
2007 between syllables. It will be centered between the syllables. The grob
2008 for this symbol is @code{LyricsVoice.LyricHyphen}.
2010 @cindex Lyric hyphen
2012 @node Automatic syllable durations
2013 @subsection Automatic syllable durations
2014 @cindex Automatic syllable durations
2016 @cindex automatic lyric durations
2017 @cindex @code{\addlyrics}
2019 If you have lyrics that are set to a melody, you can copy the rhythm
2020 of that melody into the lyrics using @code{\addlyrics}. The syntax for
2023 \addlyrics @var{musicexpr1 musicexpr2}
2026 Both @var{musicexpr1} and @var{musicexpr2} are interpreted, but every
2027 music event (``every syllable'') in @var{musicexpr2} is interpreted only
2028 when there are events in @var{musicexpr1}.
2030 @cindex @code{automaticMelismata}
2032 If the property @code{automaticMelismata} is set in the
2033 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
2036 @lilypond[verbatim,fragment]
2039 \property Voice.automaticMelismata = ##t
2040 c8 () cis d8. e16 f2
2042 \context Lyrics \lyrics {
2046 If you want the lyric lines to be above the melody staff, or in some
2047 other, more complex configuration, then build that configuration first
2048 using simultaneous music, and use @code{\addlyrics} after that.
2050 @lilypond[verbatim, singleline]
2052 \context Lyrics = LA { s1 }
2053 \context Staff = SA { s1 }
2055 \context Staff = SA \relative c' { c4 e g g }
2056 \context Lyrics = LA \lyrics { geen ge -- don -- der } >
2059 For @code{\addlyrics} you should use a single rhythm melody, and single
2060 rhythm lyrics (a constant duration is the obvious choice). If you do
2061 not, you can get undesired effects when using multiple stanzas:
2063 @lilypond[verbatim,fragment]
2066 c8 () cis d8. e16 f2
2068 \context Lyrics \lyrics
2073 It is valid (but probably not very useful) to use notes instead of
2074 lyrics for @var{musicexpr2}.
2077 @subsection More stanzas
2081 If you have multiple stanzas printed underneath each other, the vertical
2082 groups of syllables should be aligned around punctuation. LilyPond can
2083 do this if you tell it which lyric lines belong to which melody.
2085 To this end, give the Voice context an identity, and set the LyricsVoice
2086 to a name starting with that identity followed by a dash.
2087 In the following example, the Voice
2088 identity is @code{duet}, and the identities of the LyricsVoices are
2089 @code{duet-1} and @code{duet-2}.
2092 @lilypond[singleline,verbatim]
2095 \notes \relative c'' \context Voice = duet { \time 3/4
2097 \lyrics \context Lyrics <
2098 \context LyricsVoice = "duet-1" {
2099 \property LyricsVoice . stanza = "Bert"
2100 Hi, my name is bert. }
2101 \context LyricsVoice = "duet-2" {
2102 \property LyricsVoice . stanza = "Ernie"
2103 Ooooo, ch\'e -- ri, je t'aime. }
2108 You can add stanza numbers by setting @code{LyricsVoice.Stanza} (for the
2109 first system) and @code{LyricsVoice.stz} for the following
2110 systems. Notice how you must surround dots with spaces in @code{\lyrics}
2116 @cindex stanza numbering
2124 LilyPond has support for both entering and printing chords. Chords are
2125 characterized by a set of pitches. They are
2126 internally stored as simultaneous music expressions. This means you can
2127 enter chords by name and print them as note head, enter them as notes
2128 and print them as chord names, or (the most common case) enter them by
2129 name, and print them as name.
2132 @lilypond[verbatim,singleline]
2133 twoWays = \notes \transpose c'' {
2143 < \context ChordNames \twoWays
2144 \context Voice \twoWays > }
2147 Note that this example also shows that the chord printing routines do
2148 not attempt to be intelligent. If you enter @code{f bes d}, it does not
2149 interpret this as an inversion.
2153 * Printing named chords::
2158 @subsection Chords mode
2161 Chord mode is a mode where you can input sets of pitches using common
2162 names. It is introduced by the keyword @code{\chords}. It is similar
2163 to note mode, but words are also looked up in a chord modifier table
2164 (containing @code{maj}, @code{dim}, etc).
2166 Dashes and carets are used to indicate chord additions and subtractions,
2167 so articulation scripts can not be entered in Chord mode.
2169 The syntax for named chords is as follows:
2171 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
2174 @var{tonic} should be the tonic note of the chord, and @var{duration} is
2175 the chord duration in the usual notation. There are two kinds of
2176 modifiers. One type is formed by @emph{chord additions}. Additions are
2177 obtained by listing intervals separated by dots. An interval is written
2178 by its number with an optional @code{+} or @code{-} to indicate raising
2179 or lowering by half a step. Chord additions have two effects: they adds
2180 the specified interval and all lower odd numbered intervals to the
2181 chord, and they may lower or raise the specified interval.
2183 Throughout these examples, chords have been shifted around the staff
2184 using @code{\transpose}.
2186 @lilypond[fragment,verbatim]
2190 c:9 c:9-.5+.7+ c:3-.5-
2200 The second type of modifier that may appear after the @code{:} is a
2201 named modifier. Named modifiers are listed in the file
2202 @file{chord-modifiers.ly}. The available modifiers are @code{m} and
2203 @code{min} which lower the 3rd half a step, `@code{aug}' which
2204 raises the 5th, `@code{dim}' which lowers the 5th,
2205 `@code{maj}' which adds a raised 7th, and `@code{sus}'
2206 which replaces the 5th with a 4th.
2208 @lilypond[fragment,verbatim]
2211 c1:m c:min7 c:maj c:aug c:dim c:sus
2217 Chord subtractions are used to eliminate notes from a chord. The
2218 notes to be subtracted are listed after a @code{^} character,
2221 @lilypond[fragment,verbatim,center]
2230 Chord inversions can be specified by appending `@code{/}' and the name
2231 of a single note to a chord. In a chord inversion, the inverted note is
2232 transposed down until it is the lowest note in the chord. If the note
2233 is not in the chord, a warning will be printed.
2235 @lilypond[fragment,verbatim,center]
2245 Bass notes can be added by `@code{/+}' and
2246 the name of a single note to a chord. This has the effect of
2247 adding the specified note to the chord, lowered by an octave,
2248 so it becomes the lowest note in the chord.
2250 @lilypond[fragment,verbatim,center]
2261 Implementation details are quite gory. For example @code{c:4} not only
2262 adds a fourth, but also removes the third.
2265 @c . {Printing named chords}
2266 @node Printing named chords
2267 @subsection Printing named chords
2269 @cindex printing chord names
2272 @cindex @code{ChordNames}
2275 For displaying printed chord names, use the @code{ChordNames} context.
2276 The chords may be entered either using the notation described above, or
2277 directly using simultaneous music.
2279 @lilypond[verbatim,singleline]
2281 \chords {a1 b c} <d f g> <e g b>
2285 \context ChordNames \scheme
2286 \context Staff \transpose c'' \scheme
2291 You can make the chord changes stand out by setting
2292 @code{ChordNames.chordChanges} to true. This will only display chord
2293 names when there's a change in the chords scheme and at the start of a
2298 c1:m c:m \break c:m c:m d
2302 \context ChordNames {
2303 \property ChordNames.chordChanges = ##t
2305 \context Staff \transpose c'' \scheme
2309 LilyPond examines chords specified as lists of notes to determine a name
2310 to give the chord. LilyPond will not try to identify chord inversions or
2311 an added bass note, which may result in strange chord names when chords
2312 are entered as a list of pitches:
2314 @lilypond[verbatim,center,singleline]
2323 \context ChordNames \scheme
2324 \context Staff \scheme
2330 By default, a chord name system proposed by Harald Banter (See
2331 @ref{Literature}) is used. The system is very regular and predictable.
2332 Typical American style chord names may be selected by setting the
2333 @code{style} property of the @code{ChordNames.ChordName} grob to
2334 @code{'american}. Similarly @code{'jazz} selects Jazz chordnames.
2336 Routines that determine the names to be printed are written in Scheme,
2337 and may be customized by the user. The code can be found in
2338 @file{scm/chord-name.scm}. Here's an example showing the differences in
2342 @c maybe just junk verbatim option?
2343 @lilypond[verbatim,singleline]
2353 \context ChordNames = banter \scheme
2354 \context ChordNames = american {
2355 \property ChordNames.ChordName \override
2356 #'style = #'american \scheme }
2357 \context ChordNames = jazz {
2358 \property ChordNames.ChordName \override
2359 #'style = #'jazz \scheme }
2360 \context Staff \transpose c'' \scheme
2367 @section Writing parts
2369 Orchestral music involves some special notation, both in the full score,
2370 as in the individual parts. This section explains how to tackle common
2371 problems in orchestral music.
2378 * Instrument names::
2380 * Sound output for transposing instruments::
2381 * Multi measure rests::
2382 * Automatic part combining::
2383 * Hara kiri staves::
2386 @c . {Rehearsal marks}
2387 @node Rehearsal marks
2388 @subsection Rehearsal marks
2389 @cindex Rehearsal marks
2391 @cindex @code{\mark}
2392 @cindex @code{Mark_engraver}
2395 \mark @var{unsigned}
2400 This command prints a rehearsal mark above the system. You can provide
2401 a number, a string or a markup text as argument. If you use
2402 @code{\default}, the value of property @code{rehearsalMark} is used and
2403 automatically incremented.
2405 @lilypond[fragment,verbatim]
2411 c1 \mark #'(music "scripts-segno")
2416 The grob is @code{Score.RehearsalMark}. See
2417 @code{input/test/boxed-molecule.ly} if you need boxes around the marks.
2420 @subsection Bar numbers
2422 Bar numbers (grob: @code{BarNumber}) are printed at the start of the
2423 line. See @code{input/test/boxed-molecule.ly} for boxed bar numbers.
2427 It is not possible to have bar numbers printed at regular intervals
2430 @node Instrument names
2431 @subsection Instrument names
2433 You can specify an instrument name for a staff by setting
2434 @code{Staff.instrument} and @code{Staff.instr}. This will print a string
2435 before the start of the staff. For the first start, @code{instrument} is
2436 used, for the next ones @code{instr} is used.
2438 @lilypond[verbatim,singleline]
2439 \property Staff.instrument = "ploink " { c''4 }
2442 You can also use markup texts to construct more complicated instrument
2446 @lilypond[verbatim,singleline]
2448 '((font-relative-size . -2 ) (music "accidentals--1")))
2451 \property Staff.instrument = #`((kern . 0.5) (lines
2452 "2 Clarinetti" (columns " (B" ,text-flat ")")))
2460 When you put a name on a grand staff or piano staff the width of the
2461 brace is not taken into account. You must add extra spaces to the end of
2462 the name to avoid a collision.
2465 @subsection Transpose
2467 @cindex transposition of pitches
2468 @cindex @code{\transpose}
2470 A music expression can be transposed with @code{\transpose}. The syntax
2473 \transpose @var{pitch} @var{musicexpr}
2476 This means that middle C in @var{musicexpr} is transposed to
2479 @code{\transpose} distinguishes between enharmonic pitches: both
2480 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
2481 a tone. The first version will print sharps and the second version
2484 @lilypond[fragment,verbatim]
2487 { \key e \major c d e f }
2489 \transpose des'' { \key e \major c d e f }
2490 \transpose cis'' { \key e \major c d e f }
2494 If you want to use both @code{\transpose} and @code{\relative}, then
2495 you must use @code{\transpose} first. @code{\relative} will have no
2496 effect music that appears inside a @code{\transpose}.
2498 @node Sound output for transposing instruments
2499 @subsection Sound output transposing instruments
2501 When you want to make a MIDI file from a score containing transposed and
2503 instruments, you have to instruct LilyPond the pitch offset (in
2504 semitones) for the transposed instruments. This is done using the
2505 @code{transposing} property. It does not affect printed output.
2507 @cindex @code{transposing}
2510 \property Staff.instrument = #"Cl. in B-flat"
2511 \property Staff.transposing = #-2
2514 @c . {Multi measure rests}
2515 @node Multi measure rests
2516 @subsection Multi measure rests
2517 @cindex Multi measure rests
2521 Multi measure rests are entered using `@code{R}'. It is specifically
2522 meant for full bar rests and for entering parts: the rest can expand to
2524 rests, or it can be printed as a single multimeasure rest This expansion
2525 is controlled by the property @code{Score.skipBars}. If this is set to true,
2526 Lily will not expand empty measures, and the appropriate number is added
2529 @lilypond[fragment,verbatim]
2530 \time 3/4 r2. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
2533 Notice that the @code{R2.} is printed as a whole rest, centered in the
2536 @cindex whole rests for a full measure
2540 Currently, there is no way to automatically condense multiple rests into
2541 a single multimeasure rest.
2543 @cindex condensing rests
2545 @node Automatic part combining
2546 @subsection Automatic part combining
2547 @cindex automatic part combining
2548 @cindex part combiner
2551 Automatic part combining is used to merge two parts of music onto a
2552 staff in an intelligent way. It is aimed primarily at typesetting
2553 orchestral scores. When the two parts are identical for a period of
2554 time, only one is shown. In places where the two parts differ, they are
2555 typeset as separate voices, and stem directions are set automatically.
2556 Also, solo and @emph{a due} parts can be identified and marked.
2558 The syntax for part combining is
2561 \partcombine @var{context} @var{musicexpr1} @var{musicexpr2}
2563 where the pieces of music @var{musicexpr1} and @var{musicexpr2} will be
2564 combined into one context of type @var{context}. The music expressions
2565 must be interpreted by contexts whose names should start with @code{one}
2568 The most useful function of the part combiner is to combine parts into
2569 one voice, as common for wind parts in orchestral scores:
2571 @lilypond[verbatim,singleline,fragment]
2573 \context Voice=one \partcombine Voice
2574 \context Thread=one \relative c'' {
2577 \context Thread=two \relative c'' {
2583 Notice that the first @code{g} appears only once, although it was
2584 specified twice (once in each part). Stem, slur and tie directions are
2585 set automatically, depending whether there is a solo or unisono. The
2586 first part (with context called @code{one}) always gets up stems, and
2587 `solo', while the second (called @code{two}) always gets down stems and
2590 If you just want the merging parts, and not the textual markings, you
2591 may set the property @var{soloADue} to false.
2593 @lilypond[verbatim,singleline,fragment]
2595 \property Staff.soloADue = ##f
2596 \context Voice=one \partcombine Voice
2597 \context Thread=one \relative c'' {
2600 \context Thread=two \relative c'' {
2606 There are a number of other properties that you can use to tweak the
2607 behavior of part combining, refer to the automatically generated
2608 documentation of @reng{Thread_devnull_engraver} and
2609 @reng{Voice_devnull_engraver}. Look at the documentation of the
2610 responsible engravers, @code{Thread_devnull_engraver},
2611 @code{Voice_devnull_engraver} and @code{A2_engraver}.
2615 In @code{soloADue} mode, when the two voices play the same notes on and
2616 off, the part combiner may typeset @code{a2} more than once in a
2619 @lilypond[fragment,singleline]
2621 \context Voice=one \partcombine Voice
2622 \context Thread=one \relative c'' {
2625 \context Thread=two \relative c'' {
2631 @cindex @code{Thread_devnull_engraver}
2632 @cindex @code{Voice_engraver}
2633 @cindex @code{A2_engraver}
2635 @node Hara kiri staves
2636 @subsection Hara kiri staves
2638 In orchestral scores, staff lines that only have rests are usually removed.
2639 This saves some space. LilyPond also supports this through the hara
2640 kiri@footnote{Hara kiri, also called Seppuku, is the ritual suicide of
2641 the Japanese Samourai warriors.} staff. This staff commits suicide when
2642 it finds itself to be empty after the line-breaking process. It will
2643 not disappear when it contains normal rests, you must use multi measure
2646 The hara kiri staff is specialized version of the Staff context. It is
2647 available as the context identifier @code{\HaraKiriStaffContext}.
2648 Observe how the second staff in this example disappears in the second
2653 \notes \relative c' <
2654 \context Staff = SA { e4 f g a \break c1 }
2655 \context Staff = SB { c4 d e f \break R1 }
2659 \translator { \HaraKiriStaffContext }
2672 A @emph{custos} (plural: @emph{custodes}; latin word for `guard') is a
2673 staff context symbol that appears at the end of a staff line. It
2674 anticipates the pitch of the first note(s) of the following line and
2675 thus helps the player or singer to manage line breaks during
2676 performance, thus enhancing readability of a score.
2681 \property Staff.Custos \set #'style = #'mensural
2686 \consists Custos_engraver
2692 Custodes were frequently used in music notation until the 17th century.
2693 There were different appearances for different notation styles.
2694 Nowadays, they have survived only in special forms of musical notation
2695 such as via the @emph{editio vaticana} dating back to the beginning of
2698 For typesetting custodes, just put a @code{Custos_engraver} into the
2699 @code{StaffContext} when declaring the @code{\paper} block. In this
2700 block, you can also globally control the appearance of the custos symbol
2701 by setting the custos @code{style} property. Currently supported styles
2702 are @code{vaticana}, @code{medicaea}, @code{hufnagel} and
2709 \consists Custos_engraver
2710 Custos \override #'style = #'mensural
2715 The property can also be set locally, for example in a @code{\notes}
2720 \property Staff.Custos \override #'style = #'vaticana
2721 c'1 d' e' d' \break c' d' e' d'
2725 @c . {Tuning output}
2727 @section Tuning output
2729 LilyPond tries to take as much formatting as possible out of your
2730 hands. Nevertheless, there are situations where it needs some help, or
2731 where you want to override its decisions. In this section we discuss
2732 ways to do just that.
2734 Formatting is internally done by manipulating so called grobs (graphic
2735 objects). Each grob carries with it a set of properties (grob
2736 properties) specific to that object. For example, a stem grob has
2737 properties that specify its direction, length and thickness.
2739 The most direct way of tuning the output is by altering the values of
2740 these properties. There are two ways of doing that: first, you can
2741 temporarily change the definition of a certain type of grob, thus
2742 affecting a whole set of objects. Second, you can select one specific
2743 object, and set a grob property in that object.
2746 * Tuning groups of grobs ::
2747 * Tuning per grob ::
2755 @node Tuning groups of grobs
2756 @subsection Tuning groups of grobs
2758 @cindex grob description
2762 A grob definition is a Scheme association list, that is stored in a
2763 context property. By assigning to that property (using plain
2764 @code{\property}), you can change the resulting grobs.
2766 @lilypond[verbatim, fragment]
2767 c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
2770 The @code{\property} assignment effectively empties the definition of
2771 the Stem object. One of the effects is that the recipe of how it should be
2772 printed is erased, with the effect of rendering it invisible. The above
2773 assignment is available as a standard identifier, for the case that you
2777 \property Voice.Stem = \turnOff
2784 This mechanism is fairly crude, since you can only set, but not modify,
2785 the definition of a grob. For this reason, there is a more advanced
2788 The definition of a grob is actually a list of default grob
2789 properties. For example, the definition of the Stem grob (available in
2790 @file{scm/grob-description.scm}), defines the following values for
2795 (beamed-lengths . (0.0 2.5 2.0 1.5))
2796 (Y-extent-callback . ,Stem::height)
2800 You can add a property on top of the existing definition, or remove a
2801 property, thus overriding the system defaults:
2803 c'4 \property Voice.Stem \override #'thickness = #4.0
2804 c'4 \property Voice.Stem \revert #'thickness
2807 You should balance @code{\override} and @code{\revert}. If that's too
2808 much work, you can use the @code{\set} shorthand. It performs a revert
2809 followed by an override. The following example gives exactly the same
2810 result as the previous one.
2812 c'4 \property Voice.Stem \set #'thickness = #4.0
2813 c'4 \property Voice.Stem \set #'thickness = #0.8
2816 If you use @code{\set}, you must explicitly restore the default.
2819 Formally the syntax for these constructions is
2821 \property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
2822 \property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
2823 \property @var{context}.@var{grobname} \revert @var{symbol}
2825 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
2826 and @var{grobname} are strings and @var{value} is a Scheme expression.
2829 If you revert a setting which was not set in the first place, then it
2830 has no effect. However, if the setting was set as a system default, it
2831 may remove the default value, and this may give surprising results,
2832 including crashes. In other words, @code{\override} and @code{\revert},
2833 must be carefully balanced.
2835 These are examples of correct nesting of @code{\override}, @code{\set},
2838 A clumsy but correct form:
2840 \override \revert \override \revert \override \revert
2843 Shorter version of the same:
2845 \override \set \set \revert
2848 A short form, using only @code{\set}. This requires you to know the
2851 \set \set \set \set @var{to default value}
2854 If there is no default (i.e. by default, the grob property is unset),
2857 \set \set \set \revert
2860 For the digirati, the grob description is an Scheme association
2861 list. Since a Scheme list is a singly linked list, we can treat it as a
2862 stack, and @code{\override} and @code{\revert} are just push and pop
2863 operations. This pushing and popping is also used for overriding
2864 automatic beaming settings.
2868 LilyPond will hang or crash if @var{value} contains cyclic references.
2869 The backend is not very strict in type-checking grob properties. If you
2870 @code{\revert} properties that are expected to be set by default,
2873 Some grobs are created at the moment that their context is created. An
2874 example of such a grob is the staff itself (i.e. the horizontal lines).
2875 You can not change the appearance of the staff symbol by manipulating
2876 @code{\property Staff.StaffSymbol}. At the moment that @code{\property
2877 Staff} is interpreted, a Staff context is made, and the StaffSymbol is
2878 created before any @code{\override} is effective. You can deal with this
2879 either overriding properties in a @code{\translator} definition, or by
2880 using @code{\outputproperty}.
2885 @node Tuning per grob
2886 @subsection Tuning per grob
2888 @cindex \outputproperty
2890 A second way of tuning grobs is the more arcane @code{\outputproperty}
2891 feature. The syntax is as follows:
2893 \outputproperty @var{predicate} @var{symbol} = @var{value}
2895 Here @code{predicate} is a Scheme function taking a grob argument, and
2896 returning a boolean. This statement is processed by the
2897 @code{Output_property_engraver}. It instructs the engraver to feed all
2898 grobs that it sees to @var{predicate}. Whenever the predicate returns
2899 true, the grob property @var{symbol} will be set to @var{value}.
2901 You will need to combine this statement with @code{\context} to select
2902 the appropriate context to apply this to.
2904 Here are some random examples.
2907 In the following example, all note heads occurring at current staff
2908 level, are shifted up and right by setting their @code{extra-offset}
2911 @lilypond[fragment,verbatim,singleline]
2913 \context Staff \outputproperty
2914 #(make-type-checker 'note-head-interface)
2915 #'extra-offset = #'(0.5 . 0.75)
2919 @cindex @code{extra-offset}
2921 In this example, the predicate checks the @code{text} grob property, to
2922 shift only the `m.d.' text, but not the fingering instruction "2".
2923 @lilypond[verbatim,singleline]
2924 #(define (make-text-checker text)
2925 (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
2928 \notes\relative c''' {
2929 \property Voice.Stem \set #'direction = #1
2930 \outputproperty #(make-text-checker "m.d.")
2931 #'extra-offset = #'(-3.5 . -4.5)
2939 If possible, avoid this feature: the semantics are not very clean, and
2940 the syntax and semantics are up for rewrite.
2946 @subsection What to tune?
2948 This all tells you how to tune grobs, but you don't know what variables
2949 to set? The question is not answered in this part of the manual
2950 (although you may encounter some examples.).
2952 Grob properties are tied directly to the implementation of LilyPond, and
2953 they are thus a moving target. Documentation of such variables is in the
2954 automatically generated documentation. Description of properties are
2955 generated from the source code for each version. This documentation is
2956 therefore more up to date. It should be available from the same place
2957 where you got this manual.
2959 To decide how to tune a grob, you need to find the following information
2962 which grob to modify
2964 which property to modify
2966 which context the grob comes from.
2969 Included with the automatically generated documentation is a master list
2970 of grobs. Selecting a grob will take you to an overview of the
2971 properties available for that grob.
2973 There is also a master list of contexts. Selecting one takes you to an
2974 overview of that context which lists which grob types are created there.
2977 @node Font selection
2978 @subsection Font selection
2980 Most graphics in LilyPond are composed of characters of fonts. You can
2981 alter the characteristics of the font by setting certain grob
2982 properties. The mechanism that is used for this resembles La@TeX{}'s New
2983 Font Selection Scheme. Within this scheme, a font is entirely
2984 characterized by its font name.
2986 For each grob that uses fonts (in other words, each grob that supports
2987 @code{font-interface}) a font-name must be selected before it can be
2988 printed. The font name is selected by looking at a number of grob
2993 A symbol indicating the general class of the typeface. Supported are
2994 @code{roman} (Computer Modern), @code{braces} (for piano staff braces),
2995 @code{music} (the standard music font), @code{dynamic} (font for dynamic
2996 signs) and @code{typewriter}
2999 A symbol indicating the shape of the font, there are typically several
3000 font shapes available for each font family. Choices are @code{italic},
3001 @code{caps} and @code{upright}
3004 A symbol indicating the series of the font. There are typically several
3005 font series for each font family and shape. Choices are @code{medium}
3008 @item font-relative-size
3009 A number indicating the size relative the standard size. For example,
3010 with 20pt staff height, relative size -1 corresponds to 16pt staff
3011 height, and relative size +1 corresponds to 23 pt staff height.
3013 @item font-design-size
3014 A number indicating the design size of the font.
3016 This is a feature of the Computer Modern Font: each point size has a
3017 slightly different design. Smaller design sizes are relatively wider,
3018 which enhances readability. Scalable type faces such TrueType and Adobe
3019 Type1 usually come as ``one design fits all sizes''.
3022 The name of the font, without the design size, e.g. @code{cmr},
3023 @code{cmti}, etc. Setting this overrides font-family, font-shape and
3028 The font is selected by taking the first font that satisfies all
3029 qualifiers specified. You can override any of these fields through
3030 @code{\override} and @code{\revert}. The special value @code{*} matches
3031 any value for that qualifier.
3034 \property Lyrics.LyricText \override #'font-series = #'bold
3035 \property Lyrics.LyricText \override #'font-shape = #'*
3038 @cindex @code{font-style}
3040 There are also pre-cooked font selection qualifiers. These are selected
3041 through the grob property @code{font-style}. For example, the style
3042 @code{finger} selects family @code{number} and relative size @code{-3}.
3043 Styles available include @code{volta}, @code{finger}, @code{tuplet},
3044 @code{timesig}, @code{mmrest}, @code{script}, @code{large}, @code{Large}
3047 The style sheets and tables for selecting fonts are located in
3048 @file{scm/font.scm}. Refer to this file for more information.
3052 Relative size is not linked to any real size.
3054 There is no mechanism to select magnification of particular fonts,
3055 meaning that you don't have access to continuously scaled fonts. You
3056 can scale the entire output, of course, see @ref{Output scaling}.
3058 There is no style sheet provided for other fonts besides the @TeX{}
3061 @cindex font selection
3062 @cindex font magnification
3063 @cindex @code{font-interface}
3067 @subsection Text markup
3071 LilyPond has an internal mechanism to typeset texts. You can
3072 form text markup expressions by composing scheme expressions
3073 in the following way.
3075 @lilypond[verbatim, singleline]
3080 c^#'(italic "italic")
3081 d_#'((bold italic) "ff")
3083 f_#'(lines "one" (bold "two"))
3084 g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3"))
3088 Normally, the Scheme markup text is stored in the @code{text} property
3089 of a grob. Formally, it is defined as follows:
3092 text: string | (head? text+)
3093 head: markup | (markup+)
3094 markup-item: property | abbrev
3095 property: (@var{key} . @var{value})
3096 abbrev: @code{columns lines roman music bold italic named super sub}
3097 @code{overstrike text finger volta timesig mmrest mark script}
3098 @code{large Large dynamic}
3101 The markup is broken down and converted into a list of grob properties,
3102 which are prepended to the property list. The @var{key}-@var{value}
3103 pair is a grob property. A list of properties available is included in
3104 the generated documentation for @rint{Text_interface}.
3106 The following abbreviations are currently defined:
3109 horizontal mode: set all text on one line (default)
3111 vertical mode: set every text on a new line
3115 selects the Feta font (the standard font for music notation glyphs),
3116 and uses named lookup
3123 lookup by character name
3125 plain text lookup (by character value)
3131 the next text or character overstrikes this one
3133 select fingering number fontstyle
3135 select volta number fontstyle
3137 select time signature number fontstyle
3139 select multi measure rest number fontstyle
3141 select mark number fontstyle
3143 select scriptsize roman fontstyle
3145 select large roman fontstyle
3147 select Large roman fontstyle
3149 select dynamics fontstyle
3153 @cindex metronome mark
3155 One practical application of complicated markup is to fake a metronome
3159 #(define note '(columns
3160 (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
3161 #(define eight-note `(columns ,note ((kern . -0.1)
3162 (music ((raise . 3.5) "flags-u3")))))
3163 #(define dotted-eight-note
3164 `(columns ,eight-note (music "dots-dot")))
3167 \notes\relative c'' {
3168 a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64")
3174 TextScript \override #'font-shape = #'upright
3180 @node Invisible grobs
3181 @subsection Invisible grobs
3182 @cindex invisible grobs
3186 ben nog steeds niet kapot van de informatiedichtheid hier.
3192 You can imagine a number of situations where you would want to make
3193 certain grobs not show up in the output. There may be aesthetic
3194 reasons, to make the output resemble an (old) manuscript as close as
3195 possible, or to make lessons or exercises for students.
3197 Grobs can be made invisible in a number of ways:
3199 Here's an example with blanked-out notes and stems:
3200 @lilypond[singleline,verbatim]
3202 \property Voice.NoteHead \override
3204 \property Voice.Stem \override
3205 #'transparent = ##t }
3208 \property Voice.NoteHead \revert #'transparent
3209 \property Voice.Stem \revert #'transparent }
3212 \notes\relative c'' {
3214 a b c b \blanknotes c \unblanknotes d
3218 This method makes the grobs invisible but they still take the normal space.
3219 To remove all traces of the grob, you can redefine the function
3223 \notes\relative c'' {
3226 as bes c bes c d \break
3227 \property Staff.KeySignature \override #'molecule-callback = #'()
3230 \paper{linewidth=5.0\cm indent=0}
3234 A very rigorous way of removing grobs from the whole score is to remove
3235 the engraver that creates them. For example,
3237 @lilypond[singleline,verbatim]
3238 \score {\notes { c'4 d'8 e'8 g2 }
3239 \paper { \translator {
3241 \remove Stem_engraver
3247 @subsection Dirty tricks
3248 @cindex embedded tex
3250 It is possible to use @TeX{} commands in the strings, but this should be
3251 avoided because it makes it impossible for LilyPond to compute the
3252 exact length of the string, which may lead to collisions. Also, @TeX{}
3253 commands won't work with direct PostScript output (see @ref{PostScript
3256 @lilypond[fragment,relative,verbatim]
3257 a'^"3 $\\times$ \\`a deux"
3260 You can also use raw PostScript commands embedded in text scripts. This
3261 offers ultimate flexibility, but requires you to learn PostScript.
3262 Currently, embedded PostScript will @strong{not} work with direct
3263 PostScript output. Note that all dimensions that you use are in staff
3268 \notes \relative c'' {
3269 a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
3270 -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
3271 b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
3275 \paper { linewidth = 70*\staffspace }
3282 @section Page layout
3285 The page layout is the combined product of LilyPond formatting notation,
3286 and (La)@TeX{} putting the notation on a page, including page breaks.
3287 The part of LilyPond is documented here.
3301 @subsection Paper block
3304 The most important output definition is the @code{\paper} block, for
3305 music notation. The syntax is
3308 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
3311 where each of the items is one of
3314 @item An assignment.
3316 @item A context definition. See @ref{Interpretation context} for
3317 more information on context definitions.
3319 @item \stylesheet declaration. Its syntax is
3321 \stylesheet @var{alist}
3324 See @file{scm/font.scm} for details of @var{alist}.
3325 @item an @code{\elementdescriptions} declaration.
3327 \elementdescriptions @var{alist}
3329 See @file{scm/grob-description.scm} for details of
3330 @var{alist}. This command is not user-serviceable.
3334 @c . {Paper variables}
3335 @node Paper variables
3336 @subsection Paper variables
3337 @cindex Paper variables
3339 The paper block has some variables you may want to use or change:
3342 @cindex @code{indent}
3344 The indentation of the first line of music.
3345 @cindex @code{staffspace}
3347 @item @code{staffspace}
3348 The distance between two staff lines, calculated from the center
3351 @cindex @code{linewidth}
3352 @item @code{linewidth}
3353 Sets the width of the lines.
3355 If set to a negative value, a single unjustified line is produced.
3356 @c rename to singleLinePaper ?
3357 The shorthand @code{\singleLine} defines a default paper block that
3358 produces a single line.
3360 @cindex @code{textheight}
3362 @item @code{textheight}
3363 Sets the total height of the music on each page. Only used by
3366 @cindex @code{interscoreline}
3368 @item @code{interscoreline}
3369 Sets the spacing between systems. The default is 16pt.
3371 @cindex @code{interscorelinefill}
3373 @item @code{interscorelinefill}
3374 If set to a positive number, the distance between the score
3375 lines will stretch in order to fill the full page. In that
3376 case @code{interscoreline} specifies the minimum spacing.
3381 @cindex @code{stafflinethickness}
3383 @item @code{stafflinethickness}
3384 Determines the thickness of staff lines, and also acts as a scaling
3385 parameter for other line thicknesses.
3388 You may enter these dimension using units (@code{cm}, @code{in},
3389 @code{mm}, @code{pt}), or relative to another dimension
3391 linewidth = 20.0 * \staffspace
3398 @subsection Font size
3401 The Feta font provides musical symbols at six different sizes. These
3402 fonts are 11 point, 13 point, 16 point, 20 point,
3403 23 point, and 26 point. The point size of a font is the
3404 height of the five lines in a staff when displayed in the font.
3406 Definitions for these sizes are the files @file{paperSZ.ly}, where
3407 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include any of
3408 these files, the identifiers @code{paperEleven}, @code{paperThirteen},
3409 @code{paperSixteen}, @code{paperTwenty}, @code{paperTwentythree}, and
3410 @code{paperTwentysix} are defined respectively. The default
3411 @code{\paper} block is also set.
3413 The font definitions are generated using a Scheme function. For more
3414 details, see the file @file{scm/font.scm}.
3420 @subsection Paper size
3425 @cindex @code{papersize}
3427 To change the paper size, you must first set the
3428 @code{papersize} variable at top level. Set it to
3429 the strings @code{a4}, @code{letter}, or @code{legal}. After this
3430 specification, you must set the font as described above. If you want
3431 the default font, then use the 20 point font.
3435 \include "paper16.ly"
3438 The file @code{paper16.ly} will now include a file named @file{a4.ly}, which
3439 will set the paper variables @code{hsize} and @code{vsize} (used by
3444 @subsection Line break
3447 @cindex breaking lines
3449 Line breaks are normally computed automatically. They are chosen such
3450 that the resulting spacing has low variation, and looks neither cramped
3453 Occasionally you might want to override the automatic breaks; you can do
3454 this by specifying @code{\break}. This will force a line break at this
3455 point. Do remember that line breaks can only occur at places where there
3456 are bar lines. If you want to have a line break where there is no
3457 bar line, you can force an invisible bar line by entering @code{\bar
3458 ""}. Similarly, @code{\noBreak} forbids a line break at a certain point.
3460 @cindex @code{\penalty}
3462 The @code{\break} and @code{\noBreak} commands are defined in terms of
3463 the penalty command:
3468 This encourages or discourages LilyPond to make a line break at this
3473 The scaling of the @code{\penalty} argument is not well-defined. The
3474 command is rather kludgey, and slated for rewriting.
3478 @subsection Page break
3481 @cindex breaking pages
3483 Page breaks are normally computed by @TeX{}, so they are not under
3484 direct control of LilyPond. However, you can insert a commands into the
3485 @file{.tex} output to instruct @TeX{} where to break pages, by inserting
3486 the command @code{\newpage}
3487 @cindex @code{\newpage}
3493 @c why do so difficult?
3494 @c maybe should explain contents of between-system.ly,
3495 @c but not now, we're talking about page breaks here.
3497 @c details, see the example file @file{input/test/between-systems.ly}
3500 @c . {Output scaling}
3501 @node Output scaling
3502 @subsection Output scaling
3517 There is no mechanism to select magnification of particular fonts,
3518 meaning that you don't have access to continuously scaled fonts.
3522 @c . {Output formats}
3523 @node Output formats
3524 @section Output formats
3526 LilyPond can output processed music in different output formats.
3530 * PostScript output::
3532 * ASCIIScript output::
3536 @subsection TeX output
3539 LilyPond will use @TeX{} by default. Even if you want to produce
3540 PostScript output for viewing or printing, you should normally have
3541 LilyPond produce @TeX{} first. The .tex output must be processed by
3542 @TeX{} (@strong{not} La@TeX{}) to generate a .dvi. Then, @file{Dvips}
3543 is used to generate PostScript. Alternatively, @file{ly2dvi} can be
3544 used to generate the .dvi for you.
3548 Titling is not generated unless you use @file{ly2dvi}.
3551 @node PostScript output
3552 @subsection PostScript output
3553 @cindex PostScript output
3554 @cindex direct PostScript output
3556 LilyPond can produce PostScript directly, without going through @TeX{}.
3557 Currently, this is mainly useful if you cannot use TeX, because direct
3558 PostScript output has some problems; see Bugs below.
3561 $ lilypond -fps foo.ly
3562 GNU LilyPond 1.3.144
3563 Now processing: `foo.ly'
3565 Interpreting music...[3]
3566 Preprocessing elements...
3567 Calculating column positions...
3568 paper output to foo.ps...
3570 $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr
3576 Text font selection is broken.
3578 The .ps file does not contain the .pfa font files. To print a .ps
3579 created through direct postscript output, you should prepend the
3580 necessary .pfa files to LilyPond's .ps output, or upload them to the
3581 printer before printing.
3583 The line height calculation is broken, you must set @var{lineheight} in
3584 the paperblock if you have more than one staff in your score, e.g.
3589 % Set line height to 40 staff spaces
3595 @subsection Scheme output
3596 @cindex Scheme output
3598 In the typesetting stage, LilyPond builds a page description, which is
3599 then written to disk in postscript, @TeX{} or ASCII art. Before it is
3600 written, the page description is represented as Scheme expressions. You
3601 can also dump these Scheme expressions to a file, which may be
3602 convenient for debugging output routines. This is done with the Scheme
3606 $ lilypond -fscm foo.ly
3607 GNU LilyPond 1.3.144
3608 Now processing: `foo.ly'
3610 Interpreting music...[3]
3611 Preprocessing elements...
3612 Calculating column positions...
3613 paper output to foo.scm...
3616 ;;; Usage: guile -s x.scm > x.tex
3617 (primitive-load-path 'standalone.scm)
3621 $ guile -s foo.scm > foo.tex
3625 @node ASCIIScript output
3626 @subsection ASCIIScript output
3627 @cindex ASCIIScript output
3628 @cindex ascii script
3631 LilyPond can output ASCII Art. This is a two step process, LilyPond
3632 produces an ASCII description file, dubbed ASCIIScript (extension
3633 @file{.as}). ASCIIScript has a small and simple command set that
3634 includes font selection, character and string printing and line drawing
3635 commands. The program @file{as2text} is used to translate an .as file
3638 To produce ASCII Art, you must include an ASCII Art paper definition
3639 file in your .ly, one of:
3641 \include "paper-as5.ly"
3642 \include "paper-as9.ly"
3645 Here's an example use for ASCII Art output (the example file
3646 @file{as-email.ly} is included in the LilyPond distribution), the staff
3647 symbol has been made invisible:
3650 $ lilypond -fas as-email.ly
3651 GNU LilyPond 1.3.144
3652 Now processing: `as-email.ly'
3654 Interpreting music...[3]
3655 Preprocessing elements...
3656 Calculating column positions... [2]
3657 paper output to as-email.as...
3659 $ as2text as-email.as 2>/dev/null
3661 |/ |##|##| | | | | |
3662 /| | | | | |\ |\ |\ |\ |\ |
3663 / |_ 3 | | | | 5 | )| )| )| )| )|
3664 | /| \ 8 * * * | 8 * * * * * |
3674 The ASCII Art fonts are far from complete and not very well designed.
3675 It's easy to change the glyphs, though; if you think you can do better,
3676 have a look at @file{mf/*.af}.
3678 Lots of resizable symbols such as slurs, ties and tuplets are missing.
3680 The poor looks of most ASCII Art output and its limited general
3681 usefulness gives ASCII Art output a low priority; it may be
3682 dropped in future versions.
3689 LilyPond can produce MIDI output. The performance lacks lots of
3690 interesting effects, such as swing, articulation, slurring, etc., but it
3691 is good enough for proof-hearing the music you have entered. Ties,
3692 dynamics and tempo changes are interpreted.
3694 Dynamic marks, crescendi and decrescendi translate into MIDI volume
3695 levels. Dynamic marks translate to a fixed fraction of the available
3696 MIDI volume range, crescendi and decrescendi make the the volume vary
3697 linearly between their two extremities. The fractions be adjusted by
3698 overriding the @code{absolute-volume-alist} defined in
3699 @file{scm/midi.scm}.
3701 For each type of musical instrument (that MIDI supports), a volume range
3702 can be defined. This gives you basic equalizer control, which can
3703 enhance the quality of the MIDI output remarkably. You can add
3704 instruments and ranges or change the default settings by overriding the
3705 @code{instrument-equalizer-alist} defined in @file{scm/midi.scm}.
3707 Both loudness controls are combined to produce the final MIDI volume.
3712 It is currently not possible to use the percussion channel (generally
3713 channel 10 of a MIDI file).
3717 * MIDI instrument names::
3722 @subsection MIDI block
3726 The MIDI block is analogous to the paper block, but it is somewhat
3727 simpler. The @code{\midi} block can contain:
3731 @item a @code{\tempo} definition
3732 @item context definitions
3735 Assignments in the @code{\midi} block are not allowed.
3739 @cindex context definition
3741 Context definitions follow precisely the same syntax as within the
3742 \paper block. Translation modules for sound are called performers.
3743 The contexts for MIDI output are defined in @file{ly/performer.ly}.
3746 @node MIDI instrument names
3747 @subsection MIDI instrument names
3749 @cindex instrument names
3750 @cindex @code{Staff.midiInstrument}
3751 @cindex @code{Staff.instrument}
3753 The MIDI instrument name is set by the @code{Staff.midiInstrument}
3754 property or, if that property is not set, the @code{Staff.instrument}
3755 property. The instrument name should be chosen from the list in
3756 @ref{MIDI instruments}.
3760 If the selected string does not exactly match, then LilyPond uses the
3761 default (Grand Piano). It is not possible to select an instrument by
3774 @section Music entry
3782 When entering music with LilyPond, it is easy to introduce errors. This
3783 section deals with tricks and features that help you enter music, and
3784 find and correct mistakes.
3788 @subsection Relative
3790 @cindex relative octave specification
3792 Octaves are specified by adding @code{'} and @code{,} to pitch names.
3793 When you copy existing music, it is easy to accidentally put a pitch in
3794 the wrong octave and hard to find such an error. To prevent these
3795 errors, LilyPond features octave entry.
3797 @cindex @code{\relative}
3799 \relative @var{startpitch} @var{musicexpr}
3802 The octave of notes that appear in @var{musicexpr} are calculated as
3803 follows: If no octave changing marks are used, the basic interval
3804 between this and the last note is always taken to be a fourth or less
3805 (This distance is determined without regarding alterations; a
3806 @code{fisis} following a @code{ceses} will be put above the
3809 The octave changing marks @code{'} and @code{,} can be added to raise or
3810 lower the pitch by an extra octave. Upon entering relative mode, an
3811 absolute starting pitch must be specified that will act as the
3812 predecessor of the first note of @var{musicexpr}.
3814 Entering music that changes octave frequently is easy in relative mode.
3815 @lilypond[fragment,singleline,verbatim,center]
3821 And octave changing marks are used for intervals greater than a fourth.
3822 @lilypond[fragment,verbatim,center]
3824 c g c f, c' a, e'' }
3827 If the preceding item is a chord, the first note of the chord is used
3828 to determine the first note of the next chord. However, other notes
3829 within the second chord are determined by looking at the immediately
3832 @lilypond[fragment,verbatim,center]
3839 @cindex @code{\notes}
3841 The pitch after the @code{\relative} contains a note name. To parse
3842 the pitch as a note name, you have to be in note mode, so there must
3843 be a surrounding @code{\notes} keyword (which is not
3846 The relative conversion will not affect @code{\transpose},
3847 @code{\chords} or @code{\relative} sections in its argument. If you
3848 want to use relative within transposed music, you must place an
3849 additional @code{\relative} inside the @code{\transpose}.
3854 @subsection Bar check
3858 @cindex @code{barCheckNoSynchronize}
3862 Whenever a bar check is encountered during interpretation, a warning
3863 message is issued if it doesn't fall at a measure boundary. This can
3864 help you find errors in the input. Depending on the value of
3865 @code{barCheckNoSynchronize}, the beginning of the measure will be
3866 relocated, so this can also be used to shorten measures.
3868 A bar check is entered using the bar symbol, @code{|}:
3870 \time 3/4 c2 e4 | g2.
3873 @c . {Point and click}
3874 @node Point and click
3875 @subsection Point and click
3877 Point and click lets you find notes in the input by clicking on them in
3878 the Xdvi window. This makes it very easy to find input that causes some
3879 error in the sheet music.
3881 To use it, you need the following software
3883 @unnumberedsubsec Installation
3887 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,plain
3888 Xdvi} version 22.36 or newer.
3890 Note that most @TeX{} distributions ship with xdvik, which is a
3891 different and less well maintained program. To find out which xdvi you
3892 are running, try @code{xdvi --version} or @code{xdvi.bin --version}.
3896 Xdvi must be configured to find the TeX fonts and music
3897 fonts. Refer to the Xdvi documentation for more information.
3900 @unnumberedsubsec Using it
3902 Add one of these lines to the top of your .ly file. The first one is for
3903 line location only. The second one is more convenient, but requires
3904 patching @code{emacsclient} and @code{server.el}.
3907 #(set! point-and-click line-location)
3910 In the emacs startup file (usually @file{~/.emacs}), add the following
3915 Make sure that the environment variable @code{XEDITOR} is set
3918 emacsclient --no-wait +%l %f
3920 The second one, that also specifies the column, only works if you have
3921 patched your emacsclient and server, and have compiled your @code{.ly}
3922 file using the @code{line-column-location} setting.
3924 When viewing, control-mousebutton 1 will take you to the originating
3925 spot in the @file{.ly} file. Control-mousebutton 2 will show all
3929 @unnumberedsubsec Column location
3931 If you want emacs to jump to the exact spot (and not just the line) on a
3932 click, you must enable column positioning. To do so, you need to patch
3933 emacsclient. Apply @file{emacsclient.patch} (included with the source
3934 package) to @file{emacsclient.c} and @file{server.el} from the emacs
3935 source code. Recompile and stick the recompiled emacsclient into a bin
3936 directory, and put @file{server.el} into a elisp directory
3937 (e.g. @file{~/usr/share/emacs/}). Add the following to your @file{.emacs}
3938 init file, before invoking server-start.
3941 (setq load-path (cons "~/usr/share/emacs" load-path))
3944 Set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}
3946 At the top of the @code{ly} file, replace the @code{set!} line with the
3949 #(set! point-and-click line-column-location)
3952 One final hint: if you correct large files with point-and-click, then
3953 start correcting at the end of the file. When you start at the top, and
3954 insert one line, all subsequent locations will be off by a line.
3959 When you convert the @TeX{} file to PostScript using @code{dvips}, it
3960 will complain about not finding @code{src:X:Y} files. Those complaints
3961 are harmless, and can be ignored.
3963 @node Skipping corrected music
3964 @section Skipping corrected music
3966 The property @code{Score.skipTypesetting} can be used to switch on and
3967 off typesetting completely during the interpretation phase. When
3968 typesetting is switched off, the music is processed much more quickly.
3969 You can use this to skip over the parts of a score that you have already
3972 @lilypond[fragment,singleline,verbatim]
3973 \relative c'' { c8 d
3974 \property Score.skipTypesetting = ##t
3976 \property Score.skipTypesetting = ##f
3981 @node Interpretation context
3982 @section Interpretation context
3985 * Creating contexts::
3986 * Default contexts::
3987 * Context properties::
3988 * Engravers and performers::
3989 * Changing context definitions::
3990 * Defining new contexts::
3994 Interpretation contexts are objects that only exist during a run of
3995 LilyPond. During the interpretation phase of LilyPond (when it prints
3996 "interpreting music"), the music expression in a @code{\score} block is
3997 interpreted in time order. This is the same order that humans hear and
4000 During this interpretation, the interpretation context holds the
4001 state for the current point within the music. It contains information
4005 @item What notes are playing at this point?
4006 @item What symbols will be printed at this point?
4007 @item What is the current key signature, time signature, point within
4011 Contexts are grouped hierarchically: A @code{Voice} context is
4012 contained in a @code{Staff} context (because a staff can contain
4013 multiple voices at any point), a @code{Staff} context is contained in
4014 @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context.
4016 Contexts associated with sheet music output are called @emph{notation
4017 contexts}, those for sound output are called @emph{performance
4018 contexts}. The default definitions of the standard notation and
4019 performance contexts can be found in @file{ly/engraver.ly} and
4020 @file{ly/performer.ly}, respectively.
4023 @node Creating contexts
4024 @subsection Creating contexts
4026 @cindex @code{\context}
4027 @cindex context selection
4029 Contexts for a music expression can be selected manually, using the
4030 following music expression.
4033 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
4036 This instructs lilypond to interpret @var{musicexpr} within the context
4037 of type @var{contexttype} and with name @var{contextname}. If this
4038 context does not exist, it will be created.
4040 @lilypond[verbatim,singleline]
4042 \notes \relative c'' {
4043 c4 <d4 \context Staff = "another" e4> f
4049 In this example, the @code{c} and @code{d} are printed on the
4050 default staff. For the @code{e}, a context Staff called
4051 @code{another} is specified; since that does not exist, a new
4052 context is created. Within @code{another}, a (default) Voice context
4053 is created for the @code{e4}. When all music referring to a
4054 context is finished, the context is ended as well. So after the
4055 third quarter, @code{another} is removed.
4059 @node Default contexts
4060 @subsection Default contexts
4062 Most music expressions don't need an explicit @code{\context}
4063 declaration: they inherit the
4064 notation context from their parent. Each note is a music expression, and
4065 as you can see in the following example, only the sequential music
4066 enclosing the three notes has an explicit context.
4068 @lilypond[verbatim,singleline]
4069 \score { \notes \context Voice = goUp { c'4 d' e' } }
4072 There are some quirks that you must keep in mind when dealing with
4075 First, every top level music is interpreted by the Score context, in other
4076 words, you may think of @code{\score} working like
4079 \context Score @var{music}
4083 Second, contexts are created automatically to be able to interpret the
4084 music expressions. Consider the following example.
4086 @lilypond[verbatim, singleline]
4087 \score { \context Score \notes { c'4 ( d' )e' } }
4090 The sequential music is interpreted by the Score context initially
4091 (notice that the @code{\context} specification is redundant), but when a
4092 note is encountered, contexts are setup to accept that note. In this
4093 case, a Thread, Voice and Staff are created. The rest of the sequential
4094 music is also interpreted with the same Thread, Voice and Staff context,
4095 putting the notes on the same staff, in the same voice.
4097 This is a convenient mechanism, but do not expect opening chords to work
4098 without @code{\context}. For every note, a separate staff is
4101 @lilypond[verbatim, singleline]
4102 \score { \notes <c'4 es'> }
4105 Of course, if the chord is preceded by a normal note in sequential
4106 music, the chord will be interpreted by the Thread of the preceding
4108 @lilypond[verbatim,singleline]
4109 \score { \notes { c'4 <c'4 es'> } }
4114 @node Context properties
4115 @subsection Context properties
4117 Notation contexts have properties. These properties are from
4118 the @file{.ly} file using the following expression:
4119 @cindex @code{\property}
4121 \property @var{contextname}.@var{propname} = @var{value}
4124 Sets the @var{propname} property of the context @var{contextname} to the
4125 specified Scheme expression @var{value}. All @var{propname} and
4126 @var{contextname} are strings, which are typically unquoted.
4128 Properties that are set in one context are inherited by all of the
4129 contained contexts. This means that a property valid for the
4130 @code{Voice} context can be set in the @code{Score} context (for
4131 example) and thus take effect in all @code{Voice} contexts.
4133 Properties can be unset using the following expression:
4135 \property @var{contextname}.@var{propname} \unset
4138 @cindex properties, unsetting
4139 @cindex @code{\unset}
4141 This removes the definition of @var{propname} in @var{contextname}. If
4142 @var{propname} was not defined in @var{contextname} (but was inherited
4143 from a higher context), then this has no effect.
4148 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
4149 the inverse of @code{\property \set}.
4151 @node Engravers and performers
4152 @subsection Engravers and performers
4156 Basic building blocks of translation are called engravers; they are
4157 special C++ classes.
4161 @c . {Context definitions}
4162 @node Changing context definitions
4163 @subsection Changing context definitions
4165 @cindex context definition
4166 @cindex translator definition
4168 The most common way to define a context is by extending an existing
4169 context. You can change an existing context from the paper block, by
4170 first initializing a translator with an existing context identifier:
4174 @var{context-identifier}
4177 Then you can add and remove engravers using the following syntax:
4179 \remove @var{engravername}
4180 \consists @var{engravername}
4184 Here @var{engravername} is a string, the name of an engraver in the
4188 @lilypond[verbatim,singleline]
4192 \translator { \StaffContext
4193 \remove Clef_engraver
4199 You can also set properties in a translator definition. The syntax is as
4202 @var{propname} = @var{value}
4203 @var{propname} \set @var{grob-propname} = @var{pvalue}
4204 @var{propname} \override @var{grob-propname} = @var{pvalue}
4205 @var{propname} \revert @var{grob-propname}
4207 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
4208 and @code{pvalue} are Scheme expressions. These type of property
4209 assignments happen before interpretation starts, so a @code{\property}
4210 command will override any predefined settings.
4213 To simplify editing translators, all standard contexts have standard
4214 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
4215 @code{VoiceContext}, see @file{ly/engraver.ly}.
4217 @node Defining new contexts
4218 @subsection Defining new contexts
4220 If you want to build a context from scratch, you must also supply the
4221 following extra information:
4223 @item A name, specified by @code{\name @var{contextname}}.
4225 @item A cooperation module. This is specified by @code{\type
4232 \type "Engraver_group_engraver"
4235 \consists "Staff_symbol_engraver"
4236 \consists "Note_head_engraver"
4237 \consistsend "Axis_group_engraver"
4241 The argument of @code{\type} is the name for a special engraver that
4242 handles cooperation between simple engravers such as
4243 @code{Note_head_engraver} and @code{Staff_symbol_engraver}. Alternatives
4244 for this engraver are the following:
4246 @cindex @code{Engraver_group_engraver}
4247 @item @code{Engraver_group_engraver}
4248 The standard cooperation engraver.
4250 @cindex @code{Score_engraver}
4252 @item @code{Score_engraver}
4253 This is cooperation module that should be in the top level context,
4254 and only the top level context.
4256 @cindex @code{Grace_engraver_group}
4258 @item @code{Grace_engraver_group}
4259 This is a special cooperation module (resembling
4260 @code{Score_engraver}) that is used to create an embedded
4267 @item @code{\alias} @var{alternate-name}
4268 This specifies a different name. In the above example,
4269 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
4271 @item @code{\consistsend} @var{engravername}
4272 Analogous to @code{\consists}, but makes sure that
4273 @var{engravername} is always added to the end of the list of
4276 Some engraver types need to be at the end of the list; this
4277 insures they stay there even if a user adds or removes engravers.
4278 End-users generally don't need this command.
4280 @item @code{\accepts} @var{contextname}
4281 Add @var{contextname} to the list of contexts this context can
4282 contain in the context hierarchy. The first listed context is the
4283 context to create by default.
4285 @item @code{\denies}. The opposite of @code{\accepts}. Added for
4286 completeness, but is never used in practice.
4289 @item @code{\name} @var{contextname}
4290 This sets the type name of the context, e.g. @code{Staff},
4291 @code{Voice}. If the name is not specified, the translator won't do
4295 In the @code{\paper} block, it is also possible to define translator
4296 identifiers. Like other block identifiers, the identifier can only
4297 be used as the very first item of a translator. In order to define
4298 such an identifier outside of @code{\score}, you must do
4303 foo = \translator @{ @dots{} @}
4310 \translator @{ \foo @dots{} @}
4318 @cindex paper types, engravers, and pre-defined translators
4325 @c . {Syntactic details}
4326 @node Syntactic details
4327 @section Syntactic details
4328 @cindex Syntactic details
4330 This section describes details that were too boring to be put elsewhere.
4335 * Music expressions::
4336 * Manipulating music expressions::
4344 @subsection Top level
4347 This section describes what you may enter at top level.
4351 @subsubsection Score
4354 @cindex score definition
4356 The output is generated combining a music expression with an output
4357 definition. A score block has the following syntax:
4360 \score @{ @var{musicexpr} @var{outputdefs} @}
4363 @var{outputdefs} are zero or more output definitions. If none is
4364 supplied, the default @code{\paper} block will be added.
4368 @c . {Default output}
4369 @subsubsection Default output
4371 Default values for the @code{\paper} and @code{\midi} block are set by
4372 entering such a block at the top level.
4375 @subsubsection Header
4377 @cindex @code{\header}
4380 A header describes bibliographic information of the file's contents. It
4381 can also appear in a @code{\score} block. Tools like @code{ly2dvi} can
4382 use this information for generating titles. Key values that are used by
4383 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
4384 meter, arranger, piece and tagline.
4386 @cindex @code{ly2dvi}
4390 \header @{ @var{key1} = @var{val1}
4391 @var{key2} = @var{val2} @dots{} @}
4394 It is customary to put the @code{\header} at the top of the file.
4396 @subsubsection Default output
4398 A @code{\midi} or @code{\paper} block at top level sets the default
4399 paper block for all scores that lack an explicit paper block.
4403 @subsection Identifiers
4407 What has this section got to do with identifiers?
4408 It seems more appropriate in the introduction to Chapter 4,
4414 All of the information in a LilyPond input file, is internally
4415 represented as a Scheme value. In addition to normal Scheme data types
4416 (such as pair, number, boolean, etc.), LilyPond has a number of
4417 specialized data types,
4424 @item Translator_def
4428 @item Music_output_def
4429 @item Moment (rational number)
4432 LilyPond also includes some transient object types. Objects of these
4433 types are built during a LilyPond run, and do not `exist' per se within
4434 your input file. These objects are created as a result of your input
4435 file, so you can include commands in the input to manipulate them,
4436 during a lilypond run.
4439 @item Grob: short for Graphical object. See @ref{Grobs}.
4440 @item Molecule: device-independent page output object,
4441 including dimensions. Produced by some Grob functions
4443 @item Translator: object that produces audio objects or Grobs. This is
4444 not yet user accessible.
4445 @item Font_metric: object representing a font. (See @ref{Font metrics})
4450 @node Music expressions
4451 @subsection Music expressions
4453 @cindex music expressions
4455 Music in LilyPond is entered as a music expression. Notes, rests, lyric
4456 syllables are music expressions, and you can combine music expressions
4457 to form new ones, for example by enclosing a list of expressions in
4458 @code{\sequential @{ @}} or @code{< >}. In the following example, a
4459 compound expression is formed out of the quarter note @code{c} and a
4460 quarter note @code{d}:
4463 \sequential @{ c4 d4 @}
4466 @cindex Sequential music
4467 @cindex @code{\sequential}
4468 @cindex sequential music
4471 @cindex Simultaneous music
4472 @cindex @code{\simultaneous}
4474 The two basic compound music expressions are simultaneous and
4478 \sequential @code{@{} @var{musicexprlist} @code{@}}
4479 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
4481 For both, there is a shorthand:
4483 @code{@{} @var{musicexprlist} @code{@}}
4487 @code{<} @var{musicexprlist} @code{>}
4489 for simultaneous music.
4490 In principle, the way in which you nest sequential and simultaneous to
4491 produce music is not relevant. In the following example, three chords
4492 are expressed in two different ways:
4494 @lilypond[fragment,verbatim,center]
4495 \notes \context Voice {
4496 <a c'> <b d' > <c' e'>
4497 < { a b c' } { c' d' e' } >
4502 Other compound music expressions include
4505 \transpose @var{pitch} @var{expr}
4506 \apply @var{func} @var{expr}
4507 \context @var{type} = @var{id} @var{expr}
4508 \times @var{fraction} @var{expr}
4512 @c . {Manipulating music expressions}
4513 @node Manipulating music expressions
4514 @subsection Manipulating music expressions
4516 The @code{\apply} mechanism gives you access to the internal
4517 representation of music. You can write Scheme-functions that operate
4518 directly on it. The syntax is
4520 \apply #@var{func} @var{music}
4522 This means that @var{func} is applied to @var{music}. The function
4523 @var{func} should return a music expression.
4525 This example replaces the text string of a script. It also shows a dump
4526 of the music it processes, which is useful if you want to know more
4527 about how music is stored.
4529 @lilypond[verbatim,singleline]
4530 #(define (testfunc x)
4531 (if (equal? (ly-get-mus-property x 'text) "foo")
4532 (ly-set-mus-property x 'text "bar"))
4534 (ly-set-mus-property x 'elements
4535 (map testfunc (ly-get-mus-property x 'elements)))
4540 \apply #testfunc { c'4_"foo" }
4544 For more information on what is possible, see the automatically
4545 generated documentation.
4548 Directly accessing internal representations is dangerous: the
4549 implementation is subject to changes, so you should avoid this feature
4552 A final example is a function that reverses a piece of music in time:
4554 @lilypond[verbatim,singleline]
4555 #(define (reverse-music music)
4556 (let* ((elements (ly-get-mus-property music 'elements))
4557 (reversed (reverse elements))
4558 (span-dir (ly-get-mus-property music 'span-direction)))
4559 (ly-set-mus-property music 'elements reversed)
4561 (ly-set-mus-property music 'span-direction (- span-dir)))
4562 (map reverse-music reversed)
4565 music = \notes { c'4 d'4( e'4 f'4 }
4567 \score { \context Voice {
4569 \apply #reverse-music \music
4574 More examples are given in the distributed example files in
4577 @c . {Span requests}
4583 @subsubsection Span requests
4584 @cindex Span requests
4586 Notational constructs that start and end on different notes can be
4587 entered using span requests. The syntax is as follows:
4591 \spanrequest @var{startstop} @var{type}
4595 @cindex @code{\start}
4596 @cindex @code{\stop}
4598 This defines a spanning request. The @var{startstop} parameter is either
4599 -1 (@code{\start}) or 1 (@code{\stop}) and @var{type} is a string that
4600 describes what should be started. Much of the syntactic sugar is a
4601 shorthand for @code{\spanrequest}, for example,
4603 @lilypond[fragment,verbatim,center]
4604 c'4-\spanrequest \start "slur"
4605 c'4-\spanrequest \stop "slur"
4608 Among the supported types are @code{crescendo}, @code{decrescendo},
4609 @code{beam}, @code{slur}. This is an internal command. Users are
4610 encouraged to use the shorthands which are defined in the initialization
4611 file @file{spanners.ly}.
4616 @subsection Assignments
4619 Identifiers allow objects to be assigned to names during the parse
4620 stage. To assign an identifier, you use @var{name}@code{=}@var{value}
4621 and to refer to an identifier, you precede its name with a backslash:
4622 `@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
4623 the input-types listed above. Identifier assignments can appear at top
4624 level in the LilyPond file, but also in @code{\paper} blocks.
4626 An identifier can be created with any string for its name, but you will
4627 only be able to refer to identifiers whose names begin with a letter,
4628 being entirely alphabetical. It is impossible to refer to an identifier
4629 whose name is the same as the name of a keyword.
4631 The right hand side of an identifier assignment is parsed completely
4632 before the assignment is done, so it is allowed to redefine an
4633 identifier in terms of its old value, e.g.
4639 When an identifier is referenced, the information it points to is
4640 copied. For this reason, an identifier reference must always be the
4641 first item in a block.
4645 \paperIdent % wrong and invalid
4649 \paperIdent % correct
4654 @c . {Lexical modes}
4656 @subsection Lexical modes
4657 @cindex Lexical modes
4660 @cindex @code{\notes}
4661 @cindex @code{\chords}
4662 @cindex @code{\lyrics}
4664 To simplify entering notes, lyrics, and chords, LilyPond has three
4665 special input modes in addition to the default mode: note, lyrics and
4666 chords mode. These input modes change the way that normal, unquoted
4667 words are interpreted: for example, the word @code{cis} may be
4668 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
4669 major triad respectively.
4671 A mode switch is entered as a compound music expression
4673 @code{\notes} @var{musicexpr}
4674 @code{\chords} @var{musicexpr}
4675 @code{\lyrics} @var{musicexpr}.
4678 In each of these cases, these expressions do not add anything to the
4679 meaning of their arguments. They just instruct the parser in what mode
4680 to parse their arguments. The modes are treated in more detail in
4681 @ref{Lyrics} and @ref{Chords}.
4683 Different input modes may be nested.
4687 @subsection Ambiguities
4692 The grammar contains a number of ambiguities. We hope to resolve them at
4696 @item The assignment
4701 is interpreted as the string identifier assignment. However,
4702 it can also be interpreted as making a string identifier @code{\foo}
4703 containing @code{"bar"}, or a music identifier @code{\foo}
4704 containing the syllable `bar'.
4706 @item If you do a nested repeat like
4718 then it is ambiguous to which @code{\repeat} the
4719 @code{\alternative} belongs. This is the classic if-then-else
4720 dilemma. It may be solved by using braces.
4722 @item The parser is not sophisticated enough to distinguish at the
4724 @code{c4*2 / 3 } and @code{c4*2 / g} (in chord mode).
4731 @c . {Lexical details}
4732 @node Lexical details
4733 @section Lexical details
4735 Even more boring details, now on lexical side of the input parser.
4746 * Version information::
4751 @subsection Comments
4754 @cindex block comment
4755 @cindex line comment
4759 A one line comment is introduced by a @code{%} character.
4760 Block comments are started by @code{%@{} and ended by @code{%@}}.
4761 They cannot be nested.
4764 @subsection Direct Scheme
4768 @cindex Scheme, in-line code
4771 LilyPond contains a Scheme interpreter (the GUILE library) for
4772 internal use. In some places, Scheme expressions also form valid syntax:
4773 wherever it is allowed,
4777 evaluates the specified Scheme code. Example:
4779 \property Staff.TestObject \override #'foobar = #(+ 1 2)
4781 @code{\override} expects two Scheme expressions, so there are two Scheme
4782 expressions. The first one is a symbol (@code{foobar}), the second one
4783 an integer (namely, 3).
4785 In-line scheme may be used at the top level. In this case the result is
4788 Scheme is a full-blown programming language, and a full discussion is
4789 outside the scope of this document. Interested readers are referred to
4790 the website @uref{http://www.schemers.org/} for more information on
4795 @subsection Keywords
4799 Keywords start with a backslash, followed by a number of lower case
4800 alphabetic characters. These are all the keywords.
4803 apply arpeggio autochange spanrequest commandspanrequest
4804 simultaneous sequential accepts alternative bar breathe
4805 char chordmodifiers chords clef cm consists consistsend
4806 context denies duration dynamicscript elementdescriptions
4807 font grace header in lyrics key mark pitch
4808 time times midi mm name pitchnames notes outputproperty
4809 override set revert partial paper penalty property pt
4810 relative remove repeat addlyrics partcombine score
4811 script stylesheet skip textscript tempo translator
4816 @subsection Integers
4824 Formed from an optional minus sign followed by digits. Arithmetic
4825 operations cannot be done with integers, and integers cannot be mixed
4830 @cindex real numbers
4836 Formed from an optional minus sign and a sequence of digits followed
4837 by a @emph{required} decimal point and an optional exponent such as
4838 @code{-1.2e3}. Reals can be built up using the usual operations:
4839 `@code{+}', `@code{-}', `@code{*}', and
4840 `@code{/}', with parentheses for grouping.
4848 A real constant can be followed by one of the dimension keywords:
4849 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
4850 points, inches and centimeters, respectively. This converts the number
4851 a number that is the internal representation of that dimension.
4859 Begins and ends with the @code{"} character. To include a @code{"}
4860 character in a string write @code{\"}. Various other backslash
4861 sequences have special interpretations as in the C language. A string
4862 that contains no spaces can be written without the quotes. Strings can
4863 be concatenated with the @code{+} operator.
4867 @subsection Main input
4870 @cindex @code{\maininput}
4872 The @code{\maininput} command is used in init files to signal that the
4873 user file must be read. This command cannot be used in a user file.
4875 @node File inclusion
4876 @subsection File inclusion
4877 @cindex @code{\include}
4879 \include @var{filename}
4882 Include @var{filename}. The argument @var{filename} may be a quoted string (an
4883 unquoted string will not work here!) or a string identifier. The full
4884 filename including the @file{.ly} extension must be given,
4887 @node Version information
4888 @subsection Version information
4889 @cindex @code{\version}
4891 \version @var{string}
4894 Specify the version of LilyPond that a file was written for. The
4895 argument is a version string in quotes, for example @code{"1.2.0"}.
4896 This is used to detect invalid input, and to aid
4897 @code{convert-ly} a tool that automatically upgrades input files. See
4898 See @ref{convert-ly} for more information on @code{convert-ly}.
4907 @c .{Local emacs vars}
4910 @c minor-mode: font-lock
4911 @c minor-mode: outline
4912 @c outline-layout: (-1 : 0)
4913 @c outline-use-mode-specific-leader: "@c \."
4914 @c outline-primary-bullet: "{"
4915 @c outline-stylish-prefixes: nil
4916 @c outline-override-protect: t