3 @c - Reinsert subsection commands that were lost in the
4 @c ancient conversion from YODL! /MB
5 @c - Restructure! Separate internal commands from user level commands. /MB
6 @c - Add some words about Guile. /MB
7 @c - Fix indexing (keyindex) so it doesn't add line breaks /MB
9 @node Reference Manual, , , Top
10 @chapter Reference Manual
14 * Top level:: Top level
15 * Pitch names:: Pitch names
16 * Lexical conventions:: Lexical conventions
17 * Other languages:: Note names in various languages
18 * Lexical modes:: modes
20 * Music expressions:: Music expressions
21 * Atomic music expressions:: Atomic music expressions
22 * Note specification:: notedesc
24 * Manual beams:: Manual beam
25 * stem tremolo:: tremolo
26 * Compound music expressions:: Compound music expressions
29 * transpose:: transpose
30 * Ambiguities:: Ambiguities
31 * Notation conversion specifics:: Notation conversion specifics
33 * lyricprint:: lyricprint
34 * Notation Contexts:: Notation Contexts
35 * Properties:: Changing formatting
36 * Notation output definitions:: Notation output definitions
38 * Paper variables:: papervars
39 * contextdefs:: contextdefs
40 * Sound output:: Sound output
42 * Grobs:: Graphical objects
43 * Molecule:: Molecules
44 * Pre-defined Identifiers:: Pre-defined Identifiers
45 @c May be fragile. Better make single link to generated doco?
46 * Interpretation contexts:(lilypond-internals)LilyPond interpretation contexts.
47 * Engravers:(lilypond-internals)LilyPond engravers.
48 * Backend:(lilypond-internals)LilyPond backend.
53 @node Overview, , , Reference Manual
56 This document@footnote{This document has been revised for LilyPond 1.2.}
57 describes the the GNU LilyPond input format This format represents a
58 piece of music in an elegant way, but contains enough information for
59 both automatic typesetting and automatic performances.
61 LilyPond input can be classified into three types:
63 @item musical expressions: a musical expression is some combination of
65 @item output definitions: recipes for translating those musical
66 expressions into performances (MIDI) or graphics (eg. PostScript).
68 @item declarations: by declaring and naming musical expressions, you
69 can enter and edit them in manageable chunks.
74 @node Top level, , , Reference Manual
79 This section describes what you may enter at top level.
83 @cindex score definition
85 The output is generated combining a music expression with an output
86 definition. A score block has the following syntax:
89 \score @{ @var{musicexpr} @var{outputdefs} @}
92 @var{outputdefs} are zero or more output definitions. If no output
93 definition is supplied, the default @code{\paper} block will be added.
102 \header @{ @var{key1} = @var{val1};
103 @var{key2} = @var{val2}; @dots{} @}
106 A header describes the file's contents. It can also appear in a
107 @code{\score} block. Tools like @code{ly2dvi}@indexcode{ly2dvi} can use this
108 information for generating titles. Key values that are used by
109 @code{ly2dvi} are: title, subtitle, composer, opus, poet, instrument,
110 metre, arranger, piece and tagline.
112 It is customary to put the @code{\header} at the top of the file.
115 @node Pitch names, , , Reference Manual
117 Note names and chord modifiers can be customised for nationalities.
118 languages and conventions. The syntax is as follows.
120 \pitchnames @keyindex{pitchnames} @var{scheme-alist}
121 \chordmodifiers@keyindex{chordmodifiers} @var{scheme-alist}
124 See @file{ly/nederlands.ly} and @file{ly/chord-modifiers.ly} for
125 specific examples how to do this. tables can be tailored specified
126 using. Some national note names have been provided, see @ref{Other
129 A @code{\paper} block at top level sets the default paper block. A
130 @code{\midi} block at top level works similarly.
134 Identifier assignments may appear at top level. Semicolons are
135 forbidden after top level assignments.
139 @node Lexical conventions, , , Reference Manual
140 @section Lexical conventions
142 @cindex lexical conventions
146 @unnumberedsubsec Comments
153 A one line comment is introduced by a `@code{%}' character.
154 Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
155 They cannot be nested.
157 @unnumberedsubsec Scheme
161 LilyPond contains a Scheme interpreter (the GUILE library) for
162 internal use. The interpreter is accessed by the pound sign:
164 Whereever the syntax allows Scheme expressions, you may enter one as
170 Evaluates the specified Scheme code. If this is used at toplevel, then
171 the result is discarded. Example:
173 \property Staff.TestObject \override #'symbol = #(+ 1 2)
176 (in this case, @code{\override} expects two Scheme expressions.
178 [refer appendix/ online intro on Scheme]
180 @unnumberedsubsec Keywords
184 Keywords start with a backslash, followed by a number of lower case
185 alphabetic characters. These are all the keywords.
188 apply arpeggio autochange spanrequest commandspanrequest
189 simultaneous sequential accepts alternative bar breathe
190 char chordmodifiers chords clef cm consists consistsend
191 context denies duration dynamicscript elementdescriptions
192 font grace header in lyrics key mark musicalpitch
193 time times midi mm name pitchnames notes outputproperty
194 override set revert partial paper penalty property pt
195 relative remove repeat addlyrics partcombine score
196 script stylesheet skip textscript tempo translator
200 @unnumberedsubsec Integers
204 Formed from an optional minus sign followed by digits. Arithmetic
205 operations cannot be done with integers, and integers cannot be mixed
208 @unnumberedsubsec Reals
213 Formed from an optional minus sign and a sequence of digits followed
214 by a @emph{required} decimal point and an optional exponent such as
215 @code{-1.2e3}. Reals can be built up using the usual operations:
216 `@code{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and
217 `@code{/}@indexcode{/}', with parentheses for grouping.
219 A real constant can be followed by one of the dimension
222 @code{\mm}@keyindex{mm},
223 @code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or
224 @code{\cm}@keyindex{cm}, for millimeters, points, inches and
225 centimeters, respectively. This converts the number to a real that
226 is the internal representation of dimensions.
232 Begins and ends with the `@code{"}' character. To include a `@code{"}'
233 character in a string write `@code{\"}'. Various other backslash
234 sequences have special interpretations as in the C language. A string
235 that contains no spaces can be written without the quotes. See
236 @ref{Lexical modes} for details on unquoted strings; their interpretation varies
237 depending on the situation. Strings can be concatenated with the
240 The tokenizer accepts the following commands. They have no grammatical
241 function, hence they can appear anywhere in the input.
244 \maininput@keyindex{maininput}
247 This command is used in init files to signal that the user file must
248 be read. This command cannot be used in a user file.
250 @unnumberedsubsec file inclusion
253 \include@keyindex{include} @var{file}
256 Include @var{file}. The argument @var{file} may be a quoted string (an
257 unquoted string will not work here!) or a string identifier. The full
258 filename including the @file{.ly} extension must be given,
260 @unnumberedsubsec Version information
263 \version@keyindex{version} @var{string} ;
266 Specify the version of LilyPond that a file was written for. The
267 argument is a version string in quotes, for example @code{"1.2.0"}.
268 This is used to detect invalid input, and to aid
269 @code{convert-ly}, a tool that automatically upgrades input files.
273 @cindex other languages
275 @node Other languages, , , Reference Manual
277 Note name definitions have been provided in various languages.
278 Simply include the language specific init file. For example:
279 `@code{\include "english.ly"}'. The available language files and the
280 names they define are:
283 Note Names sharp flat
284 nederlands.ly c d e f g a bes b -is -es
285 english.ly c d e f g a bf b -s/-sharp -f/-flat
286 deutsch.ly c d e f g a b h -is -es
287 norsk.ly c d e f g a b h -iss/-is -ess/-es
288 svenska.ly c d e f g a b h -iss -ess
289 italiano.ly do re mi fa sol la sib si -d -b
290 catalan.ly do re mi fa sol la sib si -d/-s -b
293 Pitch names can be redefined using the @code{\pitchnames} command, see
296 @cindex Lexical Modes
300 @node Lexical modes, , , Reference Manual
302 To simplify entering notes, lyrics, and chords, @emph{Lilypond} has three
303 special input modes on top of the default mode. In each mode, words
304 are identified on the input. If @code{"word"} is encountered, it is
305 treated as a string. If @code{\word} is encountered, it is treated as
306 a keyword or as an identifier. The behavior of the modes differs in
307 two ways: Different modes treat unquoted words differently, and
308 different modes have different rules for deciding what is a word.
314 At the start of parsing, @emph{Lilypond} is in Normal mode. In Normal
315 mode, a word is an alphabetic character followed by alphanumeric
316 characters. If @code{word} is encountered on the input it is
322 Note mode is introduced by the keyword
323 @code{\notes}@keyindex{notes}. In Note mode, words can only
324 contain alphabetic characters. If @code{word} is encountered,
325 LilyPond first checks for a notename of @code{word}. If no
326 notename is found, then @code{word} is treated as a string.
328 Since combinations of numbers and dots are used for indicating
329 durations, it is not possible to enter real numbers in this mode.
334 Chord mode is introduced by the keyword
335 @code{\chords}@keyindex{chords}. It is similar to Note mode, but
336 words are also looked up in a chord modifier table (containing
337 @code{maj}, @code{dim}, etc).
339 Since combinations of numbers and dots are used for indicating
340 durations, you can not enter real numbers in this mode. Dashes
341 and carets are used to indicate chord additions and subtractions,
342 so scripts can not be entered in Chord mode.
347 Lyrics mode is introduced by the keyword
348 @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it
349 easy to include punctuation and diacritical marks in words. A
350 word in Lyrics mode begins with: an alphabetic character,
351 `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the
352 control characters @code{^A} through @code{^F}, @code{^Q} through
353 @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code
354 over 127, or a two-character combination of a backslash followed
355 by one of `@code{`}', `@code{'}', `@code{"}', or
356 `@code{^}'.@footnote{The purpose of Lyrics mode is that you can
357 enter lyrics in @TeX{} format or a standard encoding without
358 needing quotes. The precise definition of this mode indeed is
359 ludicrous. This will remain so until the authors of LilyPond
360 acquire a deeper understanding of character encoding, or someone
361 else steps up to fix this.}
363 Subsequent characters of a word can be any character that is not
364 a digit and not white space. One important consequence of this
365 is that a word can end with `@code{@}}', which may be confusing if
366 you thought the closing brace was going to terminate Lyrics
367 mode.@footnote{LilyPond will issue a warning, though.} Any
368 `@code{_}' character which appears in an unquoted word is
369 converted to a space. This provides a mechanism for introducing
370 spaces into words without using quotes. Quoted words can also be
371 used in Lyrics mode to specify words that cannot be written with
372 the above rules. Here are some examples. Not all of these words
373 are printable by @TeX{}.
377 2B_||_!2B % not a word because it starts with a digit
378 ``Hello'' % not a word because it starts with `
379 _ _ _ _ % 4 words, each one a space
382 Since combinations of numbers and dots are used for indicating
383 durations, you can not enter real numbers in this mode.
386 [todo: include short table showign differences]
388 @node Types, , , Reference Manual
393 [say something about types]
395 All of the information in a LilyPond input file, is represented as a
396 Scheme value. In addition to normal Scheme data types (such as pair,
397 number, boolean, etc.), LilyPond has a number of specialized data types,
402 @item Music: see @ref{Music expressions}
404 @item Translator_def:
405 See section @ref{contextdefs} for more information
410 @item Music_output_def (TODO: this is not really a Scheme object
411 yet. Nevertheless, you can use identifiers to make references to them )
412 @item Moment (rational number)
415 LilyPond also includes some transient object types. Objects of these
416 types are built during a LilyPond run, and do not `exist' per se within
417 your input file. These objects are created as a result of your input
418 file, so you can include commands in the input to manipulate them,
419 during a lilypond run.
422 @item Grob: short for Graphical object. See @ref{Grobs}.
423 @item Molecule: device-independent page output object,
424 including dimensions. Produced by some Grob functions
426 @item Translator: object that produces audio objects or Grobs.
427 @item Font_metric: object representing a font. (Not yet user
430 @c @item Audio_element: (todo, smobme)
433 Identifiers allow objects to be assigned to names during the parse
434 stage. To assign an identifier, you use `@var{name}=@var{value}' and to
435 refer to an identifier, you preceed its name with a backslash:
436 `@code{\}@var{name}'. Identifier assignments must appear at top level
437 in the @emph{Lilypond} file. Semicolons are forbidden after assignments
438 appearing at top level but they are obligatory after assignments
439 appearing in the @code{\paper} block, see Section @ref{paper}.
441 @var{value} is any valid Scheme value or any of the input-types listed
444 An identifier can be created with any string for its name, but you will
445 only be able to refer to identifiers whose names begin with a letter,
446 being entirely alphanumeric. It is impossible to refer to an identifier
447 whose name is the same as the name of a keyword.
449 The right hand side of an identifier assignment is parsed completely
450 before the assignment is done, so it is allowed to redefine an
451 identifier in terms of its old value, e.g.
457 When an identifier is referenced, the information it points to is
458 copied. For this reason, an identifier reference must always be the
459 first item in a block.
463 \paperIdent % wrong and invalid
467 \paperIdent % correct
473 @node Music expressions, , , Reference Manual
474 @section Music expressions
476 @cindex music expressions
478 Music in @emph{Lilypond} is entered as a music expression. Notes, rests,
479 lyric syllables are music expressions (the atomic
481 @cindex atomic music expressions
482 , and you can combine
483 music expressions to form new ones. This example forms a compound
484 expressions out of the quarter @code{c} note and a @code{d}
488 \sequential @{ c4 d4 @}
491 The meaning of this compound expression is to play the `@code{c}'
492 first, and then the `@code{d}' (as opposed to playing them
493 simultaneously, for instance).
495 Atomic music expression are discussed in
496 subsection @ref{Atomic music expressions}. Compound music expressions are
497 discussed in subsection @ref{Compound music expressions}.
501 @node Atomic music expressions, , , Reference Manual
502 @section Atomic music expressions
512 The syntax for pitch specification is
516 \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
519 @var{octave} is specified by an integer, zero for the octave
520 containing middle C. @var{note} is a number from 0 to 7, with 0
521 corresponding to C and 7 corresponding to B. The shift is zero for a
522 natural, negative to add flats, or positive to add sharps.
524 In Note and Chord mode, pitches may be designated by names. See
525 section @ref{Other languages} for pitch names in different languages.
527 The syntax for duration specification is
530 \duration@keyindex{duration}
531 @{ @var{length} @var{dotcount} @}
534 @var{length} is the negative logarithm (base 2) of the duration:
535 1 is a half note, 2 is a quarter note, 3 is an eighth
536 note, etc. The number of dots after the note is given by
539 In Note, Chord, and Lyrics mode, durations may be designated by
543 @node Note specification, , , Reference Manual
545 @cindex note specification
549 @cindex entering notes
551 A note specification has the form
554 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
557 The pitch of the note is specified by the note's name.
560 The default names are the Dutch note names. The notes are specified
561 by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
562 octave below middle C and the letters span the octave above that C.
564 @cindex notenames!Dutch
565 a sharp is formed by adding `@code{-is}' to the end of a pitch name. A
566 flat is formed by adding `@code{-es}'. Double sharps and double flats
567 are obtained by adding `@code{-isis}' or `@code{-eses}'. `@code{aes}'
568 and `@code{ees}' are contracted to `@code{as}' and `@code{es}' in Dutch,
569 but both forms will be accepted.
571 LilyPond has predefined sets of notenames for various languages. See
572 @ref{Other languages}.
576 The optional octave specification takes the form of a series of
577 single quote (`@code{'}@indexcode{'}') characters or a series of comma
578 (`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
579 octave; each @code{,} lowers the pitch by an octave.
581 @lilypond[fragment,verbatim,center]
582 c' d' e' f' g' a' b' c''
585 @lilypond[fragment,verbatim,center]
586 cis' dis' eis' fis' gis' ais' bis'
589 @lilypond[fragment,verbatim,center]
590 ces' des' es' fes' ges' as' bes'
593 @lilypond[fragment,verbatim,center]
594 cisis' eisis' gisis' aisis' beses'
597 @lilypond[fragment,verbatim,center]
598 ceses' eses' geses' ases' beses'
601 Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
602 will determine what accidentals to typeset depending on the key and
603 context. A reminder accidental
604 @cindex reminder accidental
606 forced by adding an exclamation mark `@code{!}' after the pitch. A
607 cautionary accidental,
608 @cindex cautionary accidental
610 accidental within parentheses can be obtained by adding the question
611 mark `@code{?}@indexcode{?}' after the pitch.
613 @lilypond[fragment,verbatim,center]
614 cis' d' e' cis' c'? d' e' c'!
620 Durations are entered as their reciprocal values. For notes longer
621 than a whole note, use identifiers.
627 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
636 \notes \relative c'' {
638 a1 a2 a4 a8 a16 a32 a64 a64
643 \remove "Clef_engraver";
644 \remove "Staff_symbol_engraver";
655 r1 r2 r4 r8 r16 r32 r64 r64
664 \notes \relative c'' {
666 r1 r2 r4 r8 r16 r32 r64 r64
669 loose_column_distance = 2.5 * \staffspace;
673 \remove "Clef_engraver";
674 \remove "Staff_symbol_engraver";
675 \remove "Bar_engraver";
682 If the duration is omitted then it is set equal to the previous
683 duration. If there is no previous duration, a quarter note is
684 assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
685 to obtain dotted note lengths.
687 @lilypond[fragment,verbatim,center]
691 You can alter the length of duration by writing
692 `@code{*}@var{fraction}' after it. This will not affect the
693 appearance of note heads or rests.
696 Rests are entered like notes, with note name `@code{r}@indexcode{r}',
697 or `@code{R}@indexcode{R}'. There is also a note name
698 `@code{s}@indexcode{s}', which produces a space of the specified
699 duration. `@code{R}' is specifically meant for entering parts: the
700 @code{R} rest can expand to fill a score with rests, or it can be
701 printed as a single multimeasure rest.
703 You can control the expansion by setting the property
704 @code{Score.skipBars}. If this is set to true, Lily will not expand
705 empty measures, and the multimeasure rests automatically adds the
709 @cindex lyrics expressions
711 Syllables are entered like notes, with pitches replaced by text. For
712 example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
713 with quarter note duration. Note that the hyphen has no special
714 meaning for lyrics, and does not introduce special symbols. See
715 section @ref{Lexical modes} for a description of what is interpreted as
718 Spaces can be introduced into a lyric either by using quotes
719 (`@code{"}') or by using an underscore without quotes: `@code{He_could4
720 not4}'. All unquoted underscores are converted to spaces. Printing
721 lyrics is discussed in section @ref{lyricprint}.
728 \property@keyindex{property}
729 @var{contextname}.@var{propname} = @var{value}
732 Sets the @var{propname} property of the context @var{contextname} to
733 the specified @var{value}. All three arguments are strings.
734 Depending on the context, it may be necessary to quote the strings or
735 to leave space on both sides of the dot.
739 @cindex translator switches
742 \translator@keyindex{translator}
743 @var{contexttype} = @var{name}
746 A music expression indicating that the context which is a direct
747 child of the a context of type @var{contexttype} should be shifted to
748 a context of type @var{contexttype} and the specified name.
750 Usually this is used to switch staffs in Piano music, e.g.
753 \translator Staff = top @var{Music}
757 @cindex output properties
760 These allow you to tweak what is happening in the back-end
761 directly. If you want to control every detail of the output
762 formatting, this is the feature to use. The downside to this is that
763 you need to know exactly how the backend works. Example:
766 @lilypond[fragment,verbatim]
768 \context Staff \outputproperty
769 #(make-type-checker 'Note_head)
770 #'extra-offset = #'(5.0 . 7.5)
774 This selects all note heads occurring at current staff level, and sets
775 the extra-offset of those heads to (5,7.5), shifting them up and
778 Use of this feature is entirely on your own risk: if you use this, the
779 result will depend very heavily on the implementation of the backend,
780 which we change regularly and unscrupulously.
785 Commands are music expressions that have no duration.
790 @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
793 Change the key signature. @var{type} should be
794 @code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get
795 @var{pitch}-major or @var{pitch}-minor, respectively. The second
796 argument is optional; the default is major keys. The @var{\context}
797 argument can also be given as an integer, which tells the number of
798 semitones that should be added to the pitch given in the subsequent
799 @code{\key}@keyindex{key} commands to get the corresponding major key,
800 e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard
801 mode names @code{\ionian}@keyindex{ionian},
802 @code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian},
803 @code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian},
804 @code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
808 @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
811 Specify an arbitrary key signature. The pitches from @var{pitch} will
812 be printed in the key signature in the order that they appear on the
816 \mark@keyindex{mark} @var{unsigned};
820 Prints a mark over or under the staff. You must add
821 @code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for
824 @node barlines, , , Reference Manual
827 \bar@keyindex{bar} @var{bartype};
830 This is a short-cut for doing
832 \property Score.whichBar = @var{bartype}
835 You are encouraged to use @code{\repeat} for repetitions. See
836 @ref{Repeats}, and the documentation of @code{whichBar}.
840 \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
843 A short-cut for doing
845 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
848 See the documentation of @code{timeSignatureFraction}
852 \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
855 Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
856 requests output with 76 quarter notes per minute.
859 \partial@keyindex{partial} @var{duration} @code{;}
865 \property Score.measurePosition = @var{length of duration}
868 See the documentation of @code{measurePosition}.
876 @code{|}@indexcode{|}
881 @cindex shorten measures
885 `@code{|}' is a bar check. Whenever a bar check is encountered during
886 interpretation, a warning message is issued if it doesn't fall at a
887 measure boundary. This can help you finding errors in the input.
888 Depending on the value of @code{barCheckNoSynchronize}
889 @indexcode{barCheckNoSynchronize} The beginning of the measure will be
890 relocated, so this can also be used to shorten measures.
895 \penalty@keyindex{penalty} @var{int} @code{;}
898 Discourage or encourage line breaks. See identifiers
899 @code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
900 section [on identifiers] [FIXME].
903 \clef@keyindex{clef} @var{clefname} @code{;}
909 \property Clef.clefGlyph = @var{symbol associated with clefname}
910 \property Clef.clefPosition = @var{clef Y-position for clefname}
911 \property Clef.clefOctavation = @var{extra pitch of clefname}
914 Supported clef-names include
920 \skip@keyindex{skip} @var{duration} @code{;}
923 Skips the amount of time specified by @var{duration}. If no other
924 music is played, a gap will be left for the skipped time with no
925 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
926 this has the same effect as the space rest `@code{s}'.
931 @node Manual beams, , , Reference Manual
933 A beam is specified by surrounding the beamed notes with brackets
934 `@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
936 @lilypond[fragment,verbatim,center]
937 [a'8 a'] [a'16 a' a' a']
940 Some more elaborate constructions:
942 @lilypond[fragment,verbatim,center]
943 [a'16 <a' c''> c'' <a' c''>]
944 \times 2/3 { [e'8 f' g'] }
947 Beaming can be generated automatically; see section @ref{autobeam}.
951 To place tremolo marks between notes, use @code{\repeat} with tremolo
953 @cindex tremolo beams
954 To create tremolo beams on a single note, simply attach
955 `@code{:}@var{length}' to the note itself.
957 @lilypond[fragment,verbatim,center]
958 \repeat "tremolo" 8 { c16 d16 }
959 \repeat "tremolo" 4 { c16 d16 }
962 @lilypond[fragment,verbatim,center]
967 @cindex --@@@code{-}@code{-}
975 The syntax for an extender mark is `@code{__}'. This syntax can only
976 be used within lyrics mode. The syntax for a spanning hyphen (i.e.,
977 a hyphen that will be printed between two lyric syllables) is
983 A tie connects two adjacent note heads of the same pitch. When used
984 with chords, it connects all of the note heads whose pitches match.
985 Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'.
986 If you try to tie together chords which have no common pitches, a
987 warning message will appear and no ties will be created.
989 @lilypond[fragment,verbatim,center]
990 e' ~ e' <c' e' g'> ~ <c' e' g'>
995 [TODO: explain Requests]
998 @cindex articulations
1004 A variety of symbols can appear above and below notes to indicate
1005 different characteristics of the performance. These symbols can be
1006 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1007 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1008 forced to appear above or below the note by writing
1009 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1010 respectively. Here is a chart showing symbols above notes, with the
1011 name of the corresponding symbol appearing underneath.
1017 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1018 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1019 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1020 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1021 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1022 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1023 c''-\thumb c''-\segno c''-\coda
1025 \context Lyrics \lyrics {
1026 accent__ marcato__ staccatissimo__ fermata
1027 stopped__ staccato__ tenuto__ upbow
1028 downbow__ lheel__ rheel__ ltoe
1029 rtoe__ turn__ open__ flageolet
1030 reverseturn__ trill__ prall__ mordent
1031 prallprall__ prallmordent__ uprall__ downprall
1032 thumb__ segno__ coda
1036 linewidth = 5.875\in;
1043 In addition, it is possible to place arbitrary strings of text or
1044 @TeX{} above or below notes by using a string instead of an
1045 identifier: `@code{c^"text"}'. Fingerings
1048 placed by simply using digits. All of these note ornaments appear in
1049 the printed output but have no effect on the MIDI rendering of the
1052 To save typing, fingering instructions (digits 0 to 9 are
1053 supported) and single characters shorthands exist for a few
1060 \property Voice.textStyle = typewriter
1066 c''4-^_"c-\\^{ }" s4
1073 linewidth = 5.875 \in;
1080 Dynamic marks are specified by using an identifier after a note:
1081 `@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
1082 The available dynamic marks are:
1083 @code{\ppp}@keyindex{ppp},
1084 @code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
1085 @code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
1086 @code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
1087 @code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
1088 @code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
1089 @code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
1090 @code{\rfz}@keyindex{rfz}.
1095 \textscript@keyindex{textscript} @var{text} @var{style}
1098 Defines a text to be printed over or under a note. @var{style} is a
1099 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1100 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1102 You can attach a general textscript request using this syntax:
1107 c4-\textscript "6" "finger"
1108 c4-\textscript "foo" "normal"
1113 This is equivalent to `@code{c4-6 c4-"foo"}'.
1120 \script@keyindex{script} @var{alias}
1123 Prints a symbol above or below a note. The argument is a string
1124 which points into the script-alias table defined in @file{script.scm}.
1125 The scheme definitions specify whether the symbol follows notes into
1126 the staff, dependence of symbol placement on staff direction, and a
1127 priority for placing several symbols over one note. Usually the
1128 @code{\script}@keyindex{script} keyword is not used directly. Various
1129 helpful identifier definitions appear in @file{script.ly}.
1134 Slurs connects chords and try to avoid crossing stems. A slur is
1135 started with `@code{(}' and stopped with `@code{)}'. The
1136 starting `@code{(}' appears to the right of the first note in
1137 the slur. The terminal `@code{)}' appears to the left of the
1138 first note in the slur. This makes it possible to put a note in
1139 slurs from both sides:
1141 @lilypond[fragment,verbatim,center]
1142 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1148 A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated
1149 with @code{\rc}@keyindex{rc}. A decrescendo mark is started with
1150 @code{\decr}@keyindex{decr} and terminated with
1151 @code{\rced}@keyindex{rced}. There are also shorthands for these
1152 marks. A crescendo can be started with @code{\<}@keyindex{<} and a
1153 decrescendo can be started with @code{\>}@keyindex{>}. Either one can
1154 be terminated with @code{\!}@keyindex{"!}. Note that @code{\!}
1155 must go before the last note of the dynamic mark whereas @code{\rc}
1156 and @code{\rced} go after the last note. Because these marks are
1157 bound to notes, if you want to get several marks during one note, you
1158 must use spacer notes.
1160 @lilypond[fragment,verbatim,center]
1161 c'' \< \! c'' d'' \decr e'' \rced
1162 < f''1 { s4 \< \! s2 \> \! s4 } >
1168 \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
1171 Define a spanning request. The @var{startstop} parameter is either -1
1172 (@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and
1173 @var{type} is a string that describes what should be started.
1174 Supported types are @code{crescendo}, @code{decrescendo},
1175 @code{beam}, @code{slur}. This is an internal command. Users should
1176 use the shorthands which are defined in the initialization file
1179 You can attach a (general) span request to a note using
1181 @lilypond[fragment,verbatim,center]
1182 c'4-\spanrequest \start "slur"
1183 c'4-\spanrequest \stop "slur"
1186 The slur syntax with parentheses is a shorthand for this.
1190 @cindex tremolo marks
1192 @node stem tremolo, , , Reference Manual
1194 Tremolo marks can be printed on a single note by adding
1195 `@code{:}[@var{length}]' after the note. The length must be at
1196 least 8. A @var{length} value of 8 gives one line across
1197 the note stem. If the length is omitted, then the last value is
1198 used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was
1201 @lilypond[verbatim,fragment,center]
1207 @node Compound music expressions, , , Reference Manual
1208 @section Compound music expressions
1210 @cindex compound music expressions
1212 Music expressions are compound data structures. You can nest music
1213 expressions any way you like. This simple example shows how three
1214 chords can be expressed in two different ways:
1216 @lilypond[fragment,verbatim,center]
1217 \notes \context Staff {
1219 <a c'> <b d' > <c' e'>
1220 < { a b c' } { c' d' e' } >
1224 @cindex context selection
1225 @c @keyindex{context}
1228 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
1231 Interpret @var{musicexpr} within a context of type @var{contexttype}.
1232 If the context does not exist, it will be created. The new context
1233 can optionally be given a name.
1239 Mode switching keywords form compound music expressions: @code{\notes}
1240 @keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords}
1241 @var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
1242 These expressions do not add anything to the meaning of their
1243 arguments. They are just a way to indicate that the arguments should
1244 be parsed in indicated mode. See @ref{Lexical modes} for more
1245 information on modes.
1247 @cindex sequential music
1253 \sequential@keyindex{sequential}
1254 @code{@{} @var{musicexprlist} @code{@}}
1257 This means that list should be played or written in sequence, i.e.,
1258 the second after the first, the third after the second. The duration
1259 of sequential music is the the sum of the durations of the elements.
1260 There is a shorthand, which leaves out the keyword:
1264 @code{@{} @var{musicexprlist} @code{@}}
1269 @cindex simultaneous music
1276 \simultaneous@keyindex{simultaneous}
1277 @code{@{} @var{musicexprlist} @code{@}}
1280 It constructs a music expression where all of its arguments start at
1281 the same moment. The duration is the maximum of the durations of the
1282 elements. The following shorthand is a common idiom:
1286 @code{<} @var{musicexprlist} @code{>}
1289 If you try to use a chord as the first thing in your score, you might
1290 get multiple staffs instead of a chord.
1292 @lilypond[verbatim,center]
1301 This happens because the chord is interpreted by a score context.
1302 Each time a note is encountered a default Voice context (along with a
1303 Staff context) is created. The solution is to explicitly instantiate
1306 @lilypond[verbatim,center]
1308 \notes\context Voice <c''4 e''>
1317 @cindex relative pitch specification
1319 @node relative, , , Reference Manual
1321 It is easy to get confused by octave changing marks and accidentally
1322 putting a pitch in the wrong octave. A much better way of entering a
1323 note's octave is `the relative octave' mode.
1327 \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
1330 The octave of notes that appear in @var{musicexpr} are calculated as
1331 follows: If no octave changing marks are used, the basic interval
1332 between this and the last note is always taken to be a fourth or
1333 less.@footnote{The interval is determined without regarding
1334 accidentals. A @code{fisis} following a @code{ceses} will be put above
1335 the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}'
1336 can then be added to raise or lower the pitch by an extra octave.
1337 Upon entering relative mode, an absolute starting pitch must be
1338 specified that will act as the predecessor of the first note of
1341 Entering scales is straightforward in relative mode.
1343 @lilypond[fragment,verbatim,center]
1349 And octave changing marks are used for intervals greater than a fourth.
1351 @lilypond[fragment,verbatim,center]
1353 c g c f, c' a, e'' }
1356 If the preceding item is a chord, the first note of the chord is used
1357 to determine the first note of the next chord. But other notes
1358 within the second chord are determined by looking at the immediately
1361 @lilypond[fragment,verbatim,center]
1369 The pitch after the @code{\relative} contains a notename. To parse
1370 the pitch as a notename, you have to be in note mode, so there must
1371 be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
1374 The relative conversion will not affect @code{\transpose} or
1375 @code{\relative} sections in its argument. If you want to use
1376 relative within transposed music, you must place an additional
1377 @code{\relative} inside the @code{\transpose}.
1379 It is strongly recommended to use relative pitch mode: less work,
1380 less error-prone, and more readable.
1384 Chord names are a way to generate simultaneous music expressions that
1385 correspond with traditional chord names. It can only be used in
1386 Chord mode (see section @ref{Lexical modes}).
1390 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1393 @var{tonic} should be the tonic note of the chord, and @var{duration}
1394 is the chord duration in the usual notation. There are two kinds of
1395 modifiers. One type is @emph{chord additions}, which are obtained by
1396 listing intervals separated by dots. An interval is written by its
1397 number with an optional `@code{+}' or `@code{-}' to indicate raising or
1398 lowering by half a step. Chord additions has two effects: It adds
1399 the specified interval and all lower odd numbered intervals to the
1400 chord, and it may lower or raise the specified interval. Intervals
1401 must be separated by a dot (`@code{.}').
1405 @lilypond[fragment,verbatim]
1409 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1416 The second type of modifier that may appear after the `@code{:}' is a
1417 named modifier. Named modifiers are listed in the file
1418 @file{chord-modifiers.ly}. The available modifiers are `@code{m}' and
1419 `@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which
1420 raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th,
1421 `@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}'
1422 which replaces the 5th with a 4th.
1426 @lilypond[fragment,verbatim]
1429 c1:m c:min7 c:maj c:aug c:dim c:sus
1437 Chord subtractions are used to eliminate notes from a chord. The
1438 notes to be subtracted are listed after a `@code{^}' character,
1441 @lilypond[fragment,verbatim,center]
1449 Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
1450 the name of a single note to a chord. This has the effect of
1451 lowering the specified note by an octave so it becomes the lowest
1452 note in the chord. If the specified note is not in the chord, a
1453 warning will be printed.
1455 @lilypond[fragment,verbatim,center]
1464 Bass notes can be added by `@code{/+}@indexcode{/+}' and
1465 the name of a single note to a chord. This has the effect of
1466 adding the specified note to the chord, lowered by an octave,
1467 so it becomes the lowest note in the chord.
1469 @lilypond[fragment,verbatim,center]
1478 Throughout these examples, chords have been shifted around the staff
1479 using @code{\transpose}.
1481 You should not combine @code{\relative} with named chords.
1487 Tuplets are made out of a music expression by multiplying their
1488 duration with a fraction.
1492 \times@keyindex{times} @var{fraction} @var{musicexpr}
1495 The duration of @var{musicexpr} will be multiplied by the fraction.
1496 In print, the fraction's denominator will be printed over the notes,
1497 optionally with a bracket. The most common tuplet is the triplet in
1498 which 3 notes have the length of 2, so the notes are 2/3 of
1499 their written length:
1501 @lilypond[fragment,verbatim,center]
1502 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1511 \grace@keyindex{grace} @var{musicexpr}
1514 A grace note expression has duration 0; the next real note is
1515 assumed to be the main note.
1517 You cannot have the grace note after the main note, in terms of
1518 duration, and main notes, but you can typeset the grace notes to the
1519 right of the main note using the property
1520 @code{graceAlignPosition}@indexcode{graceAlignPosition}.
1522 When grace music is interpreted, a score-within-a-score is set up:
1523 @var{musicexpr} has its own time bookkeeping, and you could (for
1524 example) have a separate time signature within grace notes. While in
1525 this score-within-a-score, you can create notes, beams, slurs, etc.
1526 Unbeamed eighth notes and shorter by default have a slash through the
1527 stem. This behavior can be controlled with the
1528 @code{flagStyle}@indexcode{flagStyle} property.
1532 @lilypond[fragment,verbatim]
1534 \grace c8 c4 \grace { [c16 c16] } c4
1535 \grace { \property Grace.flagStyle = "" c16 } c4
1541 At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
1545 @code{\grace @{ \grace c32 c16 @} c4}
1548 may result in run-time errors of LilyPond. Since the meaning of such
1549 a construct is unclear, we don't consider this a loss. Similarly,
1550 juxtaposing two @code{\grace} sections is syntactically valid, but
1551 makes no sense and may cause runtime errors.
1553 Ending a staff or score with grace notes may also generate a run-time
1554 error, since there will be no main note to attach the grace notes to.
1560 @node Repeats, , , Reference Manual
1562 In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
1563 keyword. Since repeats look and sound differently when played or
1564 printed, there are a few different variants of repeats.
1568 Repeated music is fully written (played) out. Useful for MIDI
1572 This is the normal notation: Repeats are not written out, but
1573 alternative endings (voltas) are printed, left to right.
1576 Alternative endings are written stacked, which is useful for
1580 The syntax for repeats is
1584 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1587 If you have alternative endings, you may add
1591 \alternative@keyindex{alternative}
1592 @code{@{} @var{alternative1}
1594 @var{alternative3} @dots{} @code{@}}
1597 where each @var{alternative} is a Music expression.
1599 Normal notation repeats are used like this:
1603 @lilypond[fragment,verbatim]
1605 \repeat volta 2 { c'4 d' e' f' }
1606 \repeat volta 2 { f' e' d' c' }
1611 With alternative endings:
1615 @lilypond[fragment,verbatim]
1617 \repeat volta 2 {c'4 d' e' f'}
1618 \alternative { {d'2 d'} {f' f} }
1623 Folded repeats look like this:@footnote{Folded repeats offer little
1624 more over simultaneous music. However, it is to be expected that
1625 more functionality -- especially for the MIDI backend -- will be
1630 @lilypond[fragment,verbatim]
1632 \repeat fold 2 {c'4 d' e' f'}
1633 \alternative { {d'2 d'} {f' f} }
1640 @lilypond[fragment,verbatim]
1644 \repeat volta 2 { e | c2 d2 | e2 f2 | }
1645 \alternative { { g4 g g } { a | a a a a | b1 } }
1652 If you don't give enough alternatives for all of the repeats, then
1653 the first alternative is assumed to be repeated often enough to equal
1654 the specified number of repeats.
1658 @lilypond[fragment,verbatim]
1661 \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
1662 \alternative { { g4 g g }
1663 {\partial 1; e4 e e }
1664 {\partial 1; a a a a | b1 } }
1671 It is possible to nest @code{\repeat}. This is not entirely
1672 supported: the notes will come be in the right places, but the repeat
1677 @cindex transposition of pitches
1679 @node transpose, , , Reference Manual
1681 A music expression can be transposed with
1682 @code{\transpose}@keyindex{transpose}. The syntax is
1686 \transpose @var{pitch} @var{musicexpr}
1689 This means that middle C in @var{musicexpr} is transposed to
1692 @code{\transpose} distinguishes between enharmonic pitches: both
1693 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
1694 a tone. The first version will print sharps and the second version
1699 @lilypond[fragment,verbatim]
1702 { \key e \major; c d e f }
1704 \transpose des'' { \key e \major; c d e f }
1705 \transpose cis'' { \key e \major; c d e f }
1711 If you want to use both @code{\transpose} and @code{\relative}, then
1712 you must use @code{\transpose} first. @code{\relative} will have no
1713 effect music that appears inside a @code{\transpose}.
1717 @cindex automatic lyric durations
1719 If you have lyrics that are set to a melody, you can import the
1720 rhythm of that melody into the lyrics using @code{\addlyrics}.
1721 @keyindex{addlyrics} The syntax for this is
1725 \addlyrics @var{musicexpr1 musicexpr2}
1728 This means that both @var{musicexpr1} and @var{musicexpr2} are
1729 interpreted, but that every non-command atomic music expression
1730 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1731 of @var{musicexpr1}.
1733 If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
1734 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1739 @lilypond[verbatim,fragment]
1742 \property Voice.automaticMelismata = ##t
1743 c8 () cis d8. e16 f2
1745 \context Lyrics \lyrics {
1751 You should use a single rhythm melody, and single rhythm lyrics (a
1752 constant duration is the obvious choice). If you do not, you will get
1753 undesired effects when using multiple stanzas:
1757 @lilypond[verbatim,fragment]
1760 c8 () cis d8. e16 f2
1762 \context Lyrics \lyrics
1769 It is valid (but probably not very useful) to use notes instead of
1770 lyrics for @var{musicexpr2}.
1775 @node Ambiguities, , , Reference Manual
1776 @section Ambiguities
1780 The grammar contains a number of ambiguities.@footnote{The authors
1781 hope to resolve them at a later time.}
1784 @item The assignment
1790 can be interpreted as making a string identifier @code{\foo}
1791 containing @code{"bar"}, or a music identifier @code{\foo}
1792 containing the syllable `bar'.
1794 @item The assignment
1800 can be interpreted as making an integer identifier
1801 containing -6, or a Request identifier containing the
1802 fingering `6' (with neutral direction).
1804 @item If you do a nested repeat like
1816 then it is ambiguous to which @code{\repeat} the
1817 @code{\alternative} belongs. This is the classic if-then-else
1818 dilemma. It may be solved by using braces.
1820 @item (an as yet unidentified ambiguity :-)
1825 @node Notation conversion specifics, , , Reference Manual
1826 @section Notation conversion specifics
1830 @cindex automatic beam generation
1832 @node autobeam, , , Reference Manual
1834 By default, LilyPond will generate beams automatically. This feature
1835 can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming}
1836 property to 1. It can be overridden for specific cases by
1837 specifying explicit beams.
1840 A large number of Voice properties are used to decide how to generate
1841 beams. Their default values appear in @file{auto-beam-settings.ly}.
1842 In general, beams can begin anywhere, but their ending location is
1843 significant. Beams can end on a beat, or at durations specified by
1844 the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every
1845 quarter note, for example, you could set
1846 @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams
1847 at every three eighth notes you would set it to `@code{"3/8"}'. The
1848 same syntax can be used to specify beam starting points using
1849 @code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
1851 To allow different settings for different time signatures, these
1852 property names can start with `@code{time}@var{N}@code{_}@var{M}' to
1853 restrict the definition to `@var{N}@code{/}@var{M}' time. For example,
1854 to specify beams ending only for 6/8 time you would use the
1855 property @code{Voice.time6_8beamAutoEnd}. To allow different endings
1856 for notes of different durations, the duration can be tacked onto the
1857 end of the property. To specify beam endings for beams that contain
1858 32nd notes, you would use @code{Voice.beamAutoEnd_32}.
1866 @cindex printing!chord names
1868 For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames}
1869 and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered
1870 either using the notation described above, or directly using
1875 @lilypond[fragment,verbatim]
1877 \context ChordNames {
1878 \chords{a b c} \notes{<d f g> <e g b>}
1880 \context Staff \notes {
1888 LilyPond examines chords specified as lists of notes to determine a
1889 name to give the chord. By default, LilyPond will not try to
1890 identify chord inversions:
1892 @lilypond[fragment,verbatim,center]
1894 \context ChordNameVoice \notes {
1897 \context Thread \notes {
1903 If you want inversions to be recognized, you must set the property
1904 @code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
1906 @lilypond[fragment,verbatim,center]
1908 \property Score.chordInversion = ##t
1909 \context ChordNameVoice \notes {
1912 \context Thread \notes {
1922 @cindex printing!lyrics
1924 @node lyricprint, , , Reference Manual
1926 Lyric syllables must be interpreted within a @code{Lyrics} context
1928 @cindex context!Lyrics
1931 Here is a full example:
1938 \notes \transpose c'' {
1940 e f g2 | e4 f g2 \bar "|.";
1942 \context Lyrics \lyrics {
1943 Va-4 der Ja- cob Va- der Ja- cob
1944 Slaapt gij nog?2 Slaapt4 gij nog?2
1952 You may want a continuous line after the syllables to show melismata.
1953 To achieve this effect, add a `@code{__}' lyric as a separate word
1954 after the lyric to be extended. This will create an extender, a line
1955 that extends over the entire duration of the lyric. This line will
1956 run all the way to the start of the next lyric, so you may want to
1957 shorten it by using a blank lyric (using `@code{_}').
1964 \notes \relative c'' {
1965 a4 () b () c () d | c () d () b () a | c () d () b () a
1967 \context Lyrics \lyrics {
1968 foo1 __ | bar2. __ _4 | baz1 __
1977 If you want to have hyphens centered between syllables (rather than
1978 attached to the end of the first syllable) you can use the special
1979 `@code{-}@code{-}' lyric as a separate word between syllables. This
1980 will result in a hyphen which length varies depending on the space
1981 between syllables, and which will be centered between the syllables.
1989 \notes \transpose c'' {
1991 e f g2 | e4 f g2 \bar "|.";
1993 \context Lyrics \lyrics {
1994 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1995 Slaapt gij nog?2 | Slaapt4 gij nog?2
2005 @node Notation Contexts, , , Reference Manual
2006 @section Notation Contexts
2008 @cindex notation contexts
2010 Notation contexts are objects that only exist during a run of
2011 LilyPond. During the interpretation phase of LilyPond, the Music
2012 expression contained in a @code{\score} block is interpreted in time
2013 order. This is the order in which humans read, play, and write
2016 A context is an object that holds the reading state of the
2017 expression; it contains information like
2020 @item What notes are playing at this point?
2021 @item What symbols will be printed at this point?
2022 @item In what style will they printed?
2023 @item What is the current key signature, time signature, point within
2027 Contexts are grouped hierarchically: A @code{Voice} context is
2028 contained in a @code{Staff} context (because a staff can contain
2029 multiple voices at any point), a @code{Staff} context is contained in
2030 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
2031 these can all contain multiple staffs).
2033 Contexts associated with sheet music output are called @emph{notation
2034 contexts}, those for sound output are called playing contexts.
2036 Contexts are created either manually or automatically. Initially,
2037 the top level music expression is interpreted by the top level
2038 context (the @code{Score} context). When a atomic music expression
2039 (i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested
2040 set of contexts is created that can process these atomic expressions,
2046 \score @{ \notes < c4 > @}
2051 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
2052 context. When the note `@code{c4}' itself is interpreted, a set of
2053 contexts is needed that will accept notes. The default for this is a
2054 @code{Voice} context, contained in a @code{Staff} context. Creation of
2055 these contexts results in the staff being printed.
2060 You can also create contexts manually, and you probably have to do so
2061 if you want to typeset complicated multiple part material. If a
2062 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
2063 during the interpretation phase, the @var{musicexpr} argument will be
2064 interpreted with a context of type @var{name}. If you specify a name,
2065 the specific context with that name is searched.
2067 If a context of the specified type and name can not be found, a new
2068 one is created. For example,
2074 \notes \relative c'' {
2075 c4 <d4 \context Staff = "another" e4> f
2082 In this example, the @code{c} and @code{d} are printed on the
2083 default staff. For the @code{e}, a context Staff called
2084 `@code{another}' is specified; since that does not exist, a new
2085 context is created. Within @code{another}, a (default) Voice context
2086 is created for the @code{e4}. When all music referring to a
2087 context is finished, the context is ended as well. So after the
2088 third quarter, @code{another} is removed.
2090 Almost all music expressions inherit their interpretation context
2091 from their parent. In other words, suppose that the syntax for a
2096 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
2099 When the interpretation of this music expression starts, the context
2100 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
2103 Lastly, you may wonder, why this:
2109 \notes \relative c'' @{
2117 doesn't result in this:
2122 \notes \relative c'' {
2129 For the @code{c4}, a default @code{Staff} (with a contained
2130 @code{Voice}) context is created. After the @code{c4} ends, no
2131 music refers to this default staff, so it would be ended, with the
2132 result shown. To prevent this inconvenient behavior, the context to
2133 which the sequential music refers is adjusted during the
2134 interpretation. So after the @code{c4} ends, the context of the
2135 sequential music is also the default @code{Voice} context.
2136 The @code{d4} gets interpreted in the same context
2141 These are the contexts supplied with the package. They are defined
2142 in the initialization file @file{ly/engraver.ly}.
2149 Properties that are set in one context are inherited by all of the
2150 contained contexts. This means that a property valid for the
2151 @code{Voice} context can be set in the @code{Score} context (for
2152 example) and thus take effect in all @code{Voice} contexts.
2154 Properties can be preset within the @code{\translator} block
2155 corresponding to the appropriate context. In this case, the syntax
2160 @var{propname} @code{=} @var{value}
2163 This assignment happens before interpretation starts, so a
2164 @code{\property} expression will override any predefined settings.
2166 The @code{\property} expression will create any property you specify.
2167 There is no guarantee that a property will be used. So if you spell
2168 a property name wrong, there will be no error message.
2170 The property settings are used during the interpretation phase. They
2171 are read by the LilyPond modules where interpretation contexts are
2172 built of. These modules are called @emph{translators}. Translators for
2173 notation are called @emph{engravers}, and translators for sound are
2174 called @emph{performers}.
2176 The precise result of a property is determined by the implementation
2177 of the translator that reads them. Therefore, the result of a
2178 property can vary, since it is implementation and configuration
2181 In order to fully find out what properties are used, you must
2182 currently search the source code for calls to @code{get_property}.
2183 The rest of the section is devoted to an (incomplete) overview of
2184 available properties.
2186 @mbinclude properties.itely
2188 @node Notation output definitions, , , Reference Manual
2189 @section Notation output definitions
2193 @cindex notation output
2195 @cindex output definition
2197 @node paper, , , Reference Manual
2199 The most important output definition is the @code{\paper} block, for
2200 music notation. The syntax is
2204 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2207 where each of the items is one of
2210 @item An assignment. The assignment must be terminated by a
2213 @item A context definition. See section @ref{contextdefs} for
2214 more information on context definitions.
2219 A margin shape declaration. The syntax is
2223 \shape @var{indent1}@code{,} @var{width1}@code{,}
2224 @var{indent2}@code{,} @var{width2} @dots{} @code{;}
2229 Each pair of @var{indent} and @var{width} values is a dimension
2230 specifying how far to indent and how wide to make the line.
2231 The indentation and width of successive lines are specified by
2232 the successive pairs of dimensions. The last pair of
2233 dimensions will define the characeristics of all lines beyond
2234 those explicitly specified.
2236 @item \stylesheet declaration. Its syntax is
2239 \stylesheet @var{scm}
2243 See font.scm for details of @var{scm}
2248 @cindex changing font size and paper size
2250 The Feta font provides musical symbols at six different sizes. These
2251 fonts are 11 point, 13 point, 16 point, 20 point,
2252 23 point, and 26 point. The point size of a font is the
2253 height of the five lines in a staff when displayed in the font.
2255 Definitions for these sizes are the files @file{paperSZ.ly}, where
2256 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include
2257 any of these files, the identifiers @code{paper_eleven},
2258 @code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty},
2259 @code{paper_twentythree}, and @code{paper_twentysix} are defined
2260 respectively. The default @code{\paper} block is also set.
2262 To change the paper size, you must first set the
2263 @code{papersize}@indexcode{papersize} variable at top level. Set it to the strings
2264 @code{a4}, @code{letter}, or @code{legal}. After this specification,
2265 you must set the font as described above. If you want the default
2266 font, then use the 20 point font. The new paper size will not
2267 take effect if the font is not loaded and selected afterwards. Paper
2268 size selection works by loading a file named after the paper size you
2273 @cindex paper variables
2275 @node Paper variables, , , Reference Manual
2277 There is a large number of paper variables that are used to control
2278 details of the layout. These variables control the defaults for the
2279 entire score. Usually, they do not have to be changed; they are by
2280 default set to values that depend on the font size in use. The
2281 values are used by the graphic objects while formatting the score;
2282 they are therefore implementation dependent. Most variables are
2283 accompanied by documentation in the initalization file
2284 @file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff
2287 Nevertheless, here are some variables you may want to use or change:
2290 @item @code{indent}@indexcode{indent}
2291 The indentation of the first line of music.
2293 @item @code{staffspace}@indexcode{staffspace}
2294 The distance between two staff lines, calculated from the center
2295 of the lines. You should use either this or @code{rulethickness}
2296 as a unit for distances you modify.
2298 @item @code{linewidth}@indexcode{linewidth}
2299 Sets the width of the lines. If set to -1.0, a single
2300 unjustified line is produced.
2302 @item @code{textheight}@indexcode{textheight}
2303 Sets the total height of the music on each page. Only used by
2306 @item @code{interscoreline}@indexcode{interscoreline}
2307 Sets the spacing between the score lines. Defaults to 16 pt.
2309 @item @code{interscorelinefill}@indexcode{interscorelinefill}
2310 If set to a positive number, the distance between the score
2311 lines will stretch in order to fill the full page. In that
2312 case @code{interscoreline} specifies the minimum spacing.
2315 @item @code{stafflinethickness}@indexcode{stafflinethickness}
2316 Determines the thickness of staff and bar lines.
2320 @node contextdefs, , , Reference Manual
2322 @cindex context definition
2324 A notation contexts is defined by the following information
2329 @item The LilyPond modules that do the actual conversion of music to
2330 notation. Each module is a so-called
2335 @item How these modules should cooperate, i.e. which ``cooperation
2336 module'' should be used. This cooperation module is a special
2339 @item What other contexts the context can contain,
2341 @item What properties are defined.
2344 A context definition has this syntax:
2348 \translator @code{@{}
2349 @var{translatorinit} @var{translatormodifierlist}
2353 @var{translatorinit} can be an identifier or of the form
2357 \type @var{typename} @code{;}
2360 @var{typename} is one of
2363 @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
2364 The standard cooperation engraver.
2366 @item @code{Score_engraver}@indexcode{Score_engraver}
2367 This is cooperation module that should be in the top level context.
2369 @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
2370 This is a special cooperation module (resembling
2371 @code{Score_engraver}) that is used to created an embedded
2375 @var{translatormodifierlist} is a list of items where each item is
2379 @item @code{\consists} @var{engravername} @code{;}
2380 Add @var{engravername} to the list of modules in this context.
2381 The order of engravers added with @code{\consists} is
2384 @item @code{\consistsend} @var{engravername} @code{;}
2385 Analogous to @code{\consists}, but makes sure that
2386 @var{engravername} is always added to the end of the list of
2389 Some engraver types need to be at the end of the list; this
2390 insures they are put there, and stay there, if a user adds or
2391 removes engravers. This command is usually not needed for
2394 @item @code{\accepts} @var{contextname} @code{;}
2395 Add @var{contextname} to the list of context this context can
2396 contain. The first listed context the context to create by
2399 @item @code{\remove} @var{engravername} @code{;}
2400 Remove a previously added (with @code{\consists}) engraver.
2402 @item @code{\name} @var{contextname} @code{;}
2403 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2404 the name is not specified, the translator won't do anything.
2406 @item @var{propname} @code{=} @var{value} @code{;}
2407 A property assignment. It is allowed to use reals for
2411 In the @code{\paper} block, it is also possible to define translator
2412 identifiers. Like other block identifiers, the identifier can only
2413 be used as the very first item of a translator. In order to define
2414 such an identifier outside of @code{\score}, you must do
2420 foo = \translator @{ @dots{} @}
2427 \translator @{ \foo @dots{} @}
2435 @cindex paper types, engravers, and pre-defined translators
2437 Some pre-defined identifiers can simplify modification of
2438 translators. The pre-defined identifiers are:
2441 @item @code{StaffContext}@indexcode{StaffContext}
2442 Default Staff context.
2444 @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
2445 Default RhythmicStaff context.
2447 @item @code{VoiceContext}@indexcode{VoiceContext}
2448 Default Voice context.
2450 @item @code{ScoreContext}@indexcode{ScoreContext}
2451 Default Score context.
2453 @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers}
2454 Score context with numbering at the Score level.
2456 @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext}
2457 Staff context with numbering at the Staff level.
2459 @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext}
2460 Staff context that does not print if it only contains rests.
2461 Useful for orchestral scores.@footnote{Harakiri, also called
2462 Seppuku, is the ritual suicide of the Samourai.}
2464 @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
2466 @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
2469 Using these pre-defined values, you can remove or add items to the
2478 \remove Some_engraver;
2479 \consists Different_engraver;
2487 @node Sound output, , , Reference Manual
2488 @section Sound output
2492 The MIDI block is analogous to the paper block, but it is simpler.
2493 The @code{\midi} block can contain:
2497 @item a @code{\tempo} definition
2498 @item context definitions
2501 Assignments in the @code{\midi} block are not allowed.
2505 @cindex context definition
2507 Context definitions follow precisely the same syntax as within the
2508 \paper block. Translation modules for sound are called performers.
2509 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2513 @cindex MIDI instrument names
2515 @node midilist, , , Reference Manual
2517 The MIDI instrument name is set by the
2518 @code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
2519 if that property is not set, the
2520 @code{Staff.instrument}@indexcode{Staff.instrument} property. The
2521 instrument name should be chosen from the following list. If the
2522 selected string does not exactly match, then LilyPond uses the default
2528 "acoustic grand" "contrabass" "lead 7 (fifths)"
2529 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2530 "electric grand" "pizzicato strings" "pad 1 (new age)"
2531 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2532 "electric piano 1" "timpani" "pad 3 (polysynth)"
2533 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2534 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2535 "clav" "synthstrings 1" "pad 6 (metallic)"
2536 "celesta" "synthstrings 2" "pad 7 (halo)"
2537 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2538 "music box" "voice oohs" "fx 1 (rain)"
2539 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2540 "marimba" "orchestra hit" "fx 3 (crystal)"
2541 "xylophone" "trumpet" "fx 4 (atmosphere)"
2542 "tubular bells" "trombone" "fx 5 (brightness)"
2543 "dulcimer" "tuba" "fx 6 (goblins)"
2544 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2545 "percussive organ" "french horn" "fx 8 (sci-fi)"
2546 "rock organ" "brass section" "sitar"
2547 "church organ" "synthbrass 1" "banjo"
2548 "reed organ" "synthbrass 2" "shamisen"
2549 "accordion" "soprano sax" "koto"
2550 "harmonica" "alto sax" "kalimba"
2551 "concertina" "tenor sax" "bagpipe"
2552 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2553 "acoustic guitar (steel)" "oboe" "shanai"
2554 "electric guitar (jazz)" "english horn" "tinkle bell"
2555 "electric guitar (clean)" "bassoon" "agogo"
2556 "electric guitar (muted)" "clarinet" "steel drums"
2557 "overdriven guitar" "piccolo" "woodblock"
2558 "distorted guitar" "flute" "taiko drum"
2559 "guitar harmonics" "recorder" "melodic tom"
2560 "acoustic bass" "pan flute" "synth drum"
2561 "electric bass (finger)" "blown bottle" "reverse cymbal"
2562 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2563 "fretless bass" "whistle" "breath noise"
2564 "slap bass 1" "ocarina" "seashore"
2565 "slap bass 2" "lead 1 (square)" "bird tweet"
2566 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2567 "synth bass 2" "lead 3 (calliope)" "helicopter"
2568 "violin" "lead 4 (chiff)" "applause"
2569 "viola" "lead 5 (charang)" "gunshot"
2570 "cello" "lead 6 (voice)"
2577 @node Pre-defined Identifiers, , , Reference Manual
2579 @section Pre-defined Identifiers
2581 @cindex pre-defined identifiers
2584 Various identifiers are defined in the initialization files to
2585 provide shorthands for some settings. Most of them are in
2586 @file{ly/declarations.ly}.
2589 @item @code{\break}@keyindex{break}
2590 Force a line break in music by using a large argument for the
2591 keyword @code{\penalty}.
2593 @item @code{\nobreak}@keyindex{nobreak}
2594 Prevent a line break in music by using a large negative argument
2595 for the keyword @code{\penalty}.
2597 @item @code{\normalkey}@keyindex{normalkey}
2598 Select normal key signatures where each octave has the same key
2599 signature. This sets the @code{Staff.keyoctaviation} property.
2601 @item @code{\shiftoff}@keyindex{shiftOff}
2602 Disable horizontal shifting of note heads that collide.
2604 @item @code{\shiftOn}@keyindex{shiftOn}
2605 Enable note heads that collide with other note heads to be
2606 shifted horiztonally.
2608 @item @code{\slurBoth}@keyindex{slurBoth}
2609 Allow slurs to be above or below notes.
2611 @item @code{\slurDown}@keyindex{slurDown}
2612 Force slurs to be below notes.
2614 @item @code{\slurUp}@keyindex{slurUp}
2615 Force slurs to be above notes.
2617 @item @code{\specialkey}@keyindex{specialkey}
2618 Allow key signatures do differ in different octaves. This sets
2619 the @code{Staff.keyoctaviation} property.
2621 @item @code{\stemBoth}@keyindex{stemBoth}
2622 Allow stems, beams, and slurs to point either upwards or
2623 downwards, decided automatically by LilyPond.
2625 @item @code{\stemdown}@keyindex{stemdown}
2626 Force stems, beams, and slurs to point down.
2628 @item @code{\stemUp}@keyindex{stemUp}
2629 Force stems, beams and slurs to point up.
2633 @node Grobs, , , Reference Manual
2636 This section is about Grobs (short for Graphical Objects), which are
2637 formatting objects used to create the final output. This material is
2638 normally the domain of LilyPond gurus, but occasionally, a normal user
2639 also has to deal with grobs.
2641 The most simple interaction with Grobs are when you use
2645 \property Voice.Stem \override #'direction = #1
2648 This piece of lily input causes all stem objects to be stem-up
2649 henceforth. In effect, you are telling lilypond to extend the defintion
2650 of the "Stem" grob with the setting @code{direction := 1}. Of course
2651 there are many more ways of customizing Lily output, and since most of
2652 them involve Grobs in some form, this section explains some details of
2658 * Setting grob properties::
2659 * Items and Spanners::
2660 * Pointer substitution::
2663 @node What is a grob?, , , Grobs
2665 All grobs have an X and Y-position on the page. These X and Y positions
2666 are stored in a relative format, so they can easily be combined by
2667 stacking them, hanging one grob to the side of another, and coupling
2668 them into a grouping-grob.
2670 Each grob has a reference point, or parent: the position of a grob is
2671 stored relative to that reference point. For example the X-reference
2672 point of a staccato dot usually is the note head that it applies
2673 to. Whenever the note head is moved, the staccato dot moves along
2676 If you keep following offset reference points, you will always end up at
2677 the root-object. This root object is called @code{Line_of_score}
2678 @ref{(lilypond-internals)Element Line_of_score}, and it represents a
2679 system (ie. a line of music).
2681 All grobs carry a set of grob-properties. In the Stem example above,
2682 the property @code{direction} is set to value @code{1}. The function
2683 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
2684 @code{direction} to determine how to print the stem and the flag. The
2685 appearance of a grob is determined solely by the values of its
2688 Often, a grob also is associated with a symbol. On the other hand, Some
2689 grobs do not print any symbols, but take care of grouping objects. For
2690 example, there is a separate grob that stacks staffs vertically, so they
2691 are not printed in overstrike. The NoteCollision @ref{(lilypond-internals)Element
2692 NoteCollision} is another example of an abstract grob. It only moves
2693 around chords, but doesn't print anything.
2695 A complete list of grob types is found in @ref{(lilypond-internals)Elements}
2697 Grobs are created in the "Interpreting music" phase, by things in
2698 LilyPond called engravers. In this phase of the translation, a load of
2699 grobs are created, and they are linked into a giant network of objects.
2700 This network of grobs forms the "specification" of the print
2701 problem. This problem is then solved: configurations, directions,
2702 dimensions, line breaks, etc. are calculated. Finally, the printing
2703 description in the form of Molecules (@ref{Molecule}) is extracted from
2704 the network. These are then dumped into the output file
2706 @node Callbacks, , , Grobs
2708 Offsets of grobs are relative to a parent reference point. Most
2709 positions are not known when an object is created, so these are
2710 calculated as needed. This is done by adding a callback for a specific
2713 Suppose you have the following code in a .ly file.
2715 #(define (my-callback gr axis)
2716 (* 2.0 (get-gr-property grob 'direction))
2721 \property Voice.Stem \override #'Y-offset-callbacks = #(list
2725 When the Y-offset of a Stem object is needed, LilyPond will
2726 automatically execute all callbacks for that object. In this case, it
2727 will find @code{my-callback}, and execute that. The result is that the
2728 stem is translated by two staff spaces in its direction.
2730 (note: Y-offset-callbacks is also a property)
2733 Offset callbacks can be stacked, ie.
2736 \property .... \override #'Y-offset-callbacks = #(list
2737 callback1 callback2 callback3)
2741 The callbacks will be executed in the order callback3 callback2
2742 callback1. This is used for quantized positioning: the staccato dot is
2743 above or below a note head, and it must not be on a staff-line.
2745 To achieve this, for the staccato there are two callbacks: one callback
2746 that positions the grob above or below the note head, and one callback
2747 that rounds the Y-position of the grob to the nearest open space.
2749 Similarly, the size of a grob are determined through callbacks, settable
2750 with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
2751 There can be only one extent-callback for each axis. No callback (value #f)
2752 means: "empty in this direction". If you fill in a pair, that pair
2753 hard-codes the extent in that coordinate.
2756 @node Setting grob properties, , , Grobs
2758 Grob properties are stored as GUILE association lists, with symbols as
2759 keys. From C++, element properties can be accessed using the functions
2762 SCM get_grob_property (SCM) const;
2763 void set_grob_property (const char * , SCM val);
2764 void set_immutable_grob_property (const char * , SCM val);
2765 void set_immutable_grob_property (SCM key, SCM val);
2766 void set_grob_property (SCM , SCM val);
2767 void set_grob_pointer (const char*, SCM val);
2768 SCM remove_grob_property (const char* nm);
2771 In GUILE, LilyPond provides
2774 ly-get-grob-property GROB SYMBOL
2775 ly-set-grob-property GROB SYMBOL VALUE
2778 All lookup functions identify undefined properties with
2779 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
2781 Properties are stored in two ways:
2783 @item mutable properties:
2784 element properties that change from object to object. The storage of
2785 these are private to a grob. Typically this is used to store lists of
2786 pointers to other grobs
2788 @item immutable properties:
2789 element properties that are shared across different grobs of the same
2790 type. The storage is shared, and hence it is read-only. Typically, this
2791 is used to store function callbacks, and values for shared element
2792 properties are read from @file{scm/element-description.scm}.
2795 There are two ways to manually set grob properties.
2797 You can change immutable grob properties. This is done with the
2801 \property Voice.Stem \override #'direction = #1
2804 This will push the entry @code{'(direction . 1)} on the immutable
2805 property list for stems, in effect overriding the setting from
2806 @file{scm/element-description.scm}. This can be undone by
2809 \property Voice.stem \revert #'direction
2812 If you use this a lot, this gets old quickly. So we also have a
2816 \property Context.GrobType \set #'prop = #VAL
2819 this does a @code{\revert} followed by a @code{\override}
2821 The second way is \outputproperty. This construct looks like
2824 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
2827 In this case, in every grob that satisfies @var{pred}, the property
2828 assignment @var{sym} = @var{val} is done. For example
2832 #(lambda (gr) (string? (ly-get-grob-property gr
2834 #'extra-offset = #'(-1.0 . 0.0)
2837 This shifts all elements that have a @code{text} property one staff
2838 space to the left. This mechanism is rather clumsy to use, but it allows
2839 you tweak any setting of any grob.
2841 @node Items and Spanners, , , Grobs
2842 @unnumberedsubsec Items and Spanners
2844 Grobs can also be distinguished in their role in the horizontal spacing.
2845 A lot of grobs define constraints on the spacing by their sizes. For
2846 example, note heads, clefs, stems, and all other symbols with a fixed
2847 shape. These grobs form a subtype called @code{Item}.
2849 Other grobs have a shape that depends on the horizontal spacing. For
2850 example, slur, beam, tie, etc. These grobs form a subtype called
2851 @code{Spanner}. All spanners have two span-points (these must be
2852 @code{Item}s), one on the left and one on the right. The left bound is
2853 also the X-reference point.
2855 Some items need special treatment for line breaking. For example, a
2856 clef is normally only printed at the start of a line (ie. after a line
2857 break). To model this, `breakable' items (clef, key signature, bar lines,
2858 etc.) are copied twice. Then we have three versions of each breakable
2859 item: one version if there is no line break, one version that is printed
2860 before the line break (at the end of a system), one version that is
2861 printed after the line break.
2863 Whether these versions are visible and take up space, is determined by
2864 the outcome of the visibility-lambda. This is a function taking a
2865 direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
2866 this grob should be transparent and invisible.
2868 @node Pointer substitution, , , Grobs
2869 @unnumberedsubsec Pointer substitution
2872 Symbols that cross line-breaks (such as slurs) cause some more
2873 complications. When a spanner crosses a line-break, then the spanner is
2874 "broken into pieces", for every line that the spanner is in, a copy of
2875 the grob is made. A substitution process redirects all grob-reference
2876 so that spanner grob will only reference other grobs in the same line.
2878 @node Molecule, , , Reference Manual
2880 The objective of any typesetting system is to put ink on paper in the
2881 right places. For LilyPond, this final stage is left to the TeX and the
2882 printer subsystem. For lily, the last stage in processing a score is
2883 outputting a description of what to put where. This description roughly
2892 you merely have to look at the tex output of lily to see this.
2893 Internally these instructions are encoded in Molecules:@footnote{At some
2894 point LilyPond also contained Atom-objects, but they have been replaced
2895 by Scheme expressions.}. A molecule is an object that combines
2896 dimension information (how large is this glyph ?) with
2897 what-to-print-where.
2899 Conceptually, Molecules can be constructed from Scheme code, by
2900 translating a Molecule and by combining two molecules. In BNF notation:
2903 Molecule = COMBINE Molecule Molecule
2904 | TRANSLATE Offset Molecule
2909 (refer to the C++ code for more details). All visible,
2910 ie. non-transparent, grobs have a callback to create a Molecule. The
2911 name of the property is @code{molecule-callback}, and its value should
2912 be a Scheme function taking one argument (the grob) and returning a