1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
3 Translation of GIT committish: 952705bbbb000581a13836e6a733df04511e93c5
5 When revising a translation, copy the HEAD committish of the
6 version that you are working on. For details, see the Contributors'
7 Guide, node Updating translation committishes..
12 @c Translators: Valentin Villenave, Jean-Charles Malahieude
13 @c Translation checkers: Gilles Thibault
15 @node Interfaces pour programmeurs
16 @chapter Interfaces pour programmeurs
17 @translationof Interfaces for programmers
19 Scheme permet de réaliser des affinages très pointus. Si vous ne
20 connaissez rien de Scheme, vous en aurez un aperçu au travers de notre
21 @ref{Tutoriel Scheme}.
24 * Blocs de code LilyPond::
26 * Fonctions musicales::
27 * Fonctions événementielles::
28 * Fonctions pour markups::
29 * Contextes pour programmeurs::
30 * Fonctions de rappel::
31 * Code Scheme intégré::
32 * Retouches complexes::
36 @node Blocs de code LilyPond
37 @section Blocs de code LilyPond
38 @translationof Lilypond code blocks
40 Les blocs de code LilyPond ressemblent à
42 #@{ @var{du code LilyPond} #@}
44 Ils peuvent s'utiliser partout où vous pouvez écrire du code Scheme.
45 Le lecteur Scheme est en fait quelque peu adapté pour accepter des blocs
46 de code LilyPond ; il est capable de traiter des expressions Scheme
47 intégrées débutant par @code{$} ou @code{#}.
49 Le lecteur Scheme extrait le bloc de code LilyPond et déclenche un appel
50 à l'analyseur grammatical de LilyPond (le @code{parser}) qui réalise en
51 temps réel l'interprétation de ce bloc de code LilyPond. Toute
52 expression Scheme imbriquée est exécutée dans l'environnement lexical du
53 bloc de code LilyPond, de telle sorte que vous avez accès aux variables
54 locales et aux paramètres de la fonction au moment même où le bloc de
55 code LilyPond est écrit.
57 Un bloc de code LilyPond peut contenir tout ce que vous pourriez mettre
58 à droite de l'assignation. Par ailleurs, un bloc LilyPond vide
59 correspond à une expression fantôme, et un bloc LilyPond de multiples
60 événements musicaux sera transformé en une expression de musique
64 @node Fonctions Scheme
65 @section Fonctions Scheme
66 @translationof Scheme functions
68 @cindex Scheme, fonctions (syntaxe LilyPond)
70 Les @emph{fonctions Scheme} sont des procédures Scheme chargées de créer
71 des expressions Scheme à partir de code rédigé selon la syntaxe de
72 LilyPond. Elles peuvent être appelées en de nombreux endroits, à l'aide
73 d'un @code{#}, où spécifier une valeur en syntaxe Scheme est autorisé.
74 Bien que Scheme dispose de fonctions en propre, nous nous intéresserons,
75 au fil des paragraphes qui suivent, aux fonctions @emph{syntaxiques},
76 autrement dit des fonctions qui reçoivent des arguments libellés dans la
80 * Définition de fonctions Scheme::
81 * Utilisation de fonctions Scheme::
82 * Fonctions Scheme fantômes::
85 @node Définition de fonctions Scheme
86 @subsection Définition de fonctions Scheme
87 @translationof Scheme function definitions
89 @funindex define-scheme-function
91 D'une manière générale, une fonction Scheme se définit ainsi :
95 #(define-scheme-function
96 (parser location @var{arg1} @var{arg2} @dots{})
97 (@var{type1?} @var{type2?} @dots{})
104 @multitable @columnfractions .33 .66
106 @tab doit être littéralement @code{parser}, de telle sorte que
107 l'analyseur grammatical puisse accéder aux blocs de code LilyPond
108 (@code{#@{}@dots{}@code{#@}}).
110 @item @code{@var{argN}}
111 @tab @var{n}ième argument
113 @item @code{@var{typeN?}}
114 @tab un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
115 devra retourner @code{#t}. Certains de ces prédicats, comme nous le
116 verrons plus loin, bénéficient d'un traitement particulier de la part du
117 @emph{parser}. De même existe une forme spécifique --
118 @code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
119 argument optionnels. En l'absence d'argument réel au moment de l'appel
120 de la fonction, c'est la valeur par défaut qui lui sera substituée. Les
121 valeurs par défaut sont évaluées dès l'apparition de la définition, y
122 compris dans le cas de blocs de code LilyPond ; vous devrez donc,
123 si ces valeurs par défaut ne peuvent être déterminées que plus tard,
124 mentionner une valeur spéciale que vous reconnaîtrez facilement.
125 Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
126 fournir sa valeur par défaut, celle-ci sera considérée comme étant
127 @code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
128 vérifiées ni au moment de la définition, ni à l'exécution ; il est
129 de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
130 par défaut constituée d'une expression musicale est recopiée dès la
131 définition de @code{origin} vers le paramètre @code{location}.
133 @item @code{@var{corps}}
134 @tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
135 servant de valeur de retour de la fonction. Il peut contenir des blocs
136 de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
137 @w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
138 @ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
139 @code{#} permet de référencer des arguments de la fonction -- tel
140 @samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
141 arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
142 Dans le cas où une expression Scheme introduite par @code{#} ne vous
143 permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
144 expression Scheme @qq{immédiate} à l'aide d'un @code{$}, comme
147 Lorsque votre fonction retourne une expression musicale, lui est
148 attribuée la valeur @code{origin}.
152 Certains types de prédicat font l'objet d'un traitement spécial de la
153 part de l'analyseur grammatical, dans la mesure où il n'a aucun autre
154 moyen de reconnaître efficacement les arguments. Il s'agit, à l'heure
155 actuelle, de @code{ly:pitch?} et @code{ly:duration?}.
157 Pour tous les autres prédicats, la recevabilité des arguments est
158 déterminée par un appel effectif au prédicat après que LilyPond les a
159 déjà converti en expression Scheme. Par voie de conséquence, l'argument
160 peut tout à fait se libeller en syntaxe Scheme -- introduite par un
161 @code{#} ou en tant que résultat d'un appel à une fonction Scheme. Par
162 ailleurs, LilyPond convertira en Scheme un certain nombre de
163 constructions purement LilyPond avant même d'en avoir vérifié le
164 prédicat. C'est notamment le cas de la musique, des
165 @emph{postévénements}, des chaînes simples (avec ou sans guillemets),
166 des nombres, des @emph{markups} et listes de @emph{markups}, ainsi que
167 des blocs @emph{score}, @emph{book}, @emph{bookpart}, ou qui définissent
168 un contexte ou un format de sortie.
170 Il existe certaines formes d'expression, comme la plupart du temps où la
171 musique n'est pas bornée par des accolades, où LilyPond doit lire
172 au-delà de cette même expression afin d'en déterminer la fin. Si une
173 telle expression devait, après évaluation du prédicat, faire l'objet
174 d'un argument optionnel, LilyPond n'aurait aucun moyen, à partir du
175 moment où il aura décidé que l'expression ne correspond pas au
176 paramètre, de @qq{revenir en arrière}. C'est la raison pour laquelle
177 certaines formes musicales devraient être bornées par des accolades pour
178 que LilyPond puisse les reconnaître efficacement. Il existe d'autres
179 situations pour lesquelles LilyPond lèvera toute ambiguïté grâce aux
180 fonctions de prédicat : un @samp{-3} est-il un @emph{postévénement}
181 de type doigté ou un nombre négatif@tie{}? Un @code{"a" 4} en mode
182 paroles est-il une chaîne suivie d'un nombre ou bien un événement
183 syllabe de durée @code{4} ? LilyPond répondra à ces questions
184 après consultation du prédicat. Pour toutes ces raisons, nous vous
185 enjoignons à éviter d'utiliser des prédicats permissifs tel que
186 @code{scheme?}, dès que vous voulez les utiliser dans un but particulier
187 plutôt que dans une fonction de portée générale.
189 Les différents types des prédicat propres à LilyPond sont recensés à
190 l'annexe @ruser{Types de prédicats prédéfinis}.
194 @ruser{Types de prédicats prédéfinis}.
196 Fichiers d'initialisation :
197 @file{lily/music-scheme.cc},
202 @node Utilisation de fonctions Scheme
203 @subsection Utilisation de fonctions Scheme
204 @translationof Scheme function usage
206 Vous pouvez appeler une fonction Scheme pratiquement partout où une
207 expression Scheme derrière un @code{#} peut prendre place. Vous appelez
208 une fonction Scheme en faisant précéder son nom d'un @code{\}, et en le
209 faisant suivre de ses arguments. Lorsqu'un prédicat d'argument
210 optionnel ne correspond pas à un argument, LilyPond l'ignore ainsi que
211 tous les arguments optionnels qui suivent, les remplaçant par leur
212 valeur par défaut, et @qq{sauvegarde} en tant que prochain argument
213 obligatoire l'argument qui ne correspondait pas. Dans la mesure où
214 l'argument sauvegardé doit servir, les argument optionnels ne sont en
215 fait pas considérés comme optionnels, sauf à être suivis d'un argument
218 Une exception cependant à cette règle : le fait de donner un
219 @code{\default} en tant qu'argument optionnel aura pour résultat que cet
220 argument et tous les autres arguments optionnels qui suivent seront
221 ignorés et remplacés par leur valeur par défaut. Il en va de même
222 lorsqu'aucun argument obligatoire ne suit, du fait que @code{\default}
223 ne requiert pas de sauvegarde. C'est d'ailleurs ainsi que fonctionnent
224 les commandes @code{mark} et @code{key}, qui retrouvent leur
225 comportement par défaut lorsque vous les faites suivre d'un
228 En plus de là où une expression Scheme est requise, il y a quelques
229 endroits où des expressions @code{#} sont acceptées et évaluées
230 uniquement pour leurs effets annexes. Il s'agit, dans la plupart des
231 cas, d'endroits où une affectation serait tout à fait envisageable.
233 Dans la mesure où il n'est pas bon de renvoyer une valeur qui pourrait
234 être mal interprétée dans certains contextes, nous vous enjoignons à
235 utiliser des fonctions Scheme normales uniquement dans les cas où vous
236 renvoyez toujours une valeur utile, et une fonction fantôme -- voir
237 @ref{Fonctions Scheme fantômes} -- dans le cas contraire.
240 @node Fonctions Scheme fantômes
241 @subsection Fonctions Scheme fantômes
242 @translationof Void scheme functions
244 @cindex @emph{void}, fonction
245 @cindex fantôme, fonction
247 @funindex define-void-function
250 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
251 pour renvoyer une valeur. Certains langages de programmation, tels
252 le C et Scheme, utilisent des fonctions dans les deux cas et se
253 débarrassent tout bonnement de la valeur renvoyée ; en règle
254 générale, il suffit que l'expression fasse office de déclaration, et
255 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
256 la plupart des compilateurs C actuels déclenchent un avertissement si
257 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
258 nombreuses fonctions réalisant une action, les standards Scheme
259 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
260 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
261 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
262 lorsqu'on utilise @code{set!} directement sur une variable -- mais
263 malheureusement pas toujours.
265 Une fonction LilyPond définie à l'aide de la clause
266 @code{define-void-function} vous apporte l'assurance que c'est cette
267 valeur spéciale -- la seule valeur qui satisfasse au prédicat
268 @code{void?} -- qui sera retournée.
272 #(define-void-function
275 (ly:set-option 'point-and-click #f))
277 \noPointAndClick % desactive le "pointer-cliquer"
280 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
281 expression pour ses effets annexes sans interprétation d'une quelconque
285 \void #(hashq-set! une-table une-clé une-valeur)
288 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
289 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
290 opérationnel dans le cadre de fonctions musicales telles que
291 @code{\displayMusic}.
294 @node Fonctions musicales
295 @section Fonctions musicales
296 @translationof Music functions
298 @cindex musicale, fonction
300 Les @emph{fonctions musicales} sont des procédures Scheme capables de
301 créer automatiquement des expressions musicales ; elles permettent
302 de grandement simplifier un fichier source.
305 * Définition de fonctions musicales::
306 * Utilisation de fonctions musicales::
307 * Fonctions de substitution simple::
308 * Fonctions de substitution intermédiaires::
309 * De l'usage des mathématiques dans les fonctions::
310 * Fonctions dépourvues d'argument::
311 * Fonctions musicales fantômes::
315 @node Définition de fonctions musicales
316 @subsection Définition de fonctions musicales
317 @translationof Music function definitions
319 @cindex fonction musicale, définition
321 @funindex define-music-function
323 Une fonction musicale se définit ainsi :
327 #(define-music-function
328 (parser location @var{arg1} @var{arg2} @dots{})
329 (@var{type1?} @var{type2?} @dots{})
334 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
335 Scheme}. La plupart du temps, le @code{corps} sera constitué d'un
336 @ref{Blocs de code LilyPond, bloc de code Lilypond}.
338 Les différents types des prédicat sont recensés à l'annexe
339 @ruser{Types de prédicats prédéfinis}.
343 @ruser{Types de prédicats prédéfinis}.
345 Fichiers d'initialisation :
346 @file{lily/music-scheme.cc},
351 @node Utilisation de fonctions musicales
352 @subsection Utilisation de fonctions musicales
353 @translationof Music function usage
355 Une fonction musicale peut prendre place en différents endroits.
356 Certaines restrictions s'appliqueront selon l'endroit où elle est
357 utilisée, de telle sorte que l'analyse syntaxique soit sans ambiguïté.
358 Le résultat renvoyé par une fonction musicale doit être compatible avec
359 le contexte dans lequel elle est appelée.
363 Dans une expression musicale de haut niveau@tie{}: aucune restriction.
366 En tant que post-événement, explicitement introduit par un indicateur de
367 positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@code{_}. Notez
368 bien que le renvoi d'un post-événement est valide lorsque la fonction
369 musicale est appelée comme de la musique normale ; ceci amène à un
370 résultat ressemblant à
375 Dans ce cas particulier, vous ne pouvez utiliser une expression musicale
376 @emph{ouverte} en tant que dernier argument -- argument qui se
377 composerait d'une expression musicale susceptible d'accepter des
378 post-événements additionnels.
381 En tant que partie d'un accord. L'expression musicale renvoyée doit
382 être du type @code{rhythmic-event}, et plus particulièrement un
387 Les règles spécifiques en matière d'arguments de fin rendent possible
388 l'écriture de fonctions polymorphes telles que @code{\tweak}, qui
389 peuvent s'appliquer à différentes constructions.
392 @node Fonctions de substitution simple
393 @subsection Fonctions de substitution simple
394 @translationof Simple substitution functions
396 Une fonction de substitution simple renvoie une expression musicale
397 écrite au format LilyPond et contient des arguments au format de
398 l'expression résultante. Vous en trouverez une description détaillée à
399 la rubrique @ruser{Exemples de fonction de substitution}.
402 @node Fonctions de substitution intermédiaires
403 @subsection Fonctions de substitution intermédiaires
404 @translationof Intermediate substitution functions
406 Une fonction de substitution intermédiaire est une fonction dont
407 l'expression musicale résultante mélangera du code Scheme au code
410 Certaines commandes @code{\override} nécessitent un argument
411 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
412 cell} en Scheme -- que l'on pourrait traduire par @qq{construction de
415 Cette paire peut se mentionner directement dans la fonction musicale à
416 l'aide d'une variable @code{pair?} :
420 #(define-music-function
421 (parser location beg-end)
424 \once \override Beam #'positions = #beg-end
428 \manualBeam #'(3 . 6) c8 d e f
432 Autre manière de procéder, les nombres formant la paire sont transmis
433 comme arguments séparés ; le code Scheme chargé de créer la paire
434 pourra alors être inclus dans l'expression musicale :
436 @lilypond[quote,verbatim,ragged-right]
438 #(define-music-function
439 (parser location beg end)
442 \once \override Beam #'positions = #(cons beg end)
446 \manualBeam #3 #6 c8 d e f
451 @node De l'usage des mathématiques dans les fonctions
452 @subsection De l'usage des mathématiques dans les fonctions
453 @translationof Mathematics in functions
455 Une fonction musicale peut requérir, en plus d'une simple substitution,
456 une part de programmation en Scheme.
458 @lilypond[quote,verbatim,ragged-right]
460 #(define-music-function
461 (parser location mag)
464 \override Stem #'length = #(* 7.0 mag)
465 \override NoteHead #'font-size =
466 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
470 \revert Stem #'length
471 \revert NoteHead #'font-size
476 \AltOn #1.5 c c \AltOff c2
481 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
482 s'applique à une expression musicale :
484 @lilypond[quote,verbatim,ragged-right]
486 #(define-music-function
487 (parser location mag music)
490 \override Stem #'length = #(* 7.0 mag)
491 \override NoteHead #'font-size =
492 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
494 \revert Stem #'length
495 \revert NoteHead #'font-size
499 c2 \withAlt #0.5 { c4 c }
500 \withAlt #1.5 { c c } c2
505 @node Fonctions dépourvues d'argument
506 @subsection Fonctions dépourvues d'argument
507 @translationof Functions without arguments
509 Dans la plupart des cas, une fonction dépourvue d'argument devrait
510 être créée à l'aide d'une variable :
513 dolce = \markup@{ \italic \bold dolce @}
516 Il peut, dans certains cas particuliers, s'avérer utile de créer une
517 fonction sans argument comme ici,
521 #(define-music-function
524 (if (eq? #t (ly:get-option 'display-bar-numbers))
525 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
530 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
531 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
532 en respectant la syntaxe
535 lilypond -d display-bar-numbers MONFICHIER.ly
539 @node Fonctions musicales fantômes
540 @subsection Fonctions musicales fantômes
541 @translationof Void music functions
543 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
544 une fonction musicale peut n'être exécutée que dans le but d'en retenir
545 les effets annexes ; vous devrez alors utiliser une procédure
546 @code{define-void-function}. Il peut cependant arriver que vous ayez
547 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
548 l'exemple de la rubrique précédente) une expression musicale.
549 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
550 expression musicale @code{void}.
553 @node Fonctions événementielles
554 @section Fonctions événementielles
555 @translationof Event functions
557 @funindex define-event-function
558 @cindex événementielle, fonction
560 L'utilisation d'une fonction musicale pour placer un événement requiert
561 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
562 à la syntaxe de la construction à remplacer. C'est par exemple le cas
563 lorsque vous voulez écrire une commande de nuance, instruction qui
564 ne comporte habituellement pas d'indicateur de positionnement, comme
565 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
568 @lilypond[quote,verbatim,ragged-right]
569 dyn=#(define-event-function (parser location arg) (markup?)
570 (make-dynamic-script arg))
571 \relative c' { c\dyn pfsss }
574 Vous pourriez obtenir le même résultat avec une fonction musicale, à
575 ceci près que chaque appel à la fonction devra être précédé d'un
576 indicateur de positionnement, comme @code{c-\dyn pfsss}.
579 @node Fonctions pour markups
580 @section Fonctions pour @emph{markups}
581 @translationof Markup functions
583 Les @emph{markups} sont implémentés au travers de fonctions Scheme
584 spécifiques qui produisent des objets @code{Stencil} comprenant un
585 certain nombre d'arguments.
588 * Construction d'un markup en Scheme::
589 * Fonctionnement interne des markups::
590 * Définition d'une nouvelle commande de markup::
591 * Définition d'une nouvelle commande de liste de markups::
595 @node Construction d'un markup en Scheme
596 @subsection Construction d'un @emph{markup} en Scheme
597 @translationof Markup construction in Scheme
599 @cindex définition d'une commande markup
601 La macro @code{markup} construit en Scheme des expressions @emph{markup}
602 tout en disposant d'une syntaxe proche de celle de LilyPond. Par exemple,
604 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
605 #:larger #:line ("foo" "bar" "baz")))
611 #@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
612 \larger \line @{ foo bar baz @} @} #@}
616 Vous pouvez constater les principales règles de traduction entre les
617 syntaxes respectives de LilyPond et de Scheme en matière de
618 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
619 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
620 utiliser la macro @code{markup} en Scheme exclusivement.
623 @multitable @columnfractions .3 .3
624 @item @b{LilyPond} @tab @b{Scheme}
625 @item @code{\markup markup1} @tab @code{(markup markup1)}
626 @item @code{\markup @{ markup1 markup2 ... @}} @tab
627 @code{(markup markup1 markup2 ... )}
628 @item @code{\commande-markup} @tab @code{#:commande-markup}
629 @item @code{\variable} @tab @code{variable}
630 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
631 @item @code{chaîne} @tab @code{"chaîne"}
632 @item @code{#argument-scheme} @tab @code{argument-scheme}
636 L'intégralité du langage Scheme est accessible à l'intérieur même de la
637 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
638 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
639 particulièrement pratique lorsque vous créez votre propre commande de
640 @emph{markup} -- voir
641 @ref{Définition d'une nouvelle commande de markup}.
644 L'argument @var{markup-list} des commandes @code{#:line},
645 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
646 résultat de l'appel à une fonction.
649 (markup #:line (fonction-qui-retourne-des-markups))
653 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
654 @code{make-line-markup}, @code{make-center-markup} ou
655 @code{make-column-markup} :
658 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
662 @node Fonctionnement interne des markups
663 @subsection Fonctionnement interne des @emph{markups}
664 @translationof How markups work internally
666 Dans un @emph{markup} tel que
669 \raise #0.5 "text example"
673 @code{\raise} représente en fait la fonction @code{raise-markup}.
674 L'expression @emph{markup} est enregistrée sous la forme
677 (list raise-markup 0.5 (list simple-markup "text example"))
680 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
681 la fonction @code{raise-markup} est appelée ainsi :
686 @var{liste des alists de propriété}
688 @var{le @emph{markup} "text example"})
691 La fonction @code{raise-markup} commence par créer le stencil pour la
692 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
693 portée. Il s'agit là d'un exemple relativement simple, et nous en
694 aborderons de plus complexes au fil des paragraphes suivants ;
695 d'autres exemples se trouvent directement dans le fichier
696 @file{scm/define-markup-commands.scm}.
699 @node Définition d'une nouvelle commande de markup
700 @subsection Définition d'une nouvelle commande de @emph{markup}
701 @translationof New markup command definition
703 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
704 commande de @emph{markup}.
707 * Syntaxe d'une commande markup::
708 * Attribution de propriétés::
710 * Adaptation d'une commande incorporée::
714 @node Syntaxe d'une commande markup
715 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
716 @translationof Markup command definition syntax
718 Une commande de @emph{markup} personnalisée se définit à l'aide de la
719 macro Scheme @code{define-markup-command}, placée en tête de fichier.
722 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
723 (@var{arg1-type?} @var{arg2-type?} ...)
724 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
726 ..corps de la commande..)
729 Quelques commentaires sur les arguments :
732 @item @var{nom-commande}
733 le nom que vous attribuez à votre commande de @emph{markup}.
735 la définition du @qq{layout} -- son formatage.
737 une liste de listes associatives, comprenant toutes les propriétés actives.
739 le @var{ième} argument de la commande.
740 @item @var{argi-type?}
741 un type de prédicat pour le @var{ième} argument.
744 Si la commande utilise des propriétés à partir des arguments
745 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
746 différentes propriétés ainsi que leur valeur par défaut.
748 Les arguments se distinguent selon leur type :
750 @item un @emph{markup}, correspondant au type de prédicat
751 @code{markup?}@tie{};
752 @item une liste de @emph{markups}, correspondant au type de prédicat
753 @code{markup-list?}@tie{};
754 @item tout autre objet Scheme, correspondant au types de prédicat tels
755 que @code{list?}, @code{number?}, @code{boolean?}, etc.
758 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
759 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
760 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
761 ceci de particulier qu'elles peuvent s'appliquer à des listes de
762 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
763 tous les éléments de la liste originelle se verront appliquer cette
764 fonction @emph{markup} avec ses arguments de tête.
766 La réplication des arguments de tête dans le but d'appliquer une
767 fonction @emph{markup} à une liste de markups est économique,
768 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
769 ainsi d'éventuelles pertes de performance en utilisant des arguments
770 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
771 le dernier argument est un @emph{markup}.
774 @node Attribution de propriétés
775 @unnumberedsubsubsec Attribution de propriétés
776 @translationof On properties
778 Les arguments @code{layout} et @code{props} d'une commande de
779 @emph{markup} fournissent un contexte à l'interprétation du
780 @emph{markup} : taille de fonte, longueur de ligne etc.
782 L'argument @code{layout} permet d'accéder aux propriétés définies dans
783 les blocs @code{\paper}, grâce à la fonction
784 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
785 identique à celle de la partition, est lue au travers de
788 (ly:output-def-lookup layout 'line-width)
791 L'argument @code{props} rend certaines propriétés accessibles aux
792 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
793 d'un @emph{markup} de titre d'ouvrage : toutes les variables
794 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
795 @code{props}, de telle sorte que le @emph{markup} de titrage de
796 l'ouvrage pourra accéder aux différents champs titre, compositeur etc.
797 Ceci permet aussi de configurer le comportement d'une commande de
798 @emph{markup} : la taille des fontes, par exemple, est lue à
799 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
800 La fonction appelant une commande de @emph{markup} peut altérer la
801 valeur de la propriété taille des fontes et donc en modifier le
802 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
803 @code{define-markup-command}, permet de spécifier les propriétés devant
804 être lues parmi les arguments @code{props}.
806 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
807 commande de @emph{markup}, accéder aux différentes propriétés et les
811 @node Exemple commenté
812 @unnumberedsubsubsec Exemple commenté
813 @translationof A complete example
815 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
818 Commençons par construire quelque chose d'approximatif à l'aide d'un
819 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
820 indique la commande @code{\box}, qui semble ici appropriée.
822 @lilypond[quote,verbatim,ragged-right]
823 \markup \box \box HELLO
826 Dans un souci d'esthétique, nous aimerions que le texte et les
827 encadrements ne soient pas autant accolés. Selon la documentation de
828 @code{\box}, cette commande utilise la propriété @code{box-padding},
829 fixée par défaut à 0,2. Cette même documentation nous indique
830 aussi comment la modifier :
832 @lilypond[quote,verbatim,ragged-right]
833 \markup \box \override #'(box-padding . 0.6) \box A
836 L'espacement des deux liserés est cependant toujours trop réduit ;
837 modifions le à son tour :
839 @lilypond[quote,verbatim,ragged-right]
840 \markup \override #'(box-padding . 0.4) \box
841 \override #'(box-padding . 0.6) \box A
844 Vous conviendrez que recopier une telle définition de @emph{markup}
845 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
846 @emph{markup} @code{double-box} qui prendra un seul argument -- le
847 texte. Cette commande se chargera de dessiner les encadrements, en
848 tenant compte des espacements.
851 #(define-markup-command (double-box layout props text) (markup?)
852 "Dessine un double encadrement autour du texte."
853 (interpret-markup layout props
854 #@{\markup \override #'(box-padding . 0.4) \box
855 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
858 ou bien son équivalent
861 #(define-markup-command (double-box layout props text) (markup?)
862 "Dessine un double encadrement autour du texte."
863 (interpret-markup layout props
864 (markup #:override '(box-padding . 0.4) #:box
865 #:override '(box-padding . 0.6) #:box text)))
868 @code{text} est le nom de l'argument de notre commande, et
869 @code{markup?} son type -- l'argument sera identifié comme étant un
870 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
871 plupart des commandes de @emph{markup}, construira un stencil à partir
872 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
873 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
874 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
875 transformation d'une expression @code{\markup} en expression Scheme est
878 Notre commande personnalisée s'utilise ainsi :
881 \markup \double-box A
884 Il serait intéressant de rendre cette commande @code{double-box} plus
885 souple@tie{}: les valeurs de @code{box-padding} sont figées et ne
886 peuvent être modifiées à l'envie. Pareillement, il serait bien de
887 distinguer l'espacement entre les encadrements de l'espacement entre le
888 texte et ses encadrements. Nous allons donc introduire une propriété
889 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
890 de gérer l'espacement des encadrements ; @code{box-padding} ne
891 servira alors que pour l'espacement intérieur. Voici le code adapté à
895 #(define-markup-command (double-box layout props text) (markup?)
896 #:properties ((inter-box-padding 0.4)
898 "Dessine un double encadrement autour du texte."
899 (interpret-markup layout props
900 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
901 \override #`(box-padding . ,box-padding) \box
905 Ainsi que son équivalent à partir de la macro @emph{markup} :
908 #(define-markup-command (double-box layout props text) (markup?)
909 #:properties ((inter-box-padding 0.4)
911 "Dessine un double encadrement autour du texte."
912 (interpret-markup layout props
913 (markup #:override `(box-padding . ,inter-box-padding) #:box
914 #:override `(box-padding . ,box-padding) #:box text)))
917 C'est ici le mot-clé @code{#:properties} qui permet de lire les
918 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
919 l'argumenet @code{props}@tie{}; on leur a d'ailleurs fourni des valeurs
920 par défaut au cas où elles ne seraient pas définies.
922 Ces valeurs permettront alors d'adapter les propriétés de
923 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
924 aurez remarqué, dans l'argument @code{\override}, la présence de
925 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
926 permettent d'insérer une valeur variable au sein d'une expression
929 Notre commande est maintenant prête à servir dans un @emph{markup}, et
930 les encadrements sont repositionnables.
932 @lilypond[quote,verbatim,ragged-right]
933 #(define-markup-command (double-box layout props text) (markup?)
934 #:properties ((inter-box-padding 0.4)
936 "Draw a double box around text."
937 (interpret-markup layout props
938 #{\markup \override #`(box-padding . ,inter-box-padding) \box
939 \override #`(box-padding . ,box-padding) \box
942 \markup \double-box A
943 \markup \override #'(inter-box-padding . 0.8) \double-box A
944 \markup \override #'(box-padding . 1.0) \double-box A
948 @node Adaptation d'une commande incorporée
949 @unnumberedsubsubsec Adaptation d'une commande incorporée
950 @translationof Adapting builtin commands
952 Le meilleur moyen de construire ses propres commandes de @emph{markup}
953 consiste à prendre exemple sur les commandes déjà incorporées. La
954 plupart des commandes de @emph{markup} fournies avec LilyPond sont
955 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
957 Nous pourrions, par exemple, envisager d'adapter la commande
958 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
959 est définie la commande @code{\draw-line}, expurgée de sa
963 (define-markup-command (draw-line layout props dest)
966 #:properties ((thickness 1))
968 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
972 (make-line-stencil th 0 0 x y)))
975 Avant de définir notre propre commande basée sur l'une de celles
976 fournies par LilyPond, commençons par en recopier la définition, puis
977 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
978 supprimé sans risque ; il ne sert que lors de la génération de la
979 documentation et n'est d'aucune utilité pour une commande personnalisée.
982 (define-markup-command (draw-double-line layout props dest)
984 #:properties ((thickness 1))
986 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
990 (make-line-stencil th 0 0 x y)))
993 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
994 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
995 par défaut de 6 dixièmes :
998 (define-markup-command (draw-double-line layout props dest)
1000 #:properties ((thickness 1)
1006 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1007 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1008 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1010 @lilypond[quote,verbatim,ragged-right]
1011 #(define-markup-command (my-draw-line layout props dest)
1013 #:properties ((thickness 1)
1016 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1020 (w (/ line-gap 2.0))
1021 (x (cond ((= dx 0) w)
1023 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1024 (y (* (if (< (* dx dy) 0) 1 -1)
1027 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1028 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1029 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1031 \markup \my-draw-line #'(4 . 3)
1032 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1036 @node Définition d'une nouvelle commande de liste de markups
1037 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1038 @translationof New markup list command definition
1040 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1041 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1042 la macro @code{define-markup-command} abordée à la rubrique
1043 @ref{Définition d'une nouvelle commande de markup} à ceci près que cette
1044 dernière renvoie un seul stencil, non une liste de stencils.
1046 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1047 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1048 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1049 par l'argument @code{props}.
1052 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1053 #:properties ((par-indent 2))
1054 (interpret-markup-list layout props
1055 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1058 La version purement Scheme est un peu plus complexe :
1060 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1061 #:properties ((par-indent 2))
1062 (interpret-markup-list layout props
1063 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1067 En dehors des habituels arguments @code{layout} et @code{props}, la
1068 commande de liste de @emph{markups} @code{paragraph} prend en argument
1069 une liste de @emph{markups} appelé @code{args}. Le prédicat des listes
1070 de @emph{markups} est @code{markup-list?}.
1072 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1073 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1074 @code{props}. En cas d'absence, la valeur par défaut sera
1075 de @code{2}. Ensuite est créée une liste de lignes justifiées
1076 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1077 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1078 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1079 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1080 interprétée par la fonction @code{interpret-markup-list}.
1082 Voici comment utiliser cette nouvelle commande de liste de
1083 @emph{markups}@tie{}:
1087 The art of music typography is called \italic @{(plate) engraving.@}
1088 The term derives from the traditional process of music printing.
1089 Just a few decades ago, sheet music was made by cutting and stamping
1090 the music into a zinc or pewter plate in mirror image.
1092 \override-lines #'(par-indent . 4) \paragraph @{
1093 The plate would be inked, the depressions caused by the cutting
1094 and stamping would hold ink. An image was formed by pressing paper
1095 to the plate. The stamping and cutting was completely done by
1102 @node Contextes pour programmeurs
1103 @section Contextes pour programmeurs
1104 @translationof Contexts for programmers
1107 * Évaluation d'un contexte::
1108 * Application d'une fonction à tous les objets de mise en forme::
1112 @node Évaluation d'un contexte
1113 @subsection Évaluation d'un contexte
1114 @translationof Context evaluation
1116 @cindex appel de code durant l'interprétation
1117 @funindex \applyContext
1119 Un contexte peut être modifié, au moment même de son interprétation, par
1120 du code Scheme. La syntaxe consacrée en pareil cas est
1122 \applyContext @var{fonction}
1125 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1126 unique argument : le contexte au sein duquel la commande
1127 @code{\applyContext} est appelée. Les lignes de code qui suivent auront
1128 pour effet d'afficher à l'écran, en cours de compilation, le numéro de
1134 (format #t "\nNous en sommes à la mesure ~a.\n"
1135 (ly:context-property x 'currentBarNumber)))
1139 @node Application d'une fonction à tous les objets de mise en forme
1140 @subsection Application d'une fonction à tous les objets de mise en forme
1141 @translationof Running a function on all layout objects
1143 @cindex appel de code sur des objets de mise en forme
1144 @funindex \applyOutput
1146 La manière la plus souple d'affiner un objet consiste à utiliser la
1147 commande @code{\applyOutput}. Celle-ci va insérer un événement
1148 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1151 \applyOutput @var{contexte} @var{procédure}
1155 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1157 Lors de l'interprétation de cette commande, la fonction
1158 @code{@var{procédure}} est appelée pout tout objet de rendu appartenant
1159 au contexte @code{@var{contexte}} à cet instant précis, avec les
1160 arguments suivants :
1162 @item l'objet de rendu en lui-même,
1163 @item le contexte au sein duquel cet objet est créé,
1164 @item et le contexte dans lequel @code{\applyOutput} est effectué.
1167 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1168 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1169 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1170 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1172 Voici une fonction utilisable avec la commande
1173 @code{\applyOutput} : elle @qq{blanchit} la tête des notes se
1174 trouvant sur la ligne médiane ou bien directement à son contact.
1176 @lilypond[quote,verbatim,ragged-right]
1177 #(define (blanker grob grob-origin context)
1178 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1179 (< (abs (ly:grob-property grob 'staff-position)) 2))
1180 (set! (ly:grob-property grob 'transparent) #t)))
1183 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1188 @node Fonctions de rappel
1189 @section Fonctions de rappel
1190 @translationof Callback functions
1192 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1193 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1197 \override Stem #'thickness = #2.0
1200 Une procédure Scheme peut aussi se charger de modifier des
1203 @lilypond[fragment,verbatim,quote,relative=2]
1204 \override Stem #'thickness = #(lambda (grob)
1205 (if (= UP (ly:grob-property grob 'direction))
1212 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1213 est nécessaire au processus de mise en forme.
1215 La majeure partie du procédé typographique consiste en la réalisation de
1216 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1217 utilisant particulièrement des rappels, nous mentionnerons
1221 Routine d'impression, construisant le dessin du symbole
1223 Routine effectuant le positionnement horizontal
1225 Routine calculant la largeur d'un objet
1228 La procédure prend un unique argument, en l'occurrence l'objet graphique
1231 Dans le cas où la routine doit faire appel à plusieurs arguments, le
1232 @emph{grob} en cours peut s'insérer à l'aide d'un @emph{grob} enchâssé.
1233 Voici, à titre d'illustration, un réglage pour
1234 @code{AccidentalSuggestion} :
1238 ,(ly:make-simple-closure
1240 ,(ly:make-simple-closure
1241 (list ly:self-alignment-interface::centered-on-x-parent))
1242 ,(ly:make-simple-closure
1243 (list ly:self-alignment-interface::x-aligned-on-self)))))
1247 Ici, aussi bien @code{ly:self-alignment-interface::x-aligned-on-self}
1248 que @code{ly:self-alignment-interface::centered-on-x-parent} font appel
1249 à l'argument @emph{grob}. La fonction @code{+} a pour effet
1250 d'additionner les résultats. L'ensemble est inclus dans un
1251 @code{ly:make-simple-closure} de telle sorte que l'addition s'exécute de
1254 Dans les faits, l'utilisation d'une unique procédure en tant que valeur
1255 d'une propriété revient à écrire
1258 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1262 Le @code{ly:make-simple-closure} intérieur fournit le @emph{grob} en
1263 argument à la procédure @var{proc}, l'extérieur s'assure que le résultat
1264 de la fonction sera bien renvoyé, non pas l'objet @code{simple-closure}.
1266 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1267 @emph{markup} consiste à utiliser la fonction
1268 @code{grob-interpret-markup}, comme ici :
1271 my-callback = #(lambda (grob)
1272 (grob-interpret-markup grob (markup "foo")))
1276 @node Code Scheme intégré
1277 @section Code Scheme intégré
1278 @translationof Inline Scheme code
1280 À REVOIR : l'exemple de cette rubrique n'est pas des plus judicieux puisque
1282 F = -\tweak #'font-size #-3 -\flageolet
1284 (notez le @samp{-} qui qualifie d'événement postérieur) fonctionne
1285 correctement dans ce cas d'espèce. En attendant un remaniement de cette
1286 section, faisons comme si nous l'ignorions.
1288 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1289 sa syntaxe. Par exemple, le code suivant produit une erreur.
1292 F = \tweak #'font-size #-3 -\flageolet
1300 En d'autres termes, @code{\tweak} ne se comporte pas comme une
1301 articulation : il ne peut notamment pas être accolé avec les
1302 symboles @samp{^} ou @samp{_}.
1304 C'est en se servant du langage Scheme que l'on peut résoudre ce
1305 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1306 @ref{Ajout d'articulation à des notes (exemple)}, en
1307 particulier quant à l'emploi de @code{\displayMusic}.
1310 F = #(let ((m (make-music 'ArticulationEvent
1311 'articulation-type "flageolet")))
1312 (set! (ly:music-property m 'tweaks)
1313 (acons 'font-size -3
1314 (ly:music-property m 'tweaks)))
1323 Ici les propriétés @code{tweak} de l'objet flageolet nommé
1324 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
1325 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1326 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1327 @code{acons}), et le résultat de cette opération est renvoyé par
1328 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1329 finale de @samp{m} lui-même.
1332 @node Retouches complexes
1333 @section Retouches complexes
1334 @translationof Difficult tweaks
1336 Certains réglages sont plus délicats que d'autres.
1340 L'un d'entre eux est l'apparence des objets dits @qq{extenseurs}
1341 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1342 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1343 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1344 changement de ligne, ils sont dupliqués au début du ou des systèmes
1345 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1346 héritent toutes les propriétés, y compris les éventuelles commandes
1349 En d'autres termes, une commande @code{\override} affecte toujours les
1350 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1351 partie précédant ou suivant le changement de ligne, il faut intervenir
1352 directement dans le processus de mise en page.
1353 La fonction de rappel @code{after-line-breaking} contient toute
1354 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1355 déterminés, et que des objets graphiques ont été divisés sur des
1356 systèmes différents.
1358 Dans l'exemple suivant, on définit une nouvelle opération nommée
1359 @code{my-callback}. Cette opération
1363 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1365 dans l'affirmative, recherche les différents morceaux de l'objet
1367 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1370 dans l'affirmative, applique un espacement supplémentaire
1371 (@code{extra-offset}).
1374 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1375 de façon à ce que le deuxième morceau d'une liaison divisée soit
1379 @lilypond[quote,verbatim,ragged-right]
1380 #(define (my-callback grob)
1382 ;; l'objet a-t-il été divisé ?
1383 (orig (ly:grob-original grob))
1385 ;; si oui, rechercher les morceaux frères (siblings)
1386 (siblings (if (ly:grob? orig)
1387 (ly:spanner-broken-into orig)
1390 (if (and (>= (length siblings) 2)
1391 (eq? (car (last-pair siblings)) grob))
1392 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1395 \override Tie #'after-line-breaking =
1403 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1404 rappel @code{after-line-breaking} devra également appeler celle
1405 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1406 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1407 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1411 Pour des raisons d'ordre technique, certains objets ne peuvent être
1412 modifiés par @code{\override}. Parmi ceux-là, les objets
1413 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1414 @code{\overrideProperty} sert à les modifier, de façon similaire à
1415 @code{\once \override} mais avec une syntaxe différente :
1419 #"Score.NonMusicalPaperColumn" % Nom de l'objet
1420 #'line-break-system-details % Nom de la propriété
1421 #'((next-padding . 20)) % Valeur
1424 Notez toutefois que la commande @code{\override} peut tout de même être
1425 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1426 bloc @code{\context}.
1431 @node Interfaces LilyPond Scheme
1432 @chapter Interfaces LilyPond Scheme
1433 @translationof LilyPond Scheme interfaces
1435 Ce chapitre aborde les différents outils fournis par LilyPond à
1436 l'intention des programmeurs en Scheme désireux d'obtenir des
1437 informations à partir et autour des fluxs de musique.
1439 TODO -- figure out what goes in here and how to organize it