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
409 @item Score (TODO, smobme)
410 @item Music_output_def (TODO, smobme)
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 paper output object,
424 including dimensions. Produced by some Grob functions
425 @item Translator: object that produces audio objects or Grobs
427 @item Font_metric: object representing a font. (Not yet user accessible.)
428 @item Audio_element: (TODO, smobme)
431 Identifiers allow objects to be assigned to names during the parse
432 stage. To assign an identifier, you use `@var{name}=@var{value}' and to
433 refer to an identifier, you preceed its name with a backslash:
434 `@code{\}@var{name}'. Identifier assignments must appear at top level
435 in the @emph{Lilypond} file. Semicolons are forbidden after assignments
436 appearing at top level but they are obligatory after assignments
437 appearing in the @code{\paper} block, see Section @ref{paper}.
439 @var{value} is any valid Scheme value or any of the input-types listed
442 An identifier can be created with any string for its name, but you
443 will only be able to refer to identifiers whose names begin with a
444 letter, being entirely alphanumeric. It is impossible to refer to an
445 identifier whose name is the same as the name of a keyword.
447 The right hand side of an identifier assignment is parsed completely
448 before the assignment is done, so it is allowed to redefine an
449 identifier in terms of its old value, e.g.
455 When an identifier is referenced, the information it points to is
456 copied. For this reason, an identifier reference must always be the
457 first item in a block.
461 \paperIdent % wrong and invalid
465 \paperIdent % correct
471 @node Music expressions, , , Reference Manual
472 @section Music expressions
474 @cindex music expressions
476 Music in @emph{Lilypond} is entered as a music expression. Notes, rests,
477 lyric syllables are music expressions (the atomic
479 @cindex atomic music expressions
480 , and you can combine
481 music expressions to form new ones. This example forms a compound
482 expressions out of the quarter @code{c} note and a @code{d}
486 \sequential @{ c4 d4 @}
489 The meaning of this compound expression is to play the `@code{c}'
490 first, and then the `@code{d}' (as opposed to playing them
491 simultaneously, for instance).
493 Atomic music expression are discussed in
494 subsection @ref{Atomic music expressions}. Compound music expressions are
495 discussed in subsection @ref{Compound music expressions}.
499 @node Atomic music expressions, , , Reference Manual
500 @section Atomic music expressions
510 The syntax for pitch specification is
514 \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
517 @var{octave} is specified by an integer, zero for the octave
518 containing middle C. @var{note} is a number from 0 to 7, with 0
519 corresponding to C and 7 corresponding to B. The shift is zero for a
520 natural, negative to add flats, or positive to add sharps.
522 In Note and Chord mode, pitches may be designated by names. See
523 section @ref{Other languages} for pitch names in different languages.
525 The syntax for duration specification is
528 \duration@keyindex{duration}
529 @{ @var{length} @var{dotcount} @}
532 @var{length} is the negative logarithm (base 2) of the duration:
533 1 is a half note, 2 is a quarter note, 3 is an eighth
534 note, etc. The number of dots after the note is given by
537 In Note, Chord, and Lyrics mode, durations may be designated by
541 @node Note specification, , , Reference Manual
543 @cindex note specification
547 @cindex entering notes
549 A note specification has the form
552 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
555 The pitch of the note is specified by the note's name.
558 The default names are the Dutch note names. The notes are specified
559 by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
560 octave below middle C and the letters span the octave above that C.
562 @cindex notenames!Dutch
563 a sharp is formed by adding `@code{-is}' to the end of a pitch name. A
564 flat is formed by adding `@code{-es}'. Double sharps and double flats
565 are obtained by adding `@code{-isis}' or `@code{-eses}'. `@code{aes}'
566 and `@code{ees}' are contracted to `@code{as}' and `@code{es}' in Dutch,
567 but both forms will be accepted.
569 LilyPond has predefined sets of notenames for various languages. See
570 @ref{Other languages}.
574 The optional octave specification takes the form of a series of
575 single quote (`@code{'}@indexcode{'}') characters or a series of comma
576 (`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
577 octave; each @code{,} lowers the pitch by an octave.
579 @lilypond[fragment,verbatim,center]
580 c' d' e' f' g' a' b' c''
583 @lilypond[fragment,verbatim,center]
584 cis' dis' eis' fis' gis' ais' bis'
587 @lilypond[fragment,verbatim,center]
588 ces' des' es' fes' ges' as' bes'
591 @lilypond[fragment,verbatim,center]
592 cisis' eisis' gisis' aisis' beses'
595 @lilypond[fragment,verbatim,center]
596 ceses' eses' geses' ases' beses'
599 Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
600 will determine what accidentals to typeset depending on the key and
601 context. A reminder accidental
602 @cindex reminder accidental
604 forced by adding an exclamation mark `@code{!}' after the pitch. A
605 cautionary accidental,
606 @cindex cautionary accidental
608 accidental within parentheses can be obtained by adding the question
609 mark `@code{?}@indexcode{?}' after the pitch.
611 @lilypond[fragment,verbatim,center]
612 cis' d' e' cis' c'? d' e' c'!
618 Durations are entered as their reciprocal values. For notes longer
619 than a whole note, use identifiers.
625 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
634 \notes \relative c'' {
636 a1 a2 a4 a8 a16 a32 a64 a64
641 \remove "Clef_engraver";
642 \remove "Staff_symbol_engraver";
653 r1 r2 r4 r8 r16 r32 r64 r64
662 \notes \relative c'' {
664 r1 r2 r4 r8 r16 r32 r64 r64
667 loose_column_distance = 2.5 * \staffspace;
671 \remove "Clef_engraver";
672 \remove "Staff_symbol_engraver";
673 \remove "Bar_engraver";
680 If the duration is omitted then it is set equal to the previous
681 duration. If there is no previous duration, a quarter note is
682 assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
683 to obtain dotted note lengths.
685 @lilypond[fragment,verbatim,center]
689 You can alter the length of duration by writing
690 `@code{*}@var{fraction}' after it. This will not affect the
691 appearance of note heads or rests.
694 Rests are entered like notes, with note name `@code{r}@indexcode{r}',
695 or `@code{R}@indexcode{R}'. There is also a note name
696 `@code{s}@indexcode{s}', which produces a space of the specified
697 duration. `@code{R}' is specifically meant for entering parts: the
698 @code{R} rest can expand to fill a score with rests, or it can be
699 printed as a single multimeasure rest.
701 You can control the expansion by setting the property
702 @code{Score.skipBars}. If this is set to true, Lily will not expand
703 empty measures, and the multimeasure rests automatically adds the
707 @cindex lyrics expressions
709 Syllables are entered like notes, with pitches replaced by text. For
710 example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
711 with quarter note duration. Note that the hyphen has no special
712 meaning for lyrics, and does not introduce special symbols. See
713 section @ref{Lexical modes} for a description of what is interpreted as
716 Spaces can be introduced into a lyric either by using quotes
717 (`@code{"}') or by using an underscore without quotes: `@code{He_could4
718 not4}'. All unquoted underscores are converted to spaces. Printing
719 lyrics is discussed in section @ref{lyricprint}.
726 \property@keyindex{property}
727 @var{contextname}.@var{propname} = @var{value}
730 Sets the @var{propname} property of the context @var{contextname} to
731 the specified @var{value}. All three arguments are strings.
732 Depending on the context, it may be necessary to quote the strings or
733 to leave space on both sides of the dot.
737 @cindex translator switches
740 \translator@keyindex{translator}
741 @var{contexttype} = @var{name}
744 A music expression indicating that the context which is a direct
745 child of the a context of type @var{contexttype} should be shifted to
746 a context of type @var{contexttype} and the specified name.
748 Usually this is used to switch staffs in Piano music, e.g.
751 \translator Staff = top @var{Music}
755 @cindex output properties
758 These allow you to tweak what is happening in the back-end
759 directly. If you want to control every detail of the output
760 formatting, this is the feature to use. The downside to this is that
761 you need to know exactly how the backend works. Example:
764 @lilypond[fragment,verbatim]
766 \context Staff \outputproperty
767 #(make-type-checker 'Note_head)
768 #'extra-offset = #'(5.0 . 7.5)
772 This selects all note heads occurring at current staff level, and sets
773 the extra-offset of those heads to (5,7.5), shifting them up and
776 Use of this feature is entirely on your own risk: if you use this, the
777 result will depend very heavily on the implementation of the backend,
778 which we change regularly and unscrupulously.
783 Commands are music expressions that have no duration.
788 @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
791 Change the key signature. @var{type} should be
792 @code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get
793 @var{pitch}-major or @var{pitch}-minor, respectively. The second
794 argument is optional; the default is major keys. The @var{\context}
795 argument can also be given as an integer, which tells the number of
796 semitones that should be added to the pitch given in the subsequent
797 @code{\key}@keyindex{key} commands to get the corresponding major key,
798 e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard
799 mode names @code{\ionian}@keyindex{ionian},
800 @code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian},
801 @code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian},
802 @code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
806 @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
809 Specify an arbitrary key signature. The pitches from @var{pitch} will
810 be printed in the key signature in the order that they appear on the
814 \mark@keyindex{mark} @var{unsigned};
818 Prints a mark over or under the staff. You must add
819 @code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for
822 @node barlines, , , Reference Manual
825 \bar@keyindex{bar} @var{bartype};
828 This is a short-cut for doing
830 \property Score.whichBar = @var{bartype}
833 You are encouraged to use @code{\repeat} for repetitions. See
834 @ref{Repeats}, and the documentation of @code{whichBar}.
838 \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
841 A short-cut for doing
843 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
846 See the documentation of @code{timeSignatureFraction}
850 \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
853 Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
854 requests output with 76 quarter notes per minute.
857 \partial@keyindex{partial} @var{duration} @code{;}
863 \property Score.measurePosition = @var{length of duration}
866 See the documentation of @code{measurePosition}.
874 @code{|}@indexcode{|}
879 @cindex shorten measures
883 `@code{|}' is a bar check. Whenever a bar check is encountered during
884 interpretation, a warning message is issued if it doesn't fall at a
885 measure boundary. This can help you finding errors in the input.
886 Depending on the value of @code{barCheckNoSynchronize}
887 @indexcode{barCheckNoSynchronize} The beginning of the measure will be
888 relocated, so this can also be used to shorten measures.
893 \penalty@keyindex{penalty} @var{int} @code{;}
896 Discourage or encourage line breaks. See identifiers
897 @code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
898 section [on identifiers] [FIXME].
901 \clef@keyindex{clef} @var{clefname} @code{;}
907 \property Clef.clefGlyph = @var{symbol associated with clefname}
908 \property Clef.clefPosition = @var{clef Y-position for clefname}
909 \property Clef.clefOctavation = @var{extra pitch of clefname}
912 Supported clef-names include
918 \skip@keyindex{skip} @var{duration} @code{;}
921 Skips the amount of time specified by @var{duration}. If no other
922 music is played, a gap will be left for the skipped time with no
923 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
924 this has the same effect as the space rest `@code{s}'.
929 @node Manual beams, , , Reference Manual
931 A beam is specified by surrounding the beamed notes with brackets
932 `@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
934 @lilypond[fragment,verbatim,center]
935 [a'8 a'] [a'16 a' a' a']
938 Some more elaborate constructions:
940 @lilypond[fragment,verbatim,center]
941 [a'16 <a' c''> c'' <a' c''>]
942 \times 2/3 { [e'8 f' g'] }
945 Beaming can be generated automatically; see section @ref{autobeam}.
949 To place tremolo marks between notes, use @code{\repeat} with tremolo
951 @cindex tremolo beams
952 To create tremolo beams on a single note, simply attach
953 `@code{:}@var{length}' to the note itself.
955 @lilypond[fragment,verbatim,center]
956 \repeat "tremolo" 8 { c16 d16 }
957 \repeat "tremolo" 4 { c16 d16 }
960 @lilypond[fragment,verbatim,center]
965 @cindex --@@@code{-}@code{-}
973 The syntax for an extender mark is `@code{__}'. This syntax can only
974 be used within lyrics mode. The syntax for a spanning hyphen (i.e.,
975 a hyphen that will be printed between two lyric syllables) is
981 A tie connects two adjacent note heads of the same pitch. When used
982 with chords, it connects all of the note heads whose pitches match.
983 Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'.
984 If you try to tie together chords which have no common pitches, a
985 warning message will appear and no ties will be created.
987 @lilypond[fragment,verbatim,center]
988 e' ~ e' <c' e' g'> ~ <c' e' g'>
993 [TODO: explain Requests]
996 @cindex articulations
1002 A variety of symbols can appear above and below notes to indicate
1003 different characteristics of the performance. These symbols can be
1004 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
1005 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
1006 forced to appear above or below the note by writing
1007 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
1008 respectively. Here is a chart showing symbols above notes, with the
1009 name of the corresponding symbol appearing underneath.
1015 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1016 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1017 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1018 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1019 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1020 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1021 c''-\thumb c''-\segno c''-\coda
1023 \context Lyrics \lyrics {
1024 accent__ marcato__ staccatissimo__ fermata
1025 stopped__ staccato__ tenuto__ upbow
1026 downbow__ lheel__ rheel__ ltoe
1027 rtoe__ turn__ open__ flageolet
1028 reverseturn__ trill__ prall__ mordent
1029 prallprall__ prallmordent__ uprall__ downprall
1030 thumb__ segno__ coda
1034 linewidth = 5.875\in;
1041 In addition, it is possible to place arbitrary strings of text or
1042 @TeX{} above or below notes by using a string instead of an
1043 identifier: `@code{c^"text"}'. Fingerings
1046 placed by simply using digits. All of these note ornaments appear in
1047 the printed output but have no effect on the MIDI rendering of the
1050 To save typing, fingering instructions (digits 0 to 9 are
1051 supported) and single characters shorthands exist for a few
1058 \property Voice.textStyle = typewriter
1064 c''4-^_"c-\\^{ }" s4
1071 linewidth = 5.875 \in;
1078 Dynamic marks are specified by using an identifier after a note:
1079 `@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
1080 The available dynamic marks are:
1081 @code{\ppp}@keyindex{ppp},
1082 @code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
1083 @code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
1084 @code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
1085 @code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
1086 @code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
1087 @code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
1088 @code{\rfz}@keyindex{rfz}.
1093 \textscript@keyindex{textscript} @var{text} @var{style}
1096 Defines a text to be printed over or under a note. @var{style} is a
1097 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1098 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1100 You can attach a general textscript request using this syntax:
1105 c4-\textscript "6" "finger"
1106 c4-\textscript "foo" "normal"
1111 This is equivalent to `@code{c4-6 c4-"foo"}'.
1118 \script@keyindex{script} @var{alias}
1121 Prints a symbol above or below a note. The argument is a string
1122 which points into the script-alias table defined in @file{script.scm}.
1123 The scheme definitions specify whether the symbol follows notes into
1124 the staff, dependence of symbol placement on staff direction, and a
1125 priority for placing several symbols over one note. Usually the
1126 @code{\script}@keyindex{script} keyword is not used directly. Various
1127 helpful identifier definitions appear in @file{script.ly}.
1132 Slurs connects chords and try to avoid crossing stems. A slur is
1133 started with `@code{(}' and stopped with `@code{)}'. The
1134 starting `@code{(}' appears to the right of the first note in
1135 the slur. The terminal `@code{)}' appears to the left of the
1136 first note in the slur. This makes it possible to put a note in
1137 slurs from both sides:
1139 @lilypond[fragment,verbatim,center]
1140 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1146 A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated
1147 with @code{\rc}@keyindex{rc}. A decrescendo mark is started with
1148 @code{\decr}@keyindex{decr} and terminated with
1149 @code{\rced}@keyindex{rced}. There are also shorthands for these
1150 marks. A crescendo can be started with @code{\<}@keyindex{<} and a
1151 decrescendo can be started with @code{\>}@keyindex{>}. Either one can
1152 be terminated with @code{\!}@keyindex{"!}. Note that @code{\!}
1153 must go before the last note of the dynamic mark whereas @code{\rc}
1154 and @code{\rced} go after the last note. Because these marks are
1155 bound to notes, if you want to get several marks during one note, you
1156 must use spacer notes.
1158 @lilypond[fragment,verbatim,center]
1159 c'' \< \! c'' d'' \decr e'' \rced
1160 < f''1 { s4 \< \! s2 \> \! s4 } >
1166 \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
1169 Define a spanning request. The @var{startstop} parameter is either -1
1170 (@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and
1171 @var{type} is a string that describes what should be started.
1172 Supported types are @code{crescendo}, @code{decrescendo},
1173 @code{beam}, @code{slur}. This is an internal command. Users should
1174 use the shorthands which are defined in the initialization file
1177 You can attach a (general) span request to a note using
1179 @lilypond[fragment,verbatim,center]
1180 c'4-\spanrequest \start "slur"
1181 c'4-\spanrequest \stop "slur"
1184 The slur syntax with parentheses is a shorthand for this.
1188 @cindex tremolo marks
1190 @node stem tremolo, , , Reference Manual
1192 Tremolo marks can be printed on a single note by adding
1193 `@code{:}[@var{length}]' after the note. The length must be at
1194 least 8. A @var{length} value of 8 gives one line across
1195 the note stem. If the length is omitted, then the last value is
1196 used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was
1199 @lilypond[verbatim,fragment,center]
1205 @node Compound music expressions, , , Reference Manual
1206 @section Compound music expressions
1208 @cindex compound music expressions
1210 Music expressions are compound data structures. You can nest music
1211 expressions any way you like. This simple example shows how three
1212 chords can be expressed in two different ways:
1214 @lilypond[fragment,verbatim,center]
1215 \notes \context Staff {
1217 <a c'> <b d' > <c' e'>
1218 < { a b c' } { c' d' e' } >
1222 @cindex context selection
1223 @c @keyindex{context}
1226 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
1229 Interpret @var{musicexpr} within a context of type @var{contexttype}.
1230 If the context does not exist, it will be created. The new context
1231 can optionally be given a name.
1237 Mode switching keywords form compound music expressions: @code{\notes}
1238 @keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords}
1239 @var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
1240 These expressions do not add anything to the meaning of their
1241 arguments. They are just a way to indicate that the arguments should
1242 be parsed in indicated mode. See @ref{Lexical modes} for more
1243 information on modes.
1245 @cindex sequential music
1251 \sequential@keyindex{sequential}
1252 @code{@{} @var{musicexprlist} @code{@}}
1255 This means that list should be played or written in sequence, i.e.,
1256 the second after the first, the third after the second. The duration
1257 of sequential music is the the sum of the durations of the elements.
1258 There is a shorthand, which leaves out the keyword:
1262 @code{@{} @var{musicexprlist} @code{@}}
1267 @cindex simultaneous music
1274 \simultaneous@keyindex{simultaneous}
1275 @code{@{} @var{musicexprlist} @code{@}}
1278 It constructs a music expression where all of its arguments start at
1279 the same moment. The duration is the maximum of the durations of the
1280 elements. The following shorthand is a common idiom:
1284 @code{<} @var{musicexprlist} @code{>}
1287 If you try to use a chord as the first thing in your score, you might
1288 get multiple staffs instead of a chord.
1290 @lilypond[verbatim,center]
1299 This happens because the chord is interpreted by a score context.
1300 Each time a note is encountered a default Voice context (along with a
1301 Staff context) is created. The solution is to explicitly instantiate
1304 @lilypond[verbatim,center]
1306 \notes\context Voice <c''4 e''>
1315 @cindex relative pitch specification
1317 @node relative, , , Reference Manual
1319 It is easy to get confused by octave changing marks and accidentally
1320 putting a pitch in the wrong octave. A much better way of entering a
1321 note's octave is `the relative octave' mode.
1325 \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
1328 The octave of notes that appear in @var{musicexpr} are calculated as
1329 follows: If no octave changing marks are used, the basic interval
1330 between this and the last note is always taken to be a fourth or
1331 less.@footnote{The interval is determined without regarding
1332 accidentals. A @code{fisis} following a @code{ceses} will be put above
1333 the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}'
1334 can then be added to raise or lower the pitch by an extra octave.
1335 Upon entering relative mode, an absolute starting pitch must be
1336 specified that will act as the predecessor of the first note of
1339 Entering scales is straightforward in relative mode.
1341 @lilypond[fragment,verbatim,center]
1347 And octave changing marks are used for intervals greater than a fourth.
1349 @lilypond[fragment,verbatim,center]
1351 c g c f, c' a, e'' }
1354 If the preceding item is a chord, the first note of the chord is used
1355 to determine the first note of the next chord. But other notes
1356 within the second chord are determined by looking at the immediately
1359 @lilypond[fragment,verbatim,center]
1367 The pitch after the @code{\relative} contains a notename. To parse
1368 the pitch as a notename, you have to be in note mode, so there must
1369 be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
1372 The relative conversion will not affect @code{\transpose} or
1373 @code{\relative} sections in its argument. If you want to use
1374 relative within transposed music, you must place an additional
1375 @code{\relative} inside the @code{\transpose}.
1377 It is strongly recommended to use relative pitch mode: less work,
1378 less error-prone, and more readable.
1382 Chord names are a way to generate simultaneous music expressions that
1383 correspond with traditional chord names. It can only be used in
1384 Chord mode (see section @ref{Lexical modes}).
1388 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1391 @var{tonic} should be the tonic note of the chord, and @var{duration}
1392 is the chord duration in the usual notation. There are two kinds of
1393 modifiers. One type is @emph{chord additions}, which are obtained by
1394 listing intervals separated by dots. An interval is written by its
1395 number with an optional `@code{+}' or `@code{-}' to indicate raising or
1396 lowering by half a step. Chord additions has two effects: It adds
1397 the specified interval and all lower odd numbered intervals to the
1398 chord, and it may lower or raise the specified interval. Intervals
1399 must be separated by a dot (`@code{.}').
1403 @lilypond[fragment,verbatim]
1407 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1414 The second type of modifier that may appear after the `@code{:}' is a
1415 named modifier. Named modifiers are listed in the file
1416 @file{chord-modifiers.ly}. The available modifiers are `@code{m}' and
1417 `@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which
1418 raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th,
1419 `@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}'
1420 which replaces the 5th with a 4th.
1424 @lilypond[fragment,verbatim]
1427 c1:m c:min7 c:maj c:aug c:dim c:sus
1435 Chord subtractions are used to eliminate notes from a chord. The
1436 notes to be subtracted are listed after a `@code{^}' character,
1439 @lilypond[fragment,verbatim,center]
1447 Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
1448 the name of a single note to a chord. This has the effect of
1449 lowering the specified note by an octave so it becomes the lowest
1450 note in the chord. If the specified note is not in the chord, a
1451 warning will be printed.
1453 @lilypond[fragment,verbatim,center]
1462 Bass notes can be added by `@code{/+}@indexcode{/+}' and
1463 the name of a single note to a chord. This has the effect of
1464 adding the specified note to the chord, lowered by an octave,
1465 so it becomes the lowest note in the chord.
1467 @lilypond[fragment,verbatim,center]
1476 Throughout these examples, chords have been shifted around the staff
1477 using @code{\transpose}.
1479 You should not combine @code{\relative} with named chords.
1485 Tuplets are made out of a music expression by multiplying their
1486 duration with a fraction.
1490 \times@keyindex{times} @var{fraction} @var{musicexpr}
1493 The duration of @var{musicexpr} will be multiplied by the fraction.
1494 In print, the fraction's denominator will be printed over the notes,
1495 optionally with a bracket. The most common tuplet is the triplet in
1496 which 3 notes have the length of 2, so the notes are 2/3 of
1497 their written length:
1499 @lilypond[fragment,verbatim,center]
1500 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1509 \grace@keyindex{grace} @var{musicexpr}
1512 A grace note expression has duration 0; the next real note is
1513 assumed to be the main note.
1515 You cannot have the grace note after the main note, in terms of
1516 duration, and main notes, but you can typeset the grace notes to the
1517 right of the main note using the property
1518 @code{graceAlignPosition}@indexcode{graceAlignPosition}.
1520 When grace music is interpreted, a score-within-a-score is set up:
1521 @var{musicexpr} has its own time bookkeeping, and you could (for
1522 example) have a separate time signature within grace notes. While in
1523 this score-within-a-score, you can create notes, beams, slurs, etc.
1524 Unbeamed eighth notes and shorter by default have a slash through the
1525 stem. This behavior can be controlled with the
1526 @code{flagStyle}@indexcode{flagStyle} property.
1530 @lilypond[fragment,verbatim]
1532 \grace c8 c4 \grace { [c16 c16] } c4
1533 \grace { \property Grace.flagStyle = "" c16 } c4
1539 At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
1543 @code{\grace @{ \grace c32 c16 @} c4}
1546 may result in run-time errors of LilyPond. Since the meaning of such
1547 a construct is unclear, we don't consider this a loss. Similarly,
1548 juxtaposing two @code{\grace} sections is syntactically valid, but
1549 makes no sense and may cause runtime errors.
1551 Ending a staff or score with grace notes may also generate a run-time
1552 error, since there will be no main note to attach the grace notes to.
1558 @node Repeats, , , Reference Manual
1560 In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
1561 keyword. Since repeats look and sound differently when played or
1562 printed, there are a few different variants of repeats.
1566 Repeated music is fully written (played) out. Useful for MIDI
1570 This is the normal notation: Repeats are not written out, but
1571 alternative endings (voltas) are printed, left to right.
1574 Alternative endings are written stacked, which is useful for
1578 The syntax for repeats is
1582 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1585 If you have alternative endings, you may add
1589 \alternative@keyindex{alternative}
1590 @code{@{} @var{alternative1}
1592 @var{alternative3} @dots{} @code{@}}
1595 where each @var{alternative} is a Music expression.
1597 Normal notation repeats are used like this:
1601 @lilypond[fragment,verbatim]
1603 \repeat volta 2 { c'4 d' e' f' }
1604 \repeat volta 2 { f' e' d' c' }
1609 With alternative endings:
1613 @lilypond[fragment,verbatim]
1615 \repeat volta 2 {c'4 d' e' f'}
1616 \alternative { {d'2 d'} {f' f} }
1621 Folded repeats look like this:@footnote{Folded repeats offer little
1622 more over simultaneous music. However, it is to be expected that
1623 more functionality -- especially for the MIDI backend -- will be
1628 @lilypond[fragment,verbatim]
1630 \repeat fold 2 {c'4 d' e' f'}
1631 \alternative { {d'2 d'} {f' f} }
1638 @lilypond[fragment,verbatim]
1642 \repeat volta 2 { e | c2 d2 | e2 f2 | }
1643 \alternative { { g4 g g } { a | a a a a | b1 } }
1650 If you don't give enough alternatives for all of the repeats, then
1651 the first alternative is assumed to be repeated often enough to equal
1652 the specified number of repeats.
1656 @lilypond[fragment,verbatim]
1659 \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
1660 \alternative { { g4 g g }
1661 {\partial 1; e4 e e }
1662 {\partial 1; a a a a | b1 } }
1669 It is possible to nest @code{\repeat}. This is not entirely
1670 supported: the notes will come be in the right places, but the repeat
1675 @cindex transposition of pitches
1677 @node transpose, , , Reference Manual
1679 A music expression can be transposed with
1680 @code{\transpose}@keyindex{transpose}. The syntax is
1684 \transpose @var{pitch} @var{musicexpr}
1687 This means that middle C in @var{musicexpr} is transposed to
1690 @code{\transpose} distinguishes between enharmonic pitches: both
1691 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
1692 a tone. The first version will print sharps and the second version
1697 @lilypond[fragment,verbatim]
1700 { \key e \major; c d e f }
1702 \transpose des'' { \key e \major; c d e f }
1703 \transpose cis'' { \key e \major; c d e f }
1709 If you want to use both @code{\transpose} and @code{\relative}, then
1710 you must use @code{\transpose} first. @code{\relative} will have no
1711 effect music that appears inside a @code{\transpose}.
1715 @cindex automatic lyric durations
1717 If you have lyrics that are set to a melody, you can import the
1718 rhythm of that melody into the lyrics using @code{\addlyrics}.
1719 @keyindex{addlyrics} The syntax for this is
1723 \addlyrics @var{musicexpr1 musicexpr2}
1726 This means that both @var{musicexpr1} and @var{musicexpr2} are
1727 interpreted, but that every non-command atomic music expression
1728 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1729 of @var{musicexpr1}.
1731 If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
1732 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1737 @lilypond[verbatim,fragment]
1740 \property Voice.automaticMelismata = ##t
1741 c8 () cis d8. e16 f2
1743 \context Lyrics \lyrics {
1749 You should use a single rhythm melody, and single rhythm lyrics (a
1750 constant duration is the obvious choice). If you do not, you will get
1751 undesired effects when using multiple stanzas:
1755 @lilypond[verbatim,fragment]
1758 c8 () cis d8. e16 f2
1760 \context Lyrics \lyrics
1767 It is valid (but probably not very useful) to use notes instead of
1768 lyrics for @var{musicexpr2}.
1773 @node Ambiguities, , , Reference Manual
1774 @section Ambiguities
1778 The grammar contains a number of ambiguities.@footnote{The authors
1779 hope to resolve them at a later time.}
1782 @item The assignment
1788 can be interpreted as making a string identifier @code{\foo}
1789 containing @code{"bar"}, or a music identifier @code{\foo}
1790 containing the syllable `bar'.
1792 @item The assignment
1798 can be interpreted as making an integer identifier
1799 containing -6, or a Request identifier containing the
1800 fingering `6' (with neutral direction).
1802 @item If you do a nested repeat like
1814 then it is ambiguous to which @code{\repeat} the
1815 @code{\alternative} belongs. This is the classic if-then-else
1816 dilemma. It may be solved by using braces.
1818 @item (an as yet unidentified ambiguity :-)
1823 @node Notation conversion specifics, , , Reference Manual
1824 @section Notation conversion specifics
1828 @cindex automatic beam generation
1830 @node autobeam, , , Reference Manual
1832 By default, LilyPond will generate beams automatically. This feature
1833 can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming}
1834 property to 1. It can be overridden for specific cases by
1835 specifying explicit beams.
1838 A large number of Voice properties are used to decide how to generate
1839 beams. Their default values appear in @file{auto-beam-settings.ly}.
1840 In general, beams can begin anywhere, but their ending location is
1841 significant. Beams can end on a beat, or at durations specified by
1842 the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every
1843 quarter note, for example, you could set
1844 @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams
1845 at every three eighth notes you would set it to `@code{"3/8"}'. The
1846 same syntax can be used to specify beam starting points using
1847 @code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
1849 To allow different settings for different time signatures, these
1850 property names can start with `@code{time}@var{N}@code{_}@var{M}' to
1851 restrict the definition to `@var{N}@code{/}@var{M}' time. For example,
1852 to specify beams ending only for 6/8 time you would use the
1853 property @code{Voice.time6_8beamAutoEnd}. To allow different endings
1854 for notes of different durations, the duration can be tacked onto the
1855 end of the property. To specify beam endings for beams that contain
1856 32nd notes, you would use @code{Voice.beamAutoEnd_32}.
1864 @cindex printing!chord names
1866 For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames}
1867 and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered
1868 either using the notation described above, or directly using
1873 @lilypond[fragment,verbatim]
1875 \context ChordNames {
1876 \chords{a b c} \notes{<d f g> <e g b>}
1878 \context Staff \notes {
1886 LilyPond examines chords specified as lists of notes to determine a
1887 name to give the chord. By default, LilyPond will not try to
1888 identify chord inversions:
1890 @lilypond[fragment,verbatim,center]
1892 \context ChordNameVoice \notes {
1895 \context Thread \notes {
1901 If you want inversions to be recognized, you must set the property
1902 @code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
1904 @lilypond[fragment,verbatim,center]
1906 \property Score.chordInversion = ##t
1907 \context ChordNameVoice \notes {
1910 \context Thread \notes {
1920 @cindex printing!lyrics
1922 @node lyricprint, , , Reference Manual
1924 Lyric syllables must be interpreted within a @code{Lyrics} context
1926 @cindex context!Lyrics
1929 Here is a full example:
1936 \notes \transpose c'' {
1938 e f g2 | e4 f g2 \bar "|.";
1940 \context Lyrics \lyrics {
1941 Va-4 der Ja- cob Va- der Ja- cob
1942 Slaapt gij nog?2 Slaapt4 gij nog?2
1950 You may want a continuous line after the syllables to show melismata.
1951 To achieve this effect, add a `@code{__}' lyric as a separate word
1952 after the lyric to be extended. This will create an extender, a line
1953 that extends over the entire duration of the lyric. This line will
1954 run all the way to the start of the next lyric, so you may want to
1955 shorten it by using a blank lyric (using `@code{_}').
1962 \notes \relative c'' {
1963 a4 () b () c () d | c () d () b () a | c () d () b () a
1965 \context Lyrics \lyrics {
1966 foo1 __ | bar2. __ _4 | baz1 __
1975 If you want to have hyphens centered between syllables (rather than
1976 attached to the end of the first syllable) you can use the special
1977 `@code{-}@code{-}' lyric as a separate word between syllables. This
1978 will result in a hyphen which length varies depending on the space
1979 between syllables, and which will be centered between the syllables.
1987 \notes \transpose c'' {
1989 e f g2 | e4 f g2 \bar "|.";
1991 \context Lyrics \lyrics {
1992 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1993 Slaapt gij nog?2 | Slaapt4 gij nog?2
2003 @node Notation Contexts, , , Reference Manual
2004 @section Notation Contexts
2006 @cindex notation contexts
2008 Notation contexts are objects that only exist during a run of
2009 LilyPond. During the interpretation phase of LilyPond, the Music
2010 expression contained in a @code{\score} block is interpreted in time
2011 order. This is the order in which humans read, play, and write
2014 A context is an object that holds the reading state of the
2015 expression; it contains information like
2018 @item What notes are playing at this point?
2019 @item What symbols will be printed at this point?
2020 @item In what style will they printed?
2021 @item What is the current key signature, time signature, point within
2025 Contexts are grouped hierarchically: A @code{Voice} context is
2026 contained in a @code{Staff} context (because a staff can contain
2027 multiple voices at any point), a @code{Staff} context is contained in
2028 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
2029 these can all contain multiple staffs).
2031 Contexts associated with sheet music output are called @emph{notation
2032 contexts}, those for sound output are called playing contexts.
2034 Contexts are created either manually or automatically. Initially,
2035 the top level music expression is interpreted by the top level
2036 context (the @code{Score} context). When a atomic music expression
2037 (i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested
2038 set of contexts is created that can process these atomic expressions,
2044 \score @{ \notes < c4 > @}
2049 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
2050 context. When the note `@code{c4}' itself is interpreted, a set of
2051 contexts is needed that will accept notes. The default for this is a
2052 @code{Voice} context, contained in a @code{Staff} context. Creation of
2053 these contexts results in the staff being printed.
2058 You can also create contexts manually, and you probably have to do so
2059 if you want to typeset complicated multiple part material. If a
2060 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
2061 during the interpretation phase, the @var{musicexpr} argument will be
2062 interpreted with a context of type @var{name}. If you specify a name,
2063 the specific context with that name is searched.
2065 If a context of the specified type and name can not be found, a new
2066 one is created. For example,
2072 \notes \relative c'' {
2073 c4 <d4 \context Staff = "another" e4> f
2080 In this example, the @code{c} and @code{d} are printed on the
2081 default staff. For the @code{e}, a context Staff called
2082 `@code{another}' is specified; since that does not exist, a new
2083 context is created. Within @code{another}, a (default) Voice context
2084 is created for the @code{e4}. When all music referring to a
2085 context is finished, the context is ended as well. So after the
2086 third quarter, @code{another} is removed.
2088 Almost all music expressions inherit their interpretation context
2089 from their parent. In other words, suppose that the syntax for a
2094 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
2097 When the interpretation of this music expression starts, the context
2098 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
2101 Lastly, you may wonder, why this:
2107 \notes \relative c'' @{
2115 doesn't result in this:
2120 \notes \relative c'' {
2127 For the @code{c4}, a default @code{Staff} (with a contained
2128 @code{Voice}) context is created. After the @code{c4} ends, no
2129 music refers to this default staff, so it would be ended, with the
2130 result shown. To prevent this inconvenient behavior, the context to
2131 which the sequential music refers is adjusted during the
2132 interpretation. So after the @code{c4} ends, the context of the
2133 sequential music is also the default @code{Voice} context.
2134 The @code{d4} gets interpreted in the same context
2139 These are the contexts supplied with the package. They are defined
2140 in the initialization file @file{ly/engraver.ly}.
2147 Properties that are set in one context are inherited by all of the
2148 contained contexts. This means that a property valid for the
2149 @code{Voice} context can be set in the @code{Score} context (for
2150 example) and thus take effect in all @code{Voice} contexts.
2152 Properties can be preset within the @code{\translator} block
2153 corresponding to the appropriate context. In this case, the syntax
2158 @var{propname} @code{=} @var{value}
2161 This assignment happens before interpretation starts, so a
2162 @code{\property} expression will override any predefined settings.
2164 The @code{\property} expression will create any property you specify.
2165 There is no guarantee that a property will be used. So if you spell
2166 a property name wrong, there will be no error message.
2168 The property settings are used during the interpretation phase. They
2169 are read by the LilyPond modules where interpretation contexts are
2170 built of. These modules are called @emph{translators}. Translators for
2171 notation are called @emph{engravers}, and translators for sound are
2172 called @emph{performers}.
2174 The precise result of a property is determined by the implementation
2175 of the translator that reads them. Therefore, the result of a
2176 property can vary, since it is implementation and configuration
2179 In order to fully find out what properties are used, you must
2180 currently search the source code for calls to @code{get_property}.
2181 The rest of the section is devoted to an (incomplete) overview of
2182 available properties.
2184 @mbinclude properties.itely
2186 @node Notation output definitions, , , Reference Manual
2187 @section Notation output definitions
2191 @cindex notation output
2193 @cindex output definition
2195 @node paper, , , Reference Manual
2197 The most important output definition is the @code{\paper} block, for
2198 music notation. The syntax is
2202 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2205 where each of the items is one of
2208 @item An assignment. The assignment must be terminated by a
2211 @item A context definition. See section @ref{contextdefs} for
2212 more information on context definitions.
2217 A margin shape declaration. The syntax is
2221 \shape @var{indent1}@code{,} @var{width1}@code{,}
2222 @var{indent2}@code{,} @var{width2} @dots{} @code{;}
2227 Each pair of @var{indent} and @var{width} values is a dimension
2228 specifying how far to indent and how wide to make the line.
2229 The indentation and width of successive lines are specified by
2230 the successive pairs of dimensions. The last pair of
2231 dimensions will define the characeristics of all lines beyond
2232 those explicitly specified.
2234 @item \stylesheet declaration. Its syntax is
2237 \stylesheet @var{scm}
2241 See font.scm for details of @var{scm}
2246 @cindex changing font size and paper size
2248 The Feta font provides musical symbols at six different sizes. These
2249 fonts are 11 point, 13 point, 16 point, 20 point,
2250 23 point, and 26 point. The point size of a font is the
2251 height of the five lines in a staff when displayed in the font.
2253 Definitions for these sizes are the files @file{paperSZ.ly}, where
2254 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include
2255 any of these files, the identifiers @code{paper_eleven},
2256 @code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty},
2257 @code{paper_twentythree}, and @code{paper_twentysix} are defined
2258 respectively. The default @code{\paper} block is also set.
2260 To change the paper size, you must first set the
2261 @code{papersize}@indexcode{papersize} variable at top level. Set it to the strings
2262 @code{a4}, @code{letter}, or @code{legal}. After this specification,
2263 you must set the font as described above. If you want the default
2264 font, then use the 20 point font. The new paper size will not
2265 take effect if the font is not loaded and selected afterwards. Paper
2266 size selection works by loading a file named after the paper size you
2271 @cindex paper variables
2273 @node Paper variables, , , Reference Manual
2275 There is a large number of paper variables that are used to control
2276 details of the layout. These variables control the defaults for the
2277 entire score. Usually, they do not have to be changed; they are by
2278 default set to values that depend on the font size in use. The
2279 values are used by the graphic objects while formatting the score;
2280 they are therefore implementation dependent. Most variables are
2281 accompanied by documentation in the initalization file
2282 @file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff
2285 Nevertheless, here are some variables you may want to use or change:
2288 @item @code{indent}@indexcode{indent}
2289 The indentation of the first line of music.
2291 @item @code{staffspace}@indexcode{staffspace}
2292 The distance between two staff lines, calculated from the center
2293 of the lines. You should use either this or @code{rulethickness}
2294 as a unit for distances you modify.
2296 @item @code{linewidth}@indexcode{linewidth}
2297 Sets the width of the lines. If set to -1.0, a single
2298 unjustified line is produced.
2300 @item @code{textheight}@indexcode{textheight}
2301 Sets the total height of the music on each page. Only used by
2304 @item @code{interscoreline}@indexcode{interscoreline}
2305 Sets the spacing between the score lines. Defaults to 16 pt.
2307 @item @code{interscorelinefill}@indexcode{interscorelinefill}
2308 If set to a positive number, the distance between the score
2309 lines will stretch in order to fill the full page. In that
2310 case @code{interscoreline} specifies the minimum spacing.
2313 @item @code{stafflinethickness}@indexcode{stafflinethickness}
2314 Determines the thickness of staff and bar lines.
2318 @node contextdefs, , , Reference Manual
2320 @cindex context definition
2322 A notation contexts is defined by the following information
2327 @item The LilyPond modules that do the actual conversion of music to
2328 notation. Each module is a so-called
2333 @item How these modules should cooperate, i.e. which ``cooperation
2334 module'' should be used. This cooperation module is a special
2337 @item What other contexts the context can contain,
2339 @item What properties are defined.
2342 A context definition has this syntax:
2346 \translator @code{@{}
2347 @var{translatorinit} @var{translatormodifierlist}
2351 @var{translatorinit} can be an identifier or of the form
2355 \type @var{typename} @code{;}
2358 @var{typename} is one of
2361 @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
2362 The standard cooperation engraver.
2364 @item @code{Score_engraver}@indexcode{Score_engraver}
2365 This is cooperation module that should be in the top level context.
2367 @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
2368 This is a special cooperation module (resembling
2369 @code{Score_engraver}) that is used to created an embedded
2373 @var{translatormodifierlist} is a list of items where each item is
2377 @item @code{\consists} @var{engravername} @code{;}
2378 Add @var{engravername} to the list of modules in this context.
2379 The order of engravers added with @code{\consists} is
2382 @item @code{\consistsend} @var{engravername} @code{;}
2383 Analogous to @code{\consists}, but makes sure that
2384 @var{engravername} is always added to the end of the list of
2387 Some engraver types need to be at the end of the list; this
2388 insures they are put there, and stay there, if a user adds or
2389 removes engravers. This command is usually not needed for
2392 @item @code{\accepts} @var{contextname} @code{;}
2393 Add @var{contextname} to the list of context this context can
2394 contain. The first listed context the context to create by
2397 @item @code{\remove} @var{engravername} @code{;}
2398 Remove a previously added (with @code{\consists}) engraver.
2400 @item @code{\name} @var{contextname} @code{;}
2401 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2402 the name is not specified, the translator won't do anything.
2404 @item @var{propname} @code{=} @var{value} @code{;}
2405 A property assignment. It is allowed to use reals for
2409 In the @code{\paper} block, it is also possible to define translator
2410 identifiers. Like other block identifiers, the identifier can only
2411 be used as the very first item of a translator. In order to define
2412 such an identifier outside of @code{\score}, you must do
2418 foo = \translator @{ @dots{} @}
2425 \translator @{ \foo @dots{} @}
2433 @cindex paper types, engravers, and pre-defined translators
2435 Some pre-defined identifiers can simplify modification of
2436 translators. The pre-defined identifiers are:
2439 @item @code{StaffContext}@indexcode{StaffContext}
2440 Default Staff context.
2442 @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
2443 Default RhythmicStaff context.
2445 @item @code{VoiceContext}@indexcode{VoiceContext}
2446 Default Voice context.
2448 @item @code{ScoreContext}@indexcode{ScoreContext}
2449 Default Score context.
2451 @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers}
2452 Score context with numbering at the Score level.
2454 @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext}
2455 Staff context with numbering at the Staff level.
2457 @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext}
2458 Staff context that does not print if it only contains rests.
2459 Useful for orchestral scores.@footnote{Harakiri, also called
2460 Seppuku, is the ritual suicide of the Samourai.}
2462 @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
2464 @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
2467 Using these pre-defined values, you can remove or add items to the
2476 \remove Some_engraver;
2477 \consists Different_engraver;
2485 @node Sound output, , , Reference Manual
2486 @section Sound output
2490 The MIDI block is analogous to the paper block, but it is simpler.
2491 The @code{\midi} block can contain:
2495 @item a @code{\tempo} definition
2496 @item context definitions
2499 Assignments in the @code{\midi} block are not allowed.
2503 @cindex context definition
2505 Context definitions follow precisely the same syntax as within the
2506 \paper block. Translation modules for sound are called performers.
2507 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2511 @cindex MIDI instrument names
2513 @node midilist, , , Reference Manual
2515 The MIDI instrument name is set by the
2516 @code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
2517 if that property is not set, the
2518 @code{Staff.instrument}@indexcode{Staff.instrument} property. The
2519 instrument name should be chosen from the following list. If the
2520 selected string does not exactly match, then LilyPond uses the default
2526 "acoustic grand" "contrabass" "lead 7 (fifths)"
2527 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2528 "electric grand" "pizzicato strings" "pad 1 (new age)"
2529 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2530 "electric piano 1" "timpani" "pad 3 (polysynth)"
2531 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2532 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2533 "clav" "synthstrings 1" "pad 6 (metallic)"
2534 "celesta" "synthstrings 2" "pad 7 (halo)"
2535 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2536 "music box" "voice oohs" "fx 1 (rain)"
2537 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2538 "marimba" "orchestra hit" "fx 3 (crystal)"
2539 "xylophone" "trumpet" "fx 4 (atmosphere)"
2540 "tubular bells" "trombone" "fx 5 (brightness)"
2541 "dulcimer" "tuba" "fx 6 (goblins)"
2542 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2543 "percussive organ" "french horn" "fx 8 (sci-fi)"
2544 "rock organ" "brass section" "sitar"
2545 "church organ" "synthbrass 1" "banjo"
2546 "reed organ" "synthbrass 2" "shamisen"
2547 "accordion" "soprano sax" "koto"
2548 "harmonica" "alto sax" "kalimba"
2549 "concertina" "tenor sax" "bagpipe"
2550 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2551 "acoustic guitar (steel)" "oboe" "shanai"
2552 "electric guitar (jazz)" "english horn" "tinkle bell"
2553 "electric guitar (clean)" "bassoon" "agogo"
2554 "electric guitar (muted)" "clarinet" "steel drums"
2555 "overdriven guitar" "piccolo" "woodblock"
2556 "distorted guitar" "flute" "taiko drum"
2557 "guitar harmonics" "recorder" "melodic tom"
2558 "acoustic bass" "pan flute" "synth drum"
2559 "electric bass (finger)" "blown bottle" "reverse cymbal"
2560 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2561 "fretless bass" "whistle" "breath noise"
2562 "slap bass 1" "ocarina" "seashore"
2563 "slap bass 2" "lead 1 (square)" "bird tweet"
2564 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2565 "synth bass 2" "lead 3 (calliope)" "helicopter"
2566 "violin" "lead 4 (chiff)" "applause"
2567 "viola" "lead 5 (charang)" "gunshot"
2568 "cello" "lead 6 (voice)"
2575 @node Pre-defined Identifiers, , , Reference Manual
2577 @section Pre-defined Identifiers
2579 @cindex pre-defined identifiers
2582 Various identifiers are defined in the initialization files to
2583 provide shorthands for some settings. Most of them are in
2584 @file{ly/declarations.ly}.
2587 @item @code{\break}@keyindex{break}
2588 Force a line break in music by using a large argument for the
2589 keyword @code{\penalty}.
2591 @item @code{\nobreak}@keyindex{nobreak}
2592 Prevent a line break in music by using a large negative argument
2593 for the keyword @code{\penalty}.
2595 @item @code{\normalkey}@keyindex{normalkey}
2596 Select normal key signatures where each octave has the same key
2597 signature. This sets the @code{Staff.keyoctaviation} property.
2599 @item @code{\shiftoff}@keyindex{shiftOff}
2600 Disable horizontal shifting of note heads that collide.
2602 @item @code{\shiftOn}@keyindex{shiftOn}
2603 Enable note heads that collide with other note heads to be
2604 shifted horiztonally.
2606 @item @code{\slurBoth}@keyindex{slurBoth}
2607 Allow slurs to be above or below notes.
2609 @item @code{\slurDown}@keyindex{slurDown}
2610 Force slurs to be below notes.
2612 @item @code{\slurUp}@keyindex{slurUp}
2613 Force slurs to be above notes.
2615 @item @code{\specialkey}@keyindex{specialkey}
2616 Allow key signatures do differ in different octaves. This sets
2617 the @code{Staff.keyoctaviation} property.
2619 @item @code{\stemBoth}@keyindex{stemBoth}
2620 Allow stems, beams, and slurs to point either upwards or
2621 downwards, decided automatically by LilyPond.
2623 @item @code{\stemdown}@keyindex{stemdown}
2624 Force stems, beams, and slurs to point down.
2626 @item @code{\stemUp}@keyindex{stemUp}
2627 Force stems, beams and slurs to point up.
2631 @node Grobs, , , Reference Manual
2634 This section is about Grobs (short for Graphical Objects), which are
2635 formatting objects used to create the final output. This material is
2636 normally the domain of LilyPond gurus, but occasionally, a normal user
2637 also has to deal with grobs.
2639 The most simple interaction with Grobs are when you use
2643 \property Voice.Stem \override #'direction = #1
2646 This piece of lily input causes all stem objects to be stem-up
2647 henceforth. In effect, you are telling lilypond to extend the defintion
2648 of the "Stem" grob with the setting @code{direction := 1}. Of course
2649 there are many more ways of customizing Lily output, and since most of
2650 them involve Grobs in some form, this section explains some details of
2656 * Setting grob properties::
2657 * Items and Spanners::
2658 * Pointer substitution::
2661 @node What is a grob?, , , Grobs
2663 All grobs have an X and Y-position on the page. These X and Y positions
2664 are stored in a relative format, so they can easily be combined by
2665 stacking them, hanging one grob to the side of another, and coupling
2666 them into a grouping-grob.
2668 Each grob has a reference point, or parent: the position of a grob is
2669 stored relative to that reference point. For example the X-reference
2670 point of a staccato dot usually is the note head that it applies
2671 to. Whenever the note head is moved, the staccato dot moves along
2674 If you keep following offset reference points, you will always end up at
2675 the root-object. This root object is called @code{Line_of_score}
2676 @ref{(lilypond-internals)Element Line_of_score}, and it represents a
2677 system (ie. a line of music).
2679 All grobs carry a set of grob-properties. In the Stem example above,
2680 the property @code{direction} is set to value @code{1}. The function
2681 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
2682 @code{direction} to determine how to print the stem and the flag. The
2683 appearance of a grob is determined solely by the values of its
2686 Often, a grob also is associated with a symbol. On the other hand, Some
2687 grobs do not print any symbols, but take care of grouping objects. For
2688 example, there is a separate grob that stacks staffs vertically, so they
2689 are not printed in overstrike. The NoteCollision @ref{(lilypond-internals)Element
2690 NoteCollision} is another example of an abstract grob. It only moves
2691 around chords, but doesn't print anything.
2693 A complete list of grob types is found in @ref{(lilypond-internals)Elements}
2695 Grobs are created in the "Interpreting music" phase, by things in
2696 LilyPond called engravers. In this phase of the translation, a load of
2697 grobs are created, and they are linked into a giant network of objects.
2698 This network of grobs forms the "specification" of the print
2699 problem. This problem is then solved: configurations, directions,
2700 dimensions, line breaks, etc. are calculated. Finally, the printing
2701 description in the form of Molecules (@ref{Molecule}) is extracted from
2702 the network. These are then dumped into the output file
2704 @node Callbacks, , , Grobs
2706 Offsets of grobs are relative to a parent reference point. Most
2707 positions are not known when an object is created, so these are
2708 calculated as needed. This is done by adding a callback for a specific
2711 Suppose you have the following code in a .ly file.
2713 #(define (my-callback gr axis)
2714 (* 2.0 (get-gr-property grob 'direction))
2719 \property Voice.Stem \override #'Y-offset-callbacks = #(list
2723 When the Y-offset of a Stem object is needed, LilyPond will
2724 automatically execute all callbacks for that object. In this case, it
2725 will find @code{my-callback}, and execute that. The result is that the
2726 stem is translated by two staff spaces in its direction.
2728 (note: Y-offset-callbacks is also a property)
2731 Offset callbacks can be stacked, ie.
2734 \property .... \override #'Y-offset-callbacks = #(list
2735 callback1 callback2 callback3)
2739 The callbacks will be executed in the order callback3 callback2
2740 callback1. This is used for quantized positioning: the staccato dot is
2741 above or below a note head, and it must not be on a staff-line.
2743 To achieve this, for the staccato there are two callbacks: one callback
2744 that positions the grob above or below the note head, and one callback
2745 that rounds the Y-position of the grob to the nearest open space.
2747 Similarly, the size of a grob are determined through callbacks, settable
2748 with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
2749 There can be only one extent-callback for each axis. No callback (value #f)
2750 means: "empty in this direction". If you fill in a pair, that pair
2751 hard-codes the extent in that coordinate.
2754 @node Setting grob properties, , , Grobs
2756 Grob properties are stored as GUILE association lists, with symbols as
2757 keys. From C++, element properties can be accessed using the functions
2760 SCM get_grob_property (SCM) const;
2761 void set_grob_property (const char * , SCM val);
2762 void set_immutable_grob_property (const char * , SCM val);
2763 void set_immutable_grob_property (SCM key, SCM val);
2764 void set_grob_property (SCM , SCM val);
2765 void set_grob_pointer (const char*, SCM val);
2766 SCM remove_grob_property (const char* nm);
2769 In GUILE, LilyPond provides
2772 ly-get-grob-property GROB SYMBOL
2773 ly-set-grob-property GROB SYMBOL VALUE
2776 All lookup functions identify undefined properties with
2777 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
2779 Properties are stored in two ways:
2781 @item mutable properties:
2782 element properties that change from object to object. The storage of
2783 these are private to a grob. Typically this is used to store lists of
2784 pointers to other grobs
2786 @item immutable properties:
2787 element properties that are shared across different grobs of the same
2788 type. The storage is shared, and hence it is read-only. Typically, this
2789 is used to store function callbacks, and values for shared element
2790 properties are read from @file{scm/element-description.scm}.
2793 There are two ways to manually set grob properties.
2795 You can change immutable grob properties. This is done with the
2799 \property Voice.Stem \override #'direction = #1
2802 This will push the entry @code{'(direction . 1)} on the immutable
2803 property list for stems, in effect overriding the setting from
2804 @file{scm/element-description.scm}. This can be undone by
2807 \property Voice.stem \revert #'direction
2810 If you use this a lot, this gets old quickly. So we also have a
2814 \property Context.GrobType \set #'prop = #VAL
2817 this does a @code{\revert} followed by a @code{\override}
2819 The second way is \outputproperty. This construct looks like
2822 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
2825 In this case, in every grob that satisfies @var{pred}, the property
2826 assignment @var{sym} = @var{val} is done. For example
2830 #(lambda (gr) (string? (ly-get-grob-property gr
2832 #'extra-offset = #'(-1.0 . 0.0)
2835 This shifts all elements that have a @code{text} property one staff
2838 @node Items and Spanners, , , Grobs
2840 Grobs can also be distinguished in their role in the horizontal spacing.
2841 A lot of grobs define constraints on the spacing by their sizes. For
2842 example, note heads, clefs, stems, and all other symbols with a fixed
2843 shape. These grobs form a subtype called @code{Item}.
2845 Other grobs have a shape that depends on the horizontal spacing. For
2846 example, slur, beam, tie, etc. These grobs form a subtype called
2847 @code{Spanner}. All spanners have two span-points (these must be
2848 @code{Item}s), one on the left and one on the right. The left bound is
2849 also the X-reference point.
2851 Some items need special treatment for line breaking. For example, a
2852 clef is normally only printed at the start of a line (ie. after a line
2853 break). To model this, `breakable' items (clef, key signature, bar lines,
2854 etc.) are copied twice. Then we have three versions of each breakable
2855 item: one version if there is no line break, one version that is printed
2856 before the line break (at the end of a system), one version that is
2857 printed after the line break.
2859 Whether these versions are visible and take up space, is determined by
2860 the outcome of the visibility-lambda. This is a function taking a
2861 direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
2862 this grob should be transparent and invisible.
2864 @node Pointer substitution, , , Grobs
2867 @node Molecule, , , Reference Manual
2869 The objective of any typesetting system is to put ink on paper in the
2870 right places. For LilyPond, this final stage is left to the TeX and the
2871 printer subsystem. For lily, the last stage in processing a score is
2872 outputting a description of what to put where. This description roughly
2881 you merely have to look at the tex output of lily to see this.
2882 Internally these instructions are encoded in Molecules:@footnote{At some
2883 point LilyPond also contained Atom-objects, but they have been replaced
2884 by Scheme expressions.}. A molecule is an object that combines
2885 dimension information (how large is this glyph ?) with
2886 what-to-print-where.
2888 Conceptually, Molecules can be constructed from Scheme code, by
2889 translating a Molecule and by combining two molecules. In BNF notation:
2892 Molecule = COMBINE Molecule Molecule
2893 | TRANSLATE Offset Molecule
2898 (refer to the C++ code for more details). All visible,
2899 ie. non-transparent, grobs have a callback to create a Molecule. The
2900 name of the property is @code{molecule-callback}, and its value should
2901 be a Scheme function taking one argument (the grob) and returning a