1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: ea78e54687b8beb80958e55bcd3ddfbe90ab5967
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.
58 Un bloc de code LilyPond peut contenir tout ce que vous pourriez mettre
59 à droite de l'assignation. Par ailleurs, un bloc LilyPond vide
60 correspond à une expression fantôme, et un bloc LilyPond de multiples
61 événements musicaux sera transformé en une expression de musique
65 @node Fonctions Scheme
66 @section Fonctions Scheme
67 @translationof Scheme functions
69 @cindex Scheme, fonctions (syntaxe LilyPond)
71 Les @emph{fonctions Scheme} sont des procédures Scheme chargées de créer
72 des expressions Scheme à partir de code rédigé selon la syntaxe de
73 LilyPond. Elles peuvent être appelées en de nombreux endroits, à l'aide
74 d'un @code{#}, où spécifier une valeur en syntaxe Scheme est autorisé.
75 Bien que Scheme dispose de fonctions en propre, nous nous intéresserons,
76 au fil des paragraphes qui suivent, aux fonctions @emph{syntaxiques},
77 autrement dit des fonctions qui reçoivent des arguments libellés dans la
81 * Définition de fonctions Scheme::
82 * Utilisation de fonctions Scheme::
83 * Fonctions Scheme fantômes::
86 @node Définition de fonctions Scheme
87 @subsection Définition de fonctions Scheme
88 @translationof Scheme function definitions
90 @funindex define-scheme-function
92 D'une manière générale, une fonction Scheme se définit ainsi :
96 #(define-scheme-function
97 (parser location @var{arg1} @var{arg2} @dots{})
98 (@var{type1?} @var{type2?} @dots{})
105 @multitable @columnfractions .33 .66
107 @tab doit être littéralement @code{parser}, de telle sorte que
108 l'analyseur grammatical puisse accéder aux blocs de code LilyPond
109 (@code{#@{}@dots{}@code{#@}}).
111 @item @code{@var{argN}}
112 @tab @var{n}ième argument
114 @item @code{@var{typeN?}}
115 @tab un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
116 devra retourner @code{#t}. Certains de ces prédicats, comme nous le
117 verrons plus loin, bénéficient d'un traitement particulier de la part du
118 @emph{parser}. De même existe une forme spécifique --
119 @code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
120 argument optionnels. En l'absence d'argument réel au moment de l'appel
121 de la fonction, c'est la valeur par défaut qui lui sera substituée. Les
122 valeurs par défaut sont évaluées dès l'apparition de la définition, y
123 compris dans le cas de blocs de code LilyPond ; vous devrez donc,
124 si ces valeurs par défaut ne peuvent être déterminées que plus tard,
125 mentionner une valeur spéciale que vous reconnaîtrez facilement.
126 Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
127 fournir sa valeur par défaut, celle-ci sera considérée comme étant
128 @code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
129 vérifiées ni au moment de la définition, ni à l'exécution ; il est
130 de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
131 par défaut constituée d'une expression musicale est recopiée dès la
132 définition de @code{origin} vers le paramètre @code{location}.
134 @item @code{@var{corps}}
135 @tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
136 servant de valeur de retour de la fonction. Il peut contenir des blocs
137 de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
138 @w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
139 @ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
140 @code{#} permet de référencer des arguments de la fonction -- tel
141 @samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
142 arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
143 Dans le cas où une expression Scheme introduite par @code{#} ne vous
144 permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
145 expression Scheme @qq{immédiate} à l'aide d'un @code{$}, comme
148 Lorsque votre fonction retourne une expression musicale, lui est
149 attribuée la valeur @code{origin}.
153 Certains types de prédicat font l'objet d'un traitement spécial de la
154 part de l'analyseur grammatical, dans la mesure où il n'a aucun autre
155 moyen de reconnaître efficacement les arguments. Il s'agit, à l'heure
156 actuelle, de @code{ly:pitch?} et @code{ly:duration?}.
158 Pour tous les autres prédicats, la recevabilité des arguments est
159 déterminée par un appel effectif au prédicat après que LilyPond les a
160 déjà converti en expression Scheme. Par voie de conséquence, l'argument
161 peut tout à fait se libeller en syntaxe Scheme -- introduite par un
162 @code{#} ou en tant que résultat d'un appel à une fonction Scheme. Par
163 ailleurs, LilyPond convertira en Scheme un certain nombre de
164 constructions purement LilyPond avant même d'en avoir vérifié le
165 prédicat. C'est notamment le cas de la musique, des
166 @emph{postévénements}, des chaînes simples (avec ou sans guillemets),
167 des nombres, des @emph{markups} et listes de @emph{markups}, ainsi que
168 des blocs @emph{score}, @emph{book}, @emph{bookpart}, ou qui définissent
169 un contexte ou un format de sortie.
171 Il existe certaines formes d'expression, comme la plupart du temps où la
172 musique n'est pas bornée par des accolades, où LilyPond doit lire
173 au-delà de cette même expression afin d'en déterminer la fin. Si une
174 telle expression devait, après évaluation du prédicat, faire l'objet
175 d'un argument optionnel, LilyPond n'aurait aucun moyen, à partir du
176 moment où il aura décidé que l'expression ne correspond pas au
177 paramètre, de @qq{revenir en arrière}. C'est la raison pour laquelle
178 certaines formes musicales devraient être bornées par des accolades pour
179 que LilyPond puisse les reconnaître efficacement. Il existe d'autres
180 situations pour lesquelles LilyPond lèvera toute ambiguïté grâce aux
181 fonctions de prédicat : un @samp{-3} est-il un @emph{postévénement}
182 de type doigté ou un nombre négatif@tie{}? Un @code{"a" 4} en mode
183 paroles est-il une chaîne suivie d'un nombre ou bien un événement
184 syllabe de durée @code{4} ? LilyPond répondra à ces questions
185 après consultation du prédicat. Pour toutes ces raisons, nous vous
186 enjoignons à éviter d'utiliser des prédicats permissifs tel que
187 @code{scheme?}, dès que vous voulez les utiliser dans un but particulier
188 plutôt que dans une fonction de portée générale.
190 Les différents types des prédicat propres à LilyPond sont recensés à
191 l'annexe @ruser{Types de prédicats prédéfinis}.
195 @ruser{Types de prédicats prédéfinis}.
197 Fichiers d'initialisation :
198 @file{lily/music-scheme.cc},
203 @node Utilisation de fonctions Scheme
204 @subsection Utilisation de fonctions Scheme
205 @translationof Scheme function usage
207 Vous pouvez appeler une fonction Scheme pratiquement partout où une
208 expression Scheme derrière un @code{#} peut prendre place. Vous appelez
209 une fonction Scheme en faisant précéder son nom d'un @code{\}, et en le
210 faisant suivre de ses arguments. Lorsqu'un prédicat d'argument
211 optionnel ne correspond pas à un argument, LilyPond l'ignore ainsi que
212 tous les arguments optionnels qui suivent, les remplaçant par leur
213 valeur par défaut, et @qq{sauvegarde} en tant que prochain argument
214 obligatoire l'argument qui ne correspondait pas. Dans la mesure où
215 l'argument sauvegardé doit servir, les argument optionnels ne sont en
216 fait pas considérés comme optionnels, sauf à être suivis d'un argument
219 Une exception cependant à cette règle : le fait de donner un
220 @code{\default} en tant qu'argument optionnel aura pour résultat que cet
221 argument et tous les autres arguments optionnels qui suivent seront
222 ignorés et remplacés par leur valeur par défaut. Il en va de même
223 lorsqu'aucun argument obligatoire ne suit, du fait que @code{\default}
224 ne requiert pas de sauvegarde. C'est d'ailleurs ainsi que fonctionnent
225 les commandes @code{mark} et @code{key}, qui retrouvent leur
226 comportement par défaut lorsque vous les faites suivre d'un
229 En plus de là où une expression Scheme est requise, il y a quelques
230 endroits où des expressions @code{#} sont acceptées et évaluées
231 uniquement pour leurs effets annexes. Il s'agit, dans la plupart des
232 cas, d'endroits où une affectation serait tout à fait envisageable.
234 Dans la mesure où il n'est pas bon de renvoyer une valeur qui pourrait
235 être mal interprétée dans certains contextes, nous vous enjoignons à
236 utiliser des fonctions Scheme normales uniquement dans les cas où vous
237 renvoyez toujours une valeur utile, et une fonction fantôme -- voir
238 @ref{Fonctions Scheme fantômes} -- dans le cas contraire.
241 @node Fonctions Scheme fantômes
242 @subsection Fonctions Scheme fantômes
243 @translationof Void scheme functions
245 @cindex @emph{void}, fonction
246 @cindex fantôme, fonction
248 @funindex define-void-function
251 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
252 pour renvoyer une valeur. Certains langages de programmation, tels
253 le C et Scheme, utilisent des fonctions dans les deux cas et se
254 débarrassent tout bonnement de la valeur renvoyée ; en règle
255 générale, il suffit que l'expression fasse office de déclaration, et
256 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
257 la plupart des compilateurs C actuels déclenchent un avertissement si
258 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
259 nombreuses fonctions réalisant une action, les standards Scheme
260 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
261 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
262 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
263 lorsqu'on utilise @code{set!} directement sur une variable -- mais
264 malheureusement pas toujours.
266 Une fonction LilyPond définie à l'aide de la clause
267 @code{define-void-function} vous apporte l'assurance que c'est cette
268 valeur spéciale -- la seule valeur qui satisfasse au prédicat
269 @code{void?} -- qui sera retournée.
273 #(define-void-function
276 (ly:set-option 'point-and-click #f))
278 \noPointAndClick % desactive le "pointer-cliquer"
281 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
282 expression pour ses effets annexes sans interprétation d'une quelconque
286 \void #(hashq-set! une-table une-clé une-valeur)
289 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
290 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
291 opérationnel dans le cadre de fonctions musicales telles que
292 @code{\displayMusic}.
295 @node Fonctions musicales
296 @section Fonctions musicales
297 @translationof Music functions
299 @cindex musicale, fonction
301 Les @emph{fonctions musicales} sont des procédures Scheme capables de
302 créer automatiquement des expressions musicales ; elles permettent
303 de grandement simplifier un fichier source.
306 * Définition de fonctions musicales::
307 * Utilisation de fonctions musicales::
308 * Fonctions de substitution simple::
309 * Fonctions de substitution intermédiaires::
310 * De l'usage des mathématiques dans les fonctions::
311 * Fonctions dépourvues d'argument::
312 * Fonctions musicales fantômes::
316 @node Définition de fonctions musicales
317 @subsection Définition de fonctions musicales
318 @translationof Music function definitions
320 @cindex fonction musicale, définition
322 @funindex define-music-function
324 Une fonction musicale se définit ainsi :
328 #(define-music-function
329 (parser location @var{arg1} @var{arg2} @dots{})
330 (@var{type1?} @var{type2?} @dots{})
335 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
336 Scheme}. La plupart du temps, le @code{corps} sera constitué d'un
337 @ref{Blocs de code LilyPond, bloc de code Lilypond}.
339 Les différents types des prédicat sont recensés à l'annexe
340 @ruser{Types de prédicats prédéfinis}.
344 @ruser{Types de prédicats prédéfinis}.
346 Fichiers d'initialisation :
347 @file{lily/music-scheme.cc},
352 @node Utilisation de fonctions musicales
353 @subsection Utilisation de fonctions musicales
354 @translationof Music function usage
356 Une fonction musicale peut prendre place en différents endroits.
357 Certaines restrictions s'appliqueront selon l'endroit où elle est
358 utilisée, de telle sorte que l'analyse syntaxique soit sans ambiguïté.
359 Le résultat renvoyé par une fonction musicale doit être compatible avec
360 le contexte dans lequel elle est appelée.
364 Dans une expression musicale de haut niveau@tie{}: aucune restriction.
367 En tant que post-événement, explicitement introduit par un indicateur de
368 positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@code{_}. Notez
369 bien que le renvoi d'un post-événement est valide lorsque la fonction
370 musicale est appelée comme de la musique normale ; ceci amène à un
371 résultat ressemblant à
376 Dans ce cas particulier, vous ne pouvez utiliser une expression musicale
377 @emph{ouverte} en tant que dernier argument -- argument qui se
378 composerait d'une expression musicale susceptible d'accepter des
379 post-événements additionnels.
382 En tant que partie d'un accord. L'expression musicale renvoyée doit
383 être du type @code{rhythmic-event}, et plus particulièrement un
388 Les règles spécifiques en matière d'arguments de fin rendent possible
389 l'écriture de fonctions polymorphes telles que @code{\tweak}, qui
390 peuvent s'appliquer à différentes constructions.
393 @node Fonctions de substitution simple
394 @subsection Fonctions de substitution simple
395 @translationof Simple substitution functions
397 Une fonction de substitution simple renvoie une expression musicale
398 écrite au format LilyPond et contient des arguments au format de
399 l'expression résultante. Vous en trouverez une description détaillée à
400 la rubrique @ruser{Exemples de fonction de substitution}.
403 @node Fonctions de substitution intermédiaires
404 @subsection Fonctions de substitution intermédiaires
405 @translationof Intermediate substitution functions
407 Une fonction de substitution intermédiaire est une fonction dont
408 l'expression musicale résultante mélangera du code Scheme au code
411 Certaines commandes @code{\override} nécessitent un argument
412 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
413 cell} en Scheme -- que l'on pourrait traduire par @qq{construction de
416 Cette paire peut se mentionner directement dans la fonction musicale à
417 l'aide d'une variable @code{pair?} :
421 #(define-music-function
422 (parser location beg-end)
425 \once \override Beam #'positions = #beg-end
429 \manualBeam #'(3 . 6) c8 d e f
433 Autre manière de procéder, les nombres formant la paire sont transmis
434 comme arguments séparés ; le code Scheme chargé de créer la paire
435 pourra alors être inclus dans l'expression musicale :
437 @lilypond[quote,verbatim,ragged-right]
439 #(define-music-function
440 (parser location beg end)
443 \once \override Beam #'positions = #(cons beg end)
447 \manualBeam #3 #6 c8 d e f
452 @node De l'usage des mathématiques dans les fonctions
453 @subsection De l'usage des mathématiques dans les fonctions
454 @translationof Mathematics in functions
456 Une fonction musicale peut requérir, en plus d'une simple substitution,
457 une part de programmation en Scheme.
459 @lilypond[quote,verbatim,ragged-right]
461 #(define-music-function
462 (parser location mag)
465 \override Stem #'length = #(* 7.0 mag)
466 \override NoteHead #'font-size =
467 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
471 \revert Stem #'length
472 \revert NoteHead #'font-size
477 \AltOn #1.5 c c \AltOff c2
482 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
483 s'applique à une expression musicale :
485 @lilypond[quote,verbatim,ragged-right]
487 #(define-music-function
488 (parser location mag music)
491 \override Stem #'length = #(* 7.0 mag)
492 \override NoteHead #'font-size =
493 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
495 \revert Stem #'length
496 \revert NoteHead #'font-size
500 c2 \withAlt #0.5 { c4 c }
501 \withAlt #1.5 { c c } c2
506 @node Fonctions dépourvues d'argument
507 @subsection Fonctions dépourvues d'argument
508 @translationof Functions without arguments
510 Dans la plupart des cas, une fonction dépourvue d'argument devrait
511 être créée à l'aide d'une variable :
514 dolce = \markup@{ \italic \bold dolce @}
517 Il peut, dans certains cas particuliers, s'avérer utile de créer une
518 fonction sans argument comme ici,
522 #(define-music-function
525 (if (eq? #t (ly:get-option 'display-bar-numbers))
526 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
531 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
532 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
533 en respectant la syntaxe
536 lilypond -d display-bar-numbers MONFICHIER.ly
540 @node Fonctions musicales fantômes
541 @subsection Fonctions musicales fantômes
542 @translationof Void music functions
544 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
545 une fonction musicale peut n'être exécutée que dans le but d'en retenir
546 les effets annexes ; vous devrez alors utiliser une procédure
547 @code{define-void-function}. Il peut cependant arriver que vous ayez
548 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
549 l'exemple de la rubrique précédente) une expression musicale.
550 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
551 expression musicale @code{void}.
554 @node Fonctions événementielles
555 @section Fonctions événementielles
556 @translationof Event functions
558 @funindex define-event-function
559 @cindex événementielle, fonction
561 L'utilisation d'une fonction musicale pour placer un événement requiert
562 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
563 à la syntaxe de la construction à remplacer. C'est par exemple le cas
564 lorsque vous voulez écrire une commande de nuance, instruction qui
565 ne comporte habituellement pas d'indicateur de positionnement, comme
566 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
569 @lilypond[quote,verbatim,ragged-right]
570 dyn=#(define-event-function (parser location arg) (markup?)
571 (make-dynamic-script arg))
572 \relative c' { c\dyn pfsss }
575 Vous pourriez obtenir le même résultat avec une fonction musicale, à
576 ceci près que chaque appel à la fonction devra être précédé d'un
577 indicateur de positionnement, comme @code{c-\dyn pfsss}.
580 @node Fonctions pour markups
581 @section Fonctions pour @emph{markups}
582 @translationof Markup functions
584 Les @emph{markups} sont implémentés au travers de fonctions Scheme
585 spécifiques qui produisent des objets @code{Stencil} comprenant un
586 certain nombre d'arguments.
589 * Construction d'un markup en Scheme::
590 * Fonctionnement interne des markups::
591 * Définition d'une nouvelle commande de markup::
592 * Définition d'une nouvelle commande de liste de markups::
596 @node Construction d'un markup en Scheme
597 @subsection Construction d'un @emph{markup} en Scheme
598 @translationof Markup construction in Scheme
600 @cindex définition d'une commande markup
602 La macro @code{markup} construit en Scheme des expressions @emph{markup}
603 tout en disposant d'une syntaxe proche de celle de LilyPond. Par exemple,
605 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
606 #:larger #:line ("foo" "bar" "baz")))
612 #@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
613 \larger \line @{ foo bar baz @} @} #@}
617 Vous pouvez constater les principales règles de traduction entre les
618 syntaxes respectives de LilyPond et de Scheme en matière de
619 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
620 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
621 utiliser la macro @code{markup} en Scheme exclusivement.
624 @multitable @columnfractions .3 .3
625 @item @b{LilyPond} @tab @b{Scheme}
626 @item @code{\markup markup1} @tab @code{(markup markup1)}
627 @item @code{\markup @{ markup1 markup2 ... @}} @tab
628 @code{(markup markup1 markup2 ... )}
629 @item @code{\commande-markup} @tab @code{#:commande-markup}
630 @item @code{\variable} @tab @code{variable}
631 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
632 @item @code{chaîne} @tab @code{"chaîne"}
633 @item @code{#argument-scheme} @tab @code{argument-scheme}
637 L'intégralité du langage Scheme est accessible à l'intérieur même de la
638 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
639 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
640 particulièrement pratique lorsque vous créez votre propre commande de
641 @emph{markup} -- voir
642 @ref{Définition d'une nouvelle commande de markup}.
645 L'argument @var{markup-list} des commandes @code{#:line},
646 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
647 résultat de l'appel à une fonction.
650 (markup #:line (fonction-qui-retourne-des-markups))
654 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
655 @code{make-line-markup}, @code{make-center-markup} ou
656 @code{make-column-markup} :
659 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
663 @node Fonctionnement interne des markups
664 @subsection Fonctionnement interne des @emph{markups}
665 @translationof How markups work internally
667 Dans un @emph{markup} tel que
670 \raise #0.5 "text example"
674 @code{\raise} représente en fait la fonction @code{raise-markup}.
675 L'expression @emph{markup} est enregistrée sous la forme
678 (list raise-markup 0.5 (list simple-markup "text example"))
681 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
682 la fonction @code{raise-markup} est appelée ainsi :
687 @var{liste des alists de propriété}
689 @var{le @emph{markup} "text example"})
692 La fonction @code{raise-markup} commence par créer le stencil pour la
693 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
694 portée. Il s'agit là d'un exemple relativement simple, et nous en
695 aborderons de plus complexes au fil des paragraphes suivants ;
696 d'autres exemples se trouvent directement dans le fichier
697 @file{scm/define-markup-commands.scm}.
700 @node Définition d'une nouvelle commande de markup
701 @subsection Définition d'une nouvelle commande de @emph{markup}
702 @translationof New markup command definition
704 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
705 commande de @emph{markup}.
708 * Syntaxe d'une commande markup::
709 * Attribution de propriétés::
711 * Adaptation d'une commande incorporée::
715 @node Syntaxe d'une commande markup
716 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
717 @translationof Markup command definition syntax
719 Une commande de @emph{markup} personnalisée se définit à l'aide de la
720 macro Scheme @code{define-markup-command}, placée en tête de fichier.
723 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
724 (@var{arg1-type?} @var{arg2-type?} ...)
725 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
727 ..corps de la commande..)
730 Quelques commentaires sur les arguments :
733 @item @var{nom-commande}
734 le nom que vous attribuez à votre commande de @emph{markup}.
736 la définition du @qq{layout} -- son formatage.
738 une liste de listes associatives, comprenant toutes les propriétés actives.
740 le @var{ième} argument de la commande.
741 @item @var{argi-type?}
742 un type de prédicat pour le @var{ième} argument.
745 Si la commande utilise des propriétés à partir des arguments
746 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
747 différentes propriétés ainsi que leur valeur par défaut.
749 Les arguments se distinguent selon leur type :
751 @item un @emph{markup}, correspondant au type de prédicat
752 @code{markup?}@tie{};
753 @item une liste de @emph{markups}, correspondant au type de prédicat
754 @code{markup-list?}@tie{};
755 @item tout autre objet Scheme, correspondant au types de prédicat tels
756 que @code{list?}, @code{number?}, @code{boolean?}, etc.
759 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
760 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
761 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
762 ceci de particulier qu'elles peuvent s'appliquer à des listes de
763 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
764 tous les éléments de la liste originelle se verront appliquer cette
765 fonction @emph{markup} avec ses arguments de tête.
767 La réplication des arguments de tête dans le but d'appliquer une
768 fonction @emph{markup} à une liste de markups est économique,
769 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
770 ainsi d'éventuelles pertes de performance en utilisant des arguments
771 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
772 le dernier argument est un @emph{markup}.
775 @node Attribution de propriétés
776 @unnumberedsubsubsec Attribution de propriétés
777 @translationof On properties
779 Les arguments @code{layout} et @code{props} d'une commande de
780 @emph{markup} fournissent un contexte à l'interprétation du
781 @emph{markup} : taille de fonte, longueur de ligne etc.
783 L'argument @code{layout} permet d'accéder aux propriétés définies dans
784 les blocs @code{\paper}, grâce à la fonction
785 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
786 identique à celle de la partition, est lue au travers de
789 (ly:output-def-lookup layout 'line-width)
792 L'argument @code{props} rend certaines propriétés accessibles aux
793 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
794 d'un @emph{markup} de titre d'ouvrage : toutes les variables
795 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
796 @code{props}, de telle sorte que le @emph{markup} de titrage de
797 l'ouvrage pourra accéder aux différents champs titre, compositeur etc.
798 Ceci permet aussi de configurer le comportement d'une commande de
799 @emph{markup} : la taille des fontes, par exemple, est lue à
800 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
801 La fonction appelant une commande de @emph{markup} peut altérer la
802 valeur de la propriété taille des fontes et donc en modifier le
803 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
804 @code{define-markup-command}, permet de spécifier les propriétés devant
805 être lues parmi les arguments @code{props}.
807 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
808 commande de @emph{markup}, accéder aux différentes propriétés et les
812 @node Exemple commenté
813 @unnumberedsubsubsec Exemple commenté
814 @translationof A complete example
816 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
819 Commençons par construire quelque chose d'approximatif à l'aide d'un
820 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
821 indique la commande @code{\box}, qui semble ici appropriée.
823 @lilypond[quote,verbatim,ragged-right]
824 \markup \box \box HELLO
827 Dans un souci d'esthétique, nous aimerions que le texte et les
828 encadrements ne soient pas autant accolés. Selon la documentation de
829 @code{\box}, cette commande utilise la propriété @code{box-padding},
830 fixée par défaut à 0,2. Cette même documentation nous indique
831 aussi comment la modifier :
833 @lilypond[quote,verbatim,ragged-right]
834 \markup \box \override #'(box-padding . 0.6) \box A
837 L'espacement des deux liserés est cependant toujours trop réduit ;
838 modifions le à son tour :
840 @lilypond[quote,verbatim,ragged-right]
841 \markup \override #'(box-padding . 0.4) \box
842 \override #'(box-padding . 0.6) \box A
845 Vous conviendrez que recopier une telle définition de @emph{markup}
846 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
847 @emph{markup} @code{double-box} qui prendra un seul argument -- le
848 texte. Cette commande se chargera de dessiner les encadrements, en
849 tenant compte des espacements.
852 #(define-markup-command (double-box layout props text) (markup?)
853 "Dessine un double encadrement autour du texte."
854 (interpret-markup layout props
855 #@{\markup \override #'(box-padding . 0.4) \box
856 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
859 ou bien son équivalent
862 #(define-markup-command (double-box layout props text) (markup?)
863 "Dessine un double encadrement autour du texte."
864 (interpret-markup layout props
865 (markup #:override '(box-padding . 0.4) #:box
866 #:override '(box-padding . 0.6) #:box text)))
869 @code{text} est le nom de l'argument de notre commande, et
870 @code{markup?} son type -- l'argument sera identifié comme étant un
871 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
872 plupart des commandes de @emph{markup}, construira un stencil à partir
873 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
874 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
875 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
876 transformation d'une expression @code{\markup} en expression Scheme est
879 Notre commande personnalisée s'utilise ainsi :
882 \markup \double-box A
885 Il serait intéressant de rendre cette commande @code{double-box} plus
886 souple@tie{}: les valeurs de @code{box-padding} sont figées et ne
887 peuvent être modifiées à l'envie. Pareillement, il serait bien de
888 distinguer l'espacement entre les encadrements de l'espacement entre le
889 texte et ses encadrements. Nous allons donc introduire une propriété
890 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
891 de gérer l'espacement des encadrements ; @code{box-padding} ne
892 servira alors que pour l'espacement intérieur. Voici le code adapté à
896 #(define-markup-command (double-box layout props text) (markup?)
897 #:properties ((inter-box-padding 0.4)
899 "Dessine un double encadrement autour du texte."
900 (interpret-markup layout props
901 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
902 \override #`(box-padding . ,box-padding) \box
906 Ainsi que son équivalent à partir de la macro @emph{markup} :
909 #(define-markup-command (double-box layout props text) (markup?)
910 #:properties ((inter-box-padding 0.4)
912 "Dessine un double encadrement autour du texte."
913 (interpret-markup layout props
914 (markup #:override `(box-padding . ,inter-box-padding) #:box
915 #:override `(box-padding . ,box-padding) #:box text)))
918 C'est ici le mot-clé @code{#:properties} qui permet de lire les
919 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
920 l'argumenet @code{props}@tie{}; on leur a d'ailleurs fourni des valeurs
921 par défaut au cas où elles ne seraient pas définies.
923 Ces valeurs permettront alors d'adapter les propriétés de
924 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
925 aurez remarqué, dans l'argument @code{\override}, la présence de
926 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
927 permettent d'insérer une valeur variable au sein d'une expression
930 Notre commande est maintenant prête à servir dans un @emph{markup}, et
931 les encadrements sont repositionnables.
933 @lilypond[quote,verbatim,ragged-right]
934 #(define-markup-command (double-box layout props text) (markup?)
935 #:properties ((inter-box-padding 0.4)
937 "Draw a double box around text."
938 (interpret-markup layout props
939 #{\markup \override #`(box-padding . ,inter-box-padding) \box
940 \override #`(box-padding . ,box-padding) \box
943 \markup \double-box A
944 \markup \override #'(inter-box-padding . 0.8) \double-box A
945 \markup \override #'(box-padding . 1.0) \double-box A
949 @node Adaptation d'une commande incorporée
950 @unnumberedsubsubsec Adaptation d'une commande incorporée
951 @translationof Adapting builtin commands
953 Le meilleur moyen de construire ses propres commandes de @emph{markup}
954 consiste à prendre exemple sur les commandes déjà incorporées. La
955 plupart des commandes de @emph{markup} fournies avec LilyPond sont
956 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
958 Nous pourrions, par exemple, envisager d'adapter la commande
959 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
960 est définie la commande @code{\draw-line}, expurgée de sa
964 (define-markup-command (draw-line layout props dest)
967 #:properties ((thickness 1))
969 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
973 (make-line-stencil th 0 0 x y)))
976 Avant de définir notre propre commande basée sur l'une de celles
977 fournies par LilyPond, commençons par en recopier la définition, puis
978 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
979 supprimé sans risque ; il ne sert que lors de la génération de la
980 documentation et n'est d'aucune utilité pour une commande personnalisée.
983 (define-markup-command (draw-double-line layout props dest)
985 #:properties ((thickness 1))
987 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
991 (make-line-stencil th 0 0 x y)))
994 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
995 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
996 par défaut de 6 dixièmes :
999 (define-markup-command (draw-double-line layout props dest)
1001 #:properties ((thickness 1)
1007 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1008 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1009 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1011 @lilypond[quote,verbatim,ragged-right]
1012 #(define-markup-command (my-draw-line layout props dest)
1014 #:properties ((thickness 1)
1017 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1021 (w (/ line-gap 2.0))
1022 (x (cond ((= dx 0) w)
1024 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1025 (y (* (if (< (* dx dy) 0) 1 -1)
1028 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1029 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1030 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1032 \markup \my-draw-line #'(4 . 3)
1033 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1037 @node Définition d'une nouvelle commande de liste de markups
1038 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1039 @translationof New markup list command definition
1041 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1042 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1043 la macro @code{define-markup-command} abordée à la rubrique
1044 @ref{Définition d'une nouvelle commande de markup} à ceci près que cette
1045 dernière renvoie un seul stencil, non une liste de stencils.
1047 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1048 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1049 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1050 par l'argument @code{props}.
1053 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1054 #:properties ((par-indent 2))
1055 (interpret-markup-list layout props
1056 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1059 La version purement Scheme est un peu plus complexe :
1061 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1062 #:properties ((par-indent 2))
1063 (interpret-markup-list layout props
1064 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1068 En dehors des habituels arguments @code{layout} et @code{props}, la
1069 commande de liste de @emph{markups} @code{paragraph} prend en argument
1070 une liste de @emph{markups} appelé @code{args}. Le prédicat des listes
1071 de @emph{markups} est @code{markup-list?}.
1073 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1074 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1075 @code{props}. En cas d'absence, la valeur par défaut sera
1076 de @code{2}. Ensuite est créée une liste de lignes justifiées
1077 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1078 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1079 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1080 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1081 interprétée par la fonction @code{interpret-markup-list}.
1083 Voici comment utiliser cette nouvelle commande de liste de
1084 @emph{markups}@tie{}:
1088 The art of music typography is called \italic @{(plate) engraving.@}
1089 The term derives from the traditional process of music printing.
1090 Just a few decades ago, sheet music was made by cutting and stamping
1091 the music into a zinc or pewter plate in mirror image.
1093 \override-lines #'(par-indent . 4) \paragraph @{
1094 The plate would be inked, the depressions caused by the cutting
1095 and stamping would hold ink. An image was formed by pressing paper
1096 to the plate. The stamping and cutting was completely done by
1103 @node Contextes pour programmeurs
1104 @section Contextes pour programmeurs
1105 @translationof Contexts for programmers
1108 * Évaluation d'un contexte::
1109 * Application d'une fonction à tous les objets de mise en forme::
1113 @node Évaluation d'un contexte
1114 @subsection Évaluation d'un contexte
1115 @translationof Context evaluation
1117 @cindex appel de code durant l'interprétation
1118 @funindex \applyContext
1120 Un contexte peut être modifié, au moment même de son interprétation, par
1121 du code Scheme. La syntaxe consacrée en pareil cas est
1123 \applyContext @var{fonction}
1126 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1127 unique argument : le contexte au sein duquel la commande
1128 @code{\applyContext} est appelée. Les lignes de code qui suivent auront
1129 pour effet d'afficher à l'écran, en cours de compilation, le numéro de
1135 (format #t "\nNous en sommes à la mesure ~a.\n"
1136 (ly:context-property x 'currentBarNumber)))
1140 @node Application d'une fonction à tous les objets de mise en forme
1141 @subsection Application d'une fonction à tous les objets de mise en forme
1142 @translationof Running a function on all layout objects
1144 @cindex appel de code sur des objets de mise en forme
1145 @funindex \applyOutput
1147 La manière la plus souple d'affiner un objet consiste à utiliser la
1148 commande @code{\applyOutput}. Celle-ci va insérer un événement
1149 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1152 \applyOutput @var{contexte} @var{procédure}
1156 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1158 Lors de l'interprétation de cette commande, la fonction
1159 @code{@var{procédure}} est appelée pout tout objet de rendu appartenant
1160 au contexte @code{@var{contexte}} à cet instant précis, avec les
1161 arguments suivants :
1163 @item l'objet de rendu en lui-même,
1164 @item le contexte au sein duquel cet objet est créé,
1165 @item et le contexte dans lequel @code{\applyOutput} est effectué.
1168 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1169 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1170 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1171 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1173 Voici une fonction utilisable avec la commande
1174 @code{\applyOutput} : elle @qq{blanchit} la tête des notes se
1175 trouvant sur la ligne médiane ou bien directement à son contact.
1177 @lilypond[quote,verbatim,ragged-right]
1178 #(define (blanker grob grob-origin context)
1179 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1180 (< (abs (ly:grob-property grob 'staff-position)) 2))
1181 (set! (ly:grob-property grob 'transparent) #t)))
1184 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1189 @node Fonctions de rappel
1190 @section Fonctions de rappel
1191 @translationof Callback functions
1193 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1194 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1198 \override Stem #'thickness = #2.0
1201 Une procédure Scheme peut aussi se charger de modifier des
1204 @lilypond[fragment,verbatim,quote,relative=2]
1205 \override Stem #'thickness = #(lambda (grob)
1206 (if (= UP (ly:grob-property grob 'direction))
1213 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1214 est nécessaire au processus de mise en forme.
1216 La majeure partie du procédé typographique consiste en la réalisation de
1217 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1218 utilisant particulièrement des rappels, nous mentionnerons
1222 Routine d'impression, construisant le dessin du symbole
1224 Routine effectuant le positionnement horizontal
1226 Routine calculant la largeur d'un objet
1229 La procédure prend un unique argument, en l'occurrence l'objet graphique
1232 Dans le cas où la routine doit faire appel à plusieurs arguments, le
1233 @emph{grob} en cours peut s'insérer à l'aide d'un @emph{grob} enchâssé.
1234 Voici, à titre d'illustration, un réglage pour
1235 @code{AccidentalSuggestion} :
1239 ,(ly:make-simple-closure
1241 ,(ly:make-simple-closure
1242 (list ly:self-alignment-interface::centered-on-x-parent))
1243 ,(ly:make-simple-closure
1244 (list ly:self-alignment-interface::x-aligned-on-self)))))
1248 Ici, aussi bien @code{ly:self-alignment-interface::x-aligned-on-self}
1249 que @code{ly:self-alignment-interface::centered-on-x-parent} font appel
1250 à l'argument @emph{grob}. La fonction @code{+} a pour effet
1251 d'additionner les résultats. L'ensemble est inclus dans un
1252 @code{ly:make-simple-closure} de telle sorte que l'addition s'exécute de
1255 Dans les faits, l'utilisation d'une unique procédure en tant que valeur
1256 d'une propriété revient à écrire
1259 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1263 Le @code{ly:make-simple-closure} intérieur fournit le @emph{grob} en
1264 argument à la procédure @var{proc}, l'extérieur s'assure que le résultat
1265 de la fonction sera bien renvoyé, non pas l'objet @code{simple-closure}.
1267 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1268 @emph{markup} consiste à utiliser la fonction
1269 @code{grob-interpret-markup}, comme ici :
1272 my-callback = #(lambda (grob)
1273 (grob-interpret-markup grob (markup "foo")))
1277 @node Code Scheme intégré
1278 @section Code Scheme intégré
1279 @translationof Inline Scheme code
1281 À REVOIR : l'exemple de cette rubrique n'est pas des plus judicieux puisque
1283 F = -\tweak #'font-size #-3 -\flageolet
1285 (notez le @samp{-} qui qualifie d'événement postérieur) fonctionne
1286 correctement dans ce cas d'espèce. En attendant un remaniement de cette
1287 section, faisons comme si nous l'ignorions.
1289 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1290 sa syntaxe. Par exemple, le code suivant produit une erreur.
1293 F = \tweak #'font-size #-3 -\flageolet
1301 En d'autres termes, @code{\tweak} ne se comporte pas comme une
1302 articulation : il ne peut notamment pas être accolé avec les
1303 symboles @samp{^} ou @samp{_}.
1305 C'est en se servant du langage Scheme que l'on peut résoudre ce
1306 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1307 @ref{Ajout d'articulation à des notes (exemple)}, en
1308 particulier quant à l'emploi de @code{\displayMusic}.
1311 F = #(let ((m (make-music 'ArticulationEvent
1312 'articulation-type "flageolet")))
1313 (set! (ly:music-property m 'tweaks)
1314 (acons 'font-size -3
1315 (ly:music-property m 'tweaks)))
1324 Ici les propriétés @code{tweak} de l'objet flageolet nommé
1325 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
1326 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1327 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1328 @code{acons}), et le résultat de cette opération est renvoyé par
1329 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1330 finale de @samp{m} lui-même.
1333 @node Retouches complexes
1334 @section Retouches complexes
1335 @translationof Difficult tweaks
1337 Certains réglages sont plus délicats que d'autres.
1341 L'un d'entre eux est l'apparence des objets dits @qq{extenseurs}
1342 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1343 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1344 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1345 changement de ligne, ils sont dupliqués au début du ou des systèmes
1346 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1347 héritent toutes les propriétés, y compris les éventuelles commandes
1350 En d'autres termes, une commande @code{\override} affecte toujours les
1351 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1352 partie précédant ou suivant le changement de ligne, il faut intervenir
1353 directement dans le processus de mise en page.
1354 La fonction de rappel @code{after-line-breaking} contient toute
1355 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1356 déterminés, et que des objets graphiques ont été divisés sur des
1357 systèmes différents.
1359 Dans l'exemple suivant, on définit une nouvelle opération nommée
1360 @code{my-callback}. Cette opération
1364 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1366 dans l'affirmative, recherche les différents morceaux de l'objet
1368 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1371 dans l'affirmative, applique un espacement supplémentaire
1372 (@code{extra-offset}).
1375 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1376 de façon à ce que le deuxième morceau d'une liaison divisée soit
1380 @lilypond[quote,verbatim,ragged-right]
1381 #(define (my-callback grob)
1383 ;; l'objet a-t-il été divisé ?
1384 (orig (ly:grob-original grob))
1386 ;; si oui, rechercher les morceaux frères (siblings)
1387 (siblings (if (ly:grob? orig)
1388 (ly:spanner-broken-into orig)
1391 (if (and (>= (length siblings) 2)
1392 (eq? (car (last-pair siblings)) grob))
1393 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1396 \override Tie #'after-line-breaking =
1404 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1405 rappel @code{after-line-breaking} devra également appeler celle
1406 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1407 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1408 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1412 Pour des raisons d'ordre technique, certains objets ne peuvent être
1413 modifiés par @code{\override}. Parmi ceux-là, les objets
1414 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1415 @code{\overrideProperty} sert à les modifier, de façon similaire à
1416 @code{\once \override} mais avec une syntaxe différente :
1420 #"Score.NonMusicalPaperColumn" % Nom de l'objet
1421 #'line-break-system-details % Nom de la propriété
1422 #'((next-padding . 20)) % Valeur
1425 Notez toutefois que la commande @code{\override} peut tout de même être
1426 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1427 bloc @code{\context}.
1432 @node Interfaces LilyPond Scheme
1433 @chapter Interfaces LilyPond Scheme
1434 @translationof LilyPond Scheme interfaces
1436 Ce chapitre aborde les différents outils fournis par LilyPond à
1437 l'intention des programmeurs en Scheme désireux d'obtenir des
1438 informations à partir et autour des fluxs de musique.
1440 TODO -- figure out what goes in here and how to organize it