1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 58aaa226bb22be92f59fec8da680d135666222cc
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 @cindex code, blocs LilyPond
42 @cindex LilyPond, bloc de code
44 @funindex #@{ @dots{} #@}
48 L'utilisation de Scheme pour créer des expressions musicales peut
49 s'avérer ardue, principalement à cause des imbrications et de la
50 longueur du code Scheme qui en résulte. Dans le cas de tâches
51 simples, on peut toutefois contourner une partie du problème en
52 utilisant des blocs de code LilyPond, ce qui autorise la syntaxe
53 habituelle de LilyPond au sein même de Scheme.
55 Les blocs de code LilyPond ressemblent à
58 #@{ @var{du code LilyPond} #@}
61 En voici un exemple basique :
63 @lilypond[verbatim,quote]
64 ritpp = #(define-event-function (parser location) ()
71 Les blocs de code LilyPond peuvent s'utiliser partout où vous pouvez
72 écrire du code Scheme. Le lecteur Scheme est en fait quelque peu adapté
73 pour accepter des blocs de code LilyPond ; il est capable de traiter des
74 expressions Scheme intégrées débutant par @code{$} ou @code{#}.
76 @cindex parser (fonction argument)
79 Le lecteur Scheme extrait le bloc de code LilyPond et déclenche un appel
80 à l'analyseur grammatical de LilyPond (le @code{parser}) qui réalise en
81 temps réel l'interprétation de ce bloc de code LilyPond. Toute
82 expression Scheme imbriquée est exécutée dans l'environnement lexical du
83 bloc de code LilyPond, de telle sorte que vous avez accès aux variables
84 locales et aux paramètres de la fonction au moment même où le bloc de
85 code LilyPond est écrit. Les variables définies dans d'autres modules
86 Scheme, tels ceux contenant les blocs @code{\header} ou @code{\layout},
87 ne sont pas accessibles en tant que variables Scheme (préfixées par
88 un @code{#}) mais en tant que variables LilyPond (préfixées par
91 Lorsque l'emplacement (@code{location} -- voir @ref{Fonctions Scheme})
92 fait référence à un endroit valide dans la source -- ce qui est en
93 général le cas au sein de fonctions musicales ou Scheme --, toute la
94 musique générée au sein de ce bloc de code voit son @code{origine}
95 établie à cet @emph{emplacement}.
97 Un bloc de code LilyPond peut contenir tout ce que vous pourriez mettre
98 à droite de l'assignation. Par ailleurs, un bloc LilyPond vide
99 correspond à une expression fantôme, et un bloc LilyPond de multiples
100 événements musicaux sera transformé en une expression de musique
104 @node Fonctions Scheme
105 @section Fonctions Scheme
106 @translationof Scheme functions
108 @cindex Scheme, fonctions (syntaxe LilyPond)
110 Les @emph{fonctions Scheme} sont des procédures Scheme chargées de créer
111 des expressions Scheme à partir de code rédigé selon la syntaxe de
112 LilyPond. Elles peuvent être appelées en de nombreux endroits, à l'aide
113 d'un @code{#}, où spécifier une valeur en syntaxe Scheme est autorisé.
114 Bien que Scheme dispose de fonctions en propre, nous nous intéresserons,
115 au fil des paragraphes qui suivent, aux fonctions @emph{syntaxiques},
116 autrement dit des fonctions qui reçoivent des arguments libellés dans la
120 * Définition de fonctions Scheme::
121 * Utilisation de fonctions Scheme::
122 * Fonctions Scheme fantômes::
125 @node Définition de fonctions Scheme
126 @subsection Définition de fonctions Scheme
127 @translationof Scheme function definitions
129 @funindex define-scheme-function
131 D'une manière générale, une fonction Scheme se définit ainsi :
135 #(define-scheme-function
136 (parser location @var{arg1} @var{arg2} @dots{})
137 (@var{type1?} @var{type2?} @dots{})
144 @multitable @columnfractions .33 .66
146 @tab doit être littéralement @code{parser}, de telle sorte que
147 l'analyseur grammatical puisse accéder aux blocs de code LilyPond
148 (@code{#@{}@dots{}@code{#@}}).
150 @item @code{location}
151 @tab doit être littéralement @code{location}, de telle sorte que soit
152 accessible l'emplacement de l'objet dans la source, aux fins de
153 transmettre aux messages d'erreur les fichier et numéro de ligne.
155 @item @code{@var{argN}}
156 @tab @var{n}ième argument
158 @item @code{@var{typeN?}}
159 @tab un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
160 devra retourner @code{#t}. Certains de ces prédicats, comme nous le
161 verrons plus loin, bénéficient d'un traitement particulier de la part du
162 @emph{parser}. De même existe une forme spécifique --
163 @code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
164 argument optionnels. En l'absence d'argument réel au moment de l'appel
165 de la fonction, c'est la valeur par défaut qui lui sera substituée. Les
166 valeurs par défaut sont évaluées dès l'apparition de la définition, y
167 compris dans le cas de blocs de code LilyPond ; vous devrez donc,
168 si ces valeurs par défaut ne peuvent être déterminées que plus tard,
169 mentionner une valeur spéciale que vous reconnaîtrez facilement.
170 Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
171 fournir sa valeur par défaut, celle-ci sera considérée comme étant
172 @code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
173 vérifiées ni au moment de la définition, ni à l'exécution ; il est
174 de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
175 par défaut constituée d'une expression musicale est recopiée dès la
176 définition de @code{origin} vers le paramètre @code{location}.
178 @item @code{@var{corps}}
179 @tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
180 servant de valeur de retour de la fonction. Il peut contenir des blocs
181 de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
182 @w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
183 @ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
184 @code{#} permet de référencer des arguments de la fonction -- tel
185 @samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
186 arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
187 Dans le cas où une expression Scheme introduite par @code{#} ne vous
188 permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
189 expression Scheme « immédiate » à l'aide d'un @code{$}, comme
192 Lorsque votre fonction retourne une expression musicale, lui est
193 attribuée la valeur @code{origin}.
197 Certains types de prédicat font l'objet d'un traitement spécial de la
198 part de l'analyseur grammatical, dans la mesure où il n'a aucun autre
199 moyen de reconnaître efficacement les arguments. Il s'agit, à l'heure
200 actuelle, de @code{ly:pitch?} et @code{ly:duration?}.
202 Pour tous les autres prédicats, la recevabilité des arguments est
203 déterminée par un appel effectif au prédicat après que LilyPond les a
204 déjà converti en expression Scheme. Par voie de conséquence, l'argument
205 peut tout à fait se libeller en syntaxe Scheme -- introduite par un
206 @code{#} ou en tant que résultat d'un appel à une fonction Scheme. Par
207 ailleurs, LilyPond convertira en Scheme un certain nombre de
208 constructions purement LilyPond avant même d'en avoir vérifié le
209 prédicat. C'est notamment le cas de la musique, des
210 @emph{postévénements}, des chaînes simples (avec ou sans guillemets),
211 des nombres, des @emph{markups} et listes de @emph{markups}, ainsi que
212 des blocs @emph{score}, @emph{book}, @emph{bookpart}, ou qui définissent
213 un contexte ou un format de sortie.
215 Il existe certaines formes d'expression, comme la plupart du temps où la
216 musique n'est pas bornée par des accolades, où LilyPond doit lire
217 au-delà de cette même expression afin d'en déterminer la fin. Si une
218 telle expression devait, après évaluation du prédicat, faire l'objet
219 d'un argument optionnel, LilyPond n'aurait aucun moyen, à partir du
220 moment où il aura décidé que l'expression ne correspond pas au
221 paramètre, de @qq{revenir en arrière}. C'est la raison pour laquelle
222 certaines formes musicales devraient être bornées par des accolades pour
223 que LilyPond puisse les reconnaître efficacement. Il existe d'autres
224 situations pour lesquelles LilyPond lèvera toute ambiguïté grâce aux
225 fonctions de prédicat : un @samp{-3} est-il un @emph{postévénement}
226 de type doigté ou un nombre négatif@tie{}? Un @code{"a" 4} en mode
227 paroles est-il une chaîne suivie d'un nombre ou bien un événement
228 syllabe de durée @code{4} ? LilyPond répondra à ces questions
229 après consultation du prédicat. Pour toutes ces raisons, nous vous
230 enjoignons à éviter d'utiliser des prédicats permissifs tel que
231 @code{scheme?}, dès que vous voulez les utiliser dans un but particulier
232 plutôt que dans une fonction de portée générale.
234 Les différents types des prédicat propres à LilyPond sont recensés à
235 l'annexe @ruser{Types de prédicats prédéfinis}.
239 @ruser{Types de prédicats prédéfinis}.
241 Fichiers d'initialisation :
242 @file{lily/music-scheme.cc},
247 @node Utilisation de fonctions Scheme
248 @subsection Utilisation de fonctions Scheme
249 @translationof Scheme function usage
251 Vous pouvez appeler une fonction Scheme pratiquement partout où une
252 expression Scheme derrière un @code{#} peut prendre place. Vous appelez
253 une fonction Scheme en faisant précéder son nom d'un @code{\}, et en le
254 faisant suivre de ses arguments. Lorsqu'un prédicat d'argument
255 optionnel ne correspond pas à un argument, LilyPond l'ignore ainsi que
256 tous les arguments optionnels qui suivent, les remplaçant par leur
257 valeur par défaut, et @qq{sauvegarde} en tant que prochain argument
258 obligatoire l'argument qui ne correspondait pas. Dans la mesure où
259 l'argument sauvegardé doit servir, les argument optionnels ne sont en
260 fait pas considérés comme optionnels, sauf à être suivis d'un argument
263 Une exception cependant à cette règle : le fait de donner un
264 @code{\default} en tant qu'argument optionnel aura pour résultat que cet
265 argument et tous les autres arguments optionnels qui suivent seront
266 ignorés et remplacés par leur valeur par défaut. Il en va de même
267 lorsqu'aucun argument obligatoire ne suit, du fait que @code{\default}
268 ne requiert pas de sauvegarde. C'est d'ailleurs ainsi que fonctionnent
269 les commandes @code{mark} et @code{key}, qui retrouvent leur
270 comportement par défaut lorsque vous les faites suivre d'un
273 En plus de là où une expression Scheme est requise, il y a quelques
274 endroits où des expressions @code{#} sont acceptées et évaluées
275 uniquement pour leurs effets annexes. Il s'agit, dans la plupart des
276 cas, d'endroits où une affectation serait tout à fait envisageable.
278 Dans la mesure où il n'est pas bon de renvoyer une valeur qui pourrait
279 être mal interprétée dans certains contextes, nous vous enjoignons à
280 utiliser des fonctions Scheme normales uniquement dans les cas où vous
281 renvoyez toujours une valeur utile, et une fonction fantôme -- voir
282 @ref{Fonctions Scheme fantômes} -- dans le cas contraire.
285 @node Fonctions Scheme fantômes
286 @subsection Fonctions Scheme fantômes
287 @translationof Void scheme functions
289 @cindex @emph{void}, fonction
290 @cindex fantôme, fonction
292 @funindex define-void-function
295 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
296 pour renvoyer une valeur. Certains langages de programmation, tels
297 le C et Scheme, utilisent des fonctions dans les deux cas et se
298 débarrassent tout bonnement de la valeur renvoyée ; en règle
299 générale, il suffit que l'expression fasse office de déclaration, et
300 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
301 la plupart des compilateurs C actuels déclenchent un avertissement si
302 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
303 nombreuses fonctions réalisant une action, les standards Scheme
304 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
305 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
306 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
307 lorsqu'on utilise @code{set!} directement sur une variable -- mais
308 malheureusement pas toujours.
310 Une fonction LilyPond définie à l'aide de la clause
311 @code{define-void-function} vous apporte l'assurance que c'est cette
312 valeur spéciale -- la seule valeur qui satisfasse au prédicat
313 @code{void?} -- qui sera retournée.
317 #(define-void-function
320 (ly:set-option 'point-and-click #f))
322 \noPointAndClick % desactive le "pointer-cliquer"
325 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
326 expression pour ses effets annexes sans interprétation d'une quelconque
330 \void #(hashq-set! une-table une-clé une-valeur)
333 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
334 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
335 opérationnel dans le cadre de fonctions musicales telles que
336 @code{\displayMusic}.
339 @node Fonctions musicales
340 @section Fonctions musicales
341 @translationof Music functions
343 @cindex musicale, fonction
345 Les @emph{fonctions musicales} sont des procédures Scheme capables de
346 créer automatiquement des expressions musicales ; elles permettent
347 de grandement simplifier un fichier source.
350 * Définition de fonctions musicales::
351 * Utilisation de fonctions musicales::
352 * Fonctions de substitution simple::
353 * Fonctions de substitution intermédiaires::
354 * De l'usage des mathématiques dans les fonctions::
355 * Fonctions dépourvues d'argument::
356 * Fonctions musicales fantômes::
360 @node Définition de fonctions musicales
361 @subsection Définition de fonctions musicales
362 @translationof Music function definitions
364 @cindex fonction musicale, définition
366 @funindex define-music-function
368 Une fonction musicale se définit ainsi :
372 #(define-music-function
373 (parser location @var{arg1} @var{arg2} @dots{})
374 (@var{type1?} @var{type2?} @dots{})
379 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
380 Scheme}. La plupart du temps, le @code{corps} sera constitué d'un
381 @ref{Blocs de code LilyPond, bloc de code Lilypond}.
383 Les différents types des prédicat sont recensés à l'annexe
384 @ruser{Types de prédicats prédéfinis}.
388 @ruser{Types de prédicats prédéfinis}.
390 Fichiers d'initialisation :
391 @file{lily/music-scheme.cc},
396 @node Utilisation de fonctions musicales
397 @subsection Utilisation de fonctions musicales
398 @translationof Music function usage
400 Une fonction musicale peut prendre place en différents endroits.
401 Certaines restrictions s'appliqueront selon l'endroit où elle est
402 utilisée, de telle sorte que l'analyse syntaxique soit sans ambiguïté.
403 Le résultat renvoyé par une fonction musicale doit être compatible avec
404 le contexte dans lequel elle est appelée.
408 Dans une expression musicale de haut niveau@tie{}: aucune restriction.
411 En tant que post-événement, explicitement introduit par un indicateur de
412 positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@code{_}. Notez
413 bien que le renvoi d'un post-événement est valide lorsque la fonction
414 musicale est appelée comme de la musique normale ; ceci amène à un
415 résultat ressemblant à
420 Dans ce cas particulier, vous ne pouvez utiliser une expression musicale
421 @emph{ouverte} en tant que dernier argument -- argument qui se
422 composerait d'une expression musicale susceptible d'accepter des
423 post-événements additionnels.
426 En tant que partie d'un accord. L'expression musicale renvoyée doit
427 être du type @code{rhythmic-event}, et plus particulièrement un
432 Les règles spécifiques en matière d'arguments de fin rendent possible
433 l'écriture de fonctions polymorphes telles que @code{\tweak}, qui
434 peuvent s'appliquer à différentes constructions.
437 @node Fonctions de substitution simple
438 @subsection Fonctions de substitution simple
439 @translationof Simple substitution functions
441 Une fonction de substitution simple renvoie une expression musicale
442 écrite au format LilyPond et contient des arguments au format de
443 l'expression résultante. Vous en trouverez une description détaillée à
444 la rubrique @ruser{Exemples de fonction de substitution}.
447 @node Fonctions de substitution intermédiaires
448 @subsection Fonctions de substitution intermédiaires
449 @translationof Intermediate substitution functions
451 Une fonction de substitution intermédiaire est une fonction dont
452 l'expression musicale résultante mélangera du code Scheme au code
455 Certaines commandes @code{\override} nécessitent un argument
456 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
457 cell} en Scheme -- que l'on pourrait traduire par @qq{construction de
460 Cette paire peut se mentionner directement dans la fonction musicale à
461 l'aide d'une variable @code{pair?} :
465 #(define-music-function
466 (parser location beg-end)
469 \once \override Beam.positions = #beg-end
473 \manualBeam #'(3 . 6) c8 d e f
477 Autre manière de procéder, les nombres formant la paire sont transmis
478 comme arguments séparés ; le code Scheme chargé de créer la paire
479 pourra alors être inclus dans l'expression musicale :
481 @lilypond[quote,verbatim,ragged-right]
483 #(define-music-function
484 (parser location beg end)
487 \once \override Beam.positions = #(cons beg end)
491 \manualBeam #3 #6 c8 d e f
496 @node De l'usage des mathématiques dans les fonctions
497 @subsection De l'usage des mathématiques dans les fonctions
498 @translationof Mathematics in functions
500 Une fonction musicale peut requérir, en plus d'une simple substitution,
501 une part de programmation en Scheme.
503 @lilypond[quote,verbatim,ragged-right]
505 #(define-music-function
506 (parser location mag)
509 \override Stem.length = #(* 7.0 mag)
510 \override NoteHead.font-size =
511 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
516 \revert NoteHead.font-size
521 \AltOn #1.5 c c \AltOff c2
526 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
527 s'applique à une expression musicale :
529 @lilypond[quote,verbatim,ragged-right]
531 #(define-music-function
532 (parser location mag music)
535 \override Stem.length = #(* 7.0 mag)
536 \override NoteHead.font-size =
537 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
540 \revert NoteHead.font-size
544 c2 \withAlt #0.5 { c4 c }
545 \withAlt #1.5 { c c } c2
550 @node Fonctions dépourvues d'argument
551 @subsection Fonctions dépourvues d'argument
552 @translationof Functions without arguments
554 Dans la plupart des cas, une fonction dépourvue d'argument devrait
555 être créée à l'aide d'une variable :
558 dolce = \markup@{ \italic \bold dolce @}
561 Il peut, dans certains cas particuliers, s'avérer utile de créer une
562 fonction sans argument comme ici,
566 #(define-music-function
569 (if (eq? #t (ly:get-option 'display-bar-numbers))
570 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
575 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
576 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
577 en respectant la syntaxe
580 lilypond -d display-bar-numbers MONFICHIER.ly
584 @node Fonctions musicales fantômes
585 @subsection Fonctions musicales fantômes
586 @translationof Void music functions
588 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
589 une fonction musicale peut n'être exécutée que dans le but d'en retenir
590 les effets annexes ; vous devrez alors utiliser une procédure
591 @code{define-void-function}. Il peut cependant arriver que vous ayez
592 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
593 l'exemple de la rubrique précédente) une expression musicale.
594 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
595 expression musicale @code{void}.
598 @node Fonctions événementielles
599 @section Fonctions événementielles
600 @translationof Event functions
602 @funindex define-event-function
603 @cindex événementielle, fonction
605 L'utilisation d'une fonction musicale pour placer un événement requiert
606 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
607 à la syntaxe de la construction à remplacer. C'est par exemple le cas
608 lorsque vous voulez écrire une commande de nuance, instruction qui
609 ne comporte habituellement pas d'indicateur de positionnement, comme
610 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
613 @lilypond[quote,verbatim,ragged-right]
614 dyn=#(define-event-function (parser location arg) (markup?)
615 (make-dynamic-script arg))
616 \relative c' { c\dyn pfsss }
619 Vous pourriez obtenir le même résultat avec une fonction musicale, à
620 ceci près que chaque appel à la fonction devra être précédé d'un
621 indicateur de positionnement, comme @code{c-\dyn pfsss}.
624 @node Fonctions pour markups
625 @section Fonctions pour @emph{markups}
626 @translationof Markup functions
628 Les @emph{markups} sont implémentés au travers de fonctions Scheme
629 spécifiques qui produisent des objets @code{Stencil} comprenant un
630 certain nombre d'arguments.
633 * Construction d'un markup en Scheme::
634 * Fonctionnement interne des markups::
635 * Définition d'une nouvelle commande de markup::
636 * Définition d'une nouvelle commande de liste de markups::
640 @node Construction d'un markup en Scheme
641 @subsection Construction d'un @emph{markup} en Scheme
642 @translationof Markup construction in Scheme
644 @cindex définition d'une commande markup
646 La macro @code{markup} construit en Scheme des expressions @emph{markup}
647 tout en disposant d'une syntaxe proche de celle de LilyPond. Par exemple,
649 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
650 #:larger #:line ("foo" "bar" "baz")))
656 #@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
657 \larger \line @{ foo bar baz @} @} #@}
661 Vous pouvez constater les principales règles de traduction entre les
662 syntaxes respectives de LilyPond et de Scheme en matière de
663 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
664 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
665 utiliser la macro @code{markup} en Scheme exclusivement.
668 @multitable @columnfractions .3 .3
669 @item @b{LilyPond} @tab @b{Scheme}
670 @item @code{\markup markup1} @tab @code{(markup markup1)}
671 @item @code{\markup @{ markup1 markup2 ... @}} @tab
672 @code{(markup markup1 markup2 ... )}
673 @item @code{\commande-markup} @tab @code{#:commande-markup}
674 @item @code{\variable} @tab @code{variable}
675 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
676 @item @code{chaîne} @tab @code{"chaîne"}
677 @item @code{#argument-scheme} @tab @code{argument-scheme}
681 L'intégralité du langage Scheme est accessible à l'intérieur même de la
682 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
683 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
684 particulièrement pratique lorsque vous créez votre propre commande de
685 @emph{markup} -- voir
686 @ref{Définition d'une nouvelle commande de markup}.
689 L'argument @var{markup-list} des commandes @code{#:line},
690 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
691 résultat de l'appel à une fonction.
694 (markup #:line (fonction-qui-retourne-des-markups))
698 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
699 @code{make-line-markup}, @code{make-center-markup} ou
700 @code{make-column-markup} :
703 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
707 @node Fonctionnement interne des markups
708 @subsection Fonctionnement interne des @emph{markups}
709 @translationof How markups work internally
711 Dans un @emph{markup} tel que
714 \raise #0.5 "text example"
718 @code{\raise} représente en fait la fonction @code{raise-markup}.
719 L'expression @emph{markup} est enregistrée sous la forme
722 (list raise-markup 0.5 (list simple-markup "text example"))
725 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
726 la fonction @code{raise-markup} est appelée ainsi :
731 @var{liste des alists de propriété}
733 @var{le @emph{markup} "text example"})
736 La fonction @code{raise-markup} commence par créer le stencil pour la
737 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
738 portée. Il s'agit là d'un exemple relativement simple, et nous en
739 aborderons de plus complexes au fil des paragraphes suivants ;
740 d'autres exemples se trouvent directement dans le fichier
741 @file{scm/define-markup-commands.scm}.
744 @node Définition d'une nouvelle commande de markup
745 @subsection Définition d'une nouvelle commande de @emph{markup}
746 @translationof New markup command definition
748 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
749 commande de @emph{markup}.
752 * Syntaxe d'une commande markup::
753 * Attribution de propriétés::
755 * Adaptation d'une commande incorporée::
759 @node Syntaxe d'une commande markup
760 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
761 @translationof Markup command definition syntax
763 Une commande de @emph{markup} personnalisée se définit à l'aide de la
764 macro Scheme @code{define-markup-command}, placée en tête de fichier.
767 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
768 (@var{arg1-type?} @var{arg2-type?} ...)
769 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
771 ..corps de la commande..)
774 Quelques commentaires sur les arguments :
777 @item @var{nom-commande}
778 le nom que vous attribuez à votre commande de @emph{markup}.
780 la définition du @qq{layout} -- son formatage.
782 une liste de listes associatives, comprenant toutes les propriétés actives.
784 le @var{ième} argument de la commande.
785 @item @var{argi-type?}
786 un type de prédicat pour le @var{ième} argument.
789 Si la commande utilise des propriétés à partir des arguments
790 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
791 différentes propriétés ainsi que leur valeur par défaut.
793 Les arguments se distinguent selon leur type :
795 @item un @emph{markup}, correspondant au type de prédicat
796 @code{markup?}@tie{};
797 @item une liste de @emph{markups}, correspondant au type de prédicat
798 @code{markup-list?}@tie{};
799 @item tout autre objet Scheme, correspondant au types de prédicat tels
800 que @code{list?}, @code{number?}, @code{boolean?}, etc.
803 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
804 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
805 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
806 ceci de particulier qu'elles peuvent s'appliquer à des listes de
807 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
808 tous les éléments de la liste originelle se verront appliquer cette
809 fonction @emph{markup} avec ses arguments de tête.
811 La réplication des arguments de tête dans le but d'appliquer une
812 fonction @emph{markup} à une liste de markups est économique,
813 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
814 ainsi d'éventuelles pertes de performance en utilisant des arguments
815 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
816 le dernier argument est un @emph{markup}.
819 @node Attribution de propriétés
820 @unnumberedsubsubsec Attribution de propriétés
821 @translationof On properties
823 Les arguments @code{layout} et @code{props} d'une commande de
824 @emph{markup} fournissent un contexte à l'interprétation du
825 @emph{markup} : taille de fonte, longueur de ligne etc.
827 L'argument @code{layout} permet d'accéder aux propriétés définies dans
828 les blocs @code{\paper}, grâce à la fonction
829 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
830 identique à celle de la partition, est lue au travers de
833 (ly:output-def-lookup layout 'line-width)
836 L'argument @code{props} rend certaines propriétés accessibles aux
837 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
838 d'un @emph{markup} de titre d'ouvrage : toutes les variables
839 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
840 @code{props}, de telle sorte que le @emph{markup} de titrage de
841 l'ouvrage pourra accéder aux différents champs titre, compositeur etc.
842 Ceci permet aussi de configurer le comportement d'une commande de
843 @emph{markup} : la taille des fontes, par exemple, est lue à
844 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
845 La fonction appelant une commande de @emph{markup} peut altérer la
846 valeur de la propriété taille des fontes et donc en modifier le
847 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
848 @code{define-markup-command}, permet de spécifier les propriétés devant
849 être lues parmi les arguments @code{props}.
851 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
852 commande de @emph{markup}, accéder aux différentes propriétés et les
856 @node Exemple commenté
857 @unnumberedsubsubsec Exemple commenté
858 @translationof A complete example
860 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
863 Commençons par construire quelque chose d'approximatif à l'aide d'un
864 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
865 indique la commande @code{\box}, qui semble ici appropriée.
867 @lilypond[quote,verbatim,ragged-right]
868 \markup \box \box HELLO
871 Dans un souci d'esthétique, nous aimerions que le texte et les
872 encadrements ne soient pas autant accolés. Selon la documentation de
873 @code{\box}, cette commande utilise la propriété @code{box-padding},
874 fixée par défaut à 0,2. Cette même documentation nous indique
875 aussi comment la modifier :
877 @lilypond[quote,verbatim,ragged-right]
878 \markup \box \override #'(box-padding . 0.6) \box A
881 L'espacement des deux liserés est cependant toujours trop réduit ;
882 modifions le à son tour :
884 @lilypond[quote,verbatim,ragged-right]
885 \markup \override #'(box-padding . 0.4) \box
886 \override #'(box-padding . 0.6) \box A
889 Vous conviendrez que recopier une telle définition de @emph{markup}
890 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
891 @emph{markup} @code{double-box} qui prendra un seul argument -- le
892 texte. Cette commande se chargera de dessiner les encadrements, en
893 tenant compte des espacements.
896 #(define-markup-command (double-box layout props text) (markup?)
897 "Dessine un double encadrement autour du texte."
898 (interpret-markup layout props
899 #@{\markup \override #'(box-padding . 0.4) \box
900 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
903 ou bien son équivalent
906 #(define-markup-command (double-box layout props text) (markup?)
907 "Dessine un double encadrement autour du texte."
908 (interpret-markup layout props
909 (markup #:override '(box-padding . 0.4) #:box
910 #:override '(box-padding . 0.6) #:box text)))
913 @code{text} est le nom de l'argument de notre commande, et
914 @code{markup?} son type -- l'argument sera identifié comme étant un
915 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
916 plupart des commandes de @emph{markup}, construira un stencil à partir
917 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
918 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
919 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
920 transformation d'une expression @code{\markup} en expression Scheme est
923 Notre commande personnalisée s'utilise ainsi :
926 \markup \double-box A
929 Il serait intéressant de rendre cette commande @code{double-box} plus
930 souple@tie{}: les valeurs de @code{box-padding} sont figées et ne
931 peuvent être modifiées à l'envie. Pareillement, il serait bien de
932 distinguer l'espacement entre les encadrements de l'espacement entre le
933 texte et ses encadrements. Nous allons donc introduire une propriété
934 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
935 de gérer l'espacement des encadrements ; @code{box-padding} ne
936 servira alors que pour l'espacement intérieur. Voici le code adapté à
940 #(define-markup-command (double-box layout props text) (markup?)
941 #:properties ((inter-box-padding 0.4)
943 "Dessine un double encadrement autour du texte."
944 (interpret-markup layout props
945 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
946 \override #`(box-padding . ,box-padding) \box
950 Ainsi que son équivalent à partir de la macro @emph{markup} :
953 #(define-markup-command (double-box layout props text) (markup?)
954 #:properties ((inter-box-padding 0.4)
956 "Dessine un double encadrement autour du texte."
957 (interpret-markup layout props
958 (markup #:override `(box-padding . ,inter-box-padding) #:box
959 #:override `(box-padding . ,box-padding) #:box text)))
962 C'est ici le mot-clé @code{#:properties} qui permet de lire les
963 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
964 l'argumenet @code{props}@tie{}; on leur a d'ailleurs fourni des valeurs
965 par défaut au cas où elles ne seraient pas définies.
967 Ces valeurs permettront alors d'adapter les propriétés de
968 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
969 aurez remarqué, dans l'argument @code{\override}, la présence de
970 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
971 permettent d'insérer une valeur variable au sein d'une expression
974 Notre commande est maintenant prête à servir dans un @emph{markup}, et
975 les encadrements sont repositionnables.
977 @lilypond[quote,verbatim,ragged-right]
978 #(define-markup-command (double-box layout props text) (markup?)
979 #:properties ((inter-box-padding 0.4)
981 "Draw a double box around text."
982 (interpret-markup layout props
983 #{\markup \override #`(box-padding . ,inter-box-padding) \box
984 \override #`(box-padding . ,box-padding) \box
987 \markup \double-box A
988 \markup \override #'(inter-box-padding . 0.8) \double-box A
989 \markup \override #'(box-padding . 1.0) \double-box A
993 @node Adaptation d'une commande incorporée
994 @unnumberedsubsubsec Adaptation d'une commande incorporée
995 @translationof Adapting builtin commands
997 Le meilleur moyen de construire ses propres commandes de @emph{markup}
998 consiste à prendre exemple sur les commandes déjà incorporées. La
999 plupart des commandes de @emph{markup} fournies avec LilyPond sont
1000 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
1002 Nous pourrions, par exemple, envisager d'adapter la commande
1003 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
1004 est définie la commande @code{\draw-line}, expurgée de sa
1008 (define-markup-command (draw-line layout props dest)
1011 #:properties ((thickness 1))
1013 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1017 (make-line-stencil th 0 0 x y)))
1020 Avant de définir notre propre commande basée sur l'une de celles
1021 fournies par LilyPond, commençons par en recopier la définition, puis
1022 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
1023 supprimé sans risque ; il ne sert que lors de la génération de la
1024 documentation et n'est d'aucune utilité pour une commande personnalisée.
1027 (define-markup-command (draw-double-line layout props dest)
1029 #:properties ((thickness 1))
1031 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1035 (make-line-stencil th 0 0 x y)))
1038 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
1039 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
1040 par défaut de 6 dixièmes :
1043 (define-markup-command (draw-double-line layout props dest)
1045 #:properties ((thickness 1)
1051 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1052 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1053 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1055 @lilypond[quote,verbatim,ragged-right]
1056 #(define-markup-command (my-draw-line layout props dest)
1058 #:properties ((thickness 1)
1061 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1065 (w (/ line-gap 2.0))
1066 (x (cond ((= dx 0) w)
1068 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1069 (y (* (if (< (* dx dy) 0) 1 -1)
1072 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1073 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1074 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1076 \markup \my-draw-line #'(4 . 3)
1077 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1081 @node Définition d'une nouvelle commande de liste de markups
1082 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1083 @translationof New markup list command definition
1085 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1086 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1087 la macro @code{define-markup-command} abordée à la rubrique
1088 @ref{Définition d'une nouvelle commande de markup} à ceci près que cette
1089 dernière renvoie un seul stencil, non une liste de stencils.
1091 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1092 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1093 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1094 par l'argument @code{props}.
1097 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1098 #:properties ((par-indent 2))
1099 (interpret-markup-list layout props
1100 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1103 La version purement Scheme est un peu plus complexe :
1105 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1106 #:properties ((par-indent 2))
1107 (interpret-markup-list layout props
1108 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1112 En dehors des habituels arguments @code{layout} et @code{props}, la
1113 commande de liste de @emph{markups} @code{paragraph} prend en argument
1114 une liste de @emph{markups} appelé @code{args}. Le prédicat des listes
1115 de @emph{markups} est @code{markup-list?}.
1117 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1118 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1119 @code{props}. En cas d'absence, la valeur par défaut sera
1120 de @code{2}. Ensuite est créée une liste de lignes justifiées
1121 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1122 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1123 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1124 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1125 interprétée par la fonction @code{interpret-markup-list}.
1127 Voici comment utiliser cette nouvelle commande de liste de
1128 @emph{markups}@tie{}:
1132 The art of music typography is called \italic @{(plate) engraving.@}
1133 The term derives from the traditional process of music printing.
1134 Just a few decades ago, sheet music was made by cutting and stamping
1135 the music into a zinc or pewter plate in mirror image.
1137 \override-lines #'(par-indent . 4) \paragraph @{
1138 The plate would be inked, the depressions caused by the cutting
1139 and stamping would hold ink. An image was formed by pressing paper
1140 to the plate. The stamping and cutting was completely done by
1147 @node Contextes pour programmeurs
1148 @section Contextes pour programmeurs
1149 @translationof Contexts for programmers
1152 * Évaluation d'un contexte::
1153 * Application d'une fonction à tous les objets de mise en forme::
1157 @node Évaluation d'un contexte
1158 @subsection Évaluation d'un contexte
1159 @translationof Context evaluation
1161 @cindex appel de code durant l'interprétation
1162 @funindex \applyContext
1164 Un contexte peut être modifié, au moment même de son interprétation, par
1165 du code Scheme. La syntaxe consacrée en pareil cas est
1167 \applyContext @var{fonction}
1170 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1171 unique argument : le contexte au sein duquel la commande
1172 @code{\applyContext} est appelée. Les lignes de code qui suivent auront
1173 pour effet d'afficher à l'écran, en cours de compilation, le numéro de
1179 (format #t "\nNous en sommes à la mesure ~a.\n"
1180 (ly:context-property x 'currentBarNumber)))
1184 @node Application d'une fonction à tous les objets de mise en forme
1185 @subsection Application d'une fonction à tous les objets de mise en forme
1186 @translationof Running a function on all layout objects
1188 @cindex appel de code sur des objets de mise en forme
1189 @funindex \applyOutput
1191 La manière la plus souple d'affiner un objet consiste à utiliser la
1192 commande @code{\applyOutput}. Celle-ci va insérer un événement
1193 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1196 \applyOutput @var{Contexte} @var{procédure}
1200 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1202 Lors de l'interprétation de cette commande, la fonction
1203 @code{@var{procédure}} est appelée pout tout objet de rendu appartenant
1204 au contexte @code{@var{Contexte}} à cet instant précis, avec les
1205 arguments suivants :
1207 @item l'objet de rendu en lui-même,
1208 @item le contexte au sein duquel cet objet est créé,
1209 @item et le contexte dans lequel @code{\applyOutput} est effectué.
1212 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1213 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1214 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1215 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1217 Voici une fonction utilisable avec la commande
1218 @code{\applyOutput} : elle @qq{blanchit} la tête des notes se
1219 trouvant sur la ligne médiane ou bien directement à son contact.
1221 @lilypond[quote,verbatim,ragged-right]
1222 #(define (blanker grob grob-origin context)
1223 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1224 (< (abs (ly:grob-property grob 'staff-position)) 2))
1225 (set! (ly:grob-property grob 'transparent) #t)))
1228 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1232 La @var{procédure} sera interprétée au niveau @code{Score}
1233 (partition) ou @code{Staff} dès lors que vous utiliserez l'une des
1237 \applyOutput #'Score #@var{procédure}
1238 \applyOutput #'Staff #@var{procédure}
1242 @node Fonctions de rappel
1243 @section Fonctions de rappel
1244 @translationof Callback functions
1246 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1247 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1251 \override Stem.thickness = #2.0
1254 Une procédure Scheme peut aussi se charger de modifier des
1257 @lilypond[fragment,verbatim,quote,relative=2]
1258 \override Stem.thickness = #(lambda (grob)
1259 (if (= UP (ly:grob-property grob 'direction))
1266 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1267 est nécessaire au processus de mise en forme.
1269 La majeure partie du procédé typographique consiste en la réalisation de
1270 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1271 utilisant particulièrement des rappels, nous mentionnerons
1275 Routine d'impression, construisant le dessin du symbole
1277 Routine effectuant le positionnement horizontal
1279 Routine calculant la largeur d'un objet
1282 La procédure prend un unique argument, en l'occurrence l'objet graphique
1285 Dans le cas où la routine doit faire appel à plusieurs arguments, le
1286 @emph{grob} en cours peut s'insérer à l'aide d'un @emph{grob} enchâssé.
1287 Voici, à titre d'illustration, un réglage pour
1288 @code{AccidentalSuggestion} :
1292 ,(ly:make-simple-closure
1294 ,(ly:make-simple-closure
1295 (list ly:self-alignment-interface::centered-on-x-parent))
1296 ,(ly:make-simple-closure
1297 (list ly:self-alignment-interface::x-aligned-on-self)))))
1301 Ici, aussi bien @code{ly:self-alignment-interface::x-aligned-on-self}
1302 que @code{ly:self-alignment-interface::centered-on-x-parent} font appel
1303 à l'argument @emph{grob}. La fonction @code{+} a pour effet
1304 d'additionner les résultats. L'ensemble est inclus dans un
1305 @code{ly:make-simple-closure} de telle sorte que l'addition s'exécute de
1308 Dans les faits, l'utilisation d'une unique procédure en tant que valeur
1309 d'une propriété revient à écrire
1312 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1316 Le @code{ly:make-simple-closure} intérieur fournit le @emph{grob} en
1317 argument à la procédure @var{proc}, l'extérieur s'assure que le résultat
1318 de la fonction sera bien renvoyé, non pas l'objet @code{simple-closure}.
1320 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1321 @emph{markup} consiste à utiliser la fonction
1322 @code{grob-interpret-markup}, comme ici :
1325 my-callback = #(lambda (grob)
1326 (grob-interpret-markup grob (markup "foo")))
1330 @node Code Scheme intégré
1331 @section Code Scheme intégré
1332 @translationof Inline Scheme code
1334 À REVOIR : l'exemple de cette rubrique n'est pas des plus judicieux puisque
1336 F = -\tweak font-size #-3 -\flageolet
1338 (notez le @samp{-} qui qualifie d'événement postérieur) fonctionne
1339 correctement dans ce cas d'espèce. En attendant un remaniement de cette
1340 section, faisons comme si nous l'ignorions.
1342 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1343 sa syntaxe. Par exemple, le code suivant produit une erreur.
1346 F = \tweak font-size #-3 -\flageolet
1354 En d'autres termes, @code{\tweak} ne se comporte pas comme une
1355 articulation : il ne peut notamment pas être accolé avec les
1356 symboles @samp{^} ou @samp{_}.
1358 C'est en se servant du langage Scheme que l'on peut résoudre ce
1359 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1360 @ref{Ajout d'articulation à des notes (exemple)}, en
1361 particulier quant à l'emploi de @code{\displayMusic}.
1364 F = #(let ((m (make-music 'ArticulationEvent
1365 'articulation-type "flageolet")))
1366 (set! (ly:music-property m 'tweaks)
1367 (acons 'font-size -3
1368 (ly:music-property m 'tweaks)))
1377 Ici les propriétés @code{tweak} de l'objet flageolet nommé
1378 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
1379 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1380 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1381 @code{acons}), et le résultat de cette opération est renvoyé par
1382 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1383 finale de @samp{m} lui-même.
1386 @node Retouches complexes
1387 @section Retouches complexes
1388 @translationof Difficult tweaks
1390 Certains réglages sont plus délicats que d'autres.
1394 L'un d'entre eux est l'apparence des objets dits @qq{extenseurs}
1395 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1396 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1397 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1398 changement de ligne, ils sont dupliqués au début du ou des systèmes
1399 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1400 héritent toutes les propriétés, y compris les éventuelles commandes
1403 En d'autres termes, une commande @code{\override} affecte toujours les
1404 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1405 partie précédant ou suivant le changement de ligne, il faut intervenir
1406 directement dans le processus de mise en page.
1407 La fonction de rappel @code{after-line-breaking} contient toute
1408 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1409 déterminés, et que des objets graphiques ont été divisés sur des
1410 systèmes différents.
1412 Dans l'exemple suivant, on définit une nouvelle opération nommée
1413 @code{my-callback}. Cette opération
1417 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1419 dans l'affirmative, recherche les différents morceaux de l'objet
1421 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1424 dans l'affirmative, applique un espacement supplémentaire
1425 (@code{extra-offset}).
1428 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1429 de façon à ce que le deuxième morceau d'une liaison divisée soit
1433 @lilypond[quote,verbatim,ragged-right]
1434 #(define (my-callback grob)
1436 ;; l'objet a-t-il été divisé ?
1437 (orig (ly:grob-original grob))
1439 ;; si oui, rechercher les morceaux frères (siblings)
1440 (siblings (if (ly:grob? orig)
1441 (ly:spanner-broken-into orig)
1444 (if (and (>= (length siblings) 2)
1445 (eq? (car (last-pair siblings)) grob))
1446 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1449 \override Tie.after-line-breaking =
1457 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1458 rappel @code{after-line-breaking} devra également appeler celle
1459 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1460 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1461 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1465 Pour des raisons d'ordre technique, certains objets ne peuvent être
1466 modifiés par @code{\override}. Parmi ceux-là, les objets
1467 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1468 @code{\overrideProperty} sert à les modifier, de façon similaire à
1469 @code{\once \override} mais avec une syntaxe différente :
1473 Score.NonMusicalPaperColumn % Nom de l'objet
1474 . line-break-system-details % Nom de la propriété
1475 . next-padding % Nom de la sous-propriété (optionnel)
1479 Notez toutefois que la commande @code{\override} peut tout de même être
1480 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1481 bloc @code{\context}.
1486 @node Interfaces LilyPond Scheme
1487 @chapter Interfaces LilyPond Scheme
1488 @translationof LilyPond Scheme interfaces
1490 Ce chapitre aborde les différents outils fournis par LilyPond à
1491 l'intention des programmeurs en Scheme désireux d'obtenir des
1492 informations à partir et autour des fluxs de musique.
1494 TODO -- figure out what goes in here and how to organize it