1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 815ddc522bcdec0c1266caad5cc9e723fbbb2e41
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
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}. Il existe aussi une forme spécifique --
161 @code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
162 argument optionnels. En l'absence d'argument réel au moment de l'appel
163 à la fonction, c'est la valeur par défaut qui lui sera substituée. Les
164 valeurs par défaut sont évaluées dès l'apparition de la définition, y
165 compris dans le cas de blocs de code LilyPond ; vous devrez donc,
166 si ces valeurs par défaut ne peuvent être déterminées que plus tard,
167 mentionner une valeur spéciale que vous reconnaîtrez facilement.
168 Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
169 fournir sa valeur par défaut, celle-ci sera considérée comme étant
170 @code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
171 vérifiées ni au moment de la définition, ni à l'exécution ; il est
172 de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
173 par défaut constituée d'une expression musicale est recopiée dès la
174 définition de @code{origin} vers le paramètre @code{location}.
176 @item @code{@var{corps}}
177 @tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
178 servant de valeur de retour de la fonction. Il peut contenir des blocs
179 de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
180 @w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
181 @ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
182 @code{#} permet de référencer des arguments de la fonction -- tel
183 @samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
184 arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
185 Dans le cas où une expression Scheme introduite par @code{#} ne vous
186 permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
187 expression Scheme « immédiate » à l'aide d'un @code{$}, comme
190 Lorsque votre fonction retourne une expression musicale, lui est
191 attribuée la valeur @code{origin}.
195 La recevabilité des arguments est déterminée par un appel effectif au
196 prédicat après que LilyPond les a déjà converti en expression Scheme.
197 Par voie de conséquence, l'argument peut tout à fait se libeller en
198 syntaxe Scheme -- introduite par un @code{#} ou en tant que résultat
199 d'un appel à une fonction Scheme. Par ailleurs, LilyPond convertira en
200 Scheme un certain nombre de constructions purement LilyPond avant même
201 d'en avoir vérifié le prédicat. C'est notamment le cas de la musique,
202 des @emph{postévénements}, des chaînes simples (avec ou sans
203 guillemets), des nombres, des @emph{markups} et listes de
204 @emph{markups}, ainsi que des blocs @emph{score}, @emph{book},
205 @emph{bookpart}, ou qui définissent un contexte ou un format de sortie.
207 Il existe certaines formes d'expression, comme la plupart du temps où la
208 musique n'est pas bornée par des accolades, où LilyPond doit lire
209 au-delà de cette même expression afin d'en déterminer la fin. Si une
210 telle expression devait, après évaluation du prédicat, faire l'objet
211 d'un argument optionnel, LilyPond n'aurait aucun moyen, à partir du
212 moment où il aura décidé que l'expression ne correspond pas au
213 paramètre, de « revenir en arrière ». C'est la raison pour laquelle
214 certaines formes musicales devraient être bornées par des accolades pour
215 que LilyPond puisse les reconnaître efficacement. Il existe d'autres
216 situations pour lesquelles LilyPond lèvera toute ambiguïté grâce aux
217 fonctions de prédicat : un @samp{-3} est-il un @emph{postévénement}
218 de type doigté ou un nombre négatif@tie{}? Un @code{"a" 4} en mode
219 paroles est-il une chaîne suivie d'un nombre ou bien un événement
220 syllabe de durée @code{4} ? LilyPond répondra à ces questions
221 par des interprétations successives du prédicat de l'argument, dans un
222 ordre défini de sorte à minimiser les interprétations erronées et le
223 besoin de lecture en avance.
225 Un prédicat qui accepte par exemple aussi bien une expression musicale
226 qu'une hauteur considèrera @code{c''} comme étant une hauteur plutôt
227 qu'une expression musicale. Les durées ou @emph{postévénements} qui
228 viennent juste après pourraient ne pas être cohérents avec cette
229 interprétation. C'est la raison pour laquelle il vaut mieux éviter des
230 prédicats par trop permissifs tel que @code{Scheme?} lorsque
231 l'application fait plutôt appel à des type d'argument plus spécifiques.
233 Les différents types des prédicat propres à LilyPond sont recensés à
234 l'annexe @ruser{Types de prédicats prédéfinis}.
238 @ruser{Types de prédicats prédéfinis}.
240 Fichiers d'initialisation :
241 @file{lily/music-scheme.cc},
246 @node Utilisation de fonctions Scheme
247 @subsection Utilisation de fonctions Scheme
248 @translationof Scheme function usage
250 Vous pouvez appeler une fonction Scheme pratiquement partout où une
251 expression Scheme derrière un @code{#} peut prendre place. Vous appelez
252 une fonction Scheme en faisant précéder son nom d'un @code{\}, et en le
253 faisant suivre de ses arguments. Lorsqu'un prédicat d'argument
254 optionnel ne correspond pas à un argument, LilyPond l'ignore ainsi que
255 tous les arguments optionnels qui suivent, les remplaçant par leur
256 valeur par défaut, et @qq{sauvegarde} en tant que prochain argument
257 obligatoire l'argument qui ne correspondait pas. Dans la mesure où
258 l'argument sauvegardé doit servir, les argument optionnels ne sont en
259 fait pas considérés comme optionnels, sauf à être suivis d'un argument
262 Une exception cependant à cette règle : le fait de donner un
263 @code{\default} en tant qu'argument optionnel aura pour résultat que cet
264 argument et tous les autres arguments optionnels qui suivent seront
265 ignorés et remplacés par leur valeur par défaut. Il en va de même
266 lorsqu'aucun argument obligatoire ne suit, du fait que @code{\default}
267 ne requiert pas de sauvegarde. C'est d'ailleurs ainsi que fonctionnent
268 les commandes @code{mark} et @code{key}, qui retrouvent leur
269 comportement par défaut lorsque vous les faites suivre d'un
272 En plus de là où une expression Scheme est requise, il y a quelques
273 endroits où des expressions @code{#} sont acceptées et évaluées
274 uniquement pour leurs effets annexes. Il s'agit, dans la plupart des
275 cas, d'endroits où une affectation serait tout à fait envisageable.
277 Dans la mesure où il n'est pas bon de renvoyer une valeur qui pourrait
278 être mal interprétée dans certains contextes, nous vous enjoignons à
279 utiliser des fonctions Scheme normales uniquement dans les cas où vous
280 renvoyez toujours une valeur utile, et une fonction fantôme -- voir
281 @ref{Fonctions Scheme fantômes} -- dans le cas contraire.
284 @node Fonctions Scheme fantômes
285 @subsection Fonctions Scheme fantômes
286 @translationof Void scheme functions
288 @cindex @emph{void}, fonction
289 @cindex fantôme, fonction
291 @funindex define-void-function
294 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
295 pour renvoyer une valeur. Certains langages de programmation, tels
296 le C et Scheme, utilisent des fonctions dans les deux cas et se
297 débarrassent tout bonnement de la valeur renvoyée ; en règle
298 générale, il suffit que l'expression fasse office de déclaration, et
299 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
300 la plupart des compilateurs C actuels déclenchent un avertissement si
301 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
302 nombreuses fonctions réalisant une action, les standards Scheme
303 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
304 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
305 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
306 lorsqu'on utilise @code{set!} directement sur une variable -- mais
307 malheureusement pas toujours.
309 Une fonction LilyPond définie à l'aide de la clause
310 @code{define-void-function} vous apporte l'assurance que c'est cette
311 valeur spéciale -- la seule valeur qui satisfasse au prédicat
312 @code{void?} -- qui sera retournée.
316 #(define-void-function
319 (ly:set-option 'point-and-click #f))
321 \noPointAndClick % desactive le "pointer-cliquer"
324 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
325 expression pour ses effets annexes sans interprétation d'une quelconque
329 \void #(hashq-set! une-table une-clé une-valeur)
332 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
333 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
334 opérationnel dans le cadre de fonctions musicales telles que
335 @code{\displayMusic}.
338 @node Fonctions musicales
339 @section Fonctions musicales
340 @translationof Music functions
342 @cindex musicale, fonction
344 Les @emph{fonctions musicales} sont des procédures Scheme capables de
345 créer automatiquement des expressions musicales ; elles permettent
346 de grandement simplifier un fichier source.
349 * Définition de fonctions musicales::
350 * Utilisation de fonctions musicales::
351 * Fonctions de substitution simple::
352 * Fonctions de substitution intermédiaires::
353 * De l'usage des mathématiques dans les fonctions::
354 * Fonctions dépourvues d'argument::
355 * Fonctions musicales fantômes::
359 @node Définition de fonctions musicales
360 @subsection Définition de fonctions musicales
361 @translationof Music function definitions
363 @cindex fonction musicale, définition
365 @funindex define-music-function
367 Une fonction musicale se définit ainsi :
371 #(define-music-function
372 (parser location @var{arg1} @var{arg2}@dots{})
373 (@var{type1?} @var{type2?}@dots{})
378 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
379 Scheme}. La plupart du temps, le @code{corps} sera constitué d'un
380 @ref{Blocs de code LilyPond, bloc de code Lilypond}.
382 Les différents types des prédicat sont recensés à l'annexe
383 @ruser{Types de prédicats prédéfinis}.
387 @ruser{Types de prédicats prédéfinis}.
389 Fichiers d'initialisation :
390 @file{lily/music-scheme.cc},
395 @node Utilisation de fonctions musicales
396 @subsection Utilisation de fonctions musicales
397 @translationof Music function usage
399 Une fonction musicale peut prendre place en différents endroits.
400 Certaines restrictions s'appliqueront selon l'endroit où elle est
401 utilisée, de telle sorte que l'analyse syntaxique soit sans ambiguïté.
402 Le résultat renvoyé par une fonction musicale doit être compatible avec
403 le contexte dans lequel elle est appelée.
407 Dans une expression musicale de haut niveau@tie{}: aucune restriction.
410 En tant que post-événement, explicitement introduit par un indicateur de
411 positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@code{_}.
413 Dans ce cas particulier, vous ne pouvez utiliser une expression musicale
414 @emph{ouverte} en tant que dernier argument -- argument qui se
415 composerait d'une expression musicale susceptible d'accepter des
416 postévénements additionnels.
419 En tant que partie d'un accord. L'expression musicale renvoyée doit
420 être du type @code{rhythmic-event}, et plus particulièrement un
425 Les règles spécifiques en matière d'arguments de fin rendent possible
426 l'écriture de fonctions polymorphes telles que @code{\tweak}, qui
427 peuvent s'appliquer à différentes constructions.
430 @node Fonctions de substitution simple
431 @subsection Fonctions de substitution simple
432 @translationof Simple substitution functions
434 Une fonction de substitution simple renvoie une expression musicale
435 écrite au format LilyPond et contient des arguments au format de
436 l'expression résultante. Vous en trouverez une description détaillée à
437 la rubrique @ruser{Exemples de fonction de substitution}.
440 @node Fonctions de substitution intermédiaires
441 @subsection Fonctions de substitution intermédiaires
442 @translationof Intermediate substitution functions
444 Une fonction de substitution intermédiaire est une fonction dont
445 l'expression musicale résultante mélangera du code Scheme au code
448 Certaines commandes @code{\override} nécessitent un argument
449 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
450 cell} en Scheme -- que l'on pourrait traduire par @qq{construction de
453 Cette paire peut se mentionner directement dans la fonction musicale à
454 l'aide d'une variable @code{pair?} :
458 #(define-music-function
459 (parser location beg-end)
462 \once \override Beam.positions = #beg-end
466 \manualBeam #'(3 . 6) c8 d e f
470 Autre manière de procéder, les nombres formant la paire sont transmis
471 comme arguments séparés ; le code Scheme chargé de créer la paire
472 pourra alors être inclus dans l'expression musicale :
474 @lilypond[quote,verbatim,ragged-right]
476 #(define-music-function
477 (parser location beg end)
480 \once \override Beam.positions = #(cons beg end)
484 \manualBeam #3 #6 c8 d e f
489 @cindex temporaire, dérogation (override)
490 @cindex dérogation temporaire (override)
491 @cindex propriétés, retour à la valeur précédente
493 L'entretien des propriétés peut se voir comme un empilement par
494 propriété par objet par contexte. Les fonctions musicales peuvent
495 nécessiter des dérogatoins pour une ou plusieurs propriétés pour la
496 durée de la fonction, puis de revenir aux valeurs précédentes avant de
497 quitter. Néanmoins, une dérogation normale va retirer de la pile -- ou
498 dépiler -- et supprimer le sommet de la pile de la propriété avant
499 d'y ajouter quoi que ce soit -- ou empiler -- ; la valeur précédente de
500 la propriété est de fait perdue. Lorsque la valeur antérieure doit être
501 préservée, l'instruction @code{\override} devra être préfixée d'un
502 @code{\temporary}, comme ceci :
505 \temporary \override @dots{}
508 L'utilisation d'un @code{\temporary} a pour effet d'effacer la propriété
509 @code{pop-first} (@emph{commence par dépiler} normalement activée) de la
510 dérogation ; la valeur antérieure ne sera alors pas supprimée de la pile
511 de la propriété avant d'y empiler la nouvelle valeur. Lorsqu'un
512 @code{\revert} viendra par la suite supprimer la valeur dérogatoire
513 temporaire, réapparaitra la valeur antérieure.
515 En d'autres termes, un @code{\revert} qui suit un @code{\temporary
516 \override} pour la même propriété n'apporte rien. Ce principe est aussi
517 valable pour une couple @code{\temporary} et @code{\undo} sur la même
518 musique contenant des dérogations.
520 Voici un exemple de fonction musicale utilisant cette fonctionnalité.
521 La présence du @code{\temporary} permet de s'assurer qu'en sortant de la
522 fonction, les propriétés @code{cross-staff} et @code{style} retrouveront
523 les valeurs qu'elles avaient que ne soit appelée la fonction
524 @code{crossStaff}. En l'absence de @code{\temporary}, ces propriétés
525 auraient retrouvé leurs valeurs par défaut à la sortie de la fonction.
529 #(define-music-function (parser location notes) (ly:music?)
530 (_i "Create cross-staff stems")
532 \temporary \override Stem.cross-staff = #cross-staff-connect
533 \temporary \override Flag.style = #'no-flag
535 \revert Stem.cross-staff
541 @node De l'usage des mathématiques dans les fonctions
542 @subsection De l'usage des mathématiques dans les fonctions
543 @translationof Mathematics in functions
545 Une fonction musicale peut requérir, en plus d'une simple substitution,
546 une part de programmation en Scheme.
548 @lilypond[quote,verbatim,ragged-right]
550 #(define-music-function
551 (parser location mag)
554 \override Stem.length = #(* 7.0 mag)
555 \override NoteHead.font-size =
556 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
561 \revert NoteHead.font-size
566 \AltOn #1.5 c c \AltOff c2
571 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
572 s'applique à une expression musicale :
574 @lilypond[quote,verbatim,ragged-right]
576 #(define-music-function
577 (parser location mag music)
580 \override Stem.length = #(* 7.0 mag)
581 \override NoteHead.font-size =
582 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
585 \revert NoteHead.font-size
589 c2 \withAlt #0.5 { c4 c }
590 \withAlt #1.5 { c c } c2
595 @node Fonctions dépourvues d'argument
596 @subsection Fonctions dépourvues d'argument
597 @translationof Functions without arguments
599 Dans la plupart des cas, une fonction dépourvue d'argument devrait
600 être créée à l'aide d'une variable :
603 dolce = \markup@{ \italic \bold dolce @}
606 Il peut, dans certains cas particuliers, s'avérer utile de créer une
607 fonction sans argument comme ici,
611 #(define-music-function
614 (if (eq? #t (ly:get-option 'display-bar-numbers))
615 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
620 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
621 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
622 en respectant la syntaxe
625 lilypond -d display-bar-numbers MONFICHIER.ly
629 @node Fonctions musicales fantômes
630 @subsection Fonctions musicales fantômes
631 @translationof Void music functions
633 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
634 une fonction musicale peut n'être exécutée que dans le but d'en retenir
635 les effets annexes ; vous devrez alors utiliser une procédure
636 @code{define-void-function}. Il peut cependant arriver que vous ayez
637 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
638 l'exemple de la rubrique précédente) une expression musicale.
639 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
640 expression musicale @code{void}.
643 @node Fonctions événementielles
644 @section Fonctions événementielles
645 @translationof Event functions
647 @funindex define-event-function
648 @cindex événementielle, fonction
650 L'utilisation d'une fonction musicale pour placer un événement requiert
651 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
652 à la syntaxe de la construction à remplacer. C'est par exemple le cas
653 lorsque vous voulez écrire une commande de nuance, instruction qui
654 ne comporte habituellement pas d'indicateur de positionnement, comme
655 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
658 @lilypond[quote,verbatim,ragged-right]
659 dyn=#(define-event-function (parser location arg) (markup?)
660 (make-dynamic-script arg))
661 \relative c' { c\dyn pfsss }
664 Vous pourriez obtenir le même résultat avec une fonction musicale, à
665 ceci près que chaque appel à la fonction devra être précédé d'un
666 indicateur de positionnement, comme @code{c-\dyn pfsss}.
669 @node Fonctions pour markups
670 @section Fonctions pour @emph{markups}
671 @translationof Markup functions
673 Les @emph{markups} sont implémentés au travers de fonctions Scheme
674 spécifiques qui produisent des objets @code{Stencil} comprenant un
675 certain nombre d'arguments.
678 * Construction d'un markup en Scheme::
679 * Fonctionnement interne des markups::
680 * Définition d'une nouvelle commande de markup::
681 * Définition d'une nouvelle commande de liste de markups::
685 @node Construction d'un markup en Scheme
686 @subsection Construction d'un @emph{markup} en Scheme
687 @translationof Markup construction in Scheme
689 @cindex définition d'une commande markup
691 @funindex \displayScheme
693 Les expressions @emph{markup} sont représentées en Scheme de manière
694 interne par la macro @code{markup} :
697 (markup @var{expression})
700 La commande @code{\displayScheme} permet d'obtenir la représentation en
701 Scheme d'une expression @emph{markup} :
707 \line @{ \bold \italic "hello" \raise #0.4 "world" @}
708 \larger \line @{ foo bar baz @}
714 Compiler ce code renverra en console les lignes suivantes :
721 (#:bold (#:italic "hello") #:raise 0.4 "world")
724 (#:simple "foo" #:simple "bar" #:simple "baz")))))
727 L'impression du @emph{markup} sera suspendue dès lors qu'apparaîtra un
728 @w{@samp{\void \displayScheme @var{markup}}}. Tout comme pour la
729 commande @code{\displayMusic}, le résultat de @code{\displayScheme} peut
730 être sauvegardé dans un fichier séparé. Voir à ce sujet
731 @ref{Affichage d'expressions musicales}.
734 Vous pouvez constater les principales règles de traduction entre les
735 syntaxes respectives de LilyPond et de Scheme en matière de
736 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
737 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
738 utiliser la macro @code{markup} en Scheme exclusivement.
741 @multitable @columnfractions .3 .3
742 @item @b{LilyPond} @tab @b{Scheme}
743 @item @code{\markup markup1} @tab @code{(markup markup1)}
744 @item @code{\markup @{ markup1 markup2@dots{} @}} @tab
745 @code{(markup markup1 markup2@dots{} )}
746 @item @code{\commande-markup} @tab @code{#:commande-markup}
747 @item @code{\variable} @tab @code{variable}
748 @item @code{\center-column @{ @dots{} @}} @tab
749 @code{#:center-column ( @dots{} )}
750 @item @code{chaîne} @tab @code{"chaîne"}
751 @item @code{#argument-scheme} @tab @code{argument-scheme}
755 L'intégralité du langage Scheme est accessible à l'intérieur même de la
756 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
757 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
758 particulièrement pratique lorsque vous créez votre propre commande de
759 @emph{markup} -- voir
760 @ref{Définition d'une nouvelle commande de markup}.
763 L'argument @var{markup-list} des commandes @code{#:line},
764 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
765 résultat de l'appel à une fonction.
768 (markup #:line (fonction-qui-retourne-des-markups))
772 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
773 @code{make-line-markup}, @code{make-center-markup} ou
774 @code{make-column-markup} :
777 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
781 @node Fonctionnement interne des markups
782 @subsection Fonctionnement interne des @emph{markups}
783 @translationof How markups work internally
785 Dans un @emph{markup} tel que
788 \raise #0.5 "text example"
792 @code{\raise} représente en fait la fonction @code{raise-markup}.
793 L'expression @emph{markup} est enregistrée sous la forme
796 (list raise-markup 0.5 (list simple-markup "text example"))
799 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
800 la fonction @code{raise-markup} est appelée ainsi :
805 @var{liste des alists de propriété}
807 @var{le @emph{markup} "text example"})
810 La fonction @code{raise-markup} commence par créer le stencil pour la
811 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
812 portée. Il s'agit là d'un exemple relativement simple, et nous en
813 aborderons de plus complexes au fil des paragraphes suivants ;
814 d'autres exemples se trouvent directement dans le fichier
815 @file{scm/define-markup-commands.scm}.
818 @node Définition d'une nouvelle commande de markup
819 @subsection Définition d'une nouvelle commande de @emph{markup}
820 @translationof New markup command definition
822 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
823 commande de @emph{markup}.
826 * Syntaxe d'une commande markup::
827 * Attribution de propriétés::
829 * Adaptation d'une commande incorporée::
833 @node Syntaxe d'une commande markup
834 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
835 @translationof Markup command definition syntax
837 Une commande de @emph{markup} personnalisée se définit à l'aide de la
838 macro Scheme @code{define-markup-command}, placée en tête de fichier.
841 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2}@dots{})
842 (@var{arg1-type?} @var{arg2-type?}@dots{})
843 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
845 @dots{}corps de la commande@dots{})
848 Quelques commentaires sur les arguments :
851 @item @var{nom-commande}
852 le nom que vous attribuez à votre commande de @emph{markup}.
854 la définition du @qq{layout} -- son formatage.
856 une liste de listes associatives, comprenant toutes les propriétés actives.
858 le @var{ième} argument de la commande.
859 @item @var{argi-type?}
860 un type de prédicat pour le @var{ième} argument.
863 Si la commande utilise des propriétés à partir des arguments
864 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
865 différentes propriétés ainsi que leur valeur par défaut.
867 Les arguments se distinguent selon leur type :
869 @item un @emph{markup}, correspondant au type de prédicat
870 @code{markup?}@tie{};
871 @item une liste de @emph{markups}, correspondant au type de prédicat
872 @code{markup-list?}@tie{};
873 @item tout autre objet Scheme, correspondant au types de prédicat tels
874 que @code{list?}, @code{number?}, @code{boolean?}, etc.
877 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
878 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
879 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
880 ceci de particulier qu'elles peuvent s'appliquer à des listes de
881 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
882 tous les éléments de la liste originelle se verront appliquer cette
883 fonction @emph{markup} avec ses arguments de tête.
885 La réplication des arguments de tête dans le but d'appliquer une
886 fonction @emph{markup} à une liste de markups est économique,
887 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
888 ainsi d'éventuelles pertes de performance en utilisant des arguments
889 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
890 le dernier argument est un @emph{markup}.
893 @cindex macro de markup
895 @funindex interpret-markup
897 Les commandes de @emph{markup} ont un cycle de vie relativement
898 complexe. Le corps de la définition d'une commande de @emph{markup} est
899 chargé de convertir les arguments de la commande en expression stencil
900 qui sera alors renvoyée. Bien souvent, ceci s'accomplit par un appel à
901 la fonction @code{interpret-markup}, en lui passant les arguments
902 @var{layout} et @var{props}. Ces arguments ne seront en principe connus
903 que bien plus tardivement dans le processus typographique. Lors de
904 l'expansion d'une expression LilyPond @code{\markup} ou d'une macro
905 Scheme @code{macro}, les expressions @emph{markup} auront déjà vu leurs
906 composants assemblés en expressions @emph{markup}. L'évaluation et le
907 contrôle du type des arguments à une commande de @emph{markup}
908 n'interviennent qu'au moment de l'interprétation de @code{\markup} ou
911 Seule l'application de @code{interpret-markup} sur une expression
912 @emph{markup} réalisera effectivement la conversion des expressions
913 @emph{markup} en stencil, au travers de l'exécution du corps des
914 fonctions @emph{markup}.
917 @node Attribution de propriétés
918 @unnumberedsubsubsec Attribution de propriétés
919 @translationof On properties
921 Les arguments @code{layout} et @code{props} d'une commande de
922 @emph{markup} fournissent un contexte à l'interprétation du
923 @emph{markup} : taille de fonte, longueur de ligne etc.
925 L'argument @code{layout} permet d'accéder aux propriétés définies dans
926 les blocs @code{\paper}, grâce à la fonction
927 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
928 identique à celle de la partition, est lue au travers de
931 (ly:output-def-lookup layout 'line-width)
934 L'argument @code{props} rend certaines propriétés accessibles aux
935 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
936 d'un @emph{markup} de titre d'ouvrage : toutes les variables
937 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
938 @code{props}, de telle sorte que le @emph{markup} de titrage de
939 l'ouvrage pourra accéder aux différents champs titre, compositeur etc.
940 Ceci permet aussi de configurer le comportement d'une commande de
941 @emph{markup} : la taille des fontes, par exemple, est lue à
942 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
943 La fonction appelant une commande de @emph{markup} peut altérer la
944 valeur de la propriété taille des fontes et donc en modifier le
945 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
946 @code{define-markup-command}, permet de spécifier les propriétés devant
947 être lues parmi les arguments @code{props}.
949 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
950 commande de @emph{markup}, accéder aux différentes propriétés et les
954 @node Exemple commenté
955 @unnumberedsubsubsec Exemple commenté
956 @translationof A complete example
958 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
961 Commençons par construire quelque chose d'approximatif à l'aide d'un
962 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
963 indique la commande @code{\box}, qui semble ici appropriée.
965 @lilypond[quote,verbatim,ragged-right]
966 \markup \box \box HELLO
969 Dans un souci d'esthétique, nous aimerions que le texte et les
970 encadrements ne soient pas autant accolés. Selon la documentation de
971 @code{\box}, cette commande utilise la propriété @code{box-padding},
972 fixée par défaut à 0,2. Cette même documentation nous indique
973 aussi comment la modifier :
975 @lilypond[quote,verbatim,ragged-right]
976 \markup \box \override #'(box-padding . 0.6) \box A
979 L'espacement des deux liserés est cependant toujours trop réduit ;
980 modifions le à son tour :
982 @lilypond[quote,verbatim,ragged-right]
983 \markup \override #'(box-padding . 0.4) \box
984 \override #'(box-padding . 0.6) \box A
987 Vous conviendrez que recopier une telle définition de @emph{markup}
988 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
989 @emph{markup} @code{double-box} qui prendra un seul argument -- le
990 texte. Cette commande se chargera de dessiner les encadrements, en
991 tenant compte des espacements.
994 #(define-markup-command (double-box layout props text) (markup?)
995 "Dessine un double encadrement autour du texte."
996 (interpret-markup layout props
997 #@{\markup \override #'(box-padding . 0.4) \box
998 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
1001 ou bien son équivalent
1004 #(define-markup-command (double-box layout props text) (markup?)
1005 "Dessine un double encadrement autour du texte."
1006 (interpret-markup layout props
1007 (markup #:override '(box-padding . 0.4) #:box
1008 #:override '(box-padding . 0.6) #:box text)))
1011 @code{text} est le nom de l'argument de notre commande, et
1012 @code{markup?} son type -- l'argument sera identifié comme étant un
1013 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
1014 plupart des commandes de @emph{markup}, construira un stencil à partir
1015 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
1016 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
1017 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
1018 transformation d'une expression @code{\markup} en expression Scheme est
1021 Notre commande personnalisée s'utilise ainsi :
1024 \markup \double-box A
1027 Il serait intéressant de rendre cette commande @code{double-box} plus
1028 souple@tie{}: les valeurs de @code{box-padding} sont figées et ne
1029 peuvent être modifiées à l'envie. Pareillement, il serait bien de
1030 distinguer l'espacement entre les encadrements de l'espacement entre le
1031 texte et ses encadrements. Nous allons donc introduire une propriété
1032 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
1033 de gérer l'espacement des encadrements ; @code{box-padding} ne
1034 servira alors que pour l'espacement intérieur. Voici le code adapté à
1038 #(define-markup-command (double-box layout props text) (markup?)
1039 #:properties ((inter-box-padding 0.4)
1041 "Dessine un double encadrement autour du texte."
1042 (interpret-markup layout props
1043 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
1044 \override #`(box-padding . ,box-padding) \box
1048 Ainsi que son équivalent à partir de la macro @emph{markup} :
1051 #(define-markup-command (double-box layout props text) (markup?)
1052 #:properties ((inter-box-padding 0.4)
1054 "Dessine un double encadrement autour du texte."
1055 (interpret-markup layout props
1056 (markup #:override `(box-padding . ,inter-box-padding) #:box
1057 #:override `(box-padding . ,box-padding) #:box text)))
1060 C'est ici le mot-clé @code{#:properties} qui permet de lire les
1061 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
1062 l'argumenet @code{props}@tie{}; on leur a d'ailleurs fourni des valeurs
1063 par défaut au cas où elles ne seraient pas définies.
1065 Ces valeurs permettront alors d'adapter les propriétés de
1066 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
1067 aurez remarqué, dans l'argument @code{\override}, la présence de
1068 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
1069 permettent d'insérer une valeur variable au sein d'une expression
1072 Notre commande est maintenant prête à servir dans un @emph{markup}, et
1073 les encadrements sont repositionnables.
1075 @lilypond[quote,verbatim,ragged-right]
1076 #(define-markup-command (double-box layout props text) (markup?)
1077 #:properties ((inter-box-padding 0.4)
1079 "Draw a double box around text."
1080 (interpret-markup layout props
1081 #{\markup \override #`(box-padding . ,inter-box-padding) \box
1082 \override #`(box-padding . ,box-padding) \box
1085 \markup \double-box A
1086 \markup \override #'(inter-box-padding . 0.8) \double-box A
1087 \markup \override #'(box-padding . 1.0) \double-box A
1091 @node Adaptation d'une commande incorporée
1092 @unnumberedsubsubsec Adaptation d'une commande incorporée
1093 @translationof Adapting builtin commands
1095 Le meilleur moyen de construire ses propres commandes de @emph{markup}
1096 consiste à prendre exemple sur les commandes déjà incorporées. La
1097 plupart des commandes de @emph{markup} fournies avec LilyPond sont
1098 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
1100 Nous pourrions, par exemple, envisager d'adapter la commande
1101 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
1102 est définie la commande @code{\draw-line}, expurgée de sa
1106 (define-markup-command (draw-line layout props dest)
1109 #:properties ((thickness 1))
1110 "@dots{}documentation@dots{}"
1111 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1115 (make-line-stencil th 0 0 x y)))
1118 Avant de définir notre propre commande basée sur l'une de celles
1119 fournies par LilyPond, commençons par en recopier la définition, puis
1120 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
1121 supprimé sans risque ; il ne sert que lors de la génération de la
1122 documentation et n'est d'aucune utilité pour une commande personnalisée.
1125 (define-markup-command (draw-double-line layout props dest)
1127 #:properties ((thickness 1))
1128 "@dots{}documentation@dots{}"
1129 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1133 (make-line-stencil th 0 0 x y)))
1136 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
1137 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
1138 par défaut de 6 dixièmes :
1141 (define-markup-command (draw-double-line layout props dest)
1143 #:properties ((thickness 1)
1145 "@dots{}documentation@dots{}"
1149 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1150 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1151 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1153 @lilypond[quote,verbatim,ragged-right]
1154 #(define-markup-command (my-draw-line layout props dest)
1156 #:properties ((thickness 1)
1159 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1163 (w (/ line-gap 2.0))
1164 (x (cond ((= dx 0) w)
1166 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1167 (y (* (if (< (* dx dy) 0) 1 -1)
1170 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1171 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1172 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1174 \markup \my-draw-line #'(4 . 3)
1175 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1179 @node Définition d'une nouvelle commande de liste de markups
1180 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1181 @translationof New markup list command definition
1183 @funindex define-markup-list-command
1184 @funindex interpret-markup-list
1186 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1187 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1188 la macro @code{define-markup-command} abordée à la rubrique
1189 @ref{Définition d'une nouvelle commande de markup} à ceci près que cette
1190 dernière renvoie un seul stencil, non une liste de stencils.
1192 La fonction @code{interpret-markup-list}, à l'instar de la fonction
1193 @code{interpret-markup}, permet de convertir une liste de @emph{markups}
1194 en liste de stencils.
1196 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1197 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1198 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1199 par l'argument @code{props}.
1202 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1203 #:properties ((par-indent 2))
1204 (interpret-markup-list layout props
1205 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1208 La version purement Scheme est un peu plus complexe :
1210 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1211 #:properties ((par-indent 2))
1212 (interpret-markup-list layout props
1213 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1217 En dehors des habituels arguments @code{layout} et @code{props}, la
1218 commande de liste de @emph{markups} @code{paragraph} prend en argument
1219 une liste de @emph{markups} appelé @code{args}. Le prédicat des listes
1220 de @emph{markups} est @code{markup-list?}.
1222 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1223 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1224 @code{props}. En cas d'absence, la valeur par défaut sera
1225 de @code{2}. Ensuite est créée une liste de lignes justifiées
1226 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1227 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1228 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1229 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1230 interprétée par la fonction @code{interpret-markup-list}.
1232 Voici comment utiliser cette nouvelle commande de liste de
1233 @emph{markups}@tie{}:
1237 The art of music typography is called \italic @{(plate) engraving.@}
1238 The term derives from the traditional process of music printing.
1239 Just a few decades ago, sheet music was made by cutting and stamping
1240 the music into a zinc or pewter plate in mirror image.
1242 \override-lines #'(par-indent . 4) \paragraph @{
1243 The plate would be inked, the depressions caused by the cutting
1244 and stamping would hold ink. An image was formed by pressing paper
1245 to the plate. The stamping and cutting was completely done by
1252 @node Contextes pour programmeurs
1253 @section Contextes pour programmeurs
1254 @translationof Contexts for programmers
1257 * Évaluation d'un contexte::
1258 * Application d'une fonction à tous les objets de mise en forme::
1262 @node Évaluation d'un contexte
1263 @subsection Évaluation d'un contexte
1264 @translationof Context evaluation
1266 @cindex appel de code durant l'interprétation
1267 @funindex \applyContext
1269 Un contexte peut être modifié, au moment même de son interprétation, par
1270 du code Scheme. La syntaxe consacrée en pareil cas est
1272 \applyContext @var{fonction}
1275 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1276 unique argument : le contexte au sein duquel la commande
1277 @code{\applyContext} est appelée. Les lignes de code qui suivent auront
1278 pour effet d'afficher à l'écran, en cours de compilation, le numéro de
1284 (format #t "\nNous en sommes à la mesure ~a.\n"
1285 (ly:context-property x 'currentBarNumber)))
1289 @node Application d'une fonction à tous les objets de mise en forme
1290 @subsection Application d'une fonction à tous les objets de mise en forme
1291 @translationof Running a function on all layout objects
1293 @cindex appel de code sur des objets de mise en forme
1294 @funindex \applyOutput
1296 La manière la plus souple d'affiner un objet consiste à utiliser la
1297 commande @code{\applyOutput}. Celle-ci va insérer un événement
1298 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1301 \applyOutput @var{Contexte} @var{procédure}
1305 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1307 Lors de l'interprétation de cette commande, la fonction
1308 @code{@var{procédure}} est appelée pout tout objet de rendu appartenant
1309 au contexte @code{@var{Contexte}} à cet instant précis, avec les
1310 arguments suivants :
1312 @item l'objet de rendu en lui-même,
1313 @item le contexte au sein duquel cet objet est créé,
1314 @item et le contexte dans lequel @code{\applyOutput} est effectué.
1317 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1318 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1319 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1320 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1322 Voici une fonction utilisable avec la commande
1323 @code{\applyOutput} : elle @qq{blanchit} la tête des notes se
1324 trouvant sur la ligne médiane ou bien directement à son contact.
1326 @lilypond[quote,verbatim,ragged-right]
1327 #(define (blanker grob grob-origin context)
1328 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1329 (< (abs (ly:grob-property grob 'staff-position)) 2))
1330 (set! (ly:grob-property grob 'transparent) #t)))
1333 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1337 La @var{procédure} sera interprétée au niveau @code{Score}
1338 (partition) ou @code{Staff} dès lors que vous utiliserez l'une des
1342 \applyOutput #'Score #@var{procédure}
1343 \applyOutput #'Staff #@var{procédure}
1347 @node Fonctions de rappel
1348 @section Fonctions de rappel
1349 @translationof Callback functions
1351 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1352 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1356 \override Stem.thickness = #2.0
1359 Une procédure Scheme peut aussi se charger de modifier des
1362 @lilypond[fragment,verbatim,quote,relative=2]
1363 \override Stem.thickness = #(lambda (grob)
1364 (if (= UP (ly:grob-property grob 'direction))
1371 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1372 est nécessaire au processus de mise en forme.
1374 La majeure partie du procédé typographique consiste en la réalisation de
1375 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1376 utilisant particulièrement des rappels, nous mentionnerons
1380 Routine d'impression, construisant le dessin du symbole
1382 Routine effectuant le positionnement horizontal
1384 Routine calculant la largeur d'un objet
1387 La procédure prend un unique argument, en l'occurrence l'objet graphique
1390 Dans le cas où la routine doit faire appel à plusieurs arguments, le
1391 @emph{grob} en cours peut s'insérer à l'aide d'un @emph{grob} enchâssé.
1392 Voici, à titre d'illustration, un réglage pour
1393 @code{AccidentalSuggestion} :
1397 ,(ly:make-simple-closure
1399 ,(ly:make-simple-closure
1400 (list ly:self-alignment-interface::centered-on-x-parent))
1401 ,(ly:make-simple-closure
1402 (list ly:self-alignment-interface::x-aligned-on-self)))))
1406 Ici, aussi bien @code{ly:self-alignment-interface::x-aligned-on-self}
1407 que @code{ly:self-alignment-interface::centered-on-x-parent} font appel
1408 à l'argument @emph{grob}. La fonction @code{+} a pour effet
1409 d'additionner les résultats. L'ensemble est inclus dans un
1410 @code{ly:make-simple-closure} de telle sorte que l'addition s'exécute de
1413 Dans les faits, l'utilisation d'une unique procédure en tant que valeur
1414 d'une propriété revient à écrire
1417 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1421 Le @code{ly:make-simple-closure} intérieur fournit le @emph{grob} en
1422 argument à la procédure @var{proc}, l'extérieur s'assure que le résultat
1423 de la fonction sera bien renvoyé, non pas l'objet @code{simple-closure}.
1425 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1426 @emph{markup} consiste à utiliser la fonction
1427 @code{grob-interpret-markup}, comme ici :
1430 my-callback = #(lambda (grob)
1431 (grob-interpret-markup grob (markup "foo")))
1435 @node Code Scheme intégré
1436 @section Code Scheme intégré
1437 @translationof Inline Scheme code
1439 À REVOIR : depuis la rédaction de cette section, LilyPond en est
1440 arrivé à un point tel que trouver un exemple @emph{simple} où l'on se
1441 retrouve obligé d'en venir à utiliser du code Scheme devient chose
1444 En attendant un remaniement de cette section, faisons comme si nous
1447 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1448 sa syntaxe. Par exemple, le code suivant produit une erreur de syntaxe
1449 (du moins, c'était le cas auparavant).
1452 F = \tweak font-size #-3 -\flageolet
1460 C'est en se servant du langage Scheme que l'on peut résoudre ce
1461 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1462 @ref{Ajout d'articulation à des notes (exemple)}, en
1463 particulier quant à l'emploi de @code{\displayMusic}.
1466 F = #(let ((m (make-music 'ArticulationEvent
1467 'articulation-type "flageolet")))
1468 (set! (ly:music-property m 'tweaks)
1469 (acons 'font-size -3
1470 (ly:music-property m 'tweaks)))
1479 Ici les propriétés @code{tweak} de l'objet flageolet nommé
1480 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
1481 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1482 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1483 @code{acons}), et le résultat de cette opération est renvoyé par
1484 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1485 finale de @samp{m} lui-même.
1488 @node Retouches complexes
1489 @section Retouches complexes
1490 @translationof Difficult tweaks
1492 Certains réglages sont plus délicats que d'autres.
1496 L'un d'entre eux est l'apparence des objets dits @qq{extenseurs}
1497 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1498 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1499 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1500 changement de ligne, ils sont dupliqués au début du ou des systèmes
1501 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1502 héritent toutes les propriétés, y compris les éventuelles commandes
1505 En d'autres termes, une commande @code{\override} affecte toujours les
1506 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1507 partie précédant ou suivant le changement de ligne, il faut intervenir
1508 directement dans le processus de mise en page.
1509 La fonction de rappel @code{after-line-breaking} contient toute
1510 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1511 déterminés, et que des objets graphiques ont été divisés sur des
1512 systèmes différents.
1514 Dans l'exemple suivant, on définit une nouvelle opération nommée
1515 @code{my-callback}. Cette opération
1519 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1521 dans l'affirmative, recherche les différents morceaux de l'objet
1523 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1526 dans l'affirmative, applique un espacement supplémentaire
1527 (@code{extra-offset}).
1530 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1531 de façon à ce que le deuxième morceau d'une liaison divisée soit
1535 @lilypond[quote,verbatim,ragged-right]
1536 #(define (my-callback grob)
1538 ;; l'objet a-t-il été divisé ?
1539 (orig (ly:grob-original grob))
1541 ;; si oui, rechercher les morceaux frères (siblings)
1542 (siblings (if (ly:grob? orig)
1543 (ly:spanner-broken-into orig)
1546 (if (and (>= (length siblings) 2)
1547 (eq? (car (last-pair siblings)) grob))
1548 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1551 \override Tie.after-line-breaking =
1559 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1560 rappel @code{after-line-breaking} devra également appeler celle
1561 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1562 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1563 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1567 Pour des raisons d'ordre technique, certains objets ne peuvent être
1568 modifiés par @code{\override}. Parmi ceux-là, les objets
1569 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1570 @code{\overrideProperty} sert à les modifier, de façon similaire à
1571 @code{\once \override} mais avec une syntaxe différente :
1575 Score.NonMusicalPaperColumn % Nom de l'objet
1576 . line-break-system-details % Nom de la propriété
1577 . next-padding % Nom de la sous-propriété (optionnel)
1581 Notez toutefois que la commande @code{\override} peut tout de même être
1582 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1583 bloc @code{\context}.
1588 @node Interfaces LilyPond Scheme
1589 @chapter Interfaces LilyPond Scheme
1590 @translationof LilyPond Scheme interfaces
1592 Ce chapitre aborde les différents outils fournis par LilyPond à
1593 l'intention des programmeurs en Scheme désireux d'obtenir des
1594 informations à partir et autour des fluxs de musique.
1596 TODO -- figure out what goes in here and how to organize it