1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 958e95822083954cad00e0a598eb9f12ceba67b9
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 * Retouches complexes::
36 @node Blocs de code LilyPond
37 @section Blocs de code LilyPond
38 @translationof LilyPond code blocks
40 @cindex code, blocs LilyPond
41 @cindex LilyPond, bloc de code
47 L'utilisation de Scheme pour créer des expressions musicales peut
48 s'avérer ardue, principalement à cause des imbrications et de la
49 longueur du code Scheme qui en résulte. Dans le cas de tâches
50 simples, on peut toutefois contourner une partie du problème en
51 utilisant des blocs de code LilyPond, ce qui autorise la syntaxe
52 habituelle de LilyPond au sein même de Scheme.
54 Les blocs de code LilyPond ressemblent à
57 #@{ @var{du code LilyPond} #@}
60 En voici un exemple basique :
62 @lilypond[verbatim,quote]
63 ritpp = #(define-event-function () ()
70 Les blocs de code LilyPond peuvent s'utiliser partout où vous pouvez
71 écrire du code Scheme. Le lecteur Scheme est en fait quelque peu adapté
72 pour accepter des blocs de code LilyPond ; il est capable de traiter des
73 expressions Scheme intégrées débutant par @code{$} ou @code{#}.
75 Le lecteur Scheme extrait le bloc de code LilyPond et déclenche un appel
76 à l'analyseur grammatical de LilyPond (le @emph{parser}) qui réalise en
77 temps réel l'interprétation de ce bloc de code LilyPond. Toute
78 expression Scheme imbriquée est exécutée dans l'environnement lexical du
79 bloc de code LilyPond, de telle sorte que vous avez accès aux variables
80 locales et aux paramètres de la fonction au moment même où le bloc de
81 code LilyPond est écrit. Les variables définies dans d'autres modules
82 Scheme, tels ceux contenant les blocs @code{\header} ou @code{\layout},
83 ne sont pas accessibles en tant que variables Scheme (préfixées par
84 un @code{#}) mais en tant que variables LilyPond (préfixées par
87 Toute la musique générée au sein de ce bloc de code voit son
88 @code{origine} établie à cet @emph{emplacement}.
90 Un bloc de code LilyPond peut contenir tout ce que vous pourriez mettre
91 à droite de l'assignation. Par ailleurs, un bloc LilyPond vide
92 correspond à une expression fantôme, et un bloc LilyPond de multiples
93 événements musicaux sera transformé en une expression de musique
97 @node Fonctions Scheme
98 @section Fonctions Scheme
99 @translationof Scheme functions
101 @cindex Scheme, fonctions (syntaxe LilyPond)
103 Les @emph{fonctions Scheme} sont des procédures Scheme chargées de créer
104 des expressions Scheme à partir de code rédigé selon la syntaxe de
105 LilyPond. Elles peuvent être appelées en de nombreux endroits, à l'aide
106 d'un @code{#}, où spécifier une valeur en syntaxe Scheme est autorisé.
107 Bien que Scheme dispose de fonctions en propre, nous nous intéresserons,
108 au fil des paragraphes qui suivent, aux fonctions @emph{syntaxiques},
109 autrement dit des fonctions qui reçoivent des arguments libellés dans la
113 * Définition de fonctions Scheme::
114 * Utilisation de fonctions Scheme::
115 * Fonctions Scheme fantômes::
118 @node Définition de fonctions Scheme
119 @subsection Définition de fonctions Scheme
120 @translationof Scheme function definitions
122 @funindex define-scheme-function
124 D'une manière générale, une fonction Scheme se définit ainsi :
128 #(define-scheme-function
129 (@var{arg1} @var{arg2}@dots{})
130 (@var{type1?} @var{type2?}@dots{})
137 @multitable @columnfractions .33 .66
138 @item @code{@var{argN}}
139 @tab @var{n}-ième argument
141 @item @code{@var{typeN?}}
142 @tab un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
143 devra retourner @code{#t}. Il existe aussi une forme spécifique --
144 @code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
145 argument optionnels. En l'absence d'argument réel au moment de l'appel
146 à la fonction, c'est la valeur par défaut qui lui sera substituée. Les
147 valeurs par défaut sont évaluées dès l'apparition de la définition, y
148 compris dans le cas de blocs de code LilyPond ; vous devrez donc,
149 si ces valeurs par défaut ne peuvent être déterminées que plus tard,
150 mentionner une valeur spéciale que vous reconnaîtrez facilement.
151 Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
152 fournir sa valeur par défaut, celle-ci sera considérée comme
153 étant @code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
154 vérifiées ni au moment de la définition, ni à l'exécution ; il est
155 de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
156 par défaut constituée d'une expression musicale est recopiée dès la
157 définition de @code{origin} à l'emplacement courant du code.
159 @item @code{@var{corps}}
160 @tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
161 servant de valeur de retour de la fonction. Il peut contenir des blocs
162 de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
163 @w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
164 @ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
165 @code{#} permet de référencer des arguments de la fonction -- tel
166 @samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
167 arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
168 Dans le cas où une expression Scheme introduite par @code{#} ne vous
169 permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
170 expression Scheme « immédiate » à l'aide d'un @code{$}, comme
173 Lorsque votre fonction retourne une expression musicale, lui est
174 attribuée la valeur @code{origin}.
178 La recevabilité des arguments est déterminée par un appel effectif au
179 prédicat après que LilyPond les a déjà convertis en expression Scheme.
180 Par voie de conséquence, l'argument peut tout à fait se libeller en
181 syntaxe Scheme -- introduite par un @code{#} ou en tant que résultat
182 d'un appel à une fonction Scheme. Par ailleurs, LilyPond convertira en
183 Scheme un certain nombre de constructions purement LilyPond avant même
184 d'en avoir vérifié le prédicat. C'est notamment le cas de la musique,
185 des @emph{postévénements}, des chaînes simples (avec ou sans
186 guillemets), des nombres, des @emph{markups} et listes de
187 @emph{markups}, ainsi que des blocs @emph{score}, @emph{book},
188 @emph{bookpart}, ou qui définissent un contexte ou un format de sortie.
190 Il existe certaines situations pour lesquelles LilyPond lèvera toute
191 ambiguïté grâce aux fonctions de prédicat : un @samp{-3} est-il un
192 @emph{postévénement} de type doigté ou un nombre négatif ? Un
193 @code{"a" 4} en mode paroles est-il une chaîne suivie d'un nombre ou
194 bien un événement syllabe de durée @code{4} ? LilyPond répondra à ces
195 questions par des interprétations successives du prédicat de l'argument,
196 dans un ordre défini de sorte à minimiser les interprétations erronées
197 et le besoin de lecture en avance.
199 Un prédicat qui accepte par exemple aussi bien une expression musicale
200 qu'une hauteur considèrera @code{c''} comme étant une hauteur plutôt
201 qu'une expression musicale. Les durées ou @emph{postévénements} qui
202 viennent juste après viendront modifier cette interprétation. C'est la
203 raison pour laquelle il vaut mieux éviter des prédicats par trop
204 permissifs tel que @code{Scheme?} lorsque l'application fait plutôt
205 appel à des type d'argument plus spécifiques.
207 Les différents types de prédicat propres à LilyPond sont recensés à
208 l'annexe @ruser{Types de prédicats prédéfinis}.
212 @ruser{Types de prédicats prédéfinis}.
214 Fichiers d'initialisation :
215 @file{lily/music-scheme.cc},
220 @node Utilisation de fonctions Scheme
221 @subsection Utilisation de fonctions Scheme
222 @translationof Scheme function usage
224 Vous pouvez appeler une fonction Scheme pratiquement partout où une
225 expression Scheme derrière un @code{#} peut prendre place. Vous appelez
226 une fonction Scheme en faisant précéder son nom d'un @code{\}, et en le
227 faisant suivre de ses arguments. Lorsqu'un prédicat d'argument
228 optionnel ne correspond pas à un argument, LilyPond l'ignore ainsi que
229 tous les arguments optionnels qui suivent, les remplaçant par leur
230 valeur par défaut, et « sauvegarde » en tant que prochain argument
231 obligatoire l'argument qui ne correspondait pas. Dans la mesure où
232 l'argument sauvegardé doit servir, les argument optionnels ne sont en
233 fait pas considérés comme optionnels, sauf à être suivis d'un argument
236 Une exception cependant à cette règle : le fait de donner un
237 @code{\default} en tant qu'argument optionnel aura pour résultat que cet
238 argument et tous les autres arguments optionnels qui suivent seront
239 ignorés et remplacés par leur valeur par défaut. Il en va de même
240 lorsqu'aucun argument obligatoire ne suit, du fait que @code{\default}
241 ne requiert pas de sauvegarde. C'est d'ailleurs ainsi que fonctionnent
242 les commandes @code{mark} et @code{key}, qui retrouvent leur
243 comportement par défaut lorsque vous les faites suivre d'un
246 En plus de là où une expression Scheme est requise, il y a quelques
247 endroits où des expressions @code{#} sont acceptées et évaluées
248 uniquement pour leurs effets annexes. Il s'agit, dans la plupart des
249 cas, d'endroits où une affectation serait tout à fait envisageable.
251 Dans la mesure où il n'est pas bon de renvoyer une valeur qui pourrait
252 être mal interprétée dans certains contextes, nous vous enjoignons à
253 utiliser des fonctions Scheme normales uniquement dans les cas où vous
254 renvoyez toujours une valeur utile, et une fonction fantôme -- voir
255 @ref{Fonctions Scheme fantômes} -- dans le cas contraire.
258 @node Fonctions Scheme fantômes
259 @subsection Fonctions Scheme fantômes
260 @translationof Void scheme functions
262 @cindex @emph{void}, fonction
263 @cindex fantôme, fonction
265 @funindex define-void-function
268 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
269 pour renvoyer une valeur. Certains langages de programmation, tels
270 le C et Scheme, utilisent des fonctions dans les deux cas et se
271 débarrassent tout bonnement de la valeur renvoyée ; en règle
272 générale, il suffit que l'expression fasse office de déclaration, et
273 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
274 la plupart des compilateurs C actuels déclenchent un avertissement si
275 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
276 nombreuses fonctions réalisant une action, les standards Scheme
277 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
278 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
279 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
280 lorsqu'on utilise @code{set!} directement sur une variable -- mais
281 malheureusement pas toujours.
283 Une fonction LilyPond définie à l'aide de la clause
284 @code{define-void-function} vous apporte l'assurance que c'est cette
285 valeur spéciale -- la seule valeur qui satisfasse au prédicat
286 @code{void?} -- qui sera retournée.
290 #(define-void-function
293 (ly:set-option 'point-and-click #f))
295 \noPointAndClick % desactive le "pointer-cliquer"
298 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
299 expression pour ses effets annexes sans interprétation d'une quelconque
303 \void #(hashq-set! une-table une-clé une-valeur)
306 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
307 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
308 opérationnel dans le cadre de fonctions musicales telles que
309 @code{\displayMusic}.
312 @node Fonctions musicales
313 @section Fonctions musicales
314 @translationof Music functions
316 @cindex musicale, fonction
318 Les @emph{fonctions musicales} sont des procédures Scheme capables de
319 créer automatiquement des expressions musicales ; elles permettent
320 de grandement simplifier un fichier source.
323 * Définition de fonctions musicales::
324 * Utilisation de fonctions musicales::
325 * Fonctions de substitution simple::
326 * Fonctions de substitution intermédiaires::
327 * De l'usage des mathématiques dans les fonctions::
328 * Fonctions dépourvues d'argument::
329 * Fonctions musicales fantômes::
333 @node Définition de fonctions musicales
334 @subsection Définition de fonctions musicales
335 @translationof Music function definitions
337 @cindex fonction musicale, définition
339 @funindex define-music-function
341 Une fonction musicale se définit ainsi :
345 #(define-music-function
346 (@var{arg1} @var{arg2}@dots{})
347 (@var{type1?} @var{type2?}@dots{})
352 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
353 Scheme}. La plupart du temps, le @var{corps} sera constitué d'un
354 @ref{Blocs de code LilyPond, bloc de code Lilypond}.
356 Les différents types des prédicat sont recensés à l'annexe
357 @ruser{Types de prédicats prédéfinis}.
361 @ruser{Types de prédicats prédéfinis}.
363 Fichiers d'initialisation :
364 @file{lily/music-scheme.cc},
369 @node Utilisation de fonctions musicales
370 @subsection Utilisation de fonctions musicales
371 @translationof Music function usage
373 Une « fonction musicale » doit impérativement renvoyer une expression
374 répondant au prédicat @code{ly:music?}. Ceci a pour conséquence
375 d'autoriser l'appel à une fonction musicale en tant qu'argument de type
376 @code{ly:music?} dans le cadre de l'appel à une autre fonction musicale.
378 Certaines restrictions s'appliqueront selon le contexte où une fonction
379 musicale est utilisée, de telle sorte que l'analyse syntaxique soit sans
384 Dans une expression musicale de haut niveau, aucun postévénement n'est
388 Lorsqu'une fonction musicale -- contrairement à une fonction
389 événementielle -- renvoie une expression de type postévénement, LilyPond
390 requiert son introduction par un indicateur de positionnement -- à
391 savoir @code{-}, @code{^} ou @code{_} -- de telle sorte que le
392 postévénement produit par l'appel à cette fonction s'intègre
393 correctement dans l'expression environnante.
396 En tant que partie d'un accord, l'expression musicale renvoyée doit
397 être du type @code{rhythmic-event}, et plus particulièrement un
402 Des fonctions « polymorphes » telles que @code{\tweak} peuvent
403 s'appliquer aux postévénements, constituants d'accord et expressions de
407 @node Fonctions de substitution simple
408 @subsection Fonctions de substitution simple
409 @translationof Simple substitution functions
411 Une fonction de substitution simple renvoie une expression musicale
412 écrite au format LilyPond et contient des arguments au format de
413 l'expression résultante. Vous en trouverez une description détaillée à
414 la rubrique @ruser{Exemples de fonction de substitution}.
417 @node Fonctions de substitution intermédiaires
418 @subsection Fonctions de substitution intermédiaires
419 @translationof Intermediate substitution functions
421 Une fonction de substitution intermédiaire est une fonction dont
422 l'expression musicale résultante mélangera du code Scheme au code
425 Certaines commandes @code{\override} nécessitent un argument
426 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
427 cell} en Scheme -- que l'on pourrait traduire par « construction de
430 Cette paire peut se mentionner directement dans la fonction musicale à
431 l'aide d'une variable @code{pair?} :
435 #(define-music-function
439 \once \override Beam.positions = #beg-end
443 \manualBeam #'(3 . 6) c8 d e f
447 Autre manière de procéder, les nombres formant la paire sont transmis
448 comme arguments séparés ; le code Scheme chargé de créer la paire
449 pourra alors être inclus dans l'expression musicale :
451 @lilypond[quote,verbatim,ragged-right]
453 #(define-music-function
457 \once \override Beam.positions = #(cons beg end)
461 \manualBeam #3 #6 c8 d e f
466 @cindex temporaire, dérogation (override)
467 @cindex dérogation temporaire (override)
468 @cindex propriétés, retour à la valeur précédente
470 L'entretien des propriétés peut se voir comme un empilement par
471 propriété par objet par contexte. Les fonctions musicales peuvent
472 nécessiter des dérogations pour une ou plusieurs propriétés pour la
473 durée de la fonction, puis de revenir aux valeurs précédentes avant de
474 quitter. Néanmoins, une dérogation normale va retirer de la pile -- ou
475 dépiler -- et supprimer le sommet de la pile de la propriété avant
476 d'y ajouter quoi que ce soit -- ou empiler -- ; la valeur précédente de
477 la propriété est de fait perdue. Lorsque la valeur antérieure doit être
478 préservée, l'instruction @code{\override} devra être préfixée d'un
479 @code{\temporary}, comme ceci :
482 \temporary \override @dots{}
485 L'utilisation d'un @code{\temporary} a pour effet d'effacer la propriété
486 @code{pop-first} (@emph{commence par dépiler} normalement activée) de la
487 dérogation ; la valeur antérieure ne sera alors pas supprimée de la pile
488 de la propriété avant d'y empiler la nouvelle valeur. Lorsqu'un
489 @code{\revert} viendra par la suite supprimer la valeur dérogatoire
490 temporaire, réapparaitra la valeur antérieure.
492 En d'autres termes, un @code{\revert} qui suit un @code{\temporary
493 \override} pour la même propriété n'apporte rien. Ce principe est aussi
494 valable pour un couple @code{\temporary} et @code{\undo} sur la même
495 musique contenant des dérogations.
497 Voici un exemple de fonction musicale utilisant cette fonctionnalité.
498 La présence du @code{\temporary} permet de s'assurer qu'en sortant de la
499 fonction, les propriétés @code{cross-staff} et @code{style} retrouveront
500 les valeurs qu'elles avaient avant que ne soit appelée la fonction
501 @code{crossStaff}. En l'absence de @code{\temporary}, ces propriétés
502 auraient retrouvé leurs valeurs par défaut à la sortie de la fonction.
506 #(define-music-function (notes) (ly:music?)
507 (_i "Create cross-staff stems")
509 \temporary \override Stem.cross-staff = #cross-staff-connect
510 \temporary \override Flag.style = #'no-flag
512 \revert Stem.cross-staff
518 @node De l'usage des mathématiques dans les fonctions
519 @subsection De l'usage des mathématiques dans les fonctions
520 @translationof Mathematics in functions
522 Une fonction musicale peut requérir, en plus d'une simple substitution,
523 une part de programmation en Scheme.
525 @lilypond[quote,verbatim,ragged-right]
527 #(define-music-function
531 \override Stem.length = #(* 7.0 mag)
532 \override NoteHead.font-size =
533 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
538 \revert NoteHead.font-size
543 \AltOn #1.5 c c \AltOff c2
548 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
549 s'applique à une expression musicale :
551 @lilypond[quote,verbatim,ragged-right]
553 #(define-music-function
557 \override Stem.length = #(* 7.0 mag)
558 \override NoteHead.font-size =
559 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
562 \revert NoteHead.font-size
566 c'2 \withAlt #0.5 { c4 c }
567 \withAlt #1.5 { c c } c2
572 @node Fonctions dépourvues d'argument
573 @subsection Fonctions dépourvues d'argument
574 @translationof Functions without arguments
576 Dans la plupart des cas, une fonction dépourvue d'argument devrait
577 être créée à l'aide d'une variable :
580 dolce = \markup@{ \italic \bold dolce @}
583 Il peut, dans certains cas particuliers, s'avérer utile de créer une
584 fonction sans argument comme ici,
588 #(define-music-function
591 (if (eq? #t (ly:get-option 'display-bar-numbers))
592 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
597 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
598 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
599 en respectant la syntaxe
602 lilypond -d display-bar-numbers MONFICHIER.ly
606 @node Fonctions musicales fantômes
607 @subsection Fonctions musicales fantômes
608 @translationof Void music functions
610 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
611 une fonction musicale peut n'être exécutée que dans le but d'en retenir
612 les effets annexes ; vous devrez alors utiliser une procédure
613 @code{define-void-function}. Il peut cependant arriver que vous ayez
614 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
615 l'exemple de la rubrique précédente) une expression musicale.
616 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
617 expression musicale @code{void}.
620 @node Fonctions événementielles
621 @section Fonctions événementielles
622 @translationof Event functions
624 @funindex define-event-function
625 @cindex événementielle, fonction
627 L'utilisation d'une fonction musicale pour placer un événement requiert
628 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
629 à la syntaxe de la construction à remplacer. C'est par exemple le cas
630 lorsque vous voulez écrire une commande de nuance, instruction qui
631 ne comporte habituellement pas d'indicateur de positionnement, comme
632 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
635 @lilypond[quote,verbatim,ragged-right]
636 dyn=#(define-event-function (arg) (markup?)
637 (make-dynamic-script arg))
638 \relative { c'\dyn pfsss }
641 Vous pourriez obtenir le même résultat avec une fonction musicale, à
642 ceci près que chaque appel à la fonction devra être précédé d'un
643 indicateur de positionnement, comme @code{c-\dyn pfsss}.
646 @node Fonctions pour markups
647 @section Fonctions pour @emph{markups}
648 @translationof Markup functions
650 Les @emph{markups} sont implémentés au travers de fonctions Scheme
651 spécifiques qui produisent des objets @code{Stencil} comprenant un
652 certain nombre d'arguments.
655 * Construction d'un markup en Scheme::
656 * Fonctionnement interne des markups::
657 * Définition d'une nouvelle commande de markup::
658 * Définition d'une nouvelle commande de liste de markups::
662 @node Construction d'un markup en Scheme
663 @subsection Construction d'un @emph{markup} en Scheme
664 @translationof Markup construction in Scheme
666 @cindex définition d'une commande markup
668 @funindex \displayScheme
670 Les expressions @emph{markup} sont représentées en Scheme de manière
671 interne par la macro @code{markup} :
674 (markup @var{expression})
677 La commande @code{\displayScheme} permet d'obtenir la représentation en
678 Scheme d'une expression @emph{markup} :
684 \line @{ \bold \italic "hello" \raise #0.4 "world" @}
685 \larger \line @{ foo bar baz @}
691 Compiler ce code renverra en console les lignes suivantes :
698 (#:bold (#:italic "hello") #:raise 0.4 "world")
701 (#:simple "foo" #:simple "bar" #:simple "baz")))))
704 L'impression du @emph{markup} sera suspendue dès lors qu'apparaîtra un
705 @w{@samp{\void \displayScheme @var{markup}}}. Tout comme pour la
706 commande @code{\displayMusic}, le résultat de @code{\displayScheme} peut
707 être sauvegardé dans un fichier séparé. Voir à ce sujet
708 @ref{Affichage d'expressions musicales}.
711 Vous pouvez constater les principales règles de traduction entre les
712 syntaxes respectives de LilyPond et de Scheme en matière de
713 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
714 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
715 utiliser la macro @code{markup} en Scheme exclusivement.
718 @multitable @columnfractions .3 .3
719 @item @b{LilyPond} @tab @b{Scheme}
720 @item @code{\markup markup1} @tab @code{(markup markup1)}
721 @item @code{\markup @{ markup1 markup2@dots{} @}} @tab
722 @code{(markup markup1 markup2@dots{} )}
723 @item @code{\commande-markup} @tab @code{#:commande-markup}
724 @item @code{\variable} @tab @code{variable}
725 @item @code{\center-column @{ @dots{} @}} @tab
726 @code{#:center-column ( @dots{} )}
727 @item @code{chaîne} @tab @code{"chaîne"}
728 @item @code{#argument-scheme} @tab @code{argument-scheme}
732 L'intégralité du langage Scheme est accessible à l'intérieur même de la
733 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
734 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
735 particulièrement pratique lorsque vous créez votre propre commande de
736 @emph{markup} -- voir
737 @ref{Définition d'une nouvelle commande de markup}.
740 L'argument @var{markup-list} des commandes @code{#:line},
741 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
742 résultat de l'appel à une fonction.
745 (markup #:line (fonction-qui-retourne-des-markups))
749 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
750 @code{make-line-markup}, @code{make-center-markup} ou
751 @code{make-column-markup} :
754 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
758 @node Fonctionnement interne des markups
759 @subsection Fonctionnement interne des @emph{markups}
760 @translationof How markups work internally
762 Dans un @emph{markup} tel que
765 \raise #0.5 "text example"
769 @code{\raise} représente en fait la fonction @code{raise-markup}.
770 L'expression @emph{markup} est enregistrée sous la forme
773 (list raise-markup 0.5 (list simple-markup "text example"))
776 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
777 la fonction @code{raise-markup} est appelée ainsi :
782 @var{liste des alists de propriété}
784 @var{le @emph{markup} "text example"})
787 La fonction @code{raise-markup} commence par créer le stencil pour la
788 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
789 portée. Il s'agit là d'un exemple relativement simple, et nous en
790 aborderons de plus complexes au fil des paragraphes suivants ;
791 d'autres exemples se trouvent directement dans le fichier
792 @file{scm/define-markup-commands.scm}.
795 @node Définition d'une nouvelle commande de markup
796 @subsection Définition d'une nouvelle commande de @emph{markup}
797 @translationof New markup command definition
799 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
800 commande de @emph{markup}.
803 * Syntaxe d'une commande markup::
804 * Attribution de propriétés::
806 * Adaptation d'une commande incorporée::
810 @node Syntaxe d'une commande markup
811 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
812 @translationof Markup command definition syntax
814 Une commande de @emph{markup} personnalisée se définit à l'aide de la
815 macro Scheme @code{define-markup-command}, placée en tête de fichier.
818 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2}@dots{})
819 (@var{arg1-type?} @var{arg2-type?}@dots{})
820 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
822 @dots{}corps de la commande@dots{})
825 Quelques commentaires sur les arguments :
828 @item @var{nom-commande}
829 le nom que vous attribuez à votre commande de @emph{markup}.
831 la définition du « layout » -- son formatage.
833 une liste de listes associatives, comprenant toutes les propriétés actives.
835 le @var{ième} argument de la commande.
836 @item @var{argi-type?}
837 un type de prédicat pour le @var{ième} argument.
840 Si la commande utilise des propriétés à partir des arguments
841 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
842 différentes propriétés ainsi que leur valeur par défaut.
844 Les arguments se distinguent selon leur type :
846 @item un @emph{markup}, correspondant au type de prédicat
848 @item une liste de @emph{markups}, correspondant au type de prédicat
849 @code{markup-list?} ;
850 @item tout autre objet Scheme, correspondant au types de prédicat tels
851 que @code{list?}, @code{number?}, @code{boolean?}, etc.
854 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
855 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
856 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
857 ceci de particulier qu'elles peuvent s'appliquer à des listes de
858 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
859 tous les éléments de la liste originelle se verront appliquer cette
860 fonction @emph{markup} avec ses arguments de tête.
862 La réplication des arguments de tête dans le but d'appliquer une
863 fonction @emph{markup} à une liste de markups est économique,
864 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
865 ainsi d'éventuelles pertes de performance en utilisant des arguments
866 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
867 le dernier argument est un @emph{markup}.
870 @cindex macro de markup
872 @funindex interpret-markup
874 Les commandes de @emph{markup} ont un cycle de vie relativement
875 complexe. Le corps de la définition d'une commande de @emph{markup} est
876 chargé de convertir les arguments de la commande en expression stencil
877 qui sera alors renvoyée. Bien souvent, ceci s'accomplit par un appel à
878 la fonction @code{interpret-markup}, en lui passant les arguments
879 @var{layout} et @var{props}. Ces arguments ne seront en principe connus
880 que bien plus tardivement dans le processus typographique. Lors de
881 l'expansion d'une expression LilyPond @code{\markup} ou d'une macro
882 Scheme @code{markup}, les expressions @emph{markup} auront déjà vu leurs
883 composants assemblés en expressions @emph{markup}. L'évaluation et le
884 contrôle du type des arguments à une commande de @emph{markup}
885 n'interviennent qu'au moment de l'interprétation de @code{\markup} ou
888 Seule l'application de @code{interpret-markup} sur une expression
889 @emph{markup} réalisera effectivement la conversion des expressions
890 @emph{markup} en stencil, au travers de l'exécution du corps des
891 fonctions @emph{markup}.
894 @node Attribution de propriétés
895 @unnumberedsubsubsec Attribution de propriétés
896 @translationof On properties
898 Les arguments @code{layout} et @code{props} d'une commande de
899 @emph{markup} fournissent un contexte à l'interprétation du
900 @emph{markup} : taille de fonte, longueur de ligne, etc.
902 L'argument @code{layout} permet d'accéder aux propriétés définies dans
903 les blocs @code{\paper}, grâce à la fonction
904 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
905 identique à celle de la partition, est lue au travers de
908 (ly:output-def-lookup layout 'line-width)
911 L'argument @code{props} rend certaines propriétés accessibles aux
912 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
913 d'un @emph{markup} de titre d'ouvrage : toutes les variables
914 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
915 @code{props}, de telle sorte que le @emph{markup} de titrage de
916 l'ouvrage pourra accéder aux différents champs titre, compositeur, etc.
917 Ceci permet aussi de configurer le comportement d'une commande de
918 @emph{markup} : la taille des fontes, par exemple, est lue à
919 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
920 La fonction appelant une commande de @emph{markup} peut altérer la
921 valeur de la propriété taille des fontes et donc en modifier le
922 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
923 @code{define-markup-command}, permet de spécifier les propriétés devant
924 être lues parmi les arguments @code{props}.
926 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
927 commande de @emph{markup}, accéder aux différentes propriétés et les
931 @node Exemple commenté
932 @unnumberedsubsubsec Exemple commenté
933 @translationof A complete example
935 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
938 Commençons par construire quelque chose d'approximatif à l'aide d'un
939 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
940 indique la commande @code{\box}, qui semble ici appropriée.
942 @lilypond[quote,verbatim,ragged-right]
943 \markup \box \box HELLO
946 Dans un souci d'esthétique, nous aimerions que le texte et les
947 encadrements ne soient pas autant accolés. Selon la documentation de
948 @code{\box}, cette commande utilise la propriété @code{box-padding},
949 fixée par défaut à 0,2. Cette même documentation nous indique
950 aussi comment la modifier :
952 @lilypond[quote,verbatim,ragged-right]
953 \markup \box \override #'(box-padding . 0.6) \box A
956 L'espacement des deux liserés est cependant toujours trop réduit ;
957 modifions le à son tour :
959 @lilypond[quote,verbatim,ragged-right]
960 \markup \override #'(box-padding . 0.4) \box
961 \override #'(box-padding . 0.6) \box A
964 Vous conviendrez que recopier une telle définition de @emph{markup}
965 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
966 @emph{markup} @code{double-box} qui prendra un seul argument -- le
967 texte. Cette commande se chargera de dessiner les encadrements, en
968 tenant compte des espacements.
971 #(define-markup-command (double-box layout props text) (markup?)
972 "Dessine un double encadrement autour du texte."
973 (interpret-markup layout props
974 #@{\markup \override #'(box-padding . 0.4) \box
975 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
978 ou bien son équivalent
981 #(define-markup-command (double-box layout props text) (markup?)
982 "Dessine un double encadrement autour du texte."
983 (interpret-markup layout props
984 (markup #:override '(box-padding . 0.4) #:box
985 #:override '(box-padding . 0.6) #:box text)))
988 @code{text} est le nom de l'argument de notre commande, et
989 @code{markup?} son type -- l'argument sera identifié comme étant un
990 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
991 plupart des commandes de @emph{markup}, construira un stencil à partir
992 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
993 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
994 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
995 transformation d'une expression @code{\markup} en expression Scheme est
998 Notre commande personnalisée s'utilise ainsi :
1001 \markup \double-box A
1004 Il serait intéressant de rendre cette commande @code{double-box} plus
1005 souple : les valeurs de @code{box-padding} sont figées et ne
1006 peuvent être modifiées à l'envie. Pareillement, il serait bien de
1007 distinguer l'espacement entre les encadrements de l'espacement entre le
1008 texte et ses encadrements. Nous allons donc introduire une propriété
1009 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
1010 de gérer l'espacement des encadrements ; @code{box-padding} ne
1011 servira alors que pour l'espacement intérieur. Voici le code adapté à
1015 #(define-markup-command (double-box layout props text) (markup?)
1016 #:properties ((inter-box-padding 0.4)
1018 "Dessine un double encadrement autour du texte."
1019 (interpret-markup layout props
1020 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
1021 \override #`(box-padding . ,box-padding) \box
1025 Ainsi que son équivalent à partir de la macro @emph{markup} :
1028 #(define-markup-command (double-box layout props text) (markup?)
1029 #:properties ((inter-box-padding 0.4)
1031 "Dessine un double encadrement autour du texte."
1032 (interpret-markup layout props
1033 (markup #:override `(box-padding . ,inter-box-padding) #:box
1034 #:override `(box-padding . ,box-padding) #:box text)))
1037 C'est ici le mot-clé @code{#:properties} qui permet de lire les
1038 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
1039 l'argumenet @code{props} ; on leur a d'ailleurs fourni des valeurs
1040 par défaut au cas où elles ne seraient pas définies.
1042 Ces valeurs permettront alors d'adapter les propriétés de
1043 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
1044 aurez remarqué, dans l'argument @code{\override}, la présence de
1045 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
1046 permettent d'insérer une valeur variable au sein d'une expression
1049 Notre commande est maintenant prête à servir dans un @emph{markup}, et
1050 les encadrements sont repositionnables.
1052 @lilypond[quote,verbatim,ragged-right]
1053 #(define-markup-command (double-box layout props text) (markup?)
1054 #:properties ((inter-box-padding 0.4)
1056 "Draw a double box around text."
1057 (interpret-markup layout props
1058 #{\markup \override #`(box-padding . ,inter-box-padding) \box
1059 \override #`(box-padding . ,box-padding) \box
1062 \markup \double-box A
1063 \markup \override #'(inter-box-padding . 0.8) \double-box A
1064 \markup \override #'(box-padding . 1.0) \double-box A
1068 @node Adaptation d'une commande incorporée
1069 @unnumberedsubsubsec Adaptation d'une commande incorporée
1070 @translationof Adapting builtin commands
1072 Le meilleur moyen de construire ses propres commandes de @emph{markup}
1073 consiste à prendre exemple sur les commandes déjà incorporées. La
1074 plupart des commandes de @emph{markup} fournies avec LilyPond sont
1075 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
1077 Nous pourrions, par exemple, envisager d'adapter la commande
1078 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
1079 est définie la commande @code{\draw-line}, expurgée de sa
1083 (define-markup-command (draw-line layout props dest)
1086 #:properties ((thickness 1))
1087 "@dots{}documentation@dots{}"
1088 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1092 (make-line-stencil th 0 0 x y)))
1095 Avant de définir notre propre commande basée sur l'une de celles
1096 fournies par LilyPond, commençons par en recopier la définition, puis
1097 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
1098 supprimé sans risque ; il ne sert que lors de la génération de la
1099 documentation et n'est d'aucune utilité pour une commande personnalisée.
1102 (define-markup-command (draw-double-line layout props dest)
1104 #:properties ((thickness 1))
1105 "@dots{}documentation@dots{}"
1106 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1110 (make-line-stencil th 0 0 x y)))
1113 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
1114 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
1115 par défaut de 6 dixièmes :
1118 (define-markup-command (draw-double-line layout props dest)
1120 #:properties ((thickness 1)
1122 "@dots{}documentation@dots{}"
1126 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1127 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1128 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1130 @lilypond[quote,verbatim,ragged-right]
1131 #(define-markup-command (my-draw-line layout props dest)
1133 #:properties ((thickness 1)
1136 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1140 (w (/ line-gap 2.0))
1141 (x (cond ((= dx 0) w)
1143 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1144 (y (* (if (< (* dx dy) 0) 1 -1)
1147 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1148 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1149 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1151 \markup \my-draw-line #'(4 . 3)
1152 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1156 @node Définition d'une nouvelle commande de liste de markups
1157 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1158 @translationof New markup list command definition
1160 @cindex liste de markup, définition de commande
1161 @funindex define-markup-list-command
1162 @funindex interpret-markup-list
1164 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1165 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1166 la macro @code{define-markup-command} abordée à la rubrique
1167 @ref{Définition d'une nouvelle commande de markup}, à ceci près que
1168 cette dernière renvoie un seul stencil, non une liste de stencils.
1170 La fonction @code{interpret-markup-list}, à l'instar de la fonction
1171 @code{interpret-markup}, permet de convertir une liste de @emph{markups}
1172 en liste de stencils.
1174 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1175 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1176 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1177 par l'argument @code{props}.
1180 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1181 #:properties ((par-indent 2))
1182 (interpret-markup-list layout props
1183 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1186 La version purement Scheme est un peu plus complexe :
1188 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1189 #:properties ((par-indent 2))
1190 (interpret-markup-list layout props
1191 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1195 En dehors des habituels arguments @code{layout} et @code{props}, la
1196 commande de liste de @emph{markups} @code{paragraph} prend en argument
1197 une liste de @emph{markups} appelée @code{args}. Le prédicat des listes
1198 de @emph{markups} est @code{markup-list?}.
1200 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1201 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1202 @code{props}. En cas d'absence, la valeur par défaut sera
1203 de @code{2}. Ensuite est créée une liste de lignes justifiées
1204 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1205 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1206 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1207 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1208 interprétée par la fonction @code{interpret-markup-list}.
1210 Voici comment utiliser cette nouvelle commande de liste de
1216 The art of music typography is called \italic @{(plate) engraving.@}
1217 The term derives from the traditional process of music printing.
1218 Just a few decades ago, sheet music was made by cutting and stamping
1219 the music into a zinc or pewter plate in mirror image.
1221 \override-lines #'(par-indent . 4) \paragraph @{
1222 The plate would be inked, the depressions caused by the cutting
1223 and stamping would hold ink. An image was formed by pressing paper
1224 to the plate. The stamping and cutting was completely done by
1231 @node Contextes pour programmeurs
1232 @section Contextes pour programmeurs
1233 @translationof Contexts for programmers
1236 * Évaluation d'un contexte::
1237 * Application d'une fonction à tous les objets de mise en forme::
1241 @node Évaluation d'un contexte
1242 @subsection Évaluation d'un contexte
1243 @translationof Context evaluation
1245 @cindex appel de code durant l'interprétation
1246 @funindex \applyContext
1247 @funindex make-apply-context
1248 @funindex ly:context-property
1249 @funindex ly:context-set-property!
1250 @funindex ly:context-grob-definition
1251 @funindex ly:assoc-get
1252 @funindex ly:context-pushpop-property
1254 Un contexte peut être modifié, au moment même de son interprétation, par
1255 du code Scheme. La syntaxe consacrée au sein d'un bloc LilyPond est
1258 \applyContext @var{fonction}
1262 et, dans le cadre d'un code Scheme :
1265 (make-apply-context @var{fonction})
1268 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1269 unique argument : le contexte au sein duquel la commande
1270 @code{\applyContext} est appelée. Cette fonction peut accéder aussi
1271 bien aux propriétés de @emph{grob} (y compris modifiées par
1272 @code{\override} ou @code{\set}) qu'aux propriétés de contexte. Toute
1273 action entreprise par la fonction et qui dépendrait de l'état du
1274 contexte sera limitée à l'état de ce contexte @b{au moment de l'appel à
1275 la fonction}. Par ailleurs, les adaptations résultant d'un appel à
1276 @code{\applyContext} seront effectives jusqu'à ce qu'elles soient à
1277 nouveau directement modifiées ou bien annulées, quand bien même les
1278 conditions initiales dont elles dépendent auraient changé.
1280 Voici quelques fonctions Scheme utiles avec @code{\applyContext} :
1283 @item ly:context-property
1284 recherche la valeur d'une propriété de contexte,
1286 @item ly:context-set-property!
1287 détermine une propriété de contexte,
1289 @item ly:context-grob-definition
1291 recherche la valeur d'une propriété de @emph{grob},
1293 @item ly:context-pushpop-property
1294 réalise un @code{\temporary \override} ou un @code{\revert} sur une
1295 propriété de @emph{grob}.
1298 L'exemple suivant recherche la valeur en cours de @code{fontSize} puis
1301 @lilypond[quote,verbatim]
1305 (let ((fontSize (ly:context-property context 'fontSize)))
1306 (ly:context-set-property! context 'fontSize (+ fontSize 6))))
1316 L'exemple suivant recherche la couleur des objets @code{NoteHead},
1317 @code{Stem} et @code{Beam}, puis diminue pour chacun d'eux le degré de
1320 @lilypond[quote,verbatim]
1324 (define (desaturate-grob grob)
1325 (let* ((grob-def (ly:context-grob-definition context grob))
1326 (color (ly:assoc-get 'color grob-def black))
1327 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
1328 (ly:context-pushpop-property context grob 'color new-color)))
1329 (for-each desaturate-grob '(NoteHead Stem Beam)))
1333 g'8[ g] \desaturate g[ g] \desaturate g[ g]
1334 \override NoteHead.color = #darkred
1335 \override Stem.color = #darkred
1336 \override Beam.color = #darkred
1337 g[ g] \desaturate g[ g] \desaturate g[ g]
1341 Ceci pourrait tout à fait s'implémenter sous la forme d'une fonction
1342 musicale, afin d'en réduire les effets à un seul bloc de musique. Notez
1343 comment @code{ly:context-pushpop-property} est utilisé à la fois pour un
1344 @code{\temporary \override} et pour un @code{\revert} :
1346 @lilypond[quote,verbatim]
1348 #(define-music-function
1353 (define (desaturate-grob grob)
1354 (let* ((grob-def (ly:context-grob-definition context grob))
1355 (color (ly:assoc-get 'color grob-def black))
1356 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
1357 (ly:context-pushpop-property context grob 'color new-color)))
1358 (for-each desaturate-grob '(NoteHead Stem Beam)))
1362 (define (revert-color grob)
1363 (ly:context-pushpop-property context grob 'color))
1364 (for-each revert-color '(NoteHead Stem Beam)))
1368 \override NoteHead.color = #darkblue
1369 \override Stem.color = #darkblue
1370 \override Beam.color = #darkblue
1372 \desaturate { d c b a }
1378 @node Application d'une fonction à tous les objets de mise en forme
1379 @subsection Application d'une fonction à tous les objets de mise en forme
1380 @translationof Running a function on all layout objects
1382 @cindex appel de code sur des objets de mise en forme
1383 @cindex objets de mise en forme, appel de code
1384 @funindex \applyOutput
1386 La manière la plus souple d'affiner un objet consiste à utiliser la
1387 commande @code{\applyOutput}. Celle-ci va insérer un événement
1388 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1391 \applyOutput @var{Contexte} @var{procédure}
1395 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1397 Lors de l'interprétation de cette commande, la fonction
1398 @code{@var{procédure}} est appelée pout tout objet de rendu appartenant
1399 au contexte @code{@var{Contexte}} à cet instant précis, avec les
1400 arguments suivants :
1402 @item l'objet de rendu en lui-même,
1403 @item le contexte au sein duquel cet objet est créé,
1404 @item le contexte dans lequel @code{\applyOutput} est effectué.
1407 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1408 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1409 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1410 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1412 Voici une fonction utilisable avec la commande
1413 @code{\applyOutput} : elle « blanchit » la tête des notes se trouvant
1414 sur la ligne médiane ou bien directement à son contact.
1416 @lilypond[quote,verbatim,ragged-right]
1417 #(define (blanker grob grob-origin context)
1418 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1419 (< (abs (ly:grob-property grob 'staff-position)) 2))
1420 (set! (ly:grob-property grob 'transparent) #t)))
1423 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1427 La @var{procédure} sera interprétée au niveau @code{Score}
1428 (partition) ou @code{Staff} (portée) dès lors que vous utiliserez l'une
1432 \applyOutput #'Score #@var{procédure}
1433 \applyOutput #'Staff #@var{procédure}
1437 @node Fonctions de rappel
1438 @section Fonctions de rappel
1439 @translationof Callback functions
1441 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1442 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1446 \override Stem.thickness = #2.0
1449 Une procédure Scheme peut aussi se charger de modifier des propriétés :
1451 @lilypond[fragment,verbatim,quote,relative=2]
1452 \override Stem.thickness = #(lambda (grob)
1453 (if (= UP (ly:grob-property grob 'direction))
1460 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1461 est nécessaire au processus de mise en forme.
1463 La majeure partie du procédé typographique consiste en la réalisation de
1464 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1465 utilisant particulièrement des rappels, nous mentionnerons
1469 Routine d'impression, construisant le dessin du symbole
1471 Routine effectuant le positionnement horizontal
1473 Routine calculant la largeur d'un objet
1476 La procédure prend un unique argument, en l'occurrence l'objet graphique
1479 Cette procédure, grâce à un appel à la fonction de rappel dévolue à
1480 cette propriété -- mentionnée dans la référence des propriétés internes
1481 et dans le fichier @file{define-grobs.scm} --, pourra accéder à la
1482 valeur usuelle de la propriété :
1486 \override Flag.X-offset = #(lambda (flag)
1487 (let ((default (ly:flag::calc-x-offset flag)))
1493 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1494 @emph{markup} consiste à utiliser la fonction
1495 @code{grob-interpret-markup}, comme ici :
1498 my-callback = #(lambda (grob)
1499 (grob-interpret-markup grob (markup "foo")))
1504 @n ode Code Scheme intégré
1505 @s ection Code Scheme intégré
1506 @t ranslationof Inline Scheme code
1508 À REVOIR : depuis la rédaction de cette section, LilyPond en est
1509 arrivé à un point tel que trouver un exemple @emph{simple} où l'on se
1510 retrouve obligé d'en venir à utiliser du code Scheme devient chose
1513 En attendant un remaniement de cette section, faisons comme si nous
1516 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1517 sa syntaxe. Par exemple, le code suivant produit une erreur de syntaxe
1518 (du moins, c'était le cas auparavant).
1521 F = \tweak font-size #-3 -\flageolet
1529 C'est en se servant du langage Scheme que l'on peut résoudre ce
1530 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1531 @ref{Ajout d'articulation à des notes (exemple)}, en
1532 particulier quant à l'emploi de @code{\displayMusic}.
1535 F = #(let ((m (make-music 'ArticulationEvent
1536 'articulation-type "flageolet")))
1537 (set! (ly:music-property m 'tweaks)
1538 (acons 'font-size -3
1539 (ly:music-property m 'tweaks)))
1548 Ici les propriétés @code{tweak} de l'objet flageolet nommé @samp{m}
1549 (créé au moyen de @code{make-music}) sont extraites par
1550 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1551 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1552 @code{acons}), et le résultat de cette opération est renvoyé par
1553 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1554 finale de @samp{m} lui-même.
1559 @node Retouches complexes
1560 @section Retouches complexes
1561 @translationof Difficult tweaks
1563 Certains réglages sont plus délicats que d'autres.
1567 L'un d'entre eux est l'apparence des objets dits « extenseurs »
1568 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1569 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1570 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1571 changement de ligne, ils sont dupliqués au début du ou des systèmes
1572 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1573 héritent toutes les propriétés, y compris les éventuelles commandes
1576 En d'autres termes, une commande @code{\override} affecte toujours les
1577 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1578 partie précédant ou suivant le changement de ligne, il faut intervenir
1579 directement dans le processus de mise en page.
1580 La fonction de rappel @code{after-line-breaking} contient toute
1581 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1582 déterminés, et que des objets graphiques ont été divisés sur des
1583 systèmes différents.
1585 Dans l'exemple suivant, on définit une nouvelle opération nommée
1586 @code{my-callback}. Cette opération
1590 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1592 dans l'affirmative, recherche les différents tronçons de l'objet
1594 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1597 dans l'affirmative, applique un espacement supplémentaire
1598 (@code{extra-offset}).
1601 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1602 de façon à ce que le deuxième tronçon d'une liaison divisée soit
1606 @lilypond[quote,verbatim,ragged-right]
1607 #(define (my-callback grob)
1609 ;; l'objet a-t-il été divisé ?
1610 (orig (ly:grob-original grob))
1612 ;; si oui, rechercher les tronçons frères (siblings)
1613 (siblings (if (ly:grob? orig)
1614 (ly:spanner-broken-into orig)
1617 (if (and (>= (length siblings) 2)
1618 (eq? (car (last-pair siblings)) grob))
1619 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1622 \override Tie.after-line-breaking =
1630 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1631 rappel @code{after-line-breaking} devra également appeler celle
1632 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1633 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1634 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1638 Pour des raisons d'ordre technique, certains objets ne peuvent être
1639 modifiés par @code{\override}. Parmi ceux-là, les objets
1640 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1641 @code{\overrideProperty} sert à les modifier, de façon similaire à
1642 @code{\once \override}, mais avec une syntaxe différente :
1646 Score.NonMusicalPaperColumn % Nom de l'objet
1647 . line-break-system-details % Nom de la propriété
1648 . next-padding % Nom de la sous-propriété (optionnel)
1652 Notez toutefois que la commande @code{\override} peut tout de même être
1653 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1654 bloc @code{\context}.
1659 @node Interfaces LilyPond Scheme
1660 @chapter Interfaces LilyPond Scheme
1661 @translationof LilyPond Scheme interfaces
1663 Ce chapitre aborde les différents outils fournis par LilyPond à
1664 l'intention des programmeurs en Scheme désireux d'obtenir des
1665 informations à partir et autour des fluxs de musique.
1667 TODO -- figure out what goes in here and how to organize it