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
151 A one line comment is introduced by a `@code{%}' character.
152 Block comments are started by `@code{%@{}' and ended by `@code{%@}}'.
153 They cannot be nested.
157 LilyPond contains a Scheme interpreter (the GUILE library) for
158 internal use. The interpreter is accessed by the pound sign:
160 Whereever the syntax allows Scheme expressions, you may enter one as
166 Evaluates the specified Scheme code. If this is used at toplevel, then
167 the result is discarded. Example:
169 \property Staff.TestObject \override #'symbol = #(+ 1 2)
172 (in this case, @code{\override} expects two Scheme expressions.
174 [refer appendix/ online intro on Scheme]
178 Keywords start with a backslash, followed by a number of lower case
179 alphabetic characters. These are all the keywords.
182 apply arpeggio autochange spanrequest commandspanrequest
183 simultaneous sequential accepts alternative bar breathe
184 char chordmodifiers chords clef cm consists consistsend
185 context denies duration dynamicscript elementdescriptions
186 font grace header in lyrics key mark musicalpitch
187 time times midi mm name pitchnames notes outputproperty
188 override set revert partial paper penalty property pt
189 relative remove repeat addlyrics partcombine score
190 script stylesheet skip textscript tempo translator
196 Formed from an optional minus sign followed by digits. Arithmetic
197 operations cannot be done with integers, and integers cannot be mixed
203 Formed from an optional minus sign and a sequence of digits followed
204 by a @emph{required} decimal point and an optional exponent such as
205 @code{-1.2e3}. Reals can be built up using the usual operations:
206 `@code{+}@indexcode{+}', `@code{-}@indexcode{-}', `@code{*}@indexcode{*}', and
207 `@code{/}@indexcode{/}', with parentheses for grouping.
209 A real constant can be followed by one of the dimension
212 @code{\mm}@keyindex{mm},
213 @code{\pt}@keyindex{pt}, @code{\in}@keyindex{in}, or
214 @code{\cm}@keyindex{cm}, for millimeters, points, inches and
215 centimeters, respectively. This converts the number to a real that
216 is the internal representation of dimensions.
223 Begins and ends with the `@code{"}' character. To include a `@code{"}'
224 character in a string write `@code{\"}'. Various other backslash
225 sequences have special interpretations as in the C language. A string
226 that contains no spaces can be written without the quotes. See
227 @ref{Lexical modes} for details on unquoted strings; their interpretation varies
228 depending on the situation. Strings can be concatenated with the
232 The tokenizer accepts the following commands. They have no grammatical
233 function, hence they can appear anywhere in the input.
236 \maininput@keyindex{maininput}
239 This command is used in init files to signal that the user file must
240 be read. This command cannot be used in a user file.
243 \include@keyindex{include} @var{file}
246 Include @var{file}. The argument @var{file} may be a quoted string (an
247 unquoted string will not work here!) or a string identifier. The full
248 filename including the @file{.ly} extension must be given,
251 \version@keyindex{version} @var{string} ;
254 Specify the version of LilyPond that a file was written for. The
255 argument is a version string in quotes, for example @code{"1.2.0"}.
256 This is used to detect invalid input, and to aid
257 @code{convert-ly}, a tool that automatically upgrades input files.
261 @cindex other languages
263 @node Other languages, , , Reference Manual
265 Note name definitions have been provided in various languages.
266 Simply include the language specific init file. For example:
267 `@code{\include "english.ly"}'. The available language files and the
268 names they define are:
271 Note Names sharp flat
272 nederlands.ly c d e f g a bes b -is -es
273 english.ly c d e f g a bf b -s/-sharp -f/-flat
274 deutsch.ly c d e f g a b h -is -es
275 norsk.ly c d e f g a b h -iss/-is -ess/-es
276 svenska.ly c d e f g a b h -iss -ess
277 italiano.ly do re mi fa sol la sib si -d -b
278 catalan.ly do re mi fa sol la sib si -d/-s -b
281 Pitch names can be redefined using the @code{\pitchnames} command, see
284 @cindex Lexical Modes
288 @node Lexical modes, , , Reference Manual
290 To simplify entering notes, lyrics, and chords, @emph{Lilypond} has three
291 special input modes on top of the default mode. In each mode, words
292 are identified on the input. If @code{"word"} is encountered, it is
293 treated as a string. If @code{\word} is encountered, it is treated as
294 a keyword or as an identifier. The behavior of the modes differs in
295 two ways: Different modes treat unquoted words differently, and
296 different modes have different rules for deciding what is a word.
302 At the start of parsing, @emph{Lilypond} is in Normal mode. In Normal
303 mode, a word is an alphabetic character followed by alphanumeric
304 characters. If @code{word} is encountered on the input it is
310 Note mode is introduced by the keyword
311 @code{\notes}@keyindex{notes}. In Note mode, words can only
312 contain alphabetic characters. If @code{word} is encountered,
313 LilyPond first checks for a notename of @code{word}. If no
314 notename is found, then @code{word} is treated as a string.
316 Since combinations of numbers and dots are used for indicating
317 durations, it is not possible to enter real numbers in this mode.
322 Chord mode is introduced by the keyword
323 @code{\chords}@keyindex{chords}. It is similar to Note mode, but
324 words are also looked up in a chord modifier table (containing
325 @code{maj}, @code{dim}, etc).
327 Since combinations of numbers and dots are used for indicating
328 durations, you can not enter real numbers in this mode. Dashes
329 and carets are used to indicate chord additions and subtractions,
330 so scripts can not be entered in Chord mode.
335 Lyrics mode is introduced by the keyword
336 @code{\lyrics}@keyindex{lyrics}. This mode has rules that make it
337 easy to include punctuation and diacritical marks in words. A
338 word in Lyrics mode begins with: an alphabetic character,
339 `@code{_}', `@code{?}', `@code{!}', `@code{:}', `@code{'}', the
340 control characters @code{^A} through @code{^F}, @code{^Q} through
341 @code{^W}, @code{^Y}, @code{^^}, any 8-bit character with ASCII code
342 over 127, or a two-character combination of a backslash followed
343 by one of `@code{`}', `@code{'}', `@code{"}', or
344 `@code{^}'.@footnote{The purpose of Lyrics mode is that you can
345 enter lyrics in @TeX{} format or a standard encoding without
346 needing quotes. The precise definition of this mode indeed is
347 ludicrous. This will remain so until the authors of LilyPond
348 acquire a deeper understanding of character encoding, or someone
349 else steps up to fix this.}
351 Subsequent characters of a word can be any character that is not
352 a digit and not white space. One important consequence of this
353 is that a word can end with `@code{@}}', which may be confusing if
354 you thought the closing brace was going to terminate Lyrics
355 mode.@footnote{LilyPond will issue a warning, though.} Any
356 `@code{_}' character which appears in an unquoted word is
357 converted to a space. This provides a mechanism for introducing
358 spaces into words without using quotes. Quoted words can also be
359 used in Lyrics mode to specify words that cannot be written with
360 the above rules. Here are some examples. Not all of these words
361 are printable by @TeX{}.
365 2B_||_!2B % not a word because it starts with a digit
366 ``Hello'' % not a word because it starts with `
367 _ _ _ _ % 4 words, each one a space
370 Since combinations of numbers and dots are used for indicating
371 durations, you can not enter real numbers in this mode.
374 [todo: include short table showign differences]
376 @node Types, , , Reference Manual
381 [say something about types]
383 All of the information in a LilyPond input file, is represented as a
384 Scheme value. In addition to normal Scheme data types (such as pair,
385 number, boolean, etc.), LilyPond has a number of specialized data types,
390 @item Music: see @ref{Music expressions}
392 @item Translator_def:
393 See section @ref{contextdefs} for more information
397 @item Score (TODO, smobme)
398 @item Music_output_def (TODO, smobme)
400 @item Moment (rational number)
403 LilyPond also includes some transient object types. Objects of these
404 types are built during a LilyPond run, and do not `exist' per se within
405 your input file. These objects are created as a result of your input
406 file, so you can include commands in the input to manipulate them,
407 during a lilypond run .
410 @item Grob: short for Graphical object. See @ref{Grobs}.
411 @item Molecule: device-independent paper output object,
412 including dimensions. Produced by some Grob functions
413 @item Translator: object that produces audio objects or Grobs
415 @item Font_metric: object representing a font. (Not yet user accessible.)
416 @item Audio_element: (TODO, smobme)
419 Identifiers allow objects to be assigned to names during the parse
420 stage. To assign an identifier, you use `@var{name}=@var{value}' and to
421 refer to an identifier, you preceed its name with a backslash:
422 `@code{\}@var{name}'. Identifier assignments must appear at top level
423 in the @emph{Lilypond} file. Semicolons are forbidden after assignments
424 appearing at top level but they are obligatory after assignments
425 appearing in the @code{\paper} block, see Section @ref{paper}.
427 @var{value} is any valid Scheme value or any of the input-types listed
430 An identifier can be created with any string for its name, but you
431 will only be able to refer to identifiers whose names begin with a
432 letter, being entirely alphanumeric. It is impossible to refer to an
433 identifier whose name is the same as the name of a keyword.
435 The right hand side of an identifier assignment is parsed completely
436 before the assignment is done, so it is allowed to redefine an
437 identifier in terms of its old value, e.g.
443 When an identifier is referenced, the information it points to is
444 copied. For this reason, an identifier reference must always be the
445 first item in a block.
449 \paperIdent % wrong and invalid
453 \paperIdent % correct
459 @node Music expressions, , , Reference Manual
460 @section Music expressions
462 @cindex music expressions
464 Music in @emph{Lilypond} is entered as a music expression. Notes, rests,
465 lyric syllables are music expressions (the atomic
467 @cindex atomic music expressions
468 , and you can combine
469 music expressions to form new ones. This example forms a compound
470 expressions out of the quarter @code{c} note and a @code{d}
474 \sequential @{ c4 d4 @}
477 The meaning of this compound expression is to play the `@code{c}'
478 first, and then the `@code{d}' (as opposed to playing them
479 simultaneously, for instance).
481 Atomic music expression are discussed in
482 subsection @ref{Atomic music expressions}. Compound music expressions are
483 discussed in subsection @ref{Compound music expressions}.
487 @node Atomic music expressions, , , Reference Manual
488 @section Atomic music expressions
498 The syntax for pitch specification is
502 \musicalpitch@keyindex{musicalpitch} @{ @var{octave} @var{note} @var{shift} @}
505 @var{octave} is specified by an integer, zero for the octave
506 containing middle C. @var{note} is a number from 0 to 7, with 0
507 corresponding to C and 7 corresponding to B. The shift is zero for a
508 natural, negative to add flats, or positive to add sharps.
510 In Note and Chord mode, pitches may be designated by names. See
511 section @ref{Other languages} for pitch names in different languages.
513 The syntax for duration specification is
516 \duration@keyindex{duration}
517 @{ @var{length} @var{dotcount} @}
520 @var{length} is the negative logarithm (base 2) of the duration:
521 1 is a half note, 2 is a quarter note, 3 is an eighth
522 note, etc. The number of dots after the note is given by
525 In Note, Chord, and Lyrics mode, durations may be designated by
529 @node Note specification, , , Reference Manual
531 @cindex note specification
535 @cindex entering notes
537 A note specification has the form
540 @var{pitch}[@var{octavespec}][!][?][@var{duration}]
543 The pitch of the note is specified by the note's name.
546 The default names are the Dutch note names. The notes are specified
547 by the letters `@code{c}' through `@code{b}', where `@code{c}' is an
548 octave below middle C and the letters span the octave above that C.
550 @cindex notenames!Dutch
551 a sharp is formed by adding `@code{-is}' to the end of a pitch name. A
552 flat is formed by adding `@code{-es}'. Double sharps and double flats
553 are obtained by adding `@code{-isis}' or `@code{-eses}'. `@code{aes}'
554 and `@code{ees}' are contracted to `@code{as}' and `@code{es}' in Dutch,
555 but both forms will be accepted.
557 LilyPond has predefined sets of notenames for various languages. See
558 @ref{Other languages}.
562 The optional octave specification takes the form of a series of
563 single quote (`@code{'}@indexcode{'}') characters or a series of comma
564 (`@code{,}@indexcode{,}') characters. Each @code{'} raises the pitch by one
565 octave; each @code{,} lowers the pitch by an octave.
567 @lilypond[fragment,verbatim,center]
568 c' d' e' f' g' a' b' c''
571 @lilypond[fragment,verbatim,center]
572 cis' dis' eis' fis' gis' ais' bis'
575 @lilypond[fragment,verbatim,center]
576 ces' des' es' fes' ges' as' bes'
579 @lilypond[fragment,verbatim,center]
580 cisis' eisis' gisis' aisis' beses'
583 @lilypond[fragment,verbatim,center]
584 ceses' eses' geses' ases' beses'
587 Whenever a C-sharp is desired, you must specify a C-sharp. LilyPond
588 will determine what accidentals to typeset depending on the key and
589 context. A reminder accidental
590 @cindex reminder accidental
592 forced by adding an exclamation mark `@code{!}' after the pitch. A
593 cautionary accidental,
594 @cindex cautionary accidental
596 accidental within parentheses can be obtained by adding the question
597 mark `@code{?}@indexcode{?}' after the pitch.
599 @lilypond[fragment,verbatim,center]
600 cis' d' e' cis' c'? d' e' c'!
606 Durations are entered as their reciprocal values. For notes longer
607 than a whole note, use identifiers.
613 c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64
622 \notes \relative c'' {
624 a1 a2 a4 a8 a16 a32 a64 a64
629 \remove "Clef_engraver";
630 \remove "Staff_symbol_engraver";
641 r1 r2 r4 r8 r16 r32 r64 r64
650 \notes \relative c'' {
652 r1 r2 r4 r8 r16 r32 r64 r64
655 loose_column_distance = 2.5 * \staffspace;
659 \remove "Clef_engraver";
660 \remove "Staff_symbol_engraver";
661 \remove "Bar_engraver";
668 If the duration is omitted then it is set equal to the previous
669 duration. If there is no previous duration, a quarter note is
670 assumed. The duration can be followed by a dot (`@code{.}@indexcode{.}')
671 to obtain dotted note lengths.
673 @lilypond[fragment,verbatim,center]
677 You can alter the length of duration by writing
678 `@code{*}@var{fraction}' after it. This will not affect the
679 appearance of note heads or rests.
682 Rests are entered like notes, with note name `@code{r}@indexcode{r}',
683 or `@code{R}@indexcode{R}'. There is also a note name
684 `@code{s}@indexcode{s}', which produces a space of the specified
685 duration. `@code{R}' is specifically meant for entering parts: the
686 @code{R} rest can expand to fill a score with rests, or it can be
687 printed as a single multimeasure rest.
689 You can control the expansion by setting the property
690 @code{Score.skipBars}. If this is set to true, Lily will not expand
691 empty measures, and the multimeasure rests automatically adds the
695 @cindex lyrics expressions
697 Syllables are entered like notes, with pitches replaced by text. For
698 example, `@code{Twin-4 kle4 twin-4 kle4}' enters four syllables, each
699 with quarter note duration. Note that the hyphen has no special
700 meaning for lyrics, and does not introduce special symbols. See
701 section @ref{Lexical modes} for a description of what is interpreted as
704 Spaces can be introduced into a lyric either by using quotes
705 (`@code{"}') or by using an underscore without quotes: `@code{He_could4
706 not4}'. All unquoted underscores are converted to spaces. Printing
707 lyrics is discussed in section @ref{lyricprint}.
714 \property@keyindex{property}
715 @var{contextname}.@var{propname} = @var{value}
718 Sets the @var{propname} property of the context @var{contextname} to
719 the specified @var{value}. All three arguments are strings.
720 Depending on the context, it may be necessary to quote the strings or
721 to leave space on both sides of the dot.
725 @cindex translator switches
728 \translator@keyindex{translator}
729 @var{contexttype} = @var{name}
732 A music expression indicating that the context which is a direct
733 child of the a context of type @var{contexttype} should be shifted to
734 a context of type @var{contexttype} and the specified name.
736 Usually this is used to switch staffs in Piano music, e.g.
739 \translator Staff = top @var{Music}
743 @cindex output properties
746 These allow you to tweak what is happening in the back-end
747 directly. If you want to control every detail of the output
748 formatting, this is the feature to use. The downside to this is that
749 you need to know exactly how the backend works. Example:
752 @lilypond[fragment,verbatim]
754 \context Staff \outputproperty
755 #(make-type-checker 'Note_head)
756 #'extra-offset = #'(5.0 . 7.5)
760 This selects all note heads occurring at current staff level, and sets
761 the extra-offset of those heads to (5,7.5), shifting them up and
764 Use of this feature is entirely on your own risk: if you use this, the
765 result will depend very heavily on the implementation of the backend,
766 which we change regularly and unscrupulously.
771 Commands are music expressions that have no duration.
776 @code{\key}@keyindex{key} @var{pitch} @var{type} @code{;}
779 Change the key signature. @var{type} should be
780 @code{\major}@keyindex{major} or @code{\minor}@keyindex{minor} to get
781 @var{pitch}-major or @var{pitch}-minor, respectively. The second
782 argument is optional; the default is major keys. The @var{\context}
783 argument can also be given as an integer, which tells the number of
784 semitones that should be added to the pitch given in the subsequent
785 @code{\key}@keyindex{key} commands to get the corresponding major key,
786 e.g., @code{\minor}@keyindex{minor} is defined as 3. The standard
787 mode names @code{\ionian}@keyindex{ionian},
788 @code{\locrian}@keyindex{locrian}, @code{\aeolian}@keyindex{aeolian},
789 @code{\mixolydian}@keyindex{mixolydian}, @code{\lydian}@keyindex{lydian},
790 @code{\phrygian}@keyindex{phrygian}, and @code{\dorian}@keyindex{dorian}
794 @code{\keysignature}@keyindex{keysignature} @var{pitchseq} @code{;}
797 Specify an arbitrary key signature. The pitches from @var{pitch} will
798 be printed in the key signature in the order that they appear on the
802 \mark@keyindex{mark} @var{unsigned};
806 Prints a mark over or under the staff. You must add
807 @code{Mark_engraver}@indexcode{Mark_engraver} to the Score context for
810 @node barlines, , , Reference Manual
813 \bar@keyindex{bar} @var{bartype};
816 This is a short-cut for doing
818 \property Score.whichBar = @var{bartype}
821 You are encouraged to use @code{\repeat} for repetitions. See
822 @ref{Repeats}, and the documentation of @code{whichBar}.
826 \time@keyindex{time} @var{numerator}@code{/}@var{denominator} @code{;}
829 A short-cut for doing
831 \property Score.timeSignatureFraction = #'(@var{numerator} . @var{denominator})
834 See the documentation of @code{timeSignatureFraction}
838 \tempo@keyindex{tempo} @var{duration} = @var{perminute} @code{;}
841 Used to specify the tempo. For example, `@code{\tempo 4 = 76;}'
842 requests output with 76 quarter notes per minute.
845 \partial@keyindex{partial} @var{duration} @code{;}
851 \property Score.measurePosition = @var{length of duration}
854 See the documentation of @code{measurePosition}.
862 @code{|}@indexcode{|}
867 @cindex shorten measures
871 `@code{|}' is a bar check. Whenever a bar check is encountered during
872 interpretation, a warning message is issued if it doesn't fall at a
873 measure boundary. This can help you finding errors in the input.
874 Depending on the value of @code{barCheckNoSynchronize}
875 @indexcode{barCheckNoSynchronize} The beginning of the measure will be
876 relocated, so this can also be used to shorten measures.
881 \penalty@keyindex{penalty} @var{int} @code{;}
884 Discourage or encourage line breaks. See identifiers
885 @code{\break}@keyindex{break} and @code{\nobreak}@keyindex{nobreak} in
886 section [on identifiers] [FIXME].
889 \clef@keyindex{clef} @var{clefname} @code{;}
895 \property Clef.clefGlyph = @var{symbol associated with clefname}
896 \property Clef.clefPosition = @var{clef Y-position for clefname}
897 \property Clef.clefOctavation = @var{extra pitch of clefname}
900 Supported clef-names include
906 \skip@keyindex{skip} @var{duration} @code{;}
909 Skips the amount of time specified by @var{duration}. If no other
910 music is played, a gap will be left for the skipped time with no
911 notes printed. It works in Note Mode or Lyrics Mode. In Note mode,
912 this has the same effect as the space rest `@code{s}'.
917 @node Manual beams, , , Reference Manual
919 A beam is specified by surrounding the beamed notes with brackets
920 `@code{[}@indexcode{[}' and `@code{]}@indexcode{]}'.
922 @lilypond[fragment,verbatim,center]
923 [a'8 a'] [a'16 a' a' a']
926 Some more elaborate constructions:
928 @lilypond[fragment,verbatim,center]
929 [a'16 <a' c''> c'' <a' c''>]
930 \times 2/3 { [e'8 f' g'] }
933 Beaming can be generated automatically; see section @ref{autobeam}.
937 To place tremolo marks between notes, use @code{\repeat} with tremolo
939 @cindex tremolo beams
940 To create tremolo beams on a single note, simply attach
941 `@code{:}@var{length}' to the note itself.
943 @lilypond[fragment,verbatim,center]
944 \repeat "tremolo" 8 { c16 d16 }
945 \repeat "tremolo" 4 { c16 d16 }
948 @lilypond[fragment,verbatim,center]
953 @cindex --@@@code{-}@code{-}
961 The syntax for an extender mark is `@code{__}'. This syntax can only
962 be used within lyrics mode. The syntax for a spanning hyphen (i.e.,
963 a hyphen that will be printed between two lyric syllables) is
969 A tie connects two adjacent note heads of the same pitch. When used
970 with chords, it connects all of the note heads whose pitches match.
971 Ties are indicated using the tilde symbol `@code{~}@indexcode{~}'.
972 If you try to tie together chords which have no common pitches, a
973 warning message will appear and no ties will be created.
975 @lilypond[fragment,verbatim,center]
976 e' ~ e' <c' e' g'> ~ <c' e' g'>
981 [TODO: explain Requests]
984 @cindex articulations
990 A variety of symbols can appear above and below notes to indicate
991 different characteristics of the performance. These symbols can be
992 added to a note with `@var{note}@code{-\}@var{name}'. Numerous symbols
993 are defined in @file{script.ly} and @file{script.scm}. Symbols can be
994 forced to appear above or below the note by writing
995 `@var{note}@code{^\}@var{name}' and `@var{note}@code{_\}@var{name}'
996 respectively. Here is a chart showing symbols above notes, with the
997 name of the corresponding symbol appearing underneath.
1003 c''-\accent c''-\marcato c''-\staccatissimo c''-\fermata
1004 c''-\stopped c''-\staccato c''-\tenuto c''-\upbow
1005 c''-\downbow c''^\lheel c''-\rheel c''^\ltoe
1006 c''-\rtoe c''-\turn c''-\open c''-\flageolet
1007 c''-\reverseturn c''-\trill c''-\prall c''-\mordent
1008 c''-\prallprall c''-\prallmordent c''-\upprall c''-\downprall
1009 c''-\thumb c''-\segno c''-\coda
1011 \context Lyrics \lyrics {
1012 accent__ marcato__ staccatissimo__ fermata
1013 stopped__ staccato__ tenuto__ upbow
1014 downbow__ lheel__ rheel__ ltoe
1015 rtoe__ turn__ open__ flageolet
1016 reverseturn__ trill__ prall__ mordent
1017 prallprall__ prallmordent__ uprall__ downprall
1018 thumb__ segno__ coda
1022 linewidth = 5.875\in;
1029 In addition, it is possible to place arbitrary strings of text or
1030 @TeX{} above or below notes by using a string instead of an
1031 identifier: `@code{c^"text"}'. Fingerings
1034 placed by simply using digits. All of these note ornaments appear in
1035 the printed output but have no effect on the MIDI rendering of the
1038 To save typing, fingering instructions (digits 0 to 9 are
1039 supported) and single characters shorthands exist for a few
1046 \property Voice.textStyle = typewriter
1052 c''4-^_"c-\\^{ }" s4
1059 linewidth = 5.875 \in;
1066 Dynamic marks are specified by using an identifier after a note:
1067 `@code{c4-\ff}' (the dash is optional for dynamics: `@code{c4 \ff})'.
1068 The available dynamic marks are:
1069 @code{\ppp}@keyindex{ppp},
1070 @code{\pp}@keyindex{pp}, @code{\p}@keyindex{p}, @code{\mp}@keyindex{mp},
1071 @code{\mf}@keyindex{mf}, @code{\f}@keyindex{f}, @code{\ff}@keyindex{ff},
1072 @code{\fff}@keyindex{fff}, @code{\fff}@keyindex{ffff},
1073 @code{\fp}@keyindex{fp}, @code{\sf}@keyindex{sf},
1074 @code{\sff}@keyindex{sff}, @code{\sp}@keyindex{sp},
1075 @code{\spp}@keyindex{spp}, @code{\sfz}@keyindex{sfz}, and
1076 @code{\rfz}@keyindex{rfz}.
1081 \textscript@keyindex{textscript} @var{text} @var{style}
1084 Defines a text to be printed over or under a note. @var{style} is a
1085 string that may be one of @code{roman}, @code{italic}, @code{typewriter},
1086 @code{bold}, @code{Large}, @code{large}, @code{dynamic} or @code{finger}.
1088 You can attach a general textscript request using this syntax:
1093 c4-\textscript "6" "finger"
1094 c4-\textscript "foo" "normal"
1099 This is equivalent to `@code{c4-6 c4-"foo"}'.
1106 \script@keyindex{script} @var{alias}
1109 Prints a symbol above or below a note. The argument is a string
1110 which points into the script-alias table defined in @file{script.scm}.
1111 The scheme definitions specify whether the symbol follows notes into
1112 the staff, dependence of symbol placement on staff direction, and a
1113 priority for placing several symbols over one note. Usually the
1114 @code{\script}@keyindex{script} keyword is not used directly. Various
1115 helpful identifier definitions appear in @file{script.ly}.
1120 Slurs connects chords and try to avoid crossing stems. A slur is
1121 started with `@code{(}' and stopped with `@code{)}'. The
1122 starting `@code{(}' appears to the right of the first note in
1123 the slur. The terminal `@code{)}' appears to the left of the
1124 first note in the slur. This makes it possible to put a note in
1125 slurs from both sides:
1127 @lilypond[fragment,verbatim,center]
1128 f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
1134 A crescendo mark is started with @code{\cr}@keyindex{cr} and terminated
1135 with @code{\rc}@keyindex{rc}. A decrescendo mark is started with
1136 @code{\decr}@keyindex{decr} and terminated with
1137 @code{\rced}@keyindex{rced}. There are also shorthands for these
1138 marks. A crescendo can be started with @code{\<}@keyindex{<} and a
1139 decrescendo can be started with @code{\>}@keyindex{>}. Either one can
1140 be terminated with @code{\!}@keyindex{"!}. Note that @code{\!}
1141 must go before the last note of the dynamic mark whereas @code{\rc}
1142 and @code{\rced} go after the last note. Because these marks are
1143 bound to notes, if you want to get several marks during one note, you
1144 must use spacer notes.
1146 @lilypond[fragment,verbatim,center]
1147 c'' \< \! c'' d'' \decr e'' \rced
1148 < f''1 { s4 \< \! s2 \> \! s4 } >
1154 \spanrequest@keyindex{spanrequest} @var{startstop} @var{type}
1157 Define a spanning request. The @var{startstop} parameter is either -1
1158 (@code{\start}@keyindex{start}) or 1 (@code{\stop}@keyindex{stop}) and
1159 @var{type} is a string that describes what should be started.
1160 Supported types are @code{crescendo}, @code{decrescendo},
1161 @code{beam}, @code{slur}. This is an internal command. Users should
1162 use the shorthands which are defined in the initialization file
1165 You can attach a (general) span request to a note using
1167 @lilypond[fragment,verbatim,center]
1168 c'4-\spanrequest \start "slur"
1169 c'4-\spanrequest \stop "slur"
1172 The slur syntax with parentheses is a shorthand for this.
1176 @cindex tremolo marks
1178 @node stem tremolo, , , Reference Manual
1180 Tremolo marks can be printed on a single note by adding
1181 `@code{:}[@var{length}]' after the note. The length must be at
1182 least 8. A @var{length} value of 8 gives one line across
1183 the note stem. If the length is omitted, then the last value is
1184 used, or the value of the @code{tremoloFlags}@indexcode{tremoloFlags} property if there was
1187 @lilypond[verbatim,fragment,center]
1193 @node Compound music expressions, , , Reference Manual
1194 @section Compound music expressions
1196 @cindex compound music expressions
1198 Music expressions are compound data structures. You can nest music
1199 expressions any way you like. This simple example shows how three
1200 chords can be expressed in two different ways:
1202 @lilypond[fragment,verbatim,center]
1203 \notes \context Staff {
1205 <a c'> <b d' > <c' e'>
1206 < { a b c' } { c' d' e' } >
1210 @cindex context selection
1211 @c @keyindex{context}
1214 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
1217 Interpret @var{musicexpr} within a context of type @var{contexttype}.
1218 If the context does not exist, it will be created. The new context
1219 can optionally be given a name.
1225 Mode switching keywords form compound music expressions: @code{\notes}
1226 @keyindex{notes} @var{musicexpr}, @code{\chords} @keyindex{chords}
1227 @var{musicexpr}, and @code{\lyrics} @keyindex{lyrics} @var{musicexpr}.
1228 These expressions do not add anything to the meaning of their
1229 arguments. They are just a way to indicate that the arguments should
1230 be parsed in indicated mode. See @ref{Lexical modes} for more
1231 information on modes.
1233 @cindex sequential music
1239 \sequential@keyindex{sequential}
1240 @code{@{} @var{musicexprlist} @code{@}}
1243 This means that list should be played or written in sequence, i.e.,
1244 the second after the first, the third after the second. The duration
1245 of sequential music is the the sum of the durations of the elements.
1246 There is a shorthand, which leaves out the keyword:
1250 @code{@{} @var{musicexprlist} @code{@}}
1255 @cindex simultaneous music
1262 \simultaneous@keyindex{simultaneous}
1263 @code{@{} @var{musicexprlist} @code{@}}
1266 It constructs a music expression where all of its arguments start at
1267 the same moment. The duration is the maximum of the durations of the
1268 elements. The following shorthand is a common idiom:
1272 @code{<} @var{musicexprlist} @code{>}
1275 If you try to use a chord as the first thing in your score, you might
1276 get multiple staffs instead of a chord.
1278 @lilypond[verbatim,center]
1287 This happens because the chord is interpreted by a score context.
1288 Each time a note is encountered a default Voice context (along with a
1289 Staff context) is created. The solution is to explicitly instantiate
1292 @lilypond[verbatim,center]
1294 \notes\context Voice <c''4 e''>
1303 @cindex relative pitch specification
1305 @node relative, , , Reference Manual
1307 It is easy to get confused by octave changing marks and accidentally
1308 putting a pitch in the wrong octave. A much better way of entering a
1309 note's octave is `the relative octave' mode.
1313 \relative@keyindex{relative} @var{startpitch} @var{musicexpr}
1316 The octave of notes that appear in @var{musicexpr} are calculated as
1317 follows: If no octave changing marks are used, the basic interval
1318 between this and the last note is always taken to be a fourth or
1319 less.@footnote{The interval is determined without regarding
1320 accidentals. A @code{fisis} following a @code{ceses} will be put above
1321 the @code{ceses}.} The octave changing marks `@code{'}' and `@code{,}'
1322 can then be added to raise or lower the pitch by an extra octave.
1323 Upon entering relative mode, an absolute starting pitch must be
1324 specified that will act as the predecessor of the first note of
1327 Entering scales is straightforward in relative mode.
1329 @lilypond[fragment,verbatim,center]
1335 And octave changing marks are used for intervals greater than a fourth.
1337 @lilypond[fragment,verbatim,center]
1339 c g c f, c' a, e'' }
1342 If the preceding item is a chord, the first note of the chord is used
1343 to determine the first note of the next chord. But other notes
1344 within the second chord are determined by looking at the immediately
1347 @lilypond[fragment,verbatim,center]
1355 The pitch after the @code{\relative} contains a notename. To parse
1356 the pitch as a notename, you have to be in note mode, so there must
1357 be a surrounding @code{\notes}@keyindex{notes} keyword (which is not
1360 The relative conversion will not affect @code{\transpose} or
1361 @code{\relative} sections in its argument. If you want to use
1362 relative within transposed music, you must place an additional
1363 @code{\relative} inside the @code{\transpose}.
1365 It is strongly recommended to use relative pitch mode: less work,
1366 less error-prone, and more readable.
1370 Chord names are a way to generate simultaneous music expressions that
1371 correspond with traditional chord names. It can only be used in
1372 Chord mode (see section @ref{Lexical modes}).
1376 @var{tonic}[@var{duration}][@code{-}@var{modifiers}][@code{^}@var{subtractions}][@code{/}@var{inversion}][@code{/+}@var{bass}].
1379 @var{tonic} should be the tonic note of the chord, and @var{duration}
1380 is the chord duration in the usual notation. There are two kinds of
1381 modifiers. One type is @emph{chord additions}, which are obtained by
1382 listing intervals separated by dots. An interval is written by its
1383 number with an optional `@code{+}' or `@code{-}' to indicate raising or
1384 lowering by half a step. Chord additions has two effects: It adds
1385 the specified interval and all lower odd numbered intervals to the
1386 chord, and it may lower or raise the specified interval. Intervals
1387 must be separated by a dot (`@code{.}').
1391 @lilypond[fragment,verbatim]
1395 c:9 c:9-.5+.7+ c:3-.5- c:4.6.8
1402 The second type of modifier that may appear after the `@code{:}' is a
1403 named modifier. Named modifiers are listed in the file
1404 @file{chord-modifiers.ly}. The available modifiers are `@code{m}' and
1405 `@code{min}' which lower the 3rd half a step, `@code{aug}@indexcode{aug}' which
1406 raises the 5th, `@code{dim}@indexcode{dim}' which lowers the 5th,
1407 `@code{maj}@indexcode{maj}' which adds a raised 7th, and `@code{sus}@indexcode{sus}'
1408 which replaces the 5th with a 4th.
1412 @lilypond[fragment,verbatim]
1415 c1:m c:min7 c:maj c:aug c:dim c:sus
1423 Chord subtractions are used to eliminate notes from a chord. The
1424 notes to be subtracted are listed after a `@code{^}' character,
1427 @lilypond[fragment,verbatim,center]
1435 Chord inversions can be specified by appending `@code{/}@indexcode{/}' and
1436 the name of a single note to a chord. This has the effect of
1437 lowering the specified note by an octave so it becomes the lowest
1438 note in the chord. If the specified note is not in the chord, a
1439 warning will be printed.
1441 @lilypond[fragment,verbatim,center]
1450 Bass notes can be added by `@code{/+}@indexcode{/+}' and
1451 the name of a single note to a chord. This has the effect of
1452 adding the specified note to the chord, lowered by an octave,
1453 so it becomes the lowest note in the chord.
1455 @lilypond[fragment,verbatim,center]
1464 Throughout these examples, chords have been shifted around the staff
1465 using @code{\transpose}.
1467 You should not combine @code{\relative} with named chords.
1473 Tuplets are made out of a music expression by multiplying their
1474 duration with a fraction.
1478 \times@keyindex{times} @var{fraction} @var{musicexpr}
1481 The duration of @var{musicexpr} will be multiplied by the fraction.
1482 In print, the fraction's denominator will be printed over the notes,
1483 optionally with a bracket. The most common tuplet is the triplet in
1484 which 3 notes have the length of 2, so the notes are 2/3 of
1485 their written length:
1487 @lilypond[fragment,verbatim,center]
1488 g'4 \times 2/3 {c'4 c' c'} d'4 d'4
1497 \grace@keyindex{grace} @var{musicexpr}
1500 A grace note expression has duration 0; the next real note is
1501 assumed to be the main note.
1503 You cannot have the grace note after the main note, in terms of
1504 duration, and main notes, but you can typeset the grace notes to the
1505 right of the main note using the property
1506 @code{graceAlignPosition}@indexcode{graceAlignPosition}.
1508 When grace music is interpreted, a score-within-a-score is set up:
1509 @var{musicexpr} has its own time bookkeeping, and you could (for
1510 example) have a separate time signature within grace notes. While in
1511 this score-within-a-score, you can create notes, beams, slurs, etc.
1512 Unbeamed eighth notes and shorter by default have a slash through the
1513 stem. This behavior can be controlled with the
1514 @code{flagStyle}@indexcode{flagStyle} property.
1518 @lilypond[fragment,verbatim]
1520 \grace c8 c4 \grace { [c16 c16] } c4
1521 \grace { \property Grace.flagStyle = "" c16 } c4
1527 At present, nesting @code{\grace}@keyindex{grace} notes, e.g.
1531 @code{\grace @{ \grace c32 c16 @} c4}
1534 may result in run-time errors of LilyPond. Since the meaning of such
1535 a construct is unclear, we don't consider this a loss. Similarly,
1536 juxtaposing two @code{\grace} sections is syntactically valid, but
1537 makes no sense and may cause runtime errors.
1539 Ending a staff or score with grace notes may also generate a run-time
1540 error, since there will be no main note to attach the grace notes to.
1546 @node Repeats, , , Reference Manual
1548 In order to specify repeats, use the @code{\repeat}@keyindex{repeat}
1549 keyword. Since repeats look and sound differently when played or
1550 printed, there are a few different variants of repeats.
1554 Repeated music is fully written (played) out. Useful for MIDI
1558 This is the normal notation: Repeats are not written out, but
1559 alternative endings (voltas) are printed, left to right.
1562 Alternative endings are written stacked, which is useful for
1566 The syntax for repeats is
1570 \repeat @var{variant} @var{repeatcount} @var{repeatbody}
1573 If you have alternative endings, you may add
1577 \alternative@keyindex{alternative}
1578 @code{@{} @var{alternative1}
1580 @var{alternative3} @dots{} @code{@}}
1583 where each @var{alternative} is a Music expression.
1585 Normal notation repeats are used like this:
1589 @lilypond[fragment,verbatim]
1591 \repeat volta 2 { c'4 d' e' f' }
1592 \repeat volta 2 { f' e' d' c' }
1597 With alternative endings:
1601 @lilypond[fragment,verbatim]
1603 \repeat volta 2 {c'4 d' e' f'}
1604 \alternative { {d'2 d'} {f' f} }
1609 Folded repeats look like this:@footnote{Folded repeats offer little
1610 more over simultaneous music. However, it is to be expected that
1611 more functionality -- especially for the MIDI backend -- will be
1616 @lilypond[fragment,verbatim]
1618 \repeat fold 2 {c'4 d' e' f'}
1619 \alternative { {d'2 d'} {f' f} }
1626 @lilypond[fragment,verbatim]
1630 \repeat volta 2 { e | c2 d2 | e2 f2 | }
1631 \alternative { { g4 g g } { a | a a a a | b1 } }
1638 If you don't give enough alternatives for all of the repeats, then
1639 the first alternative is assumed to be repeated often enough to equal
1640 the specified number of repeats.
1644 @lilypond[fragment,verbatim]
1647 \repeat volta 3 { \partial 4; e | c2 d2 | e2 f2 | }
1648 \alternative { { g4 g g }
1649 {\partial 1; e4 e e }
1650 {\partial 1; a a a a | b1 } }
1657 It is possible to nest @code{\repeat}. This is not entirely
1658 supported: the notes will come be in the right places, but the repeat
1663 @cindex transposition of pitches
1665 @node transpose, , , Reference Manual
1667 A music expression can be transposed with
1668 @code{\transpose}@keyindex{transpose}. The syntax is
1672 \transpose @var{pitch} @var{musicexpr}
1675 This means that middle C in @var{musicexpr} is transposed to
1678 @code{\transpose} distinguishes between enharmonic pitches: both
1679 @code{\transpose cis'} or @code{\transpose des'} will transpose up half
1680 a tone. The first version will print sharps and the second version
1685 @lilypond[fragment,verbatim]
1688 { \key e \major; c d e f }
1690 \transpose des'' { \key e \major; c d e f }
1691 \transpose cis'' { \key e \major; c d e f }
1697 If you want to use both @code{\transpose} and @code{\relative}, then
1698 you must use @code{\transpose} first. @code{\relative} will have no
1699 effect music that appears inside a @code{\transpose}.
1703 @cindex automatic lyric durations
1705 If you have lyrics that are set to a melody, you can import the
1706 rhythm of that melody into the lyrics using @code{\addlyrics}.
1707 @keyindex{addlyrics} The syntax for this is
1711 \addlyrics @var{musicexpr1 musicexpr2}
1714 This means that both @var{musicexpr1} and @var{musicexpr2} are
1715 interpreted, but that every non-command atomic music expression
1716 (``every syllable'') in @var{musicexpr2} is interpreted using timing
1717 of @var{musicexpr1}.
1719 If the property @code{automaticMelismata}@indexcode{automaticMelismata} is set in the
1720 context of @var{musicexpr1}, no lyrics will be put on slurred or tied
1725 @lilypond[verbatim,fragment]
1728 \property Voice.automaticMelismata = ##t
1729 c8 () cis d8. e16 f2
1731 \context Lyrics \lyrics {
1737 You should use a single rhythm melody, and single rhythm lyrics (a
1738 constant duration is the obvious choice). If you do not, you will get
1739 undesired effects when using multiple stanzas:
1743 @lilypond[verbatim,fragment]
1746 c8 () cis d8. e16 f2
1748 \context Lyrics \lyrics
1755 It is valid (but probably not very useful) to use notes instead of
1756 lyrics for @var{musicexpr2}.
1761 @node Ambiguities, , , Reference Manual
1762 @section Ambiguities
1766 The grammar contains a number of ambiguities.@footnote{The authors
1767 hope to resolve them at a later time.}
1770 @item The assignment
1776 can be interpreted as making a string identifier @code{\foo}
1777 containing @code{"bar"}, or a music identifier @code{\foo}
1778 containing the syllable `bar'.
1780 @item The assignment
1786 can be interpreted as making an integer identifier
1787 containing -6, or a Request identifier containing the
1788 fingering `6' (with neutral direction).
1790 @item If you do a nested repeat like
1802 then it is ambiguous to which @code{\repeat} the
1803 @code{\alternative} belongs. This is the classic if-then-else
1804 dilemma. It may be solved by using braces.
1806 @item (an as yet unidentified ambiguity :-)
1811 @node Notation conversion specifics, , , Reference Manual
1812 @section Notation conversion specifics
1816 @cindex automatic beam generation
1818 @node autobeam, , , Reference Manual
1820 By default, LilyPond will generate beams automatically. This feature
1821 can be disabled by setting the @code{Voice.noAutoBeaming}@indexcode{Voice.noAutoBeaming}
1822 property to 1. It can be overridden for specific cases by
1823 specifying explicit beams.
1826 A large number of Voice properties are used to decide how to generate
1827 beams. Their default values appear in @file{auto-beam-settings.ly}.
1828 In general, beams can begin anywhere, but their ending location is
1829 significant. Beams can end on a beat, or at durations specified by
1830 the @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} property. To end beams every
1831 quarter note, for example, you could set
1832 @code{Voice.beamAutoEnd}@indexcode{Voice.beamAutoEnd} equal to `@code{"1/4"}'. To end beams
1833 at every three eighth notes you would set it to `@code{"3/8"}'. The
1834 same syntax can be used to specify beam starting points using
1835 @code{Voice.beamAutoBegin}@indexcode{Voice.beamAutoBegin}.
1837 To allow different settings for different time signatures, these
1838 property names can start with `@code{time}@var{N}@code{_}@var{M}' to
1839 restrict the definition to `@var{N}@code{/}@var{M}' time. For example,
1840 to specify beams ending only for 6/8 time you would use the
1841 property @code{Voice.time6_8beamAutoEnd}. To allow different endings
1842 for notes of different durations, the duration can be tacked onto the
1843 end of the property. To specify beam endings for beams that contain
1844 32nd notes, you would use @code{Voice.beamAutoEnd_32}.
1852 @cindex printing!chord names
1854 For displaying printed chord names, use the @code{ChordNames}@indexcode{ChordNames}
1855 and @code{ChordNameVoice}@indexcode{ChordNameVoice} contexts. The chords may be entered
1856 either using the notation described above, or directly using
1861 @lilypond[fragment,verbatim]
1863 \context ChordNames {
1864 \chords{a b c} \notes{<d f g> <e g b>}
1866 \context Staff \notes {
1874 LilyPond examines chords specified as lists of notes to determine a
1875 name to give the chord. By default, LilyPond will not try to
1876 identify chord inversions:
1878 @lilypond[fragment,verbatim,center]
1880 \context ChordNameVoice \notes {
1883 \context Thread \notes {
1889 If you want inversions to be recognized, you must set the property
1890 @code{ChordNames.chordInversion}@indexcode{ChordNames.chordInversion}:
1892 @lilypond[fragment,verbatim,center]
1894 \property Score.chordInversion = ##t
1895 \context ChordNameVoice \notes {
1898 \context Thread \notes {
1908 @cindex printing!lyrics
1910 @node lyricprint, , , Reference Manual
1912 Lyric syllables must be interpreted within a @code{Lyrics} context
1914 @cindex context!Lyrics
1917 Here is a full example:
1924 \notes \transpose c'' {
1926 e f g2 | e4 f g2 \bar "|.";
1928 \context Lyrics \lyrics {
1929 Va-4 der Ja- cob Va- der Ja- cob
1930 Slaapt gij nog?2 Slaapt4 gij nog?2
1938 You may want a continuous line after the syllables to show melismata.
1939 To achieve this effect, add a `@code{__}' lyric as a separate word
1940 after the lyric to be extended. This will create an extender, a line
1941 that extends over the entire duration of the lyric. This line will
1942 run all the way to the start of the next lyric, so you may want to
1943 shorten it by using a blank lyric (using `@code{_}').
1950 \notes \relative c'' {
1951 a4 () b () c () d | c () d () b () a | c () d () b () a
1953 \context Lyrics \lyrics {
1954 foo1 __ | bar2. __ _4 | baz1 __
1963 If you want to have hyphens centered between syllables (rather than
1964 attached to the end of the first syllable) you can use the special
1965 `@code{-}@code{-}' lyric as a separate word between syllables. This
1966 will result in a hyphen which length varies depending on the space
1967 between syllables, and which will be centered between the syllables.
1975 \notes \transpose c'' {
1977 e f g2 | e4 f g2 \bar "|.";
1979 \context Lyrics \lyrics {
1980 Va4 -- der Ja -- cob | Va -- der Ja -- cob |
1981 Slaapt gij nog?2 | Slaapt4 gij nog?2
1991 @node Notation Contexts, , , Reference Manual
1992 @section Notation Contexts
1994 @cindex notation contexts
1996 Notation contexts are objects that only exist during a run of
1997 LilyPond. During the interpretation phase of LilyPond, the Music
1998 expression contained in a @code{\score} block is interpreted in time
1999 order. This is the order in which humans read, play, and write
2002 A context is an object that holds the reading state of the
2003 expression; it contains information like
2006 @item What notes are playing at this point?
2007 @item What symbols will be printed at this point?
2008 @item In what style will they printed?
2009 @item What is the current key signature, time signature, point within
2013 Contexts are grouped hierarchically: A @code{Voice} context is
2014 contained in a @code{Staff} context (because a staff can contain
2015 multiple voices at any point), a @code{Staff} context is contained in
2016 a @code{Score}, @code{StaffGroup}, or @code{ChoirStaff} context (because
2017 these can all contain multiple staffs).
2019 Contexts associated with sheet music output are called @emph{notation
2020 contexts}, those for sound output are called playing contexts.
2022 Contexts are created either manually or automatically. Initially,
2023 the top level music expression is interpreted by the top level
2024 context (the @code{Score} context). When a atomic music expression
2025 (i.e. a note, a rest, @code{\bar}, or @code{\time} commands), a nested
2026 set of contexts is created that can process these atomic expressions,
2032 \score @{ \notes < c4 > @}
2037 The sequential music, `@code{@{ c4 @}}' is interpreted by @code{Score}
2038 context. When the note `@code{c4}' itself is interpreted, a set of
2039 contexts is needed that will accept notes. The default for this is a
2040 @code{Voice} context, contained in a @code{Staff} context. Creation of
2041 these contexts results in the staff being printed.
2046 You can also create contexts manually, and you probably have to do so
2047 if you want to typeset complicated multiple part material. If a
2048 `@code{\context} @var{name} @var{musicexpr}' expression is encountered
2049 during the interpretation phase, the @var{musicexpr} argument will be
2050 interpreted with a context of type @var{name}. If you specify a name,
2051 the specific context with that name is searched.
2053 If a context of the specified type and name can not be found, a new
2054 one is created. For example,
2060 \notes \relative c'' {
2061 c4 <d4 \context Staff = "another" e4> f
2068 In this example, the @code{c} and @code{d} are printed on the
2069 default staff. For the @code{e}, a context Staff called
2070 `@code{another}' is specified; since that does not exist, a new
2071 context is created. Within @code{another}, a (default) Voice context
2072 is created for the @code{e4}. When all music referring to a
2073 context is finished, the context is ended as well. So after the
2074 third quarter, @code{another} is removed.
2076 Almost all music expressions inherit their interpretation context
2077 from their parent. In other words, suppose that the syntax for a
2082 \keyword @var{musicexpr1} @var{musicexpr2} @dots{}
2085 When the interpretation of this music expression starts, the context
2086 for @var{musicexpr1}, @var{musicexpr2}, etc. is that of the total
2089 Lastly, you may wonder, why this:
2095 \notes \relative c'' @{
2103 doesn't result in this:
2108 \notes \relative c'' {
2115 For the @code{c4}, a default @code{Staff} (with a contained
2116 @code{Voice}) context is created. After the @code{c4} ends, no
2117 music refers to this default staff, so it would be ended, with the
2118 result shown. To prevent this inconvenient behavior, the context to
2119 which the sequential music refers is adjusted during the
2120 interpretation. So after the @code{c4} ends, the context of the
2121 sequential music is also the default @code{Voice} context.
2122 The @code{d4} gets interpreted in the same context
2127 These are the contexts supplied with the package. They are defined
2128 in the initialization file @file{ly/engraver.ly}.
2135 Properties that are set in one context are inherited by all of the
2136 contained contexts. This means that a property valid for the
2137 @code{Voice} context can be set in the @code{Score} context (for
2138 example) and thus take effect in all @code{Voice} contexts.
2140 Properties can be preset within the @code{\translator} block
2141 corresponding to the appropriate context. In this case, the syntax
2146 @var{propname} @code{=} @var{value}
2149 This assignment happens before interpretation starts, so a
2150 @code{\property} expression will override any predefined settings.
2152 The @code{\property} expression will create any property you specify.
2153 There is no guarantee that a property will be used. So if you spell
2154 a property name wrong, there will be no error message.
2156 The property settings are used during the interpretation phase. They
2157 are read by the LilyPond modules where interpretation contexts are
2158 built of. These modules are called @emph{translators}. Translators for
2159 notation are called @emph{engravers}, and translators for sound are
2160 called @emph{performers}.
2162 The precise result of a property is determined by the implementation
2163 of the translator that reads them. Therefore, the result of a
2164 property can vary, since it is implementation and configuration
2167 In order to fully find out what properties are used, you must
2168 currently search the source code for calls to @code{get_property}.
2169 The rest of the section is devoted to an (incomplete) overview of
2170 available properties.
2172 @mbinclude properties.itely
2174 @node Notation output definitions, , , Reference Manual
2175 @section Notation output definitions
2179 @cindex notation output
2181 @cindex output definition
2183 @node paper, , , Reference Manual
2185 The most important output definition is the @code{\paper} block, for
2186 music notation. The syntax is
2190 @code{\paper @{} [@var{paperidentifier}] @var{items} @code{@}}
2193 where each of the items is one of
2196 @item An assignment. The assignment must be terminated by a
2199 @item A context definition. See section @ref{contextdefs} for
2200 more information on context definitions.
2205 A margin shape declaration. The syntax is
2209 \shape @var{indent1}@code{,} @var{width1}@code{,}
2210 @var{indent2}@code{,} @var{width2} @dots{} @code{;}
2215 Each pair of @var{indent} and @var{width} values is a dimension
2216 specifying how far to indent and how wide to make the line.
2217 The indentation and width of successive lines are specified by
2218 the successive pairs of dimensions. The last pair of
2219 dimensions will define the characeristics of all lines beyond
2220 those explicitly specified.
2222 @item \stylesheet declaration. Its syntax is
2225 \stylesheet @var{scm}
2229 See font.scm for details of @var{scm}
2234 @cindex changing font size and paper size
2236 The Feta font provides musical symbols at six different sizes. These
2237 fonts are 11 point, 13 point, 16 point, 20 point,
2238 23 point, and 26 point. The point size of a font is the
2239 height of the five lines in a staff when displayed in the font.
2241 Definitions for these sizes are the files @file{paperSZ.ly}, where
2242 @code{SZ} is one of 11, 13, 16, 20, 23 and 26. If you include
2243 any of these files, the identifiers @code{paper_eleven},
2244 @code{paper_thirteen}, @code{paper_sixteen}, @code{paper_twenty},
2245 @code{paper_twentythree}, and @code{paper_twentysix} are defined
2246 respectively. The default @code{\paper} block is also set.
2248 To change the paper size, you must first set the
2249 @code{papersize}@indexcode{papersize} variable at top level. Set it to the strings
2250 @code{a4}, @code{letter}, or @code{legal}. After this specification,
2251 you must set the font as described above. If you want the default
2252 font, then use the 20 point font. The new paper size will not
2253 take effect if the font is not loaded and selected afterwards. Paper
2254 size selection works by loading a file named after the paper size you
2259 @cindex paper variables
2261 @node Paper variables, , , Reference Manual
2263 There is a large number of paper variables that are used to control
2264 details of the layout. These variables control the defaults for the
2265 entire score. Usually, they do not have to be changed; they are by
2266 default set to values that depend on the font size in use. The
2267 values are used by the graphic objects while formatting the score;
2268 they are therefore implementation dependent. Most variables are
2269 accompanied by documentation in the initalization file
2270 @file{params.ly} or @file{paperSZ.ly}, where @code{SZ} is the staff
2273 Nevertheless, here are some variables you may want to use or change:
2276 @item @code{indent}@indexcode{indent}
2277 The indentation of the first line of music.
2279 @item @code{staffspace}@indexcode{staffspace}
2280 The distance between two staff lines, calculated from the center
2281 of the lines. You should use either this or @code{rulethickness}
2282 as a unit for distances you modify.
2284 @item @code{linewidth}@indexcode{linewidth}
2285 Sets the width of the lines. If set to -1.0, a single
2286 unjustified line is produced.
2288 @item @code{textheight}@indexcode{textheight}
2289 Sets the total height of the music on each page. Only used by
2292 @item @code{interscoreline}@indexcode{interscoreline}
2293 Sets the spacing between the score lines. Defaults to 16 pt.
2295 @item @code{interscorelinefill}@indexcode{interscorelinefill}
2296 If set to a positive number, the distance between the score
2297 lines will stretch in order to fill the full page. In that
2298 case @code{interscoreline} specifies the minimum spacing.
2301 @item @code{stafflinethickness}@indexcode{stafflinethickness}
2302 Determines the thickness of staff and bar lines.
2306 @node contextdefs, , , Reference Manual
2308 @cindex context definition
2310 A notation contexts is defined by the following information
2315 @item The LilyPond modules that do the actual conversion of music to
2316 notation. Each module is a so-called
2321 @item How these modules should cooperate, i.e. which ``cooperation
2322 module'' should be used. This cooperation module is a special
2325 @item What other contexts the context can contain,
2327 @item What properties are defined.
2330 A context definition has this syntax:
2334 \translator @code{@{}
2335 @var{translatorinit} @var{translatormodifierlist}
2339 @var{translatorinit} can be an identifier or of the form
2343 \type @var{typename} @code{;}
2346 @var{typename} is one of
2349 @item @code{Engraver_group_engraver}@indexcode{Engraver_group_engraver}
2350 The standard cooperation engraver.
2352 @item @code{Score_engraver}@indexcode{Score_engraver}
2353 This is cooperation module that should be in the top level context.
2355 @item @code{Grace_engraver_group}@indexcode{Grace_engraver_group}
2356 This is a special cooperation module (resembling
2357 @code{Score_engraver}) that is used to created an embedded
2361 @var{translatormodifierlist} is a list of items where each item is
2365 @item @code{\consists} @var{engravername} @code{;}
2366 Add @var{engravername} to the list of modules in this context.
2367 The order of engravers added with @code{\consists} is
2370 @item @code{\consistsend} @var{engravername} @code{;}
2371 Analogous to @code{\consists}, but makes sure that
2372 @var{engravername} is always added to the end of the list of
2375 Some engraver types need to be at the end of the list; this
2376 insures they are put there, and stay there, if a user adds or
2377 removes engravers. This command is usually not needed for
2380 @item @code{\accepts} @var{contextname} @code{;}
2381 Add @var{contextname} to the list of context this context can
2382 contain. The first listed context the context to create by
2385 @item @code{\remove} @var{engravername} @code{;}
2386 Remove a previously added (with @code{\consists}) engraver.
2388 @item @code{\name} @var{contextname} @code{;}
2389 This sets name of the context, e.g. @code{Staff}, @code{Voice}. If
2390 the name is not specified, the translator won't do anything.
2392 @item @var{propname} @code{=} @var{value} @code{;}
2393 A property assignment. It is allowed to use reals for
2397 In the @code{\paper} block, it is also possible to define translator
2398 identifiers. Like other block identifiers, the identifier can only
2399 be used as the very first item of a translator. In order to define
2400 such an identifier outside of @code{\score}, you must do
2406 foo = \translator @{ @dots{} @}
2413 \translator @{ \foo @dots{} @}
2421 @cindex paper types, engravers, and pre-defined translators
2423 Some pre-defined identifiers can simplify modification of
2424 translators. The pre-defined identifiers are:
2427 @item @code{StaffContext}@indexcode{StaffContext}
2428 Default Staff context.
2430 @item @code{RhythmicStaffContext}@indexcode{RhythmicStaffContext}
2431 Default RhythmicStaff context.
2433 @item @code{VoiceContext}@indexcode{VoiceContext}
2434 Default Voice context.
2436 @item @code{ScoreContext}@indexcode{ScoreContext}
2437 Default Score context.
2439 @item @code{ScoreWithNumbers}@indexcode{ScoreWithNumbers}
2440 Score context with numbering at the Score level.
2442 @item @code{BarNumberingStaffContext}@indexcode{BarNumberingStaffContext}
2443 Staff context with numbering at the Staff level.
2445 @item @code{HaraKiriStaffContext}@indexcode{HaraKiriStaffContext}
2446 Staff context that does not print if it only contains rests.
2447 Useful for orchestral scores.@footnote{Harakiri, also called
2448 Seppuku, is the ritual suicide of the Samourai.}
2450 @item @code{OrchestralPartStaffContext}@indexcode{OrchestralPartStaffContext}
2452 @item @code{OrchestralScoreContext}@indexcode{OrchestralScoreContext}
2455 Using these pre-defined values, you can remove or add items to the
2464 \remove Some_engraver;
2465 \consists Different_engraver;
2473 @node Sound output, , , Reference Manual
2474 @section Sound output
2478 The MIDI block is analogous to the paper block, but it is simpler.
2479 The @code{\midi} block can contain:
2483 @item a @code{\tempo} definition
2484 @item context definitions
2487 Assignments in the @code{\midi} block are not allowed.
2491 @cindex context definition
2493 Context definitions follow precisely the same syntax as within the
2494 \paper block. Translation modules for sound are called performers.
2495 The contexts for MIDI output are defined in @file{ly/performer.ly}.
2499 @cindex MIDI instrument names
2501 @node midilist, , , Reference Manual
2503 The MIDI instrument name is set by the
2504 @code{Staff.midiInstrument}@indexcode{Staff.midiInstrument} property or,
2505 if that property is not set, the
2506 @code{Staff.instrument}@indexcode{Staff.instrument} property. The
2507 instrument name should be chosen from the following list. If the
2508 selected string does not exactly match, then LilyPond uses the default
2514 "acoustic grand" "contrabass" "lead 7 (fifths)"
2515 "bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
2516 "electric grand" "pizzicato strings" "pad 1 (new age)"
2517 "honky-tonk" "orchestral strings" "pad 2 (warm)"
2518 "electric piano 1" "timpani" "pad 3 (polysynth)"
2519 "electric piano 2" "string ensemble 1" "pad 4 (choir)"
2520 "harpsichord" "string ensemble 2" "pad 5 (bowed)"
2521 "clav" "synthstrings 1" "pad 6 (metallic)"
2522 "celesta" "synthstrings 2" "pad 7 (halo)"
2523 "glockenspiel" "choir aahs" "pad 8 (sweep)"
2524 "music box" "voice oohs" "fx 1 (rain)"
2525 "vibraphone" "synth voice" "fx 2 (soundtrack)"
2526 "marimba" "orchestra hit" "fx 3 (crystal)"
2527 "xylophone" "trumpet" "fx 4 (atmosphere)"
2528 "tubular bells" "trombone" "fx 5 (brightness)"
2529 "dulcimer" "tuba" "fx 6 (goblins)"
2530 "drawbar organ" "muted trumpet" "fx 7 (echoes)"
2531 "percussive organ" "french horn" "fx 8 (sci-fi)"
2532 "rock organ" "brass section" "sitar"
2533 "church organ" "synthbrass 1" "banjo"
2534 "reed organ" "synthbrass 2" "shamisen"
2535 "accordion" "soprano sax" "koto"
2536 "harmonica" "alto sax" "kalimba"
2537 "concertina" "tenor sax" "bagpipe"
2538 "acoustic guitar (nylon)" "baritone sax" "fiddle"
2539 "acoustic guitar (steel)" "oboe" "shanai"
2540 "electric guitar (jazz)" "english horn" "tinkle bell"
2541 "electric guitar (clean)" "bassoon" "agogo"
2542 "electric guitar (muted)" "clarinet" "steel drums"
2543 "overdriven guitar" "piccolo" "woodblock"
2544 "distorted guitar" "flute" "taiko drum"
2545 "guitar harmonics" "recorder" "melodic tom"
2546 "acoustic bass" "pan flute" "synth drum"
2547 "electric bass (finger)" "blown bottle" "reverse cymbal"
2548 "electric bass (pick)" "skakuhachi" "guitar fret noise"
2549 "fretless bass" "whistle" "breath noise"
2550 "slap bass 1" "ocarina" "seashore"
2551 "slap bass 2" "lead 1 (square)" "bird tweet"
2552 "synth bass 1" "lead 2 (sawtooth)" "telephone ring"
2553 "synth bass 2" "lead 3 (calliope)" "helicopter"
2554 "violin" "lead 4 (chiff)" "applause"
2555 "viola" "lead 5 (charang)" "gunshot"
2556 "cello" "lead 6 (voice)"
2563 @node Pre-defined Identifiers, , , Reference Manual
2565 @section Pre-defined Identifiers
2567 @cindex pre-defined identifiers
2570 Various identifiers are defined in the initialization files to
2571 provide shorthands for some settings. Most of them are in
2572 @file{ly/declarations.ly}.
2575 @item @code{\break}@keyindex{break}
2576 Force a line break in music by using a large argument for the
2577 keyword @code{\penalty}.
2579 @item @code{\nobreak}@keyindex{nobreak}
2580 Prevent a line break in music by using a large negative argument
2581 for the keyword @code{\penalty}.
2583 @item @code{\normalkey}@keyindex{normalkey}
2584 Select normal key signatures where each octave has the same key
2585 signature. This sets the @code{Staff.keyoctaviation} property.
2587 @item @code{\shiftoff}@keyindex{shiftOff}
2588 Disable horizontal shifting of note heads that collide.
2590 @item @code{\shiftOn}@keyindex{shiftOn}
2591 Enable note heads that collide with other note heads to be
2592 shifted horiztonally.
2594 @item @code{\slurBoth}@keyindex{slurBoth}
2595 Allow slurs to be above or below notes.
2597 @item @code{\slurDown}@keyindex{slurDown}
2598 Force slurs to be below notes.
2600 @item @code{\slurUp}@keyindex{slurUp}
2601 Force slurs to be above notes.
2603 @item @code{\specialkey}@keyindex{specialkey}
2604 Allow key signatures do differ in different octaves. This sets
2605 the @code{Staff.keyoctaviation} property.
2607 @item @code{\stemBoth}@keyindex{stemBoth}
2608 Allow stems, beams, and slurs to point either upwards or
2609 downwards, decided automatically by LilyPond.
2611 @item @code{\stemdown}@keyindex{stemdown}
2612 Force stems, beams, and slurs to point down.
2614 @item @code{\stemUp}@keyindex{stemUp}
2615 Force stems, beams and slurs to point up.
2619 @node Grobs, , , Reference Manual
2622 This section is about Grobs (short for Graphical Objects), which are
2623 formatting objects used to create the final output. This material is
2624 normally the domain of LilyPond gurus, but occasionally, a normal user
2625 also has to deal with grobs.
2627 The most simple interaction with Grobs are when you use
2631 \property Voice.Stem \override #'direction = #1
2634 This piece of lily input causes all stem objects to be stem-up
2635 henceforth. In effect, you are telling lilypond to extend the defintion
2636 of the "Stem" grob with the setting @code{direction := 1}. Of course
2637 there are many more ways of customizing Lily output, and since most of
2638 them involve Grobs in some form, this section explains some details of
2644 * Setting grob properties::
2645 * Items and Spanners::
2646 * Pointer substitution::
2649 @node What is a grob?, , , Grobs
2651 All grobs have an X and Y-position on the page. These X and Y positions
2652 are stored in a relative format, so they can easily be combined by
2653 stacking them, hanging one grob to the side of another, and coupling
2654 them into a grouping-grob.
2656 Each grob has a reference point, or parent: the position of a grob is
2657 stored relative to that reference point. For example the X-reference
2658 point of a staccato dot usually is the note head that it applies
2659 to. Whenever the note head is moved, the staccato dot moves along
2662 If you keep following offset reference points, you will always end up at
2663 the root-object. This root object is called @code{Line_of_score}
2664 @ref{(lilypond-internals)Element Line_of_score}, and it represents a
2665 system (ie. a line of music).
2667 All grobs carry a set of grob-properties. In the Stem example above,
2668 the property @code{direction} is set to value @code{1}. The function
2669 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
2670 @code{direction} to determine how to print the stem and the flag. The
2671 appearance of a grob is determined solely by the values of its
2674 Often, a grob also is associated with a symbol. On the other hand, Some
2675 grobs do not print any symbols, but take care of grouping objects. For
2676 example, there is a separate grob that stacks staffs vertically, so they
2677 are not printed in overstrike. The NoteCollision @ref{(lilypond-internals)Element
2678 NoteCollision} is another example of an abstract grob. It only moves
2679 around chords, but doesn't print anything.
2681 A complete list of grob types is found in @ref{(lilypond-internals)Elements}
2683 Grobs are created in the "Interpreting music" phase, by things in
2684 LilyPond called engravers. In this phase of the translation, a load of
2685 grobs are created, and they are linked into a giant network of objects.
2686 This network of grobs forms the "specification" of the print
2687 problem. This problem is then solved: configurations, directions,
2688 dimensions, line breaks, etc. are calculated. Finally, the printing
2689 description in the form of Molecules (@ref{Molecule}) is extracted from
2690 the network. These are then dumped into the output file
2692 @node Callbacks, , , Grobs
2694 Offsets of grobs are relative to a parent reference point. Most
2695 positions are not known when an object is created, so these are
2696 calculated as needed. This is done by adding a callback for a specific
2699 Suppose you have the following code in a .ly file.
2701 #(define (my-callback gr axis)
2702 (* 2.0 (get-gr-property grob 'direction))
2707 \property Voice.Stem \override #'Y-offset-callbacks = #(list
2711 When the Y-offset of a Stem object is needed, LilyPond will
2712 automatically execute all callbacks for that object. In this case, it
2713 will find @code{my-callback}, and execute that. The result is that the
2714 stem is translated by two staff spaces in its direction.
2716 (note: Y-offset-callbacks is also a property)
2719 Offset callbacks can be stacked, ie.
2722 \property .... \override #'Y-offset-callbacks = #(list
2723 callback1 callback2 callback3)
2727 The callbacks will be executed in the order callback3 callback2
2728 callback1. This is used for quantized positioning: the staccato dot is
2729 above or below a note head, and it must not be on a staff-line.
2731 To achieve this, for the staccato there are two callbacks: one callback
2732 that positions the grob above or below the note head, and one callback
2733 that rounds the Y-position of the grob to the nearest open space.
2735 Similarly, the size of a grob are determined through callbacks, settable
2736 with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
2737 There can be only one extent-callback for each axis. No callback (value #f)
2738 means: "empty in this direction". If you fill in a pair, that pair
2739 hard-codes the extent in that coordinate.
2742 @node Setting grob properties, , , Grobs
2744 Grob properties are stored as GUILE association lists, with symbols as
2745 keys. From C++, element properties can be accessed using the functions
2748 SCM get_grob_property (SCM) const;
2749 void set_grob_property (const char * , SCM val);
2750 void set_immutable_grob_property (const char * , SCM val);
2751 void set_immutable_grob_property (SCM key, SCM val);
2752 void set_grob_property (SCM , SCM val);
2753 void set_grob_pointer (const char*, SCM val);
2754 SCM remove_grob_property (const char* nm);
2757 In GUILE, LilyPond provides
2760 ly-get-grob-property GROB SYMBOL
2761 ly-set-grob-property GROB SYMBOL VALUE
2764 All lookup functions identify undefined properties with
2765 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
2767 Properties are stored in two ways:
2769 @item mutable properties:
2770 element properties that change from object to object. The storage of
2771 these are private to a grob. Typically this is used to store lists of
2772 pointers to other grobs
2774 @item immutable properties:
2775 element properties that are shared across different grobs of the same
2776 type. The storage is shared, and hence it is read-only. Typically, this
2777 is used to store function callbacks, and values for shared element
2778 properties are read from @file{scm/element-description.scm}.
2781 There are two ways to manually set grob properties.
2783 You can change immutable grob properties. This is done with the
2787 \property Voice.Stem \override #'direction = #1
2790 This will push the entry @code{'(direction . 1)} on the immutable
2791 property list for stems, in effect overriding the setting from
2792 @file{scm/element-description.scm}. This can be undone by
2795 \property Voice.stem \revert #'direction
2798 If you use this a lot, this gets old quickly. So we also have a
2802 \property Context.GrobType \set #'prop = #VAL
2805 this does a @code{\revert} followed by a @code{\override}
2807 The second way is \outputproperty. This construct looks like
2810 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
2813 In this case, in every grob that satisfies @var{pred}, the property
2814 assignment @var{sym} = @var{val} is done. For example
2818 #(lambda (gr) (string? (ly-get-grob-property gr
2820 #'extra-offset = #'(-1.0 . 0.0)
2823 This shifts all elements that have a @code{text} property one staff
2826 @node Items and Spanners, , , Grobs
2828 Grobs can also be distinguished in their role in the horizontal spacing.
2829 A lot of grobs define constraints on the spacing by their sizes. For
2830 example, note heads, clefs, stems, and all other symbols with a fixed
2831 shape. These grobs form a subtype called @code{Item}.
2833 Other grobs have a shape that depends on the horizontal spacing. For
2834 example, slur, beam, tie, etc. These grobs form a subtype called
2835 @code{Spanner}. All spanners have two span-points (these must be
2836 @code{Item}s), one on the left and one on the right. The left bound is
2837 also the X-reference point.
2839 Some items need special treatment for line breaking. For example, a
2840 clef is normally only printed at the start of a line (ie. after a line
2841 break). To model this, `breakable' items (clef, key signature, bar lines,
2842 etc.) are copied twice. Then we have three versions of each breakable
2843 item: one version if there is no line break, one version that is printed
2844 before the line break (at the end of a system), one version that is
2845 printed after the line break.
2847 Whether these versions are visible and take up space, is determined by
2848 the outcome of the visibility-lambda. This is a function taking a
2849 direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
2850 this grob should be transparent and invisible.
2852 @node Pointer substitution, , , Grobs
2855 @node Molecule, , , Reference Manual
2857 The objective of any typesetting system is to put ink on paper in the
2858 right places. For LilyPond, this final stage is left to the TeX and the
2859 printer subsystem. For lily, the last stage in processing a score is
2860 outputting a description of what to put where. This description roughly
2869 you merely have to look at the tex output of lily to see this.
2870 Internally these instructions are encoded in Molecules:@footnote{At some
2871 point LilyPond also contained Atom-objects, but they have been replaced
2872 by Scheme expressions.}. A molecule is an object that combines
2873 dimension information (how large is this glyph ?) with
2874 what-to-print-where.
2876 Conceptually, Molecules can be constructed from Scheme code, by
2877 translating a Molecule and by combining two molecules. In BNF notation:
2880 Molecule = COMBINE Molecule Molecule
2881 | TRANSLATE Offset Molecule
2886 (refer to the C++ code for more details). All visible,
2887 ie. non-transparent, grobs have a callback to create a Molecule. The
2888 name of the property is @code{molecule-callback}, and its value should
2889 be a Scheme function taking one argument (the grob) and returning a