1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
2 @c This file is part of ../user/lilypond.tely
4 Translation of GIT committish: da55a1ec3c4b8195efc910b0c986c27f244def85
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
10 @node Changing defaults
11 @chapter Changing defaults
14 LilyPond est conçu pour engendrer, par défaut, des partitions de la
15 plus haute qualité. Cependant, on peut parfois avoir à modifier cette
16 mise en page par défaut. Celle-ci est réglée par tout un ensemble de
17 @qq{leviers et manettes}, dont ce chapitre ne cherche pas à faire
18 l'inventaire exhaustif. Le propos est plutôt ici de mettre en évidence
19 les différents groupes auxquels s'apparentent ces contrôles, et d'expliquer
20 comment trouver le bon levier pour obtenir tel ou tel effet en particulier.
22 @cindex Référence du programme
24 Les moyens de contrôle des différents réglages sont décrits dans un document
27 référence du programme
30 @ref{Top,Référence du programme,,lilypond-internals}.
32 Ce guide répertorie toutes les variables, fonctions et autre options que
33 LilyPond met à votre disposition. Il est consultable en ligne, au format HTML,
34 @c leave the @uref as one long line.
35 @uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
36 mais est également inclus dans la documentation fournie avec le logiciel.
38 Il est quatre domaines dans lesquels on peut modifier les réglages par défaut :
42 La notation automatique, ce qui revient à modifier la manière dont les éléments
43 de notation sont automatiquement créés -- par exemple, les règles de ligatures.
46 L'apparence, qui se rapporte aux objets pris individuellement -- ainsi de la direction
47 des hampes, du placement des indications textuelles.
50 Les contextes, qui recouvrent la manière dont les évènements musicaux sont représentés sous forme de
51 notation -- par exemple, le fait d'attribuer un chiffre de mesure distinct à chaque portée.
54 La mise en page, autrement dit les marges, l'espacement, la taille du papier ; tous ces facteurs
55 font l'objet des chapitres @ref{Non-musical notation} et @ref{Spacing issues}.
58 En sous-main, LilyPond se sert du langage Scheme (un dérivé du LISP) comme
59 infrastructure. Modifier les choix de mise en page revient à pénétrer dans
60 les entrailles du programme, et de ce fait requiert l'emploi du Scheme.
61 Les fragments de Scheme, dans un fichier @code{.ly}, sont introduits par le
62 caractère @q{hash}, (@code{#}, improprement surnommé @q{dièse}).@footnote{Le
63 @ref{Scheme tutorial} fournit quelques notions de base pour saisir des nombres,
64 des listes, des chaînes de caractères ou des symboles, en Scheme.}
68 * Automatic notation::
69 * Interpretation contexts::
70 * The \override command::
74 @node Automatic notation
75 @section Automatic notation
77 Cette section s'intéresse à la manière dont les altérations accidentelles
78 et les ligatures sont automatiquement ajoutées.
81 * Automatic accidentals::
82 * Setting automatic beam behavior::
85 @node Automatic accidentals
86 @subsection Automatic accidentals
87 @cindex Altérations accidentelles automatiques
89 Une fonction a été créée pour regrouper les règles suivant lesquelles
90 s'impriment les altérations. Elle s'invoque de la manière suivante :
92 @funindex set-accidental-style
94 #(set-accidental-style 'REGLE)
97 @c TODO: check the context stuff below
98 @c -does it *really* work?
99 @c -the default contexts as specified in
100 @c scm/music-function.scm seem to be different -vv
102 Cette fonction prend pour argument le nom de la règle d'altérations,
103 auquel peut s'ajouter, comme argument facultatif, le contexte
104 devant être affecté :
107 #(set-accidental-style 'REGLE #('CONTEXTE#))
110 Si aucun contexte n'est spécifié, le contexte @code{Staff} sera affecté ;
111 cependant on peut souhaiter l'appliquer au contexte @code{Voice} en lieu
114 Les régles d'altérations suivantes sont possibles :
118 C'est la règle d'impression par défaut, qui se rapporte à l'usage
119 en vigueur au XVIIIème siècle : les altérations accidentelles sont valables toute
120 une mesure, et uniquement à leur propre octave.
123 @lilypond[quote,ragged-right]
124 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
125 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
127 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
128 \change Staff = up cis' \change Staff = down <fis, a>
129 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
134 << \context Staff = "up" {
135 %#(set-accidental-style 'default)
137 \context Staff = "down"{
138 %#(set-accidental-style 'default)
140 \header { piece = \markup {\fill-line { \fontsize #3 "'default" }}}
145 En principe, LilyPond se souvient de toutes les altérations présentes sur la
146 portée (contexte Staff). Avec cette règle, cependant, les altérations sont indépendantes
147 pour chacune des voix.
152 #(set-accidental-style 'voice)
157 De ce fait, les altérations d'une voix sont ignorées dans les autres voix,
158 ce qui peut donner lieu à un résultat malencontreux. Dans l'exemple suivant,
159 il est difficile de dire si le deuxième @samp{la} est dièse ou naturel.
161 @lilypond[quote,ragged-right]
162 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
163 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
165 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
166 \change Staff = up cis' \change Staff = down <fis, a>
167 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
172 << \context Staff = "up" {
173 #(set-accidental-style 'voice)
175 \context Staff = "down"{
176 #(set-accidental-style 'voice)
178 \header { piece = \markup {\fill-line { \fontsize #3 "'voice" }}}
182 La règle @code{voice} n'est à envisager que dans le cas de voix devant être lues par
183 des musiciens différents. S'il s'agit d'un @q{conducteur}, ou d'une portée destinée
184 à un seul musicien, il vaut mieux utiliser @code{modern} ou @code{modern-cautionary}.
188 @funindex modern style accidentals
189 Cette règle est la plus courante au XXème siècle. Les altérations accidentelles
190 sont imprimées comme avec le style @code{default}, mais lorsque une note non-altérée
191 apparaît à une octave différente, ou bien dans la mesure suivante, des bécarres de précaution
192 sont ajoutés. Dans l'exemple suivant, notez ainsi les deux bécarres dans la
193 deuxième mesure de la main droite.
195 @lilypond[quote,ragged-right]
196 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
197 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
199 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
200 \change Staff = up cis' \change Staff = down <fis, a>
201 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
206 << \context Staff = "up" {
207 #(set-accidental-style 'modern)
209 \context Staff = "down"{
210 #(set-accidental-style 'modern)
212 \header { piece = \markup {\fill-line { \fontsize #3 "'modern" }}}
216 @item @code{modern-cautionary}
217 @funindex modern-cautionary
218 Cette règle est équivalente à @code{modern}, mais les bécarres de précaution sont
219 imprimés de façon particulière : soit plus petits, soit (par défaut) entre parenthèses.
220 Il est possible de le définir au moyen de la propriété @code{cautionary-style}
221 pour l'objet @internalsref{AccidentalSuggestion}.
223 @lilypond[quote,ragged-right]
224 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
225 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
227 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
228 \change Staff = up cis' \change Staff = down <fis, a>
229 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
234 << \context Staff = "up" {
235 #(set-accidental-style 'modern-cautionary)
237 \context Staff = "down"{
238 #(set-accidental-style 'modern-cautionary)
240 \header { piece = \markup {\fill-line { \fontsize #3 "'modern-cautionary" }}}
244 @funindex modern-voice
246 Cette règle sert aux altérations dans de la musique polyphonique destinée
247 autant à des musiciens différents qu'à quelqu'un qui lirait l'ensemble des voix.
248 Les altérations sont imprimées voix par voix, mais les autres voix, dans le même
249 contexte @internalsref{Staff}, en @emph{tiennent compte} cette fois.
251 @lilypond[quote,ragged-right]
252 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
253 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
255 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
256 \change Staff = up cis' \change Staff = down <fis, a>
257 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
262 << \context Staff = "up" {
263 #(set-accidental-style 'modern-voice)
265 \context Staff = "down"{
266 #(set-accidental-style 'modern-voice)
268 \header { piece = \markup {\fill-line { \fontsize #3 "'modern-voice" }}}
272 @funindex modern-voice-cautionary
273 @item modern-voice-cautionary
274 Cette régle est similaire à la précédente, mais les altérations de précautions
275 (celles que n'aurait pas ajoutées @code{voice}), sont imprimées de façon
276 particulière. On retrouve donc toutes les altérations qu'imprimerait
277 @code{default}, mais certaines sont considérées comme étant @qq{de précaution}.
279 @lilypond[quote,ragged-right]
280 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
281 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
283 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
284 \change Staff = up cis' \change Staff = down <fis, a>
285 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
290 << \context Staff = "up" {
291 #(set-accidental-style 'modern-voice-cautionary)
293 \context Staff = "down"{
294 #(set-accidental-style 'modern-voice-cautionary)
296 \header { piece = \markup {\fill-line { \fontsize #3 "'modern-voice-cautionary" }}}
301 @funindex piano accidentals
302 Cette règle est adaptée aux contextes GrandStaff -- ce qui n'empêche pas de devoir la spécifier
303 pour chaque portée individuelle au sein du contexte GrandStaff.
306 \new GrandStaff @{ <<
307 \new Staff = "up" @{ <<
308 #(set-accidental-style 'piano)
311 \new Staff = "down"@{ <<
312 #(set-accidental-style 'piano)
318 Cette règle est communément employée pour les partitions de piano au XXème siècle.
319 Très similaire à @code{modern} de par son comportement, elle s'en distingue en ce que
320 les altérations tiennent compte des autre portées du contexte @internalsref{GrandStaff} ou
321 @internalsref{PianoStaff}.
323 @lilypond[quote,ragged-right]
324 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
325 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
327 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
328 \change Staff = up cis' \change Staff = down <fis, a>
329 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
334 << \context Staff = "up" {
335 #(set-accidental-style 'piano)
337 \context Staff = "down"{
338 #(set-accidental-style 'piano)
340 \header { piece = \markup {\fill-line { \fontsize #3 "'piano" }}}
344 @item piano-cautionary
345 @funindex #(set-accidental-style 'piano-cautionary)
346 Identique à @code{#(set-accidental-style 'piano)}, mais les altérations de précaution
347 sont imprimées différemment.
349 @lilypond[quote,ragged-right]
350 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
351 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
353 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
354 \change Staff = up cis' \change Staff = down <fis, a>
355 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
360 << \context Staff = "up" {
361 #(set-accidental-style 'piano-cautionary)
363 \context Staff = "down"{
364 #(set-accidental-style 'piano-cautionary)
366 \header { piece = \markup {\fill-line { \fontsize #3 "'piano-cautionary" }}}
371 @funindex no-reset accidental style
372 C'est la même règle que @code{default}, mais l'effet des altérations accidentelles
373 ne cesse jamais, même dans les mesures suivantes.
374 @lilypond[quote,ragged-right]
375 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
376 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
378 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
379 \change Staff = up cis' \change Staff = down <fis, a>
380 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
385 << \context Staff = "up" {
386 #(set-accidental-style 'no-reset)
388 \context Staff = "down"{
389 #(set-accidental-style 'no-reset)
391 \header { piece = \markup {\fill-line { \fontsize #3 "'no-reset" }}}
396 Tout le contraire de @code{no-reset}: l'effet des altérations cesse aussitôt,
397 et de ce fait, toutes les altérations, quelque soit leur place dans la mesure, sont
398 imprimées, en fonction de l'armure éventuelle.
400 @lilypond[quote,ragged-right]
401 musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
402 \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
404 musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
405 \change Staff = up cis' \change Staff = down <fis, a>
406 \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
411 << \context Staff = "up" {
412 #(set-accidental-style 'forget)
414 \context Staff = "down"{
415 #(set-accidental-style 'forget)
417 \header { piece = \markup {\fill-line { \fontsize #3 "'forget" }}}
425 Référence du programme : @internalsref{Accidental_engraver},
426 @internalsref{Accidental}, @internalsref{AccidentalSuggestion} et @internalsref{AccidentalPlacement}.
431 Les notes simultanées sont considérées comme des évènements séquentiels.
432 Ce qui implique que, dans un accord, les altérations accidentelles sont
433 imprimées comme si les notes de l'accords apparaissaient une par une, en fonction
434 de l'ordre dans lequels elles ont été saisies -- ce qui peut poser problème lorsqu'au
435 sein d'un accord certaines altérations dépendent les unes des autres. Ce problème
436 est à résoudre manuellement, en insérant des @code{!} et des @code{?} après les notes
440 @node Setting automatic beam behavior
441 @subsection Setting automatic beam behavior
443 @funindex autoBeamSettings
444 @funindex (end * * * *)
445 @funindex (begin * * * *)
446 @cindex ligatures automatiques, réglage
447 @cindex réglage des ligatures automatiques
449 @c [TODO: use \applyContext]
451 Dans les métriques courantes, les ligatures automatiques peuvent commencer
452 sur n'importe quelle note, mais ne peuvent se terminer qu'à certains points précis
453 dans la mesure : sur une pulsation, ou après toute durée spécifiée par les propriétés
454 nommées @code{autoBeamSettings}. Ces propriétés consistent en une liste de règles
455 relatives au début ou à la fin des ligatures. Par défaut, elles sont définies dans
457 @file{scm/@/auto@/-beam@/.scm}.
459 On peut ajouter à cette liste une nouvelle règle, au moyen de la commande
461 #(override-auto-beam-setting '(extrémité p q n m) a b [contexte])
466 @item @code{extrémité} désigne le début (@code{begin}) ou la fin (@code{end}) de la ligature.
468 @item @code{p/q} désigne la valeur rythmique de la note que l'on veut affecter, ou de la
469 plus brève des notes concernées. Si cette règle doit s'appliquer à toutes les ligatures,
470 remplacez @code{p} et @code{q} par des étoiles @qq{@code{*}}.
473 @item @code{n/m} est le chiffre de mesure dans lequel la règle doit s'appliquer. Si
474 celle-ci doit s'appliquer dans toutes les métriques, remplacez @code{n} et @code{m}
475 par des étoiles @qq{@code{*}}.
477 @item @code{a/b} est l'emplacement, dans la mesure, auquel les ligatures doivent
478 débuter ou s'achever (suivant la valeur @q{extrémité} que nous venons de voir).
481 @item @code{contexte} est un argument facultatif, qui détermine le contexte dans lequel
482 la règle doit s'appliquer. Par défaut, il s'agit de @code{'Voice}.
483 @code{#(score-override-auto-beam-setting '(A B C D) E F)} équivaut à
484 @code{#(override-auto-beam-setting '(A B C D) E F 'Score)}.
488 Par exemple, si l'on veut que les ligatures s'achèvent toujours après la première noire :
492 #(override-auto-beam-setting '(end * * * *) 1 4)
495 On peut obliger une règle de ligatures à ne s'appliquer qu'à des groupes dont la note
496 la plus brève est d'une valeur précise :
498 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
500 #(override-auto-beam-setting '(end 1 16 * *) 1 16)
502 a32 a a a a16 a a a a a |
503 #(override-auto-beam-setting '(end 1 32 * *) 1 16)
504 a32 a a a a16 a a a a a |
507 On peut obliger une règle de ligatures à ne s'appliquer que pour un chiffre de mesure
510 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
512 #(override-auto-beam-setting '(end * * 5 8) 2 8)
520 Enfin, on peut désactiver une règle de ligatures au moyen du réglage suivant :
523 #(revert-auto-beam-setting '(extrémité p q n m) a b [contexte])
527 @code{extrémité}, @code{p}, @code{q}, @code{n}, @code{m}, @code{a}, @code{b} et @code{contexte}
528 étant les mêmes que plus haut. Il est même possible de désactiver des règles que l'on n'a pas
529 explicitement créées : les règles par défaut, qui se trouvent dans le fichier @file{scm/@/auto@/-beam@/.scm}.
533 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
535 a16 a a a a a a a a a a a a a a a
536 #(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
537 a16 a a a a a a a a a a a a a a a
540 La commande @code{revert-auto-beam-setting} requiert exactement les mêmes arguments
541 que la règle d'origine. En d'autres termes, les étoiles ne seront pas prises en compte ici.
543 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
545 #(override-auto-beam-setting '(end 1 16 1 4) 1 8)
547 #(revert-auto-beam-setting '(end 1 16 * *) 1 8) % ceci ne désactive pas la règle !
549 #(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % ceci marche
555 @c TODO: old material -- not covered by above stuff, I think.
556 Si, dans une mesure à 5/4, l'on veut que les ligatures soient regroupées temps par temps,
557 il est nécessaire d'indiquer toutes les terminaisons de ligatures.
559 #(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
560 #(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
561 #(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
562 #(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
566 La même syntaxe peut servir à définir les points de départ des ligatures.
567 Dans l'exemple suivant, les ligatures automatiques ne peuvent se terminer
568 que sur une noire pointée.
570 #(override-auto-beam-setting '(end * * * *) 3 8)
571 #(override-auto-beam-setting '(end * * * *) 1 2)
572 #(override-auto-beam-setting '(end * * * *) 7 8)
574 @c ???? Je n'y comprends rien --vv
575 Dans une mesure à 4/4, cela implique que les ligatures ne peuvent se terminer que sur
576 la troisième croche, ou sur le quatrième temps (après la valeur de deux fois trois croches).
578 Si une ligature se fait de manière inattendue, pensez à vérifer les règles automatiques
579 dans le fichier @file{scm/@/auto@/-beam@/.scm} pour rechercher d'éventuels conflits, dans
580 la mesure ou les règles par défaut s'ajoutent à vos propres règles. Il est alors nécessaire
581 de désactiver toute règle par défaut conduisant à des ligatures indésirables.
583 Ainsi, pour obtenir des ligatures en groupes de @code{(3 4 3 2)} notes, dans une mesure à 12/8,
584 il faudra préalablement utiliser :
587 %%% annulons les réglages par défaut relatifs à 12/8, dans scm/auto-beam.scm
588 #(revert-auto-beam-setting '(end * * 12 8) 3 8)
589 #(revert-auto-beam-setting '(end * * 12 8) 3 4)
590 #(revert-auto-beam-setting '(end * * 12 8) 9 8)
592 %%% puis ajoutons nos propres règles
593 #(override-auto-beam-setting '(end 1 8 12 8) 3 8)
594 #(override-auto-beam-setting '(end 1 8 12 8) 7 8)
595 #(override-auto-beam-setting '(end 1 8 12 8) 10 8)
598 @cindex ligatures automatiques
599 @cindex groupes de notes
600 @funindex autoBeaming
603 Si des ligatures sont utilisées dans les paroles d'une chanson (pour indiquer des mélismes),
604 les ligatures automatiques doivent être désactivées, avec @code{\autoBeamOff}.
609 @funindex \autoBeamOff
611 @funindex \autoBeamOn
616 Les groupes de notes reliées par les ligatures peuvent être spécifiés au moyen
617 de la propriété @code{beatGrouping}.
619 @lilypond[quote,verbatim,relative=2,fragment,ragged-right]
621 \set beatGrouping = #'(2 3)
623 \set beatGrouping = #'(3 2)
630 Si une partition se termine alors qu'une ligature automatique est restée inachevée,
631 cette dernière ligature ne sera pas imprimée du tout. C'est également valable dans
632 le cas d'une musique polyphonique, saisie avec la syntaxe @code{<< @dots{} \\ @dots{}
633 >>}, où une voix se terminerait sans que la dernière ligature
636 @node Interpretation contexts
637 @section Interpretation contexts
639 This section describes what contexts are, and how to modify them.
642 * Contexts explained::
643 * Creating contexts::
644 * Changing context properties on the fly::
645 * Modifying context plug-ins::
646 * Layout tunings within contexts::
647 * Changing context default settings::
648 * Defining new contexts::
649 * Aligning contexts::
650 * Vertical grouping of grobs::
654 @node Contexts explained
655 @subsection Contexts explained
657 When music is printed, a lot of notational elements must be added to the
658 output. For example, compare the input and output of the following example:
660 @lilypond[quote,verbatim,relative=2,fragment]
664 The input is rather sparse, but in the output, bar lines, accidentals,
665 clef, and time signature are added. LilyPond @emph{interprets} the
666 input. During this step, the musical information is inspected in time
667 order, similar to reading a score from left to right. While reading
668 the input, the program remembers where measure boundaries are, and which
669 pitches require explicit accidentals. This information can be presented on
670 several levels. For example, the effect of an accidental is limited
671 to a single staff, while a bar line must be synchronized across the
674 Within LilyPond, these rules and bits of information are grouped in
675 @emph{Contexts}. Some examples of contexts are @context{Voice},
676 @context{Staff}, and @context{Score}. They are hierarchical, for
677 example: a @context{Staff} can contain many @context{Voice}s, and a
678 @context{Score} can contain many @context{Staff} contexts.
681 @image{context-example,5cm,,}
684 Each context has the responsibility for enforcing some notation rules,
685 creating some notation objects and maintaining the associated
686 properties. For example, the @context{Voice} context may introduce an
687 accidental and then the @context{Staff} context maintains the rule to
688 show or suppress the accidental for the remainder of the measure. The
689 synchronization of bar lines is handled at @context{Score} context.
691 However, in some music we may not want the bar lines to be
692 synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
693 such cases, we must modify the default settings of the @context{Score}
694 and @context{Staff} contexts.
696 For very simple scores, contexts are created implicitly, and you need
697 not be aware of them. For larger pieces, such as anything with more
698 than one staff, they must be
699 created explicitly to make sure that you get as many staves as you
700 need, and that they are in the correct order. For typesetting pieces
701 with specialized notation, it can be useful to modify existing or
702 to define new contexts.
705 A complete description of all available contexts is in the program
708 @internalsref{Contexts}.
711 Translation @arrow{} Context.
714 @c [TODO: describe propagation]
717 @node Creating contexts
718 @subsection Creating contexts
720 For scores with only one voice and one staff, contexts are
721 created automatically. For more complex scores, it is necessary to
722 create them by hand. There are three commands that do this.
727 The easiest command is @code{\new}, and it also the quickest to type.
728 It is prepended to a music expression, for example
732 @cindex Context, creating
735 \new @var{type} @var{music expression}
739 where @var{type} is a context name (like @code{Staff} or
740 @code{Voice}). This command creates a new context, and starts
741 interpreting the @var{music expression} with that.
743 A practical application of @code{\new} is a score with many
744 staves. Each part that should be on its own staff, is preceded with
747 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
754 The @code{\new} command may also give a name to the context,
757 \new @var{type} = @var{id} @var{music}
759 However, this user specified name is only used if there is no other
760 context already earlier with the same name.
766 Like @code{\new}, the @code{\context} command also directs a music
767 expression to a context object, but gives the context an explicit name. The
771 \context @var{type} = @var{id} @var{music}
774 This form will search for an existing context of type @var{type}
775 called @var{id}. If that context does not exist yet, a new
776 context with the specified name is created. This is useful if
777 the context is referred to later on. For example, when
778 setting lyrics the melody is in a named context
781 \context Voice = "@b{tenor}" @var{music}
785 so the texts can be properly aligned to its notes,
788 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
793 Another possible use of named contexts is funneling two different
794 music expressions into one context. In the following example,
795 articulations and notes are entered separately,
799 arts = @{ s4-. s4-> @}
802 They are combined by sending both to the same @context{Voice} context,
806 \new Staff \context Voice = "A" \music
807 \context Voice = "A" \arts
810 @lilypond[quote,ragged-right]
814 \new Staff \context Voice = "A" \music
815 \context Voice = "A" \arts
819 With this mechanism, it is possible to define an Urtext (original
820 edition), with the option to put several distinct articulations on the
823 @cindex creating contexts
826 The third command for creating contexts is
828 \context @var{type} @var{music}
833 This is similar to @code{\context} with @code{= @var{id}}, but matches
834 any context of type @var{type}, regardless of its given name.
836 This variant is used with music expressions that can be interpreted at
837 several levels. For example, the @code{\applyOutput} command (see
838 @ref{Running a function on all layout objects}). Without an explicit
839 @code{\context}, it is usually applied to @context{Voice}
842 \applyOutput #'@var{context} #@var{function} % apply to Voice
845 To have it interpreted at the @context{Score} or @context{Staff} level use
849 \applyOutput #'Score #@var{function}
850 \applyOutput #'Staff #@var{function}
856 @node Changing context properties on the fly
857 @subsection Changing context properties on the fly
861 @cindex changing properties
863 Each context can have different @emph{properties}, variables contained
864 in that context. They can be changed during the interpretation step.
865 This is achieved by inserting the @code{\set} command in the music,
868 \set @var{context}.@var{prop} = #@var{value}
872 @lilypond[quote,verbatim,relative=2,fragment]
874 \set Score.skipBars = ##t
878 This command skips measures that have no notes. The result is that
879 multi-rests are condensed. The value assigned is a Scheme object. In
880 this case, it is @code{#t}, the boolean True value.
882 If the @var{context} argument is left out, then the current bottom-most
883 context (typically @context{ChordNames}, @context{Voice}, or
884 @context{Lyrics}) is used. In this example,
886 @lilypond[quote,verbatim,relative=2,fragment]
888 \set autoBeaming = ##f
893 the @var{context} argument to @code{\set} is left out, so automatic
894 beaming is switched off in the current @internalsref{Voice}. Note that
895 the bottom-most context does not always contain the property that you
896 wish to change -- for example, attempting to set the @code{skipBars}
897 property (of the bottom-most context, in this case @code{Voice}) will
900 @lilypond[quote,verbatim,relative=2,fragment]
906 Contexts are hierarchical, so if a bigger context was specified, for
907 example @context{Staff}, then the change would also apply to all
908 @context{Voice}s in the current stave. The change is applied
909 @q{on-the-fly}, during the music, so that the setting only affects the
910 second group of eighth notes.
914 There is also an @code{\unset} command,
916 \unset @var{context}.@var{prop}
920 which removes the definition of @var{prop}. This command removes
921 the definition only if it is set in @var{context}, so
924 \set Staff.autoBeaming = ##f
928 introduces a property setting at @code{Staff} level. The setting also
929 applies to the current @code{Voice}. However,
932 \unset Voice.autoBeaming
936 does not have any effect. To cancel this setting, the @code{\unset}
937 must be specified on the same level as the original @code{\set}. In
938 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
941 \unset Staff.autoBeaming
944 Like @code{\set}, the @var{context} argument does not have to be
945 specified for a bottom context, so the two statements
948 \set Voice.autoBeaming = ##t
949 \set autoBeaming = ##t
957 Settings that should only apply to a single time-step can be entered
958 with @code{\once}, for example in
960 @lilypond[quote,verbatim,relative=2,fragment]
962 \once \set fontSize = #4.7
967 the property @code{fontSize} is unset automatically after the second
970 A full description of all available context properties is in the
971 program reference, see
973 @internalsref{Tunable context properties}.
976 Translation @arrow{} Tunable context properties.
980 @node Modifying context plug-ins
981 @subsection Modifying context plug-ins
983 Notation contexts (like @code{Score} and @code{Staff}) not only
985 they also contain plug-ins called @q{engravers} that create notation
986 elements. For example, the @code{Voice} context contains a
987 @code{Note_head_engraver} and the @code{Staff} context contains a
988 @code{Key_signature_engraver}.
990 For a full a description of each plug-in, see
992 @internalsref{Engravers}.
995 Program reference @arrow Translation @arrow{} Engravers.
997 Every context described in
999 @internalsref{Contexts}
1002 Program reference @arrow Translation @arrow{} Context.
1004 lists the engravers used for that context.
1007 It can be useful to shuffle around these plug-ins. This is done by
1008 starting a new context with @code{\new} or @code{\context}, and
1014 \new @var{context} \with @{
1027 where the @dots{} should be the name of an engraver. Here is a simple
1028 example which removes @code{Time_signature_engraver} and
1029 @code{Clef_engraver} from a @code{Staff} context,
1031 @lilypond[quote,relative=1,verbatim,fragment]
1037 \remove "Time_signature_engraver"
1038 \remove "Clef_engraver"
1045 In the second staff there are no time signature or clef symbols. This
1046 is a rather crude method of making objects disappear since it will affect
1047 the entire staff. This method also influences the spacing, which may or
1048 may not be desirable. A more
1049 sophisticated method of blanking objects is shown in @ref{Common tweaks}.
1051 The next example shows a practical application. Bar lines and time
1052 signatures are normally synchronized across the score. This is done
1053 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
1054 This plug-in keeps an administration of time signature, location
1055 within the measure, etc. By moving thes engraver from @code{Score} to
1056 @code{Staff} context, we can have a score where each staff has its own
1059 @cindex polymetric scores
1060 @cindex Time signatures, multiple
1062 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
1064 \remove "Timing_translator"
1065 \remove "Default_bar_line_engraver"
1068 \consists "Timing_translator"
1069 \consists "Default_bar_line_engraver"
1075 \consists "Timing_translator"
1076 \consists "Default_bar_line_engraver"
1085 @node Layout tunings within contexts
1086 @subsection Layout tunings within contexts
1088 Each context is responsible for creating certain types of graphical
1089 objects. The settings used for printing these objects are also stored by
1090 context. By changing these settings, the appearance of objects can be
1093 The syntax for this is
1096 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1099 Here @var{name} is the name of a graphical object, like @code{Stem} or
1100 @code{NoteHead}, and @var{property} is an internal variable of the
1101 formatting system (@q{grob property} or @q{layout property}). The latter is a
1102 symbol, so it must be quoted. The subsection @ref{Constructing a
1103 tweak}, explains what to fill in for @var{name}, @var{property}, and
1104 @var{value}. Here we only discuss the functionality of this command.
1109 \override Staff.Stem #'thickness = #4.0
1113 makes stems thicker (the default is 1.3, with staff line thickness as a
1114 unit). Since the command specifies @context{Staff} as context, it only
1115 applies to the current staff. Other staves will keep their normal
1116 appearance. Here we see the command in action:
1118 @lilypond[quote,verbatim,relative=2,fragment]
1120 \override Staff.Stem #'thickness = #4.0
1126 The @code{\override} command changes the definition of the @code{Stem}
1127 within the current @context{Staff}. After the command is interpreted
1128 all stems are thickened.
1130 Analogous to @code{\set}, the @var{context} argument may be left out,
1131 causing the default context @context{Voice} to be used. Adding
1132 @code{\once} applies the change during one timestep only.
1134 @lilypond[quote,fragment,verbatim,relative=2]
1136 \once \override Stem #'thickness = #4.0
1141 The @code{\override} must be done before the object is
1142 started. Therefore, when altering @emph{Spanner} objects such as slurs
1143 or beams, the @code{\override} command must be executed at the moment
1144 when the object is created. In this example,
1146 @lilypond[quote,fragment,verbatim,relative=2]
1147 \override Slur #'thickness = #3.0
1149 \override Beam #'thickness = #0.6
1154 the slur is fatter but the beam is not. This is because the command for
1155 @code{Beam} comes after the Beam is started, so it has no effect.
1157 Analogous to @code{\unset}, the @code{\revert} command for a context
1158 undoes an @code{\override} command; like with @code{\unset}, it only
1159 affects settings that were made in the same context. In other words, the
1160 @code{\revert} in the next example does not do anything.
1163 \override Voice.Stem #'thickness = #4.0
1164 \revert Staff.Stem #'thickness
1167 Some tweakable options are called @q{subproperties} and reside inside
1168 properties. To tweak those, use commands of the form
1170 @c leave this as a long long
1172 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1179 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1185 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
1186 @internalsref{PropertySet}, @internalsref{Backend}, and
1187 @internalsref{All layout objects}.
1192 The back-end is not very strict in type-checking object properties.
1193 Cyclic references in Scheme values for properties can cause hangs
1194 or crashes, or both.
1197 @node Changing context default settings
1198 @subsection Changing context default settings
1200 The adjustments of the previous subsections (@ref{Changing context
1201 properties on the fly}, @ref{Modifying context plug-ins}, and
1202 @ref{Layout tunings within contexts}) can also be entered separately
1203 from the music in the @code{\layout} block,
1212 \override Stem #'thickness = #4.0
1213 \remove "Time_signature_engraver"
1218 The @code{\Staff} command brings in the existing definition of the
1219 staff context so that it can be modified.
1224 \override Stem #'thickness = #4.0
1225 \remove "Time_signature_engraver"
1229 affect all staves in the score. Other contexts can be modified
1232 The @code{\set} keyword is optional within the @code{\layout} block, so
1248 It is not possible to collect context changes in a variable and apply
1249 them to a @code{\context} definition by referring to that variable.
1251 The @code{\RemoveEmptyStaffContext} will overwrite your current
1252 @code{\Staff} settings. If you wish to change the defaults for a
1253 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
1254 after calling @code{\RemoveemptyStaffContext}, ie
1259 \RemoveEmptyStaffContext
1261 \override Stem #'thickness = #4.0
1267 @node Defining new contexts
1268 @subsection Defining new contexts
1270 Specific contexts, like @context{Staff} and @code{Voice}, are made of
1271 simple building blocks. It is possible to create new types of
1272 contexts with different combinations of engraver plug-ins.
1274 The next example shows how to build a different type of
1275 @context{Voice} context from scratch. It will be similar to
1276 @code{Voice}, but only prints centered slash noteheads. It can be used
1277 to indicate improvisation in jazz pieces,
1279 @lilypond[quote,ragged-right]
1280 \layout { \context {
1282 \type "Engraver_group"
1283 \consists "Note_heads_engraver"
1284 \consists "Text_engraver"
1285 \consists Pitch_squash_engraver
1286 squashedPosition = #0
1287 \override NoteHead #'style = #'slash
1288 \override Stem #'transparent = ##t
1292 \accepts "ImproVoice"
1296 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
1297 c4 c^"undress" c_"while playing :)" c }
1303 These settings are defined within a @code{\context} block inside a
1304 @code{\layout} block,
1314 In the following discussion, the example input shown should go in place
1315 of the @dots{} in the previous fragment.
1317 First it is necessary to define a name for the new context:
1323 Since it is similar to the @context{Voice}, we want commands that work
1324 on (existing) @context{Voice}s to remain working. This is achieved by
1325 giving the new context an alias @context{Voice},
1331 The context will print notes and instructive texts, so we need to add
1332 the engravers which provide this functionality,
1335 \consists Note_heads_engraver
1336 \consists Text_engraver
1339 but we only need this on the center line,
1342 \consists Pitch_squash_engraver
1343 squashedPosition = #0
1346 The @internalsref{Pitch_squash_engraver} modifies note heads (created
1347 by @internalsref{Note_heads_engraver}) and sets their vertical
1348 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
1351 The notes look like a slash, and have no stem,
1354 \override NoteHead #'style = #'slash
1355 \override Stem #'transparent = ##t
1358 All these plug-ins have to cooperate, and this is achieved with a
1359 special plug-in, which must be marked with the keyword @code{\type}.
1360 This should always be @internalsref{Engraver_group},
1363 \type "Engraver_group"
1366 Put together, we get
1371 \type "Engraver_group"
1372 \consists "Note_heads_engraver"
1373 \consists "Text_engraver"
1374 \consists Pitch_squash_engraver
1375 squashedPosition = #0
1376 \override NoteHead #'style = #'slash
1377 \override Stem #'transparent = ##t
1383 Contexts form hierarchies. We want to hang the @context{ImproVoice}
1384 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
1385 modify the @code{Staff} definition with the @code{\accepts}
1396 The opposite of @code{\accepts} is @code{\denies},
1397 which is sometimes needed when reusing existing context definitions.
1399 Putting both into a @code{\layout} block, like
1409 \accepts "ImproVoice"
1414 Then the output at the start of this subsection can be entered as
1422 c c_"while playing :)"
1429 @node Aligning contexts
1430 @subsection Aligning contexts
1432 New contexts may be aligned above or below exisiting contexts. This
1433 could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and
1437 @findex alignAboveContext
1438 @findex alignBelowContext
1440 @lilypond[quote,ragged-right]
1441 ossia = { f4 f f f }
1443 \relative c' \new Staff = "main" {
1446 \new Staff \with {alignAboveContext=main} \ossia
1447 { d8 f d f d f d f }
1454 @node Vertical grouping of grobs
1455 @subsection Vertical grouping of grobs
1457 The VerticalAlignment and VerticalAxisGroup grobs work together.
1458 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
1459 etc. VerticalAlignment then vertically aligns the different grobs
1460 grouped together by VerticalAxisGroup. There is usually only one
1461 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
1465 @node The \override command
1466 @section The @code{\override} command
1468 In the previous section, we have already touched on a command that
1469 changes layout details: the @code{\override} command. In this section,
1470 we will look in more detail at how to use the command in practice. The
1471 general syntax of this command is:
1474 \override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
1477 This will set the @var{layout_property} of the specified @var{layout_object},
1478 which is a member of the @var{context}, to the @var{value}.
1481 * Constructing a tweak::
1482 * Navigating the program reference::
1483 * Layout interfaces::
1484 * Determining the grob property::
1485 * Objects connected to the input::
1486 * Using Scheme code instead of \tweak::
1487 * \set versus \override::
1488 * Difficult tweaks::
1493 @node Constructing a tweak
1494 @subsection Constructing a tweak
1496 Commands which change output generally look like
1499 \override Voice.Stem #'thickness = #3.0
1503 To construct this tweak we must determine these bits of information:
1506 @item the context: here @context{Voice}.
1507 @item the layout object: here @code{Stem}.
1508 @item the layout property: here @code{thickness}.
1509 @item a sensible value: here @code{3.0}.
1512 Some tweakable options are called @q{subproperties} and reside inside
1513 properties. To tweak those, use commands in the form
1516 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1519 @cindex internal documentation
1520 @cindex finding graphical objects
1521 @cindex graphical object descriptions
1524 @cindex internal documentation
1526 For many properties, regardless of the data type of the property, setting the
1527 property to false ( @code{##f} ) will result in turning it off, causing
1528 Lilypond to ignore that property entirely. This is particularly useful for
1529 turning off grob properties which may otherwise be causing problems.
1531 We demonstrate how to glean this information from the notation manual
1532 and the program reference.
1537 @node Navigating the program reference
1538 @subsection Navigating the program reference
1540 Suppose we want to move the fingering indication in the fragment
1543 @lilypond[quote,fragment,relative=2,verbatim]
1549 If you visit the documentation on fingering instructions (in
1550 @ref{Fingering instructions}), you will notice:
1555 Program reference: @internalsref{Fingering}.
1560 @c outdated info; probably will delete.
1562 This fragment points to two parts of the program reference: a page
1563 on @code{FingerEvent} and one on @code{Fingering}.
1565 The page on @code{FingerEvent} describes the properties of the music
1566 expression for the input @code{-2}. The page contains many links
1567 forward. For example, it says
1570 Accepted by: @internalsref{Fingering_engraver},
1574 That link brings us to the documentation for the Engraver, the
1578 This engraver creates the following layout objects: @internalsref{Fingering}.
1581 In other words, once the @code{FingerEvent}s are interpreted, the
1582 @code{Fingering_engraver} plug-in will process them.
1586 @c I can't figure out what this is supposed to mean. -gp
1588 The @code{Fingering_engraver} is also listed to create
1589 @internalsref{Fingering} objects,
1591 @c old info? it doesn't make any sense to me with our current docs.
1593 second bit of information listed under @b{See also} in the Notation
1598 The programmer's reference is available as an HTML document. It is
1599 highly recommended that you read it in HTML form, either online or
1600 by downloading the HTML documentation. This section will be much more
1601 difficult to understand if you are using the
1605 Follow the link to @internalsref{Fingering}. At the top of the
1609 Fingering objects are created by: @internalsref{Fingering_engraver} and
1610 @internalsref{New_fingering_engraver}.
1613 By following related links inside the program reference, we can follow the
1614 flow of information within the program:
1618 @item @internalsref{Fingering}:
1619 @internalsref{Fingering} objects are created by:
1620 @internalsref{Fingering_engraver}
1622 @item @internalsref{Fingering_engraver}:
1623 Music types accepted: @internalsref{fingering-event}
1625 @item @internalsref{fingering-event}:
1626 Music event type @code{fingering-event} is in Music expressions named
1627 @internalsref{FingerEvent}
1630 This path goes against the flow of information in the program: it
1631 starts from the output, and ends at the input event. You could
1632 also start at an input event, and read with the flow of
1633 information, eventually ending up at the output object(s).
1635 The program reference can also be browsed like a normal document. It
1636 contains chapters on
1638 @internalsref{Music definitions},
1641 @code{Music definitions}
1643 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1644 chapter lists all the definitions used and all properties that may be
1648 @node Layout interfaces
1649 @subsection Layout interfaces
1651 @cindex interface, layout
1652 @cindex layout interface
1655 The HTML page that we found in the previous section describes the
1656 layout object called @internalsref{Fingering}. Such an object is a
1657 symbol within the score. It has properties that store numbers (like
1658 thicknesses and directions), but also pointers to related objects. A
1659 layout object is also called a @emph{Grob}, which is short for Graphical
1660 Object. For more details about Grobs, see @internalsref{grob-interface}.
1662 The page for @code{Fingering} lists the definitions for the
1663 @code{Fingering} object. For example, the page says
1666 @code{padding} (dimension, in staff space):
1672 which means that the number will be kept at a distance of at least 0.5
1676 Each layout object may have several functions as a notational or
1677 typographical element. For example, the Fingering object
1678 has the following aspects
1682 Its size is independent of the horizontal spacing, unlike slurs or beams.
1685 It is a piece of text. Granted, it is usually a very short text.
1688 That piece of text is typeset with a font, unlike slurs or beams.
1691 Horizontally, the center of the symbol should be aligned to the
1692 center of the notehead.
1695 Vertically, the symbol is placed next to the note and the staff.
1698 The vertical position is also coordinated with other superscript
1699 and subscript symbols.
1702 Each of these aspects is captured in so-called @emph{interface}s,
1703 which are listed on the @internalsref{Fingering} page at the bottom
1706 This object supports the following interfaces:
1707 @internalsref{item-interface},
1708 @internalsref{self-alignment-interface},
1709 @internalsref{side-position-interface}, @internalsref{text-interface},
1710 @internalsref{text-script-interface}, @internalsref{font-interface},
1711 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1714 Clicking any of the links will take you to the page of the respective
1715 object interface. Each interface has a number of properties. Some of
1716 them are not user-serviceable (@q{Internal properties}), but others
1719 We have been talking of @emph{the} @code{Fingering} object, but actually it
1720 does not amount to much. The initialization file (see
1721 @ref{Default files})
1722 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
1727 (avoid-slur . around)
1728 (slur-padding . 0.2)
1729 (staff-padding . 0.5)
1730 (self-alignment-X . 0)
1731 (self-alignment-Y . 0)
1732 (script-priority . 100)
1733 (stencil . ,ly:text-interface::print)
1734 (direction . ,ly:script-interface::calc-direction)
1735 (font-encoding . fetaNumber)
1736 (font-size . -5) ; don't overlap when next to heads.
1737 (meta . ((class . Item)
1738 (interfaces . (finger-interface
1740 text-script-interface
1742 side-position-interface
1743 self-alignment-interface
1744 item-interface))))))
1748 As you can see, the @code{Fingering} object is nothing more than a
1749 bunch of variable settings, and the webpage in the Program Reference
1750 is directly generated from this definition.
1753 @node Determining the grob property
1754 @subsection Determining the grob property
1756 Recall that we wanted to change the position of the @b{2} in
1758 @lilypond[quote,fragment,relative=2,verbatim]
1764 Since the @b{2} is vertically positioned next to its note, we have to
1765 meddle with the interface associated with this positioning. This is
1766 done using @code{side-position-interface}. The page for this interface
1770 @code{side-position-interface}
1772 Position a victim object (this one) next to other objects (the
1773 support). The property @code{direction} signifies where to put the
1774 victim object relative to the support (left or right, up or down?)
1779 Below this description, the variable @code{padding} is described as
1784 (dimension, in staff space)
1786 Add this much extra space between objects that are next to each other.
1790 By increasing the value of @code{padding}, we can move the
1791 fingering away from the notehead. The following command inserts
1792 3 staff spaces of white
1793 between the note and the fingering:
1795 \once \override Voice.Fingering #'padding = #3
1798 Inserting this command before the Fingering object is created,
1799 i.e., before @code{c2}, yields the following result:
1801 @lilypond[quote,relative=2,fragment,verbatim]
1802 \once \override Voice.Fingering #'padding = #3
1809 In this case, the context for this tweak is @context{Voice}. This
1810 fact can also be deduced from the program reference, for the page for
1811 the @internalsref{Fingering_engraver} plug-in says
1814 Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
1818 @node Objects connected to the input
1819 @subsection Objects connected to the input
1823 In some cases, it is possible to take a short-cut for tuning graphical
1824 objects. For objects that result directly from a piece of the input,
1825 you can use the @code{\tweak} function, for example
1827 @lilypond[relative=2,fragment,verbatim,ragged-right]
1830 \tweak #'color #red d
1832 \tweak #'duration-log #1 a
1833 >4-\tweak #'padding #10 -.
1836 As you can see, properties are set in the objects directly,
1837 without mentioning the grob name or context where this should be
1840 This technique only works for objects that are directly connected to
1841 an @internalsref{event} from the input, for example
1844 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1845 @item articulation signs, caused by articulation instructions
1848 It notably does not work for stems and accidentals (these are caused
1849 by note heads, not by music events) or clefs (these are not caused by
1850 music inputs, but rather by the change of a property value).
1852 There are very few objects which are @emph{directly} connected to
1853 output. A normal note (like @code{c4}) is not directly connected
1857 \tweak #'color #red c4
1861 does not change color. See @ref{Displaying music expressions}, for
1865 @node Using Scheme code instead of \tweak
1866 @subsection Using Scheme code instead of @code{\tweak}
1868 The main disadvantage of @code{\tweak} is its syntactical
1869 inflexibility. For example, the following produces a syntax error.
1872 F = \tweak #'font-size #-3 -\flageolet
1880 With other words, @code{\tweak} doesn't behave like an articulation
1881 regarding the syntax; in particular, it can't be attached with
1882 @samp{^} and @samp{_}.
1884 Using Scheme, this problem can be circumvented. The route to the
1885 result is given in @ref{Adding articulation to notes (example)},
1886 especially how to use @code{\displayMusic} as a helping guide.
1889 F = #(let ((m (make-music 'ArticulationEvent
1890 'articulation-type "flageolet")))
1891 (set! (ly:music-property m 'tweaks)
1892 (acons 'font-size -3
1893 (ly:music-property m 'tweaks)))
1902 Here, the @code{tweaks} properties of the flageolet object
1903 @samp{m} (created with @code{make-music}) are extracted with
1904 @code{ly:music-property}, a new key-value pair to change the
1905 font size is prepended to the property list with the
1906 @code{acons} Scheme function, and the result is finally
1907 written back with @code{set!}. The last element of the
1908 @code{let} block is the return value, @samp{m} itself.
1911 @node \set versus \override
1912 @subsection @code{\set} vs. @code{\override}
1914 We have seen two methods of changing properties: @code{\set} and
1915 @code{\override}. There are actually two different kinds of
1918 Contexts can have properties, which are usually named in
1919 @code{studlyCaps}. They mostly control the translation from
1920 music to notatino, eg. @code{localKeySignature} (for determining
1921 whether to print accidentals), @code{measurePosition} (for
1922 determining when to print a barline). Context properties can
1923 change value over time while interpreting a piece of music;
1924 @code{measurePosition} is an obvious example of
1925 this. Context properties are modified with @code{\set}.
1927 There is a special type of context property: the element
1928 description. These properties are named in @code{StudlyCaps}
1929 (starting with capital letters). They contain the
1930 @q{default settings} for said graphical object as an
1931 association list. See @file{scm/@/define@/-grobs@/.scm}
1932 to see what kind of settings there are. Element descriptions
1933 may be modified with @code{\override}.
1935 @code{\override} is actually a shorthand;
1938 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1942 is more or less equivalent to
1944 @c leave this long line -gp
1946 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1949 The value of @code{context} (the alist) is used to initalize
1950 the properties of individual grobs. Grobs also have
1951 properties, named in Scheme style, with
1952 @code{dashed-words}. The values of grob properties change
1953 during the formatting process: formatting basically amounts
1954 to computing properties using callback functions.
1956 @code{fontSize} is a special property: it is equivalent to
1957 entering @code{\override ... #'font-size} for all pertinent
1958 objects. Since this is a common change, the special
1959 property (modified with @code{\set}) was created.
1962 @node Difficult tweaks
1963 @subsection Difficult tweaks
1965 There are a few classes of difficult adjustments.
1971 One type of difficult adjustment is the appearance of spanner objects,
1972 such as slur and tie. Initially, only one of these objects is created,
1973 and they can be adjusted with the normal mechanism. However, in some
1974 cases the spanners cross line breaks. If this happens, these objects
1975 are cloned. A separate object is created for every system that it is
1976 in. These are clones of the original object and inherit all
1977 properties, including @code{\override}s.
1980 In other words, an @code{\override} always affects all pieces of a
1981 broken spanner. To change only one part of a spanner at a line break,
1982 it is necessary to hook into the formatting process. The
1983 @code{after-line-breaking} callback contains the Scheme procedure that
1984 is called after the line breaks have been determined, and layout
1985 objects have been split over different systems.
1987 In the following example, we define a procedure
1988 @code{my-callback}. This procedure
1992 determines if we have been split across line breaks
1994 if yes, retrieves all the split objects
1996 checks if we are the last of the split objects
1998 if yes, it sets @code{extra-offset}.
2001 This procedure is installed into @internalsref{Tie}, so the last part
2002 of the broken tie is translated up.
2004 @lilypond[quote,verbatim,ragged-right]
2005 #(define (my-callback grob)
2007 ; have we been split?
2008 (orig (ly:grob-original grob))
2010 ; if yes, get the split pieces (our siblings)
2011 (siblings (if (ly:grob? orig)
2012 (ly:spanner-broken-into orig) '() )))
2014 (if (and (>= (length siblings) 2)
2015 (eq? (car (last-pair siblings)) grob))
2016 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
2019 \override Tie #'after-line-breaking =
2026 When applying this trick, the new @code{after-line-breaking} callback
2027 should also call the old one @code{after-line-breaking}, if there is
2028 one. For example, if using this with @code{Hairpin},
2029 @code{ly:hairpin::after-line-breaking} should also be called.
2032 @item Some objects cannot be changed with @code{\override} for
2033 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
2034 and @code{PaperColumn}. They can be changed with the
2035 @code{\overrideProperty} function, which works similar to @code{\once
2036 \override}, but uses a different syntax.
2040 #"Score.NonMusicalPaperColumn" % Grob name
2041 #'line-break-system-details % Property name
2042 #'((next-padding . 20)) % Value
2045 Note, however, that @code{\override}, applied to
2046 @code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
2047 expected within @code{\context} blocks.