1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 0cde75024b6f1210b059c48b624e1026836c96aa
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @c Translators: Valentin Villenave, Jean-Charles Malahieude
14 @c Translation checkers: Gilles Thibault
16 @node Interfaces pour programmeurs
17 @chapter Interfaces pour programmeurs
18 @translationof Interfaces for programmers
20 Scheme permet de réaliser des affinages très pointus. Si vous ne
21 connaissez rien de Scheme, vous en aurez un aperçu au travers de notre
22 @ref{Tutoriel Scheme}.
25 * Blocs de code LilyPond::
27 * Fonctions musicales::
28 * Fonctions événementielles::
29 * Fonctions pour markups::
30 * Contextes pour programmeurs::
31 * Fonctions de rappel::
32 * Code Scheme intégré::
33 * Retouches complexes::
37 @node Blocs de code LilyPond
38 @section Blocs de code LilyPond
39 @translationof Lilypond code blocks
41 Les blocs de code LilyPond ressemblent à
43 #@{ @var{du code LilyPond} #@}
45 Ils peuvent s'utiliser partout où vous pouvez écrire du code Scheme.
46 Le lecteur Scheme est en fait quelque peu adapté pour accepter des blocs
47 de code LilyPond ; il est capable de traiter des expressions Scheme
48 intégrées débutant par @code{$} ou @code{#}.
50 Le lecteur Scheme extrait le bloc de code LilyPond et déclenche un appel
51 à l'analyseur grammatical de LilyPond (le @code{parser}) qui réalise en
52 temps réel l'interprétation de ce bloc de code LilyPond. Toute
53 expression Scheme imbriquée est exécutée dans l'environnement lexical du
54 bloc de code LilyPond, de telle sorte que vous avez accès aux variables
55 locales et aux paramètres de la fonction au moment même où le bloc de
56 code LilyPond est écrit. Lorsque l'@code{emplacement} fait référence à
57 un endroit valide dans la source -- ce qui est en général le cas au sein
58 de fonctions musicales ou Scheme --, toute la musique générée au sein de
59 ce bloc de code voit son @code{origine} établie à cet
62 Un bloc de code LilyPond peut contenir tout ce que vous pourriez mettre
63 à droite de l'assignation. Par ailleurs, un bloc LilyPond vide
64 correspond à une expression fantôme, et un bloc LilyPond de multiples
65 événements musicaux sera transformé en une expression de musique
69 @node Fonctions Scheme
70 @section Fonctions Scheme
71 @translationof Scheme functions
73 @cindex Scheme, fonctions (syntaxe LilyPond)
75 Les @emph{fonctions Scheme} sont des procédures Scheme chargées de créer
76 des expressions Scheme à partir de code rédigé selon la syntaxe de
77 LilyPond. Elles peuvent être appelées en de nombreux endroits, à l'aide
78 d'un @code{#}, où spécifier une valeur en syntaxe Scheme est autorisé.
79 Bien que Scheme dispose de fonctions en propre, nous nous intéresserons,
80 au fil des paragraphes qui suivent, aux fonctions @emph{syntaxiques},
81 autrement dit des fonctions qui reçoivent des arguments libellés dans la
85 * Définition de fonctions Scheme::
86 * Utilisation de fonctions Scheme::
87 * Fonctions Scheme fantômes::
90 @node Définition de fonctions Scheme
91 @subsection Définition de fonctions Scheme
92 @translationof Scheme function definitions
94 @funindex define-scheme-function
96 D'une manière générale, une fonction Scheme se définit ainsi :
100 #(define-scheme-function
101 (parser location @var{arg1} @var{arg2} @dots{})
102 (@var{type1?} @var{type2?} @dots{})
109 @multitable @columnfractions .33 .66
111 @tab doit être littéralement @code{parser}, de telle sorte que
112 l'analyseur grammatical puisse accéder aux blocs de code LilyPond
113 (@code{#@{}@dots{}@code{#@}}).
115 @item @code{@var{argN}}
116 @tab @var{n}ième argument
118 @item @code{@var{typeN?}}
119 @tab un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
120 devra retourner @code{#t}. Certains de ces prédicats, comme nous le
121 verrons plus loin, bénéficient d'un traitement particulier de la part du
122 @emph{parser}. De même existe une forme spécifique --
123 @code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
124 argument optionnels. En l'absence d'argument réel au moment de l'appel
125 de la fonction, c'est la valeur par défaut qui lui sera substituée. Les
126 valeurs par défaut sont évaluées dès l'apparition de la définition, y
127 compris dans le cas de blocs de code LilyPond ; vous devrez donc,
128 si ces valeurs par défaut ne peuvent être déterminées que plus tard,
129 mentionner une valeur spéciale que vous reconnaîtrez facilement.
130 Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
131 fournir sa valeur par défaut, celle-ci sera considérée comme étant
132 @code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
133 vérifiées ni au moment de la définition, ni à l'exécution ; il est
134 de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
135 par défaut constituée d'une expression musicale est recopiée dès la
136 définition de @code{origin} vers le paramètre @code{location}.
138 @item @code{@var{corps}}
139 @tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
140 servant de valeur de retour de la fonction. Il peut contenir des blocs
141 de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
142 @w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
143 @ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
144 @code{#} permet de référencer des arguments de la fonction -- tel
145 @samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
146 arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
147 Dans le cas où une expression Scheme introduite par @code{#} ne vous
148 permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
149 expression Scheme @qq{immédiate} à l'aide d'un @code{$}, comme
152 Lorsque votre fonction retourne une expression musicale, lui est
153 attribuée la valeur @code{origin}.
157 Certains types de prédicat font l'objet d'un traitement spécial de la
158 part de l'analyseur grammatical, dans la mesure où il n'a aucun autre
159 moyen de reconnaître efficacement les arguments. Il s'agit, à l'heure
160 actuelle, de @code{ly:pitch?} et @code{ly:duration?}.
162 Pour tous les autres prédicats, la recevabilité des arguments est
163 déterminée par un appel effectif au prédicat après que LilyPond les a
164 déjà converti en expression Scheme. Par voie de conséquence, l'argument
165 peut tout à fait se libeller en syntaxe Scheme -- introduite par un
166 @code{#} ou en tant que résultat d'un appel à une fonction Scheme. Par
167 ailleurs, LilyPond convertira en Scheme un certain nombre de
168 constructions purement LilyPond avant même d'en avoir vérifié le
169 prédicat. C'est notamment le cas de la musique, des
170 @emph{postévénements}, des chaînes simples (avec ou sans guillemets),
171 des nombres, des @emph{markups} et listes de @emph{markups}, ainsi que
172 des blocs @emph{score}, @emph{book}, @emph{bookpart}, ou qui définissent
173 un contexte ou un format de sortie.
175 Il existe certaines formes d'expression, comme la plupart du temps où la
176 musique n'est pas bornée par des accolades, où LilyPond doit lire
177 au-delà de cette même expression afin d'en déterminer la fin. Si une
178 telle expression devait, après évaluation du prédicat, faire l'objet
179 d'un argument optionnel, LilyPond n'aurait aucun moyen, à partir du
180 moment où il aura décidé que l'expression ne correspond pas au
181 paramètre, de @qq{revenir en arrière}. C'est la raison pour laquelle
182 certaines formes musicales devraient être bornées par des accolades pour
183 que LilyPond puisse les reconnaître efficacement. Il existe d'autres
184 situations pour lesquelles LilyPond lèvera toute ambiguïté grâce aux
185 fonctions de prédicat : un @samp{-3} est-il un @emph{postévénement}
186 de type doigté ou un nombre négatif@tie{}? Un @code{"a" 4} en mode
187 paroles est-il une chaîne suivie d'un nombre ou bien un événement
188 syllabe de durée @code{4} ? LilyPond répondra à ces questions
189 après consultation du prédicat. Pour toutes ces raisons, nous vous
190 enjoignons à éviter d'utiliser des prédicats permissifs tel que
191 @code{scheme?}, dès que vous voulez les utiliser dans un but particulier
192 plutôt que dans une fonction de portée générale.
194 Les différents types des prédicat propres à LilyPond sont recensés à
195 l'annexe @ruser{Types de prédicats prédéfinis}.
199 @ruser{Types de prédicats prédéfinis}.
201 Fichiers d'initialisation :
202 @file{lily/music-scheme.cc},
207 @node Utilisation de fonctions Scheme
208 @subsection Utilisation de fonctions Scheme
209 @translationof Scheme function usage
211 Vous pouvez appeler une fonction Scheme pratiquement partout où une
212 expression Scheme derrière un @code{#} peut prendre place. Vous appelez
213 une fonction Scheme en faisant précéder son nom d'un @code{\}, et en le
214 faisant suivre de ses arguments. Lorsqu'un prédicat d'argument
215 optionnel ne correspond pas à un argument, LilyPond l'ignore ainsi que
216 tous les arguments optionnels qui suivent, les remplaçant par leur
217 valeur par défaut, et @qq{sauvegarde} en tant que prochain argument
218 obligatoire l'argument qui ne correspondait pas. Dans la mesure où
219 l'argument sauvegardé doit servir, les argument optionnels ne sont en
220 fait pas considérés comme optionnels, sauf à être suivis d'un argument
223 Une exception cependant à cette règle : le fait de donner un
224 @code{\default} en tant qu'argument optionnel aura pour résultat que cet
225 argument et tous les autres arguments optionnels qui suivent seront
226 ignorés et remplacés par leur valeur par défaut. Il en va de même
227 lorsqu'aucun argument obligatoire ne suit, du fait que @code{\default}
228 ne requiert pas de sauvegarde. C'est d'ailleurs ainsi que fonctionnent
229 les commandes @code{mark} et @code{key}, qui retrouvent leur
230 comportement par défaut lorsque vous les faites suivre d'un
233 En plus de là où une expression Scheme est requise, il y a quelques
234 endroits où des expressions @code{#} sont acceptées et évaluées
235 uniquement pour leurs effets annexes. Il s'agit, dans la plupart des
236 cas, d'endroits où une affectation serait tout à fait envisageable.
238 Dans la mesure où il n'est pas bon de renvoyer une valeur qui pourrait
239 être mal interprétée dans certains contextes, nous vous enjoignons à
240 utiliser des fonctions Scheme normales uniquement dans les cas où vous
241 renvoyez toujours une valeur utile, et une fonction fantôme -- voir
242 @ref{Fonctions Scheme fantômes} -- dans le cas contraire.
245 @node Fonctions Scheme fantômes
246 @subsection Fonctions Scheme fantômes
247 @translationof Void scheme functions
249 @cindex @emph{void}, fonction
250 @cindex fantôme, fonction
252 @funindex define-void-function
255 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
256 pour renvoyer une valeur. Certains langages de programmation, tels
257 le C et Scheme, utilisent des fonctions dans les deux cas et se
258 débarrassent tout bonnement de la valeur renvoyée ; en règle
259 générale, il suffit que l'expression fasse office de déclaration, et
260 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
261 la plupart des compilateurs C actuels déclenchent un avertissement si
262 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
263 nombreuses fonctions réalisant une action, les standards Scheme
264 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
265 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
266 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
267 lorsqu'on utilise @code{set!} directement sur une variable -- mais
268 malheureusement pas toujours.
270 Une fonction LilyPond définie à l'aide de la clause
271 @code{define-void-function} vous apporte l'assurance que c'est cette
272 valeur spéciale -- la seule valeur qui satisfasse au prédicat
273 @code{void?} -- qui sera retournée.
277 #(define-void-function
280 (ly:set-option 'point-and-click #f))
282 \noPointAndClick % desactive le "pointer-cliquer"
285 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
286 expression pour ses effets annexes sans interprétation d'une quelconque
290 \void #(hashq-set! une-table une-clé une-valeur)
293 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
294 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
295 opérationnel dans le cadre de fonctions musicales telles que
296 @code{\displayMusic}.
299 @node Fonctions musicales
300 @section Fonctions musicales
301 @translationof Music functions
303 @cindex musicale, fonction
305 Les @emph{fonctions musicales} sont des procédures Scheme capables de
306 créer automatiquement des expressions musicales ; elles permettent
307 de grandement simplifier un fichier source.
310 * Définition de fonctions musicales::
311 * Utilisation de fonctions musicales::
312 * Fonctions de substitution simple::
313 * Fonctions de substitution intermédiaires::
314 * De l'usage des mathématiques dans les fonctions::
315 * Fonctions dépourvues d'argument::
316 * Fonctions musicales fantômes::
320 @node Définition de fonctions musicales
321 @subsection Définition de fonctions musicales
322 @translationof Music function definitions
324 @cindex fonction musicale, définition
326 @funindex define-music-function
328 Une fonction musicale se définit ainsi :
332 #(define-music-function
333 (parser location @var{arg1} @var{arg2} @dots{})
334 (@var{type1?} @var{type2?} @dots{})
339 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
340 Scheme}. La plupart du temps, le @code{corps} sera constitué d'un
341 @ref{Blocs de code LilyPond, bloc de code Lilypond}.
343 Les différents types des prédicat sont recensés à l'annexe
344 @ruser{Types de prédicats prédéfinis}.
348 @ruser{Types de prédicats prédéfinis}.
350 Fichiers d'initialisation :
351 @file{lily/music-scheme.cc},
356 @node Utilisation de fonctions musicales
357 @subsection Utilisation de fonctions musicales
358 @translationof Music function usage
360 Une fonction musicale peut prendre place en différents endroits.
361 Certaines restrictions s'appliqueront selon l'endroit où elle est
362 utilisée, de telle sorte que l'analyse syntaxique soit sans ambiguïté.
363 Le résultat renvoyé par une fonction musicale doit être compatible avec
364 le contexte dans lequel elle est appelée.
368 Dans une expression musicale de haut niveau@tie{}: aucune restriction.
371 En tant que post-événement, explicitement introduit par un indicateur de
372 positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@code{_}. Notez
373 bien que le renvoi d'un post-événement est valide lorsque la fonction
374 musicale est appelée comme de la musique normale ; ceci amène à un
375 résultat ressemblant à
380 Dans ce cas particulier, vous ne pouvez utiliser une expression musicale
381 @emph{ouverte} en tant que dernier argument -- argument qui se
382 composerait d'une expression musicale susceptible d'accepter des
383 post-événements additionnels.
386 En tant que partie d'un accord. L'expression musicale renvoyée doit
387 être du type @code{rhythmic-event}, et plus particulièrement un
392 Les règles spécifiques en matière d'arguments de fin rendent possible
393 l'écriture de fonctions polymorphes telles que @code{\tweak}, qui
394 peuvent s'appliquer à différentes constructions.
397 @node Fonctions de substitution simple
398 @subsection Fonctions de substitution simple
399 @translationof Simple substitution functions
401 Une fonction de substitution simple renvoie une expression musicale
402 écrite au format LilyPond et contient des arguments au format de
403 l'expression résultante. Vous en trouverez une description détaillée à
404 la rubrique @ruser{Exemples de fonction de substitution}.
407 @node Fonctions de substitution intermédiaires
408 @subsection Fonctions de substitution intermédiaires
409 @translationof Intermediate substitution functions
411 Une fonction de substitution intermédiaire est une fonction dont
412 l'expression musicale résultante mélangera du code Scheme au code
415 Certaines commandes @code{\override} nécessitent un argument
416 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
417 cell} en Scheme -- que l'on pourrait traduire par @qq{construction de
420 Cette paire peut se mentionner directement dans la fonction musicale à
421 l'aide d'une variable @code{pair?} :
425 #(define-music-function
426 (parser location beg-end)
429 \once \override Beam.positions = #beg-end
433 \manualBeam #'(3 . 6) c8 d e f
437 Autre manière de procéder, les nombres formant la paire sont transmis
438 comme arguments séparés ; le code Scheme chargé de créer la paire
439 pourra alors être inclus dans l'expression musicale :
441 @lilypond[quote,verbatim,ragged-right]
443 #(define-music-function
444 (parser location beg end)
447 \once \override Beam.positions = #(cons beg end)
451 \manualBeam #3 #6 c8 d e f
456 @node De l'usage des mathématiques dans les fonctions
457 @subsection De l'usage des mathématiques dans les fonctions
458 @translationof Mathematics in functions
460 Une fonction musicale peut requérir, en plus d'une simple substitution,
461 une part de programmation en Scheme.
463 @lilypond[quote,verbatim,ragged-right]
465 #(define-music-function
466 (parser location mag)
469 \override Stem.length = #(* 7.0 mag)
470 \override NoteHead.font-size =
471 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
476 \revert NoteHead.font-size
481 \AltOn #1.5 c c \AltOff c2
486 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
487 s'applique à une expression musicale :
489 @lilypond[quote,verbatim,ragged-right]
491 #(define-music-function
492 (parser location mag music)
495 \override Stem.length = #(* 7.0 mag)
496 \override NoteHead.font-size =
497 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
500 \revert NoteHead.font-size
504 c2 \withAlt #0.5 { c4 c }
505 \withAlt #1.5 { c c } c2
510 @node Fonctions dépourvues d'argument
511 @subsection Fonctions dépourvues d'argument
512 @translationof Functions without arguments
514 Dans la plupart des cas, une fonction dépourvue d'argument devrait
515 être créée à l'aide d'une variable :
518 dolce = \markup@{ \italic \bold dolce @}
521 Il peut, dans certains cas particuliers, s'avérer utile de créer une
522 fonction sans argument comme ici,
526 #(define-music-function
529 (if (eq? #t (ly:get-option 'display-bar-numbers))
530 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
535 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
536 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
537 en respectant la syntaxe
540 lilypond -d display-bar-numbers MONFICHIER.ly
544 @node Fonctions musicales fantômes
545 @subsection Fonctions musicales fantômes
546 @translationof Void music functions
548 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
549 une fonction musicale peut n'être exécutée que dans le but d'en retenir
550 les effets annexes ; vous devrez alors utiliser une procédure
551 @code{define-void-function}. Il peut cependant arriver que vous ayez
552 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
553 l'exemple de la rubrique précédente) une expression musicale.
554 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
555 expression musicale @code{void}.
558 @node Fonctions événementielles
559 @section Fonctions événementielles
560 @translationof Event functions
562 @funindex define-event-function
563 @cindex événementielle, fonction
565 L'utilisation d'une fonction musicale pour placer un événement requiert
566 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
567 à la syntaxe de la construction à remplacer. C'est par exemple le cas
568 lorsque vous voulez écrire une commande de nuance, instruction qui
569 ne comporte habituellement pas d'indicateur de positionnement, comme
570 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
573 @lilypond[quote,verbatim,ragged-right]
574 dyn=#(define-event-function (parser location arg) (markup?)
575 (make-dynamic-script arg))
576 \relative c' { c\dyn pfsss }
579 Vous pourriez obtenir le même résultat avec une fonction musicale, à
580 ceci près que chaque appel à la fonction devra être précédé d'un
581 indicateur de positionnement, comme @code{c-\dyn pfsss}.
584 @node Fonctions pour markups
585 @section Fonctions pour @emph{markups}
586 @translationof Markup functions
588 Les @emph{markups} sont implémentés au travers de fonctions Scheme
589 spécifiques qui produisent des objets @code{Stencil} comprenant un
590 certain nombre d'arguments.
593 * Construction d'un markup en Scheme::
594 * Fonctionnement interne des markups::
595 * Définition d'une nouvelle commande de markup::
596 * Définition d'une nouvelle commande de liste de markups::
600 @node Construction d'un markup en Scheme
601 @subsection Construction d'un @emph{markup} en Scheme
602 @translationof Markup construction in Scheme
604 @cindex définition d'une commande markup
606 La macro @code{markup} construit en Scheme des expressions @emph{markup}
607 tout en disposant d'une syntaxe proche de celle de LilyPond. Par exemple,
609 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
610 #:larger #:line ("foo" "bar" "baz")))
616 #@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
617 \larger \line @{ foo bar baz @} @} #@}
621 Vous pouvez constater les principales règles de traduction entre les
622 syntaxes respectives de LilyPond et de Scheme en matière de
623 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
624 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
625 utiliser la macro @code{markup} en Scheme exclusivement.
628 @multitable @columnfractions .3 .3
629 @item @b{LilyPond} @tab @b{Scheme}
630 @item @code{\markup markup1} @tab @code{(markup markup1)}
631 @item @code{\markup @{ markup1 markup2 ... @}} @tab
632 @code{(markup markup1 markup2 ... )}
633 @item @code{\commande-markup} @tab @code{#:commande-markup}
634 @item @code{\variable} @tab @code{variable}
635 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
636 @item @code{chaîne} @tab @code{"chaîne"}
637 @item @code{#argument-scheme} @tab @code{argument-scheme}
641 L'intégralité du langage Scheme est accessible à l'intérieur même de la
642 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
643 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
644 particulièrement pratique lorsque vous créez votre propre commande de
645 @emph{markup} -- voir
646 @ref{Définition d'une nouvelle commande de markup}.
649 L'argument @var{markup-list} des commandes @code{#:line},
650 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
651 résultat de l'appel à une fonction.
654 (markup #:line (fonction-qui-retourne-des-markups))
658 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
659 @code{make-line-markup}, @code{make-center-markup} ou
660 @code{make-column-markup} :
663 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
667 @node Fonctionnement interne des markups
668 @subsection Fonctionnement interne des @emph{markups}
669 @translationof How markups work internally
671 Dans un @emph{markup} tel que
674 \raise #0.5 "text example"
678 @code{\raise} représente en fait la fonction @code{raise-markup}.
679 L'expression @emph{markup} est enregistrée sous la forme
682 (list raise-markup 0.5 (list simple-markup "text example"))
685 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
686 la fonction @code{raise-markup} est appelée ainsi :
691 @var{liste des alists de propriété}
693 @var{le @emph{markup} "text example"})
696 La fonction @code{raise-markup} commence par créer le stencil pour la
697 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
698 portée. Il s'agit là d'un exemple relativement simple, et nous en
699 aborderons de plus complexes au fil des paragraphes suivants ;
700 d'autres exemples se trouvent directement dans le fichier
701 @file{scm/define-markup-commands.scm}.
704 @node Définition d'une nouvelle commande de markup
705 @subsection Définition d'une nouvelle commande de @emph{markup}
706 @translationof New markup command definition
708 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
709 commande de @emph{markup}.
712 * Syntaxe d'une commande markup::
713 * Attribution de propriétés::
715 * Adaptation d'une commande incorporée::
719 @node Syntaxe d'une commande markup
720 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
721 @translationof Markup command definition syntax
723 Une commande de @emph{markup} personnalisée se définit à l'aide de la
724 macro Scheme @code{define-markup-command}, placée en tête de fichier.
727 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
728 (@var{arg1-type?} @var{arg2-type?} ...)
729 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
731 ..corps de la commande..)
734 Quelques commentaires sur les arguments :
737 @item @var{nom-commande}
738 le nom que vous attribuez à votre commande de @emph{markup}.
740 la définition du @qq{layout} -- son formatage.
742 une liste de listes associatives, comprenant toutes les propriétés actives.
744 le @var{ième} argument de la commande.
745 @item @var{argi-type?}
746 un type de prédicat pour le @var{ième} argument.
749 Si la commande utilise des propriétés à partir des arguments
750 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
751 différentes propriétés ainsi que leur valeur par défaut.
753 Les arguments se distinguent selon leur type :
755 @item un @emph{markup}, correspondant au type de prédicat
756 @code{markup?}@tie{};
757 @item une liste de @emph{markups}, correspondant au type de prédicat
758 @code{markup-list?}@tie{};
759 @item tout autre objet Scheme, correspondant au types de prédicat tels
760 que @code{list?}, @code{number?}, @code{boolean?}, etc.
763 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
764 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
765 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
766 ceci de particulier qu'elles peuvent s'appliquer à des listes de
767 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
768 tous les éléments de la liste originelle se verront appliquer cette
769 fonction @emph{markup} avec ses arguments de tête.
771 La réplication des arguments de tête dans le but d'appliquer une
772 fonction @emph{markup} à une liste de markups est économique,
773 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
774 ainsi d'éventuelles pertes de performance en utilisant des arguments
775 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
776 le dernier argument est un @emph{markup}.
779 @node Attribution de propriétés
780 @unnumberedsubsubsec Attribution de propriétés
781 @translationof On properties
783 Les arguments @code{layout} et @code{props} d'une commande de
784 @emph{markup} fournissent un contexte à l'interprétation du
785 @emph{markup} : taille de fonte, longueur de ligne etc.
787 L'argument @code{layout} permet d'accéder aux propriétés définies dans
788 les blocs @code{\paper}, grâce à la fonction
789 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
790 identique à celle de la partition, est lue au travers de
793 (ly:output-def-lookup layout 'line-width)
796 L'argument @code{props} rend certaines propriétés accessibles aux
797 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
798 d'un @emph{markup} de titre d'ouvrage : toutes les variables
799 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
800 @code{props}, de telle sorte que le @emph{markup} de titrage de
801 l'ouvrage pourra accéder aux différents champs titre, compositeur etc.
802 Ceci permet aussi de configurer le comportement d'une commande de
803 @emph{markup} : la taille des fontes, par exemple, est lue à
804 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
805 La fonction appelant une commande de @emph{markup} peut altérer la
806 valeur de la propriété taille des fontes et donc en modifier le
807 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
808 @code{define-markup-command}, permet de spécifier les propriétés devant
809 être lues parmi les arguments @code{props}.
811 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
812 commande de @emph{markup}, accéder aux différentes propriétés et les
816 @node Exemple commenté
817 @unnumberedsubsubsec Exemple commenté
818 @translationof A complete example
820 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
823 Commençons par construire quelque chose d'approximatif à l'aide d'un
824 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
825 indique la commande @code{\box}, qui semble ici appropriée.
827 @lilypond[quote,verbatim,ragged-right]
828 \markup \box \box HELLO
831 Dans un souci d'esthétique, nous aimerions que le texte et les
832 encadrements ne soient pas autant accolés. Selon la documentation de
833 @code{\box}, cette commande utilise la propriété @code{box-padding},
834 fixée par défaut à 0,2. Cette même documentation nous indique
835 aussi comment la modifier :
837 @lilypond[quote,verbatim,ragged-right]
838 \markup \box \override #'(box-padding . 0.6) \box A
841 L'espacement des deux liserés est cependant toujours trop réduit ;
842 modifions le à son tour :
844 @lilypond[quote,verbatim,ragged-right]
845 \markup \override #'(box-padding . 0.4) \box
846 \override #'(box-padding . 0.6) \box A
849 Vous conviendrez que recopier une telle définition de @emph{markup}
850 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
851 @emph{markup} @code{double-box} qui prendra un seul argument -- le
852 texte. Cette commande se chargera de dessiner les encadrements, en
853 tenant compte des espacements.
856 #(define-markup-command (double-box layout props text) (markup?)
857 "Dessine un double encadrement autour du texte."
858 (interpret-markup layout props
859 #@{\markup \override #'(box-padding . 0.4) \box
860 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
863 ou bien son équivalent
866 #(define-markup-command (double-box layout props text) (markup?)
867 "Dessine un double encadrement autour du texte."
868 (interpret-markup layout props
869 (markup #:override '(box-padding . 0.4) #:box
870 #:override '(box-padding . 0.6) #:box text)))
873 @code{text} est le nom de l'argument de notre commande, et
874 @code{markup?} son type -- l'argument sera identifié comme étant un
875 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
876 plupart des commandes de @emph{markup}, construira un stencil à partir
877 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
878 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
879 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
880 transformation d'une expression @code{\markup} en expression Scheme est
883 Notre commande personnalisée s'utilise ainsi :
886 \markup \double-box A
889 Il serait intéressant de rendre cette commande @code{double-box} plus
890 souple@tie{}: les valeurs de @code{box-padding} sont figées et ne
891 peuvent être modifiées à l'envie. Pareillement, il serait bien de
892 distinguer l'espacement entre les encadrements de l'espacement entre le
893 texte et ses encadrements. Nous allons donc introduire une propriété
894 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
895 de gérer l'espacement des encadrements ; @code{box-padding} ne
896 servira alors que pour l'espacement intérieur. Voici le code adapté à
900 #(define-markup-command (double-box layout props text) (markup?)
901 #:properties ((inter-box-padding 0.4)
903 "Dessine un double encadrement autour du texte."
904 (interpret-markup layout props
905 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
906 \override #`(box-padding . ,box-padding) \box
910 Ainsi que son équivalent à partir de la macro @emph{markup} :
913 #(define-markup-command (double-box layout props text) (markup?)
914 #:properties ((inter-box-padding 0.4)
916 "Dessine un double encadrement autour du texte."
917 (interpret-markup layout props
918 (markup #:override `(box-padding . ,inter-box-padding) #:box
919 #:override `(box-padding . ,box-padding) #:box text)))
922 C'est ici le mot-clé @code{#:properties} qui permet de lire les
923 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
924 l'argumenet @code{props}@tie{}; on leur a d'ailleurs fourni des valeurs
925 par défaut au cas où elles ne seraient pas définies.
927 Ces valeurs permettront alors d'adapter les propriétés de
928 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
929 aurez remarqué, dans l'argument @code{\override}, la présence de
930 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
931 permettent d'insérer une valeur variable au sein d'une expression
934 Notre commande est maintenant prête à servir dans un @emph{markup}, et
935 les encadrements sont repositionnables.
937 @lilypond[quote,verbatim,ragged-right]
938 #(define-markup-command (double-box layout props text) (markup?)
939 #:properties ((inter-box-padding 0.4)
941 "Draw a double box around text."
942 (interpret-markup layout props
943 #{\markup \override #`(box-padding . ,inter-box-padding) \box
944 \override #`(box-padding . ,box-padding) \box
947 \markup \double-box A
948 \markup \override #'(inter-box-padding . 0.8) \double-box A
949 \markup \override #'(box-padding . 1.0) \double-box A
953 @node Adaptation d'une commande incorporée
954 @unnumberedsubsubsec Adaptation d'une commande incorporée
955 @translationof Adapting builtin commands
957 Le meilleur moyen de construire ses propres commandes de @emph{markup}
958 consiste à prendre exemple sur les commandes déjà incorporées. La
959 plupart des commandes de @emph{markup} fournies avec LilyPond sont
960 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
962 Nous pourrions, par exemple, envisager d'adapter la commande
963 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
964 est définie la commande @code{\draw-line}, expurgée de sa
968 (define-markup-command (draw-line layout props dest)
971 #:properties ((thickness 1))
973 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
977 (make-line-stencil th 0 0 x y)))
980 Avant de définir notre propre commande basée sur l'une de celles
981 fournies par LilyPond, commençons par en recopier la définition, puis
982 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
983 supprimé sans risque ; il ne sert que lors de la génération de la
984 documentation et n'est d'aucune utilité pour une commande personnalisée.
987 (define-markup-command (draw-double-line layout props dest)
989 #:properties ((thickness 1))
991 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
995 (make-line-stencil th 0 0 x y)))
998 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
999 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
1000 par défaut de 6 dixièmes :
1003 (define-markup-command (draw-double-line layout props dest)
1005 #:properties ((thickness 1)
1011 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1012 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1013 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1015 @lilypond[quote,verbatim,ragged-right]
1016 #(define-markup-command (my-draw-line layout props dest)
1018 #:properties ((thickness 1)
1021 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1025 (w (/ line-gap 2.0))
1026 (x (cond ((= dx 0) w)
1028 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1029 (y (* (if (< (* dx dy) 0) 1 -1)
1032 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1033 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1034 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1036 \markup \my-draw-line #'(4 . 3)
1037 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1041 @node Définition d'une nouvelle commande de liste de markups
1042 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1043 @translationof New markup list command definition
1045 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1046 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1047 la macro @code{define-markup-command} abordée à la rubrique
1048 @ref{Définition d'une nouvelle commande de markup} à ceci près que cette
1049 dernière renvoie un seul stencil, non une liste de stencils.
1051 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1052 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1053 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1054 par l'argument @code{props}.
1057 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1058 #:properties ((par-indent 2))
1059 (interpret-markup-list layout props
1060 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1063 La version purement Scheme est un peu plus complexe :
1065 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1066 #:properties ((par-indent 2))
1067 (interpret-markup-list layout props
1068 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1072 En dehors des habituels arguments @code{layout} et @code{props}, la
1073 commande de liste de @emph{markups} @code{paragraph} prend en argument
1074 une liste de @emph{markups} appelé @code{args}. Le prédicat des listes
1075 de @emph{markups} est @code{markup-list?}.
1077 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1078 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1079 @code{props}. En cas d'absence, la valeur par défaut sera
1080 de @code{2}. Ensuite est créée une liste de lignes justifiées
1081 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1082 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1083 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1084 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1085 interprétée par la fonction @code{interpret-markup-list}.
1087 Voici comment utiliser cette nouvelle commande de liste de
1088 @emph{markups}@tie{}:
1092 The art of music typography is called \italic @{(plate) engraving.@}
1093 The term derives from the traditional process of music printing.
1094 Just a few decades ago, sheet music was made by cutting and stamping
1095 the music into a zinc or pewter plate in mirror image.
1097 \override-lines #'(par-indent . 4) \paragraph @{
1098 The plate would be inked, the depressions caused by the cutting
1099 and stamping would hold ink. An image was formed by pressing paper
1100 to the plate. The stamping and cutting was completely done by
1107 @node Contextes pour programmeurs
1108 @section Contextes pour programmeurs
1109 @translationof Contexts for programmers
1112 * Évaluation d'un contexte::
1113 * Application d'une fonction à tous les objets de mise en forme::
1117 @node Évaluation d'un contexte
1118 @subsection Évaluation d'un contexte
1119 @translationof Context evaluation
1121 @cindex appel de code durant l'interprétation
1122 @funindex \applyContext
1124 Un contexte peut être modifié, au moment même de son interprétation, par
1125 du code Scheme. La syntaxe consacrée en pareil cas est
1127 \applyContext @var{fonction}
1130 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1131 unique argument : le contexte au sein duquel la commande
1132 @code{\applyContext} est appelée. Les lignes de code qui suivent auront
1133 pour effet d'afficher à l'écran, en cours de compilation, le numéro de
1139 (format #t "\nNous en sommes à la mesure ~a.\n"
1140 (ly:context-property x 'currentBarNumber)))
1144 @node Application d'une fonction à tous les objets de mise en forme
1145 @subsection Application d'une fonction à tous les objets de mise en forme
1146 @translationof Running a function on all layout objects
1148 @cindex appel de code sur des objets de mise en forme
1149 @funindex \applyOutput
1151 La manière la plus souple d'affiner un objet consiste à utiliser la
1152 commande @code{\applyOutput}. Celle-ci va insérer un événement
1153 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1156 \applyOutput @var{Contexte} @var{procédure}
1160 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1162 Lors de l'interprétation de cette commande, la fonction
1163 @code{@var{procédure}} est appelée pout tout objet de rendu appartenant
1164 au contexte @code{@var{Contexte}} à cet instant précis, avec les
1165 arguments suivants :
1167 @item l'objet de rendu en lui-même,
1168 @item le contexte au sein duquel cet objet est créé,
1169 @item et le contexte dans lequel @code{\applyOutput} est effectué.
1172 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1173 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1174 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1175 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1177 Voici une fonction utilisable avec la commande
1178 @code{\applyOutput} : elle @qq{blanchit} la tête des notes se
1179 trouvant sur la ligne médiane ou bien directement à son contact.
1181 @lilypond[quote,verbatim,ragged-right]
1182 #(define (blanker grob grob-origin context)
1183 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1184 (< (abs (ly:grob-property grob 'staff-position)) 2))
1185 (set! (ly:grob-property grob 'transparent) #t)))
1188 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1192 La @var{procédure} sera interprétée au niveau @code{Score}
1193 (partition) ou @code{Staff} dès lors que vous utiliserez l'une des
1197 \applyOutput #'Score #@var{procédure}
1198 \applyOutput #'Staff #@var{procédure}
1202 @node Fonctions de rappel
1203 @section Fonctions de rappel
1204 @translationof Callback functions
1206 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1207 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1211 \override Stem.thickness = #2.0
1214 Une procédure Scheme peut aussi se charger de modifier des
1217 @lilypond[fragment,verbatim,quote,relative=2]
1218 \override Stem.thickness = #(lambda (grob)
1219 (if (= UP (ly:grob-property grob 'direction))
1226 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1227 est nécessaire au processus de mise en forme.
1229 La majeure partie du procédé typographique consiste en la réalisation de
1230 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1231 utilisant particulièrement des rappels, nous mentionnerons
1235 Routine d'impression, construisant le dessin du symbole
1237 Routine effectuant le positionnement horizontal
1239 Routine calculant la largeur d'un objet
1242 La procédure prend un unique argument, en l'occurrence l'objet graphique
1245 Dans le cas où la routine doit faire appel à plusieurs arguments, le
1246 @emph{grob} en cours peut s'insérer à l'aide d'un @emph{grob} enchâssé.
1247 Voici, à titre d'illustration, un réglage pour
1248 @code{AccidentalSuggestion} :
1252 ,(ly:make-simple-closure
1254 ,(ly:make-simple-closure
1255 (list ly:self-alignment-interface::centered-on-x-parent))
1256 ,(ly:make-simple-closure
1257 (list ly:self-alignment-interface::x-aligned-on-self)))))
1261 Ici, aussi bien @code{ly:self-alignment-interface::x-aligned-on-self}
1262 que @code{ly:self-alignment-interface::centered-on-x-parent} font appel
1263 à l'argument @emph{grob}. La fonction @code{+} a pour effet
1264 d'additionner les résultats. L'ensemble est inclus dans un
1265 @code{ly:make-simple-closure} de telle sorte que l'addition s'exécute de
1268 Dans les faits, l'utilisation d'une unique procédure en tant que valeur
1269 d'une propriété revient à écrire
1272 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1276 Le @code{ly:make-simple-closure} intérieur fournit le @emph{grob} en
1277 argument à la procédure @var{proc}, l'extérieur s'assure que le résultat
1278 de la fonction sera bien renvoyé, non pas l'objet @code{simple-closure}.
1280 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1281 @emph{markup} consiste à utiliser la fonction
1282 @code{grob-interpret-markup}, comme ici :
1285 my-callback = #(lambda (grob)
1286 (grob-interpret-markup grob (markup "foo")))
1290 @node Code Scheme intégré
1291 @section Code Scheme intégré
1292 @translationof Inline Scheme code
1294 À REVOIR : l'exemple de cette rubrique n'est pas des plus judicieux puisque
1296 F = -\tweak font-size #-3 -\flageolet
1298 (notez le @samp{-} qui qualifie d'événement postérieur) fonctionne
1299 correctement dans ce cas d'espèce. En attendant un remaniement de cette
1300 section, faisons comme si nous l'ignorions.
1302 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1303 sa syntaxe. Par exemple, le code suivant produit une erreur.
1306 F = \tweak font-size #-3 -\flageolet
1314 En d'autres termes, @code{\tweak} ne se comporte pas comme une
1315 articulation : il ne peut notamment pas être accolé avec les
1316 symboles @samp{^} ou @samp{_}.
1318 C'est en se servant du langage Scheme que l'on peut résoudre ce
1319 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1320 @ref{Ajout d'articulation à des notes (exemple)}, en
1321 particulier quant à l'emploi de @code{\displayMusic}.
1324 F = #(let ((m (make-music 'ArticulationEvent
1325 'articulation-type "flageolet")))
1326 (set! (ly:music-property m 'tweaks)
1327 (acons 'font-size -3
1328 (ly:music-property m 'tweaks)))
1337 Ici les propriétés @code{tweak} de l'objet flageolet nommé
1338 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
1339 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1340 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1341 @code{acons}), et le résultat de cette opération est renvoyé par
1342 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1343 finale de @samp{m} lui-même.
1346 @node Retouches complexes
1347 @section Retouches complexes
1348 @translationof Difficult tweaks
1350 Certains réglages sont plus délicats que d'autres.
1354 L'un d'entre eux est l'apparence des objets dits @qq{extenseurs}
1355 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1356 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1357 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1358 changement de ligne, ils sont dupliqués au début du ou des systèmes
1359 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1360 héritent toutes les propriétés, y compris les éventuelles commandes
1363 En d'autres termes, une commande @code{\override} affecte toujours les
1364 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1365 partie précédant ou suivant le changement de ligne, il faut intervenir
1366 directement dans le processus de mise en page.
1367 La fonction de rappel @code{after-line-breaking} contient toute
1368 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1369 déterminés, et que des objets graphiques ont été divisés sur des
1370 systèmes différents.
1372 Dans l'exemple suivant, on définit une nouvelle opération nommée
1373 @code{my-callback}. Cette opération
1377 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1379 dans l'affirmative, recherche les différents morceaux de l'objet
1381 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1384 dans l'affirmative, applique un espacement supplémentaire
1385 (@code{extra-offset}).
1388 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1389 de façon à ce que le deuxième morceau d'une liaison divisée soit
1393 @lilypond[quote,verbatim,ragged-right]
1394 #(define (my-callback grob)
1396 ;; l'objet a-t-il été divisé ?
1397 (orig (ly:grob-original grob))
1399 ;; si oui, rechercher les morceaux frères (siblings)
1400 (siblings (if (ly:grob? orig)
1401 (ly:spanner-broken-into orig)
1404 (if (and (>= (length siblings) 2)
1405 (eq? (car (last-pair siblings)) grob))
1406 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1409 \override Tie.after-line-breaking =
1417 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1418 rappel @code{after-line-breaking} devra également appeler celle
1419 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1420 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1421 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1425 Pour des raisons d'ordre technique, certains objets ne peuvent être
1426 modifiés par @code{\override}. Parmi ceux-là, les objets
1427 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1428 @code{\overrideProperty} sert à les modifier, de façon similaire à
1429 @code{\once \override} mais avec une syntaxe différente :
1433 Score.NonMusicalPaperColumn % Nom de l'objet
1434 . line-break-system-details % Nom de la propriété
1435 . next-padding % Nom de la sous-propriété (optionnel)
1439 Notez toutefois que la commande @code{\override} peut tout de même être
1440 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1441 bloc @code{\context}.
1446 @node Interfaces LilyPond Scheme
1447 @chapter Interfaces LilyPond Scheme
1448 @translationof LilyPond Scheme interfaces
1450 Ce chapitre aborde les différents outils fournis par LilyPond à
1451 l'intention des programmeurs en Scheme désireux d'obtenir des
1452 informations à partir et autour des fluxs de musique.
1454 TODO -- figure out what goes in here and how to organize it