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.
544 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
546 #(override-auto-beam-setting '(end 1 16 1 4) 1 8)
548 #(revert-auto-beam-setting '(end 1 16 * *) 1 8) % ceci ne désactive pas la règle !
550 #(revert-auto-beam-setting '(end 1 16 1 4) 1 8) % ceci marche
556 @c TODO: old material -- not covered by above stuff, I think.
557 Si, dans une mesure à 5/4, l'on veut que les ligatures soient regroupées temps par temps,
558 il est nécessaire d'indiquer toutes les terminaisons de ligatures.
560 #(override-auto-beam-setting '(end * * * *) 1 4 'Staff)
561 #(override-auto-beam-setting '(end * * * *) 1 2 'Staff)
562 #(override-auto-beam-setting '(end * * * *) 3 4 'Staff)
563 #(override-auto-beam-setting '(end * * * *) 5 4 'Staff)
567 La même syntaxe peut servir à définir les points de départ des ligatures.
568 Dans l'exemple suivant, les ligatures automatiques ne peuvent se terminer
569 que sur une noire pointée.
571 #(override-auto-beam-setting '(end * * * *) 3 8)
572 #(override-auto-beam-setting '(end * * * *) 1 2)
573 #(override-auto-beam-setting '(end * * * *) 7 8)
575 @c ???? Je n'y comprends rien --vv
576 Dans une mesure à 4/4, cela implique que les ligatures ne peuvent se terminer que sur
577 la troisième croche, ou sur le quatrième temps (après la valeur de deux fois trois croches).
579 Si une ligature se fait de manière inattendue, pensez à vérifer les règles automatiques
580 dans le fichier @file{scm/@/auto@/-beam@/.scm} pour rechercher d'éventuels conflits, dans
581 la mesure ou les règles par défaut s'ajoutent à vos propres règles. Il est alors nécessaire
582 de désactiver toute règle par défaut conduisant à des ligatures indésirables.
584 Ainsi, pour obtenir des ligatures en groupes de @code{(3 4 3 2)} notes, dans une mesure à 12/8,
585 il faudra préalablement utiliser :
588 %%% annulons les réglages par défaut relatifs à 12/8, dans scm/auto-beam.scm
589 #(revert-auto-beam-setting '(end * * 12 8) 3 8)
590 #(revert-auto-beam-setting '(end * * 12 8) 3 4)
591 #(revert-auto-beam-setting '(end * * 12 8) 9 8)
593 %%% puis ajoutons nos propres règles
594 #(override-auto-beam-setting '(end 1 8 12 8) 3 8)
595 #(override-auto-beam-setting '(end 1 8 12 8) 7 8)
596 #(override-auto-beam-setting '(end 1 8 12 8) 10 8)
599 @cindex ligatures automatiques
600 @cindex groupes de notes
601 @funindex autoBeaming
604 Si des ligatures sont utilisées dans les paroles d'une chanson (pour indiquer des mélismes),
605 les ligatures automatiques doivent être désactivées, avec @code{\autoBeamOff}.
610 @funindex \autoBeamOff
612 @funindex \autoBeamOn
617 Les groupes de notes reliées par les ligatures peuvent être spécifiés au moyen
618 de la propriété @code{beatGrouping}.
620 @lilypond[quote,verbatim,relative=2,fragment,ragged-right]
622 \set beatGrouping = #'(2 3)
624 \set beatGrouping = #'(3 2)
631 Si une partition se termine alors qu'une ligature automatique est restée inachevée,
632 cette dernière ligature ne sera pas imprimée du tout. C'est également valable dans
633 le cas d'une musique polyphonique, saisie avec la syntaxe @code{<< @dots{} \\ @dots{}
634 >>}, où une voix se terminerait sans que la dernière ligature
637 @node Interpretation contexts
638 @section Interpretation contexts
640 This section describes what contexts are, and how to modify them.
643 * Contexts explained::
644 * Creating contexts::
645 * Changing context properties on the fly::
646 * Modifying context plug-ins::
647 * Layout tunings within contexts::
648 * Changing context default settings::
649 * Defining new contexts::
650 * Aligning contexts::
651 * Vertical grouping of grobs::
655 @node Contexts explained
656 @subsection Contexts explained
658 When music is printed, a lot of notational elements must be added to the
659 output. For example, compare the input and output of the following example:
661 @lilypond[quote,verbatim,relative=2,fragment]
665 The input is rather sparse, but in the output, bar lines, accidentals,
666 clef, and time signature are added. LilyPond @emph{interprets} the
667 input. During this step, the musical information is inspected in time
668 order, similar to reading a score from left to right. While reading
669 the input, the program remembers where measure boundaries are, and which
670 pitches require explicit accidentals. This information can be presented on
671 several levels. For example, the effect of an accidental is limited
672 to a single staff, while a bar line must be synchronized across the
675 Within LilyPond, these rules and bits of information are grouped in
676 @emph{Contexts}. Some examples of contexts are @context{Voice},
677 @context{Staff}, and @context{Score}. They are hierarchical, for
678 example: a @context{Staff} can contain many @context{Voice}s, and a
679 @context{Score} can contain many @context{Staff} contexts.
682 @image{context-example,5cm,,}
685 Each context has the responsibility for enforcing some notation rules,
686 creating some notation objects and maintaining the associated
687 properties. For example, the @context{Voice} context may introduce an
688 accidental and then the @context{Staff} context maintains the rule to
689 show or suppress the accidental for the remainder of the measure. The
690 synchronization of bar lines is handled at @context{Score} context.
692 However, in some music we may not want the bar lines to be
693 synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
694 such cases, we must modify the default settings of the @context{Score}
695 and @context{Staff} contexts.
697 For very simple scores, contexts are created implicitly, and you need
698 not be aware of them. For larger pieces, such as anything with more
699 than one staff, they must be
700 created explicitly to make sure that you get as many staves as you
701 need, and that they are in the correct order. For typesetting pieces
702 with specialized notation, it can be useful to modify existing or
703 to define new contexts.
706 A complete description of all available contexts is in the program
709 @internalsref{Contexts}.
712 Translation @arrow{} Context.
715 @c [TODO: describe propagation]
718 @node Creating contexts
719 @subsection Creating contexts
721 For scores with only one voice and one staff, contexts are
722 created automatically. For more complex scores, it is necessary to
723 create them by hand. There are three commands that do this.
728 The easiest command is @code{\new}, and it also the quickest to type.
729 It is prepended to a music expression, for example
733 @cindex Context, creating
736 \new @var{type} @var{music expression}
740 where @var{type} is a context name (like @code{Staff} or
741 @code{Voice}). This command creates a new context, and starts
742 interpreting the @var{music expression} with that.
744 A practical application of @code{\new} is a score with many
745 staves. Each part that should be on its own staff, is preceded with
748 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
755 The @code{\new} command may also give a name to the context,
758 \new @var{type} = @var{id} @var{music}
760 However, this user specified name is only used if there is no other
761 context already earlier with the same name.
767 Like @code{\new}, the @code{\context} command also directs a music
768 expression to a context object, but gives the context an explicit name. The
772 \context @var{type} = @var{id} @var{music}
775 This form will search for an existing context of type @var{type}
776 called @var{id}. If that context does not exist yet, a new
777 context with the specified name is created. This is useful if
778 the context is referred to later on. For example, when
779 setting lyrics the melody is in a named context
782 \context Voice = "@b{tenor}" @var{music}
786 so the texts can be properly aligned to its notes,
789 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
794 Another possible use of named contexts is funneling two different
795 music expressions into one context. In the following example,
796 articulations and notes are entered separately,
800 arts = @{ s4-. s4-> @}
803 They are combined by sending both to the same @context{Voice} context,
807 \new Staff \context Voice = "A" \music
808 \context Voice = "A" \arts
811 @lilypond[quote,ragged-right]
815 \new Staff \context Voice = "A" \music
816 \context Voice = "A" \arts
820 With this mechanism, it is possible to define an Urtext (original
821 edition), with the option to put several distinct articulations on the
824 @cindex creating contexts
827 The third command for creating contexts is
829 \context @var{type} @var{music}
834 This is similar to @code{\context} with @code{= @var{id}}, but matches
835 any context of type @var{type}, regardless of its given name.
837 This variant is used with music expressions that can be interpreted at
838 several levels. For example, the @code{\applyOutput} command (see
839 @ref{Running a function on all layout objects}). Without an explicit
840 @code{\context}, it is usually applied to @context{Voice}
843 \applyOutput #'@var{context} #@var{function} % apply to Voice
846 To have it interpreted at the @context{Score} or @context{Staff} level use
850 \applyOutput #'Score #@var{function}
851 \applyOutput #'Staff #@var{function}
857 @node Changing context properties on the fly
858 @subsection Changing context properties on the fly
862 @cindex changing properties
864 Each context can have different @emph{properties}, variables contained
865 in that context. They can be changed during the interpretation step.
866 This is achieved by inserting the @code{\set} command in the music,
869 \set @var{context}.@var{prop} = #@var{value}
873 @lilypond[quote,verbatim,relative=2,fragment]
875 \set Score.skipBars = ##t
879 This command skips measures that have no notes. The result is that
880 multi-rests are condensed. The value assigned is a Scheme object. In
881 this case, it is @code{#t}, the boolean True value.
883 If the @var{context} argument is left out, then the current bottom-most
884 context (typically @context{ChordNames}, @context{Voice}, or
885 @context{Lyrics}) is used. In this example,
887 @lilypond[quote,verbatim,relative=2,fragment]
889 \set autoBeaming = ##f
894 the @var{context} argument to @code{\set} is left out, so automatic
895 beaming is switched off in the current @internalsref{Voice}. Note that
896 the bottom-most context does not always contain the property that you
897 wish to change -- for example, attempting to set the @code{skipBars}
898 property (of the bottom-most context, in this case @code{Voice}) will
901 @lilypond[quote,verbatim,relative=2,fragment]
907 Contexts are hierarchical, so if a bigger context was specified, for
908 example @context{Staff}, then the change would also apply to all
909 @context{Voice}s in the current stave. The change is applied
910 @q{on-the-fly}, during the music, so that the setting only affects the
911 second group of eighth notes.
915 There is also an @code{\unset} command,
917 \unset @var{context}.@var{prop}
921 which removes the definition of @var{prop}. This command removes
922 the definition only if it is set in @var{context}, so
925 \set Staff.autoBeaming = ##f
929 introduces a property setting at @code{Staff} level. The setting also
930 applies to the current @code{Voice}. However,
933 \unset Voice.autoBeaming
937 does not have any effect. To cancel this setting, the @code{\unset}
938 must be specified on the same level as the original @code{\set}. In
939 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
942 \unset Staff.autoBeaming
945 Like @code{\set}, the @var{context} argument does not have to be
946 specified for a bottom context, so the two statements
949 \set Voice.autoBeaming = ##t
950 \set autoBeaming = ##t
958 Settings that should only apply to a single time-step can be entered
959 with @code{\once}, for example in
961 @lilypond[quote,verbatim,relative=2,fragment]
963 \once \set fontSize = #4.7
968 the property @code{fontSize} is unset automatically after the second
971 A full description of all available context properties is in the
972 program reference, see
974 @internalsref{Tunable context properties}.
977 Translation @arrow{} Tunable context properties.
981 @node Modifying context plug-ins
982 @subsection Modifying context plug-ins
984 Notation contexts (like @code{Score} and @code{Staff}) not only
986 they also contain plug-ins called @q{engravers} that create notation
987 elements. For example, the @code{Voice} context contains a
988 @code{Note_head_engraver} and the @code{Staff} context contains a
989 @code{Key_signature_engraver}.
991 For a full a description of each plug-in, see
993 @internalsref{Engravers}.
996 Program reference @arrow Translation @arrow{} Engravers.
998 Every context described in
1000 @internalsref{Contexts}
1003 Program reference @arrow Translation @arrow{} Context.
1005 lists the engravers used for that context.
1008 It can be useful to shuffle around these plug-ins. This is done by
1009 starting a new context with @code{\new} or @code{\context}, and
1015 \new @var{context} \with @{
1028 where the @dots{} should be the name of an engraver. Here is a simple
1029 example which removes @code{Time_signature_engraver} and
1030 @code{Clef_engraver} from a @code{Staff} context,
1032 @lilypond[quote,relative=1,verbatim,fragment]
1038 \remove "Time_signature_engraver"
1039 \remove "Clef_engraver"
1046 In the second staff there are no time signature or clef symbols. This
1047 is a rather crude method of making objects disappear since it will affect
1048 the entire staff. This method also influences the spacing, which may or
1049 may not be desirable. A more
1050 sophisticated method of blanking objects is shown in @ref{Common tweaks}.
1052 The next example shows a practical application. Bar lines and time
1053 signatures are normally synchronized across the score. This is done
1054 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
1055 This plug-in keeps an administration of time signature, location
1056 within the measure, etc. By moving thes engraver from @code{Score} to
1057 @code{Staff} context, we can have a score where each staff has its own
1060 @cindex polymetric scores
1061 @cindex Time signatures, multiple
1063 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
1065 \remove "Timing_translator"
1066 \remove "Default_bar_line_engraver"
1069 \consists "Timing_translator"
1070 \consists "Default_bar_line_engraver"
1076 \consists "Timing_translator"
1077 \consists "Default_bar_line_engraver"
1086 @node Layout tunings within contexts
1087 @subsection Layout tunings within contexts
1089 Each context is responsible for creating certain types of graphical
1090 objects. The settings used for printing these objects are also stored by
1091 context. By changing these settings, the appearance of objects can be
1094 The syntax for this is
1097 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1100 Here @var{name} is the name of a graphical object, like @code{Stem} or
1101 @code{NoteHead}, and @var{property} is an internal variable of the
1102 formatting system (@q{grob property} or @q{layout property}). The latter is a
1103 symbol, so it must be quoted. The subsection @ref{Constructing a
1104 tweak}, explains what to fill in for @var{name}, @var{property}, and
1105 @var{value}. Here we only discuss the functionality of this command.
1110 \override Staff.Stem #'thickness = #4.0
1114 makes stems thicker (the default is 1.3, with staff line thickness as a
1115 unit). Since the command specifies @context{Staff} as context, it only
1116 applies to the current staff. Other staves will keep their normal
1117 appearance. Here we see the command in action:
1119 @lilypond[quote,verbatim,relative=2,fragment]
1121 \override Staff.Stem #'thickness = #4.0
1127 The @code{\override} command changes the definition of the @code{Stem}
1128 within the current @context{Staff}. After the command is interpreted
1129 all stems are thickened.
1131 Analogous to @code{\set}, the @var{context} argument may be left out,
1132 causing the default context @context{Voice} to be used. Adding
1133 @code{\once} applies the change during one timestep only.
1135 @lilypond[quote,fragment,verbatim,relative=2]
1137 \once \override Stem #'thickness = #4.0
1142 The @code{\override} must be done before the object is
1143 started. Therefore, when altering @emph{Spanner} objects such as slurs
1144 or beams, the @code{\override} command must be executed at the moment
1145 when the object is created. In this example,
1147 @lilypond[quote,fragment,verbatim,relative=2]
1148 \override Slur #'thickness = #3.0
1150 \override Beam #'thickness = #0.6
1155 the slur is fatter but the beam is not. This is because the command for
1156 @code{Beam} comes after the Beam is started, so it has no effect.
1158 Analogous to @code{\unset}, the @code{\revert} command for a context
1159 undoes an @code{\override} command; like with @code{\unset}, it only
1160 affects settings that were made in the same context. In other words, the
1161 @code{\revert} in the next example does not do anything.
1164 \override Voice.Stem #'thickness = #4.0
1165 \revert Staff.Stem #'thickness
1168 Some tweakable options are called @q{subproperties} and reside inside
1169 properties. To tweak those, use commands of the form
1171 @c leave this as a long long
1173 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1180 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1186 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
1187 @internalsref{PropertySet}, @internalsref{Backend}, and
1188 @internalsref{All layout objects}.
1193 The back-end is not very strict in type-checking object properties.
1194 Cyclic references in Scheme values for properties can cause hangs
1195 or crashes, or both.
1198 @node Changing context default settings
1199 @subsection Changing context default settings
1201 The adjustments of the previous subsections (@ref{Changing context
1202 properties on the fly}, @ref{Modifying context plug-ins}, and
1203 @ref{Layout tunings within contexts}) can also be entered separately
1204 from the music in the @code{\layout} block,
1213 \override Stem #'thickness = #4.0
1214 \remove "Time_signature_engraver"
1219 The @code{\Staff} command brings in the existing definition of the
1220 staff context so that it can be modified.
1225 \override Stem #'thickness = #4.0
1226 \remove "Time_signature_engraver"
1230 affect all staves in the score. Other contexts can be modified
1233 The @code{\set} keyword is optional within the @code{\layout} block, so
1249 It is not possible to collect context changes in a variable and apply
1250 them to a @code{\context} definition by referring to that variable.
1252 The @code{\RemoveEmptyStaffContext} will overwrite your current
1253 @code{\Staff} settings. If you wish to change the defaults for a
1254 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
1255 after calling @code{\RemoveemptyStaffContext}, ie
1260 \RemoveEmptyStaffContext
1262 \override Stem #'thickness = #4.0
1268 @node Defining new contexts
1269 @subsection Defining new contexts
1271 Specific contexts, like @context{Staff} and @code{Voice}, are made of
1272 simple building blocks. It is possible to create new types of
1273 contexts with different combinations of engraver plug-ins.
1275 The next example shows how to build a different type of
1276 @context{Voice} context from scratch. It will be similar to
1277 @code{Voice}, but only prints centered slash noteheads. It can be used
1278 to indicate improvisation in jazz pieces,
1280 @lilypond[quote,ragged-right]
1281 \layout { \context {
1283 \type "Engraver_group"
1284 \consists "Note_heads_engraver"
1285 \consists "Text_engraver"
1286 \consists Pitch_squash_engraver
1287 squashedPosition = #0
1288 \override NoteHead #'style = #'slash
1289 \override Stem #'transparent = ##t
1293 \accepts "ImproVoice"
1297 a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
1298 c4 c^"undress" c_"while playing :)" c }
1304 These settings are defined within a @code{\context} block inside a
1305 @code{\layout} block,
1315 In the following discussion, the example input shown should go in place
1316 of the @dots{} in the previous fragment.
1318 First it is necessary to define a name for the new context:
1324 Since it is similar to the @context{Voice}, we want commands that work
1325 on (existing) @context{Voice}s to remain working. This is achieved by
1326 giving the new context an alias @context{Voice},
1332 The context will print notes and instructive texts, so we need to add
1333 the engravers which provide this functionality,
1336 \consists Note_heads_engraver
1337 \consists Text_engraver
1340 but we only need this on the center line,
1343 \consists Pitch_squash_engraver
1344 squashedPosition = #0
1347 The @internalsref{Pitch_squash_engraver} modifies note heads (created
1348 by @internalsref{Note_heads_engraver}) and sets their vertical
1349 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
1352 The notes look like a slash, and have no stem,
1355 \override NoteHead #'style = #'slash
1356 \override Stem #'transparent = ##t
1359 All these plug-ins have to cooperate, and this is achieved with a
1360 special plug-in, which must be marked with the keyword @code{\type}.
1361 This should always be @internalsref{Engraver_group},
1364 \type "Engraver_group"
1367 Put together, we get
1372 \type "Engraver_group"
1373 \consists "Note_heads_engraver"
1374 \consists "Text_engraver"
1375 \consists Pitch_squash_engraver
1376 squashedPosition = #0
1377 \override NoteHead #'style = #'slash
1378 \override Stem #'transparent = ##t
1384 Contexts form hierarchies. We want to hang the @context{ImproVoice}
1385 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
1386 modify the @code{Staff} definition with the @code{\accepts}
1397 The opposite of @code{\accepts} is @code{\denies},
1398 which is sometimes needed when reusing existing context definitions.
1400 Putting both into a @code{\layout} block, like
1410 \accepts "ImproVoice"
1415 Then the output at the start of this subsection can be entered as
1423 c c_"while playing :)"
1430 @node Aligning contexts
1431 @subsection Aligning contexts
1433 New contexts may be aligned above or below exisiting contexts. This
1434 could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and
1438 @findex alignAboveContext
1439 @findex alignBelowContext
1441 @lilypond[quote,ragged-right]
1442 ossia = { f4 f f f }
1444 \relative c' \new Staff = "main" {
1447 \new Staff \with {alignAboveContext=main} \ossia
1448 { d8 f d f d f d f }
1455 @node Vertical grouping of grobs
1456 @subsection Vertical grouping of grobs
1458 The VerticalAlignment and VerticalAxisGroup grobs work together.
1459 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
1460 etc. VerticalAlignment then vertically aligns the different grobs
1461 grouped together by VerticalAxisGroup. There is usually only one
1462 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
1466 @node The \override command
1467 @section The @code{\override} command
1469 In the previous section, we have already touched on a command that
1470 changes layout details: the @code{\override} command. In this section,
1471 we will look in more detail at how to use the command in practice. The
1472 general syntax of this command is:
1475 \override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
1478 This will set the @var{layout_property} of the specified @var{layout_object},
1479 which is a member of the @var{context}, to the @var{value}.
1482 * Constructing a tweak::
1483 * Navigating the program reference::
1484 * Layout interfaces::
1485 * Determining the grob property::
1486 * Objects connected to the input::
1487 * Using Scheme code instead of \tweak::
1488 * \set versus \override::
1489 * Difficult tweaks::
1494 @node Constructing a tweak
1495 @subsection Constructing a tweak
1497 Commands which change output generally look like
1500 \override Voice.Stem #'thickness = #3.0
1504 To construct this tweak we must determine these bits of information:
1507 @item the context: here @context{Voice}.
1508 @item the layout object: here @code{Stem}.
1509 @item the layout property: here @code{thickness}.
1510 @item a sensible value: here @code{3.0}.
1513 Some tweakable options are called @q{subproperties} and reside inside
1514 properties. To tweak those, use commands in the form
1517 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1520 @cindex internal documentation
1521 @cindex finding graphical objects
1522 @cindex graphical object descriptions
1525 @cindex internal documentation
1527 For many properties, regardless of the data type of the property, setting the
1528 property to false ( @code{##f} ) will result in turning it off, causing
1529 Lilypond to ignore that property entirely. This is particularly useful for
1530 turning off grob properties which may otherwise be causing problems.
1532 We demonstrate how to glean this information from the notation manual
1533 and the program reference.
1538 @node Navigating the program reference
1539 @subsection Navigating the program reference
1541 Suppose we want to move the fingering indication in the fragment
1544 @lilypond[quote,fragment,relative=2,verbatim]
1550 If you visit the documentation on fingering instructions (in
1551 @ref{Fingering instructions}), you will notice:
1556 Program reference: @internalsref{Fingering}.
1561 @c outdated info; probably will delete.
1563 This fragment points to two parts of the program reference: a page
1564 on @code{FingerEvent} and one on @code{Fingering}.
1566 The page on @code{FingerEvent} describes the properties of the music
1567 expression for the input @code{-2}. The page contains many links
1568 forward. For example, it says
1571 Accepted by: @internalsref{Fingering_engraver},
1575 That link brings us to the documentation for the Engraver, the
1579 This engraver creates the following layout objects: @internalsref{Fingering}.
1582 In other words, once the @code{FingerEvent}s are interpreted, the
1583 @code{Fingering_engraver} plug-in will process them.
1587 @c I can't figure out what this is supposed to mean. -gp
1589 The @code{Fingering_engraver} is also listed to create
1590 @internalsref{Fingering} objects,
1592 @c old info? it doesn't make any sense to me with our current docs.
1594 second bit of information listed under @b{See also} in the Notation
1599 The programmer's reference is available as an HTML document. It is
1600 highly recommended that you read it in HTML form, either online or
1601 by downloading the HTML documentation. This section will be much more
1602 difficult to understand if you are using the
1606 Follow the link to @internalsref{Fingering}. At the top of the
1610 Fingering objects are created by: @internalsref{Fingering_engraver} and
1611 @internalsref{New_fingering_engraver}.
1614 By following related links inside the program reference, we can follow the
1615 flow of information within the program:
1619 @item @internalsref{Fingering}:
1620 @internalsref{Fingering} objects are created by:
1621 @internalsref{Fingering_engraver}
1623 @item @internalsref{Fingering_engraver}:
1624 Music types accepted: @internalsref{fingering-event}
1626 @item @internalsref{fingering-event}:
1627 Music event type @code{fingering-event} is in Music expressions named
1628 @internalsref{FingerEvent}
1631 This path goes against the flow of information in the program: it
1632 starts from the output, and ends at the input event. You could
1633 also start at an input event, and read with the flow of
1634 information, eventually ending up at the output object(s).
1636 The program reference can also be browsed like a normal document. It
1637 contains chapters on
1639 @internalsref{Music definitions},
1642 @code{Music definitions}
1644 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1645 chapter lists all the definitions used and all properties that may be
1649 @node Layout interfaces
1650 @subsection Layout interfaces
1652 @cindex interface, layout
1653 @cindex layout interface
1656 The HTML page that we found in the previous section describes the
1657 layout object called @internalsref{Fingering}. Such an object is a
1658 symbol within the score. It has properties that store numbers (like
1659 thicknesses and directions), but also pointers to related objects. A
1660 layout object is also called a @emph{Grob}, which is short for Graphical
1661 Object. For more details about Grobs, see @internalsref{grob-interface}.
1663 The page for @code{Fingering} lists the definitions for the
1664 @code{Fingering} object. For example, the page says
1667 @code{padding} (dimension, in staff space):
1673 which means that the number will be kept at a distance of at least 0.5
1677 Each layout object may have several functions as a notational or
1678 typographical element. For example, the Fingering object
1679 has the following aspects
1683 Its size is independent of the horizontal spacing, unlike slurs or beams.
1686 It is a piece of text. Granted, it is usually a very short text.
1689 That piece of text is typeset with a font, unlike slurs or beams.
1692 Horizontally, the center of the symbol should be aligned to the
1693 center of the notehead.
1696 Vertically, the symbol is placed next to the note and the staff.
1699 The vertical position is also coordinated with other superscript
1700 and subscript symbols.
1703 Each of these aspects is captured in so-called @emph{interface}s,
1704 which are listed on the @internalsref{Fingering} page at the bottom
1707 This object supports the following interfaces:
1708 @internalsref{item-interface},
1709 @internalsref{self-alignment-interface},
1710 @internalsref{side-position-interface}, @internalsref{text-interface},
1711 @internalsref{text-script-interface}, @internalsref{font-interface},
1712 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1715 Clicking any of the links will take you to the page of the respective
1716 object interface. Each interface has a number of properties. Some of
1717 them are not user-serviceable (@q{Internal properties}), but others
1720 We have been talking of @emph{the} @code{Fingering} object, but actually it
1721 does not amount to much. The initialization file (see
1722 @ref{Default files})
1723 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
1728 (avoid-slur . around)
1729 (slur-padding . 0.2)
1730 (staff-padding . 0.5)
1731 (self-alignment-X . 0)
1732 (self-alignment-Y . 0)
1733 (script-priority . 100)
1734 (stencil . ,ly:text-interface::print)
1735 (direction . ,ly:script-interface::calc-direction)
1736 (font-encoding . fetaNumber)
1737 (font-size . -5) ; don't overlap when next to heads.
1738 (meta . ((class . Item)
1739 (interfaces . (finger-interface
1741 text-script-interface
1743 side-position-interface
1744 self-alignment-interface
1745 item-interface))))))
1749 As you can see, the @code{Fingering} object is nothing more than a
1750 bunch of variable settings, and the webpage in the Program Reference
1751 is directly generated from this definition.
1754 @node Determining the grob property
1755 @subsection Determining the grob property
1757 Recall that we wanted to change the position of the @b{2} in
1759 @lilypond[quote,fragment,relative=2,verbatim]
1765 Since the @b{2} is vertically positioned next to its note, we have to
1766 meddle with the interface associated with this positioning. This is
1767 done using @code{side-position-interface}. The page for this interface
1771 @code{side-position-interface}
1773 Position a victim object (this one) next to other objects (the
1774 support). The property @code{direction} signifies where to put the
1775 victim object relative to the support (left or right, up or down?)
1780 Below this description, the variable @code{padding} is described as
1785 (dimension, in staff space)
1787 Add this much extra space between objects that are next to each other.
1791 By increasing the value of @code{padding}, we can move the
1792 fingering away from the notehead. The following command inserts
1793 3 staff spaces of white
1794 between the note and the fingering:
1796 \once \override Voice.Fingering #'padding = #3
1799 Inserting this command before the Fingering object is created,
1800 i.e., before @code{c2}, yields the following result:
1802 @lilypond[quote,relative=2,fragment,verbatim]
1803 \once \override Voice.Fingering #'padding = #3
1810 In this case, the context for this tweak is @context{Voice}. This
1811 fact can also be deduced from the program reference, for the page for
1812 the @internalsref{Fingering_engraver} plug-in says
1815 Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
1819 @node Objects connected to the input
1820 @subsection Objects connected to the input
1824 In some cases, it is possible to take a short-cut for tuning graphical
1825 objects. For objects that result directly from a piece of the input,
1826 you can use the @code{\tweak} function, for example
1828 @lilypond[relative=2,fragment,verbatim,ragged-right]
1831 \tweak #'color #red d
1833 \tweak #'duration-log #1 a
1834 >4-\tweak #'padding #10 -.
1837 As you can see, properties are set in the objects directly,
1838 without mentioning the grob name or context where this should be
1841 This technique only works for objects that are directly connected to
1842 an @internalsref{event} from the input, for example
1845 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1846 @item articulation signs, caused by articulation instructions
1849 It notably does not work for stems and accidentals (these are caused
1850 by note heads, not by music events) or clefs (these are not caused by
1851 music inputs, but rather by the change of a property value).
1853 There are very few objects which are @emph{directly} connected to
1854 output. A normal note (like @code{c4}) is not directly connected
1858 \tweak #'color #red c4
1862 does not change color. See @ref{Displaying music expressions}, for
1866 @node Using Scheme code instead of \tweak
1867 @subsection Using Scheme code instead of @code{\tweak}
1869 The main disadvantage of @code{\tweak} is its syntactical
1870 inflexibility. For example, the following produces a syntax error.
1873 F = \tweak #'font-size #-3 -\flageolet
1881 With other words, @code{\tweak} doesn't behave like an articulation
1882 regarding the syntax; in particular, it can't be attached with
1883 @samp{^} and @samp{_}.
1885 Using Scheme, this problem can be circumvented. The route to the
1886 result is given in @ref{Adding articulation to notes (example)},
1887 especially how to use @code{\displayMusic} as a helping guide.
1890 F = #(let ((m (make-music 'ArticulationEvent
1891 'articulation-type "flageolet")))
1892 (set! (ly:music-property m 'tweaks)
1893 (acons 'font-size -3
1894 (ly:music-property m 'tweaks)))
1903 Here, the @code{tweaks} properties of the flageolet object
1904 @samp{m} (created with @code{make-music}) are extracted with
1905 @code{ly:music-property}, a new key-value pair to change the
1906 font size is prepended to the property list with the
1907 @code{acons} Scheme function, and the result is finally
1908 written back with @code{set!}. The last element of the
1909 @code{let} block is the return value, @samp{m} itself.
1912 @node \set versus \override
1913 @subsection @code{\set} vs. @code{\override}
1915 We have seen two methods of changing properties: @code{\set} and
1916 @code{\override}. There are actually two different kinds of
1919 Contexts can have properties, which are usually named in
1920 @code{studlyCaps}. They mostly control the translation from
1921 music to notatino, eg. @code{localKeySignature} (for determining
1922 whether to print accidentals), @code{measurePosition} (for
1923 determining when to print a barline). Context properties can
1924 change value over time while interpreting a piece of music;
1925 @code{measurePosition} is an obvious example of
1926 this. Context properties are modified with @code{\set}.
1928 There is a special type of context property: the element
1929 description. These properties are named in @code{StudlyCaps}
1930 (starting with capital letters). They contain the
1931 @q{default settings} for said graphical object as an
1932 association list. See @file{scm/@/define@/-grobs@/.scm}
1933 to see what kind of settings there are. Element descriptions
1934 may be modified with @code{\override}.
1936 @code{\override} is actually a shorthand;
1939 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1943 is more or less equivalent to
1945 @c leave this long line -gp
1947 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1950 The value of @code{context} (the alist) is used to initalize
1951 the properties of individual grobs. Grobs also have
1952 properties, named in Scheme style, with
1953 @code{dashed-words}. The values of grob properties change
1954 during the formatting process: formatting basically amounts
1955 to computing properties using callback functions.
1957 @code{fontSize} is a special property: it is equivalent to
1958 entering @code{\override ... #'font-size} for all pertinent
1959 objects. Since this is a common change, the special
1960 property (modified with @code{\set}) was created.
1963 @node Difficult tweaks
1964 @subsection Difficult tweaks
1966 There are a few classes of difficult adjustments.
1972 One type of difficult adjustment is the appearance of spanner objects,
1973 such as slur and tie. Initially, only one of these objects is created,
1974 and they can be adjusted with the normal mechanism. However, in some
1975 cases the spanners cross line breaks. If this happens, these objects
1976 are cloned. A separate object is created for every system that it is
1977 in. These are clones of the original object and inherit all
1978 properties, including @code{\override}s.
1981 In other words, an @code{\override} always affects all pieces of a
1982 broken spanner. To change only one part of a spanner at a line break,
1983 it is necessary to hook into the formatting process. The
1984 @code{after-line-breaking} callback contains the Scheme procedure that
1985 is called after the line breaks have been determined, and layout
1986 objects have been split over different systems.
1988 In the following example, we define a procedure
1989 @code{my-callback}. This procedure
1993 determines if we have been split across line breaks
1995 if yes, retrieves all the split objects
1997 checks if we are the last of the split objects
1999 if yes, it sets @code{extra-offset}.
2002 This procedure is installed into @internalsref{Tie}, so the last part
2003 of the broken tie is translated up.
2005 @lilypond[quote,verbatim,ragged-right]
2006 #(define (my-callback grob)
2008 ; have we been split?
2009 (orig (ly:grob-original grob))
2011 ; if yes, get the split pieces (our siblings)
2012 (siblings (if (ly:grob? orig)
2013 (ly:spanner-broken-into orig) '() )))
2015 (if (and (>= (length siblings) 2)
2016 (eq? (car (last-pair siblings)) grob))
2017 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
2020 \override Tie #'after-line-breaking =
2027 When applying this trick, the new @code{after-line-breaking} callback
2028 should also call the old one @code{after-line-breaking}, if there is
2029 one. For example, if using this with @code{Hairpin},
2030 @code{ly:hairpin::after-line-breaking} should also be called.
2033 @item Some objects cannot be changed with @code{\override} for
2034 technical reasons. Examples of those are @code{NonMusicalPaperColumn}
2035 and @code{PaperColumn}. They can be changed with the
2036 @code{\overrideProperty} function, which works similar to @code{\once
2037 \override}, but uses a different syntax.
2041 #"Score.NonMusicalPaperColumn" % Grob name
2042 #'line-break-system-details % Property name
2043 #'((next-padding . 20)) % Value
2046 Note, however, that @code{\override}, applied to
2047 @code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
2048 expected within @code{\context} blocks.