1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 8c1840ca28a05b3dad8d595e04d03779ba0a286a
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 à partir de LilyPond en faisant précéder son nom
227 d'un @code{\}, et en le faisant suivre de ses arguments. Lorsqu'un
228 prédicat d'argument optionnel ne correspond pas à un argument, LilyPond
229 l'ignore ainsi que tous les arguments optionnels qui suivent, les
230 remplaçant par leur valeur par défaut, et « sauvegarde » en tant que
231 prochain argument obligatoire l'argument qui ne correspondait pas. Dans
232 la mesure où l'argument sauvegardé doit servir, les argument optionnels
233 ne sont en fait pas considérés comme optionnels, sauf à être suivis d'un
234 argument obligatoire.
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.
257 Pour des raisons de commodité, il est possible de faire appel à des
258 fonctions Scheme directement en Scheme, courcircuitant ainsi l'analyseur
259 de LilyPond. Leur nom s'utilise comme n'importe quel nom de fonction.
260 Le contrôle de typologie des arguments et l'omission des arguments
261 optionnels seront traîtés de la même manière que lorsque l'appel est
262 fait à partir de LilyPond, la valeur Scheme @code{*unspecified*} ayant
263 le rôle du mot réservé @code{\default} pour omettre explicitement les
264 arguments optionnels.
267 @node Fonctions Scheme fantômes
268 @subsection Fonctions Scheme fantômes
269 @translationof Void scheme functions
271 @cindex @emph{void}, fonction
272 @cindex fantôme, fonction
274 @funindex define-void-function
277 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
278 pour renvoyer une valeur. Certains langages de programmation, tels
279 le C et Scheme, utilisent des fonctions dans les deux cas et se
280 débarrassent tout bonnement de la valeur renvoyée ; en règle
281 générale, il suffit que l'expression fasse office de déclaration, et
282 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
283 la plupart des compilateurs C actuels déclenchent un avertissement si
284 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
285 nombreuses fonctions réalisant une action, les standards Scheme
286 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
287 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
288 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
289 lorsqu'on utilise @code{set!} directement sur une variable -- mais
290 malheureusement pas toujours.
292 Une fonction LilyPond définie à l'aide de la clause
293 @code{define-void-function} vous apporte l'assurance que c'est cette
294 valeur spéciale -- la seule valeur qui satisfasse au prédicat
295 @code{void?} -- qui sera retournée.
299 #(define-void-function
302 (ly:set-option 'point-and-click #f))
304 \noPointAndClick % desactive le "pointer-cliquer"
307 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
308 expression pour ses effets annexes sans interprétation d'une quelconque
312 \void #(hashq-set! une-table une-clé une-valeur)
315 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
316 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
317 opérationnel dans le cadre de fonctions musicales telles que
318 @code{\displayMusic}.
321 @node Fonctions musicales
322 @section Fonctions musicales
323 @translationof Music functions
325 @cindex musicale, fonction
327 Les @emph{fonctions musicales} sont des procédures Scheme capables de
328 créer automatiquement des expressions musicales ; elles permettent
329 de grandement simplifier un fichier source.
332 * Définition de fonctions musicales::
333 * Utilisation de fonctions musicales::
334 * Fonctions de substitution simple::
335 * Fonctions de substitution intermédiaires::
336 * De l'usage des mathématiques dans les fonctions::
337 * Fonctions dépourvues d'argument::
338 * Fonctions musicales fantômes::
342 @node Définition de fonctions musicales
343 @subsection Définition de fonctions musicales
344 @translationof Music function definitions
346 @cindex fonction musicale, définition
348 @funindex define-music-function
350 Une fonction musicale se définit ainsi :
354 #(define-music-function
355 (@var{arg1} @var{arg2}@dots{})
356 (@var{type1?} @var{type2?}@dots{})
361 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
362 Scheme}. La plupart du temps, le @var{corps} sera constitué d'un
363 @ref{Blocs de code LilyPond, bloc de code LilyPond}.
365 Les différents types des prédicat sont recensés à l'annexe
366 @ruser{Types de prédicats prédéfinis}.
370 @ruser{Types de prédicats prédéfinis}.
372 Fichiers d'initialisation :
373 @file{lily/music-scheme.cc},
378 @node Utilisation de fonctions musicales
379 @subsection Utilisation de fonctions musicales
380 @translationof Music function usage
382 Une « fonction musicale » doit impérativement renvoyer une expression
383 répondant au prédicat @code{ly:music?}. Ceci a pour conséquence
384 d'autoriser l'appel à une fonction musicale en tant qu'argument de type
385 @code{ly:music?} dans le cadre de l'appel à une autre fonction musicale.
387 Certaines restrictions s'appliqueront selon le contexte où une fonction
388 musicale est utilisée, de telle sorte que l'analyse syntaxique soit sans
393 Dans une expression musicale de haut niveau, aucun postévénement n'est
397 Lorsqu'une fonction musicale -- contrairement à une fonction
398 événementielle -- renvoie une expression de type postévénement, LilyPond
399 requiert son introduction par un indicateur de positionnement -- à
400 savoir @code{-}, @code{^} ou @code{_} -- de telle sorte que le
401 postévénement produit par l'appel à cette fonction s'intègre
402 correctement dans l'expression environnante.
405 En tant que partie d'un accord, l'expression musicale renvoyée doit
406 être du type @code{rhythmic-event}, et plus particulièrement un
411 Des fonctions « polymorphes » telles que @code{\tweak} peuvent
412 s'appliquer aux postévénements, constituants d'accord et expressions de
416 @node Fonctions de substitution simple
417 @subsection Fonctions de substitution simple
418 @translationof Simple substitution functions
420 Une fonction de substitution simple renvoie une expression musicale
421 écrite au format LilyPond et contient des arguments au format de
422 l'expression résultante. Vous en trouverez une description détaillée à
423 la rubrique @ruser{Exemples de fonction de substitution}.
426 @node Fonctions de substitution intermédiaires
427 @subsection Fonctions de substitution intermédiaires
428 @translationof Intermediate substitution functions
430 Une fonction de substitution intermédiaire est une fonction dont
431 l'expression musicale résultante mélangera du code Scheme au code
434 Certaines commandes @code{\override} nécessitent un argument
435 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
436 cell} en Scheme -- que l'on pourrait traduire par « construction de
439 Cette paire peut se mentionner directement dans la fonction musicale à
440 l'aide d'une variable @code{pair?} :
444 #(define-music-function
448 \once \override Beam.positions = #beg-end
452 \manualBeam #'(3 . 6) c8 d e f
456 Autre manière de procéder, les nombres formant la paire sont transmis
457 comme arguments séparés ; le code Scheme chargé de créer la paire
458 pourra alors être inclus dans l'expression musicale :
460 @lilypond[quote,verbatim,ragged-right]
462 #(define-music-function
466 \once \override Beam.positions = #(cons beg end)
470 \manualBeam #3 #6 c8 d e f
475 @cindex temporaire, dérogation (override)
476 @cindex dérogation temporaire (override)
477 @cindex propriétés, retour à la valeur précédente
479 L'entretien des propriétés peut se voir comme un empilement par
480 propriété par objet par contexte. Les fonctions musicales peuvent
481 nécessiter des dérogations pour une ou plusieurs propriétés pour la
482 durée de la fonction, puis de revenir aux valeurs précédentes avant de
483 quitter. Néanmoins, une dérogation normale va retirer de la pile -- ou
484 dépiler -- et supprimer le sommet de la pile de la propriété avant
485 d'y ajouter quoi que ce soit -- ou empiler -- ; la valeur précédente de
486 la propriété est de fait perdue. Lorsque la valeur antérieure doit être
487 préservée, l'instruction @code{\override} devra être préfixée d'un
488 @code{\temporary}, comme ceci :
491 \temporary \override @dots{}
494 L'utilisation d'un @code{\temporary} a pour effet d'effacer la propriété
495 @code{pop-first} (@emph{commence par dépiler} normalement activée) de la
496 dérogation ; la valeur antérieure ne sera alors pas supprimée de la pile
497 de la propriété avant d'y empiler la nouvelle valeur. Lorsqu'un
498 @code{\revert} viendra par la suite supprimer la valeur dérogatoire
499 temporaire, réapparaitra la valeur antérieure.
501 En d'autres termes, un @code{\revert} qui suit un @code{\temporary
502 \override} pour la même propriété n'apporte rien. Ce principe est aussi
503 valable pour un couple @code{\temporary} et @code{\undo} sur la même
504 musique contenant des dérogations.
506 Voici un exemple de fonction musicale utilisant cette fonctionnalité.
507 La présence du @code{\temporary} permet de s'assurer qu'en sortant de la
508 fonction, les propriétés @code{cross-staff} et @code{style} retrouveront
509 les valeurs qu'elles avaient avant que ne soit appelée la fonction
510 @code{crossStaff}. En l'absence de @code{\temporary}, ces propriétés
511 auraient retrouvé leurs valeurs par défaut à la sortie de la fonction.
515 #(define-music-function (notes) (ly:music?)
516 (_i "Create cross-staff stems")
518 \temporary \override Stem.cross-staff = #cross-staff-connect
519 \temporary \override Flag.style = #'no-flag
521 \revert Stem.cross-staff
527 @node De l'usage des mathématiques dans les fonctions
528 @subsection De l'usage des mathématiques dans les fonctions
529 @translationof Mathematics in functions
531 Une fonction musicale peut requérir, en plus d'une simple substitution,
532 une part de programmation en Scheme.
534 @lilypond[quote,verbatim,ragged-right]
536 #(define-music-function
540 \override Stem.length = #(* 7.0 mag)
541 \override NoteHead.font-size =
542 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
547 \revert NoteHead.font-size
552 \AltOn #1.5 c c \AltOff c2
557 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
558 s'applique à une expression musicale :
560 @lilypond[quote,verbatim,ragged-right]
562 #(define-music-function
566 \override Stem.length = #(* 7.0 mag)
567 \override NoteHead.font-size =
568 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
571 \revert NoteHead.font-size
575 c'2 \withAlt #0.5 { c4 c }
576 \withAlt #1.5 { c c } c2
581 @node Fonctions dépourvues d'argument
582 @subsection Fonctions dépourvues d'argument
583 @translationof Functions without arguments
585 Dans la plupart des cas, une fonction dépourvue d'argument devrait
586 être créée à l'aide d'une variable :
589 dolce = \markup@{ \italic \bold dolce @}
592 Il peut, dans certains cas particuliers, s'avérer utile de créer une
593 fonction sans argument comme ici,
597 #(define-music-function
600 (if (eq? #t (ly:get-option 'display-bar-numbers))
601 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
606 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
607 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
608 en respectant la syntaxe
611 lilypond -d display-bar-numbers MONFICHIER.ly
615 @node Fonctions musicales fantômes
616 @subsection Fonctions musicales fantômes
617 @translationof Void music functions
619 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
620 une fonction musicale peut n'être exécutée que dans le but d'en retenir
621 les effets annexes ; vous devrez alors utiliser une procédure
622 @code{define-void-function}. Il peut cependant arriver que vous ayez
623 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
624 l'exemple de la rubrique précédente) une expression musicale.
625 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
626 expression musicale @code{void}.
629 @node Fonctions événementielles
630 @section Fonctions événementielles
631 @translationof Event functions
633 @funindex define-event-function
634 @cindex événementielle, fonction
636 L'utilisation d'une fonction musicale pour placer un événement requiert
637 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
638 à la syntaxe de la construction à remplacer. C'est par exemple le cas
639 lorsque vous voulez écrire une commande de nuance, instruction qui
640 ne comporte habituellement pas d'indicateur de positionnement, comme
641 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
644 @lilypond[quote,verbatim,ragged-right]
645 dyn=#(define-event-function (arg) (markup?)
646 (make-dynamic-script arg))
647 \relative { c'\dyn pfsss }
650 Vous pourriez obtenir le même résultat avec une fonction musicale, à
651 ceci près que chaque appel à la fonction devra être précédé d'un
652 indicateur de positionnement, comme @code{c-\dyn pfsss}.
655 @node Fonctions pour markups
656 @section Fonctions pour @emph{markups}
657 @translationof Markup functions
659 Les @emph{markups} sont implémentés au travers de fonctions Scheme
660 spécifiques qui produisent des objets @code{Stencil} comprenant un
661 certain nombre d'arguments.
664 * Construction d'un markup en Scheme::
665 * Fonctionnement interne des markups::
666 * Définition d'une nouvelle commande de markup::
667 * Définition d'une nouvelle commande de liste de markups::
671 @node Construction d'un markup en Scheme
672 @subsection Construction d'un @emph{markup} en Scheme
673 @translationof Markup construction in Scheme
675 @cindex définition d'une commande markup
677 @funindex \displayScheme
679 Les expressions @emph{markup} sont représentées en Scheme de manière
680 interne par la macro @code{markup} :
683 (markup @var{expression})
686 La commande @code{\displayScheme} permet d'obtenir la représentation en
687 Scheme d'une expression @emph{markup} :
693 \line @{ \bold \italic "hello" \raise #0.4 "world" @}
694 \larger \line @{ foo bar baz @}
700 Compiler ce code renverra en console les lignes suivantes :
707 (#:bold (#:italic "hello") #:raise 0.4 "world")
710 (#:simple "foo" #:simple "bar" #:simple "baz")))))
713 L'impression du @emph{markup} sera suspendue dès lors qu'apparaîtra un
714 @w{@samp{\void \displayScheme @var{markup}}}. Tout comme pour la
715 commande @code{\displayMusic}, le résultat de @code{\displayScheme} peut
716 être sauvegardé dans un fichier séparé. Voir à ce sujet
717 @ref{Affichage d'expressions musicales}.
720 Vous pouvez constater les principales règles de traduction entre les
721 syntaxes respectives de LilyPond et de Scheme en matière de
722 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
723 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
724 utiliser la macro @code{markup} en Scheme exclusivement.
727 @multitable @columnfractions .3 .3
728 @item @b{LilyPond} @tab @b{Scheme}
729 @item @code{\markup markup1} @tab @code{(markup markup1)}
730 @item @code{\markup @{ markup1 markup2@dots{} @}} @tab
731 @code{(markup markup1 markup2@dots{} )}
732 @item @code{\commande-markup} @tab @code{#:commande-markup}
733 @item @code{\variable} @tab @code{variable}
734 @item @code{\center-column @{ @dots{} @}} @tab
735 @code{#:center-column ( @dots{} )}
736 @item @code{chaîne} @tab @code{"chaîne"}
737 @item @code{#argument-scheme} @tab @code{argument-scheme}
741 L'intégralité du langage Scheme est accessible à l'intérieur même de la
742 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
743 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
744 particulièrement pratique lorsque vous créez votre propre commande de
745 @emph{markup} -- voir
746 @ref{Définition d'une nouvelle commande de markup}.
749 L'argument @var{markup-list} des commandes @code{#:line},
750 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
751 résultat de l'appel à une fonction.
754 (markup #:line (fonction-qui-retourne-des-markups))
758 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
759 @code{make-line-markup}, @code{make-center-markup} ou
760 @code{make-column-markup} :
763 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
767 @node Fonctionnement interne des markups
768 @subsection Fonctionnement interne des @emph{markups}
769 @translationof How markups work internally
771 Dans un @emph{markup} tel que
774 \raise #0.5 "text example"
778 @code{\raise} représente en fait la fonction @code{raise-markup}.
779 L'expression @emph{markup} est enregistrée sous la forme
782 (list raise-markup 0.5 (list simple-markup "text example"))
785 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
786 la fonction @code{raise-markup} est appelée ainsi :
791 @var{liste des alists de propriété}
793 @var{le @emph{markup} "text example"})
796 La fonction @code{raise-markup} commence par créer le stencil pour la
797 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
798 portée. Il s'agit là d'un exemple relativement simple, et nous en
799 aborderons de plus complexes au fil des paragraphes suivants ;
800 d'autres exemples se trouvent directement dans le fichier
801 @file{scm/define-markup-commands.scm}.
804 @node Définition d'une nouvelle commande de markup
805 @subsection Définition d'une nouvelle commande de @emph{markup}
806 @translationof New markup command definition
808 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
809 commande de @emph{markup}.
812 * Syntaxe d'une commande markup::
813 * Attribution de propriétés::
815 * Adaptation d'une commande incorporée::
819 @node Syntaxe d'une commande markup
820 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
821 @translationof Markup command definition syntax
823 Une commande de @emph{markup} personnalisée se définit à l'aide de la
824 macro Scheme @code{define-markup-command}, placée en tête de fichier.
827 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2}@dots{})
828 (@var{arg1-type?} @var{arg2-type?}@dots{})
829 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
831 @dots{}corps de la commande@dots{})
834 Quelques commentaires sur les arguments :
837 @item @var{nom-commande}
838 le nom que vous attribuez à votre commande de @emph{markup}.
840 la définition du « layout » -- son formatage.
842 une liste de listes associatives, comprenant toutes les propriétés actives.
844 le @var{ième} argument de la commande.
845 @item @var{argi-type?}
846 un type de prédicat pour le @var{ième} argument.
849 Si la commande utilise des propriétés à partir des arguments
850 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
851 différentes propriétés ainsi que leur valeur par défaut.
853 Les arguments se distinguent selon leur type :
855 @item un @emph{markup}, correspondant au type de prédicat
857 @item une liste de @emph{markups}, correspondant au type de prédicat
858 @code{markup-list?} ;
859 @item tout autre objet Scheme, correspondant au types de prédicat tels
860 que @code{list?}, @code{number?}, @code{boolean?}, etc.
863 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
864 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
865 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
866 ceci de particulier qu'elles peuvent s'appliquer à des listes de
867 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
868 tous les éléments de la liste originelle se verront appliquer cette
869 fonction @emph{markup} avec ses arguments de tête.
871 La réplication des arguments de tête dans le but d'appliquer une
872 fonction @emph{markup} à une liste de markups est économique,
873 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
874 ainsi d'éventuelles pertes de performance en utilisant des arguments
875 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
876 le dernier argument est un @emph{markup}.
879 @cindex macro de markup
881 @funindex interpret-markup
883 Les commandes de @emph{markup} ont un cycle de vie relativement
884 complexe. Le corps de la définition d'une commande de @emph{markup} est
885 chargé de convertir les arguments de la commande en expression stencil
886 qui sera alors renvoyée. Bien souvent, ceci s'accomplit par un appel à
887 la fonction @code{interpret-markup}, en lui passant les arguments
888 @var{layout} et @var{props}. Ces arguments ne seront en principe connus
889 que bien plus tardivement dans le processus typographique. Lors de
890 l'expansion d'une expression LilyPond @code{\markup} ou d'une macro
891 Scheme @code{markup}, les expressions @emph{markup} auront déjà vu leurs
892 composants assemblés en expressions @emph{markup}. L'évaluation et le
893 contrôle du type des arguments à une commande de @emph{markup}
894 n'interviennent qu'au moment de l'interprétation de @code{\markup} ou
897 Seule l'application de @code{interpret-markup} sur une expression
898 @emph{markup} réalisera effectivement la conversion des expressions
899 @emph{markup} en stencil, au travers de l'exécution du corps des
900 fonctions @emph{markup}.
903 @node Attribution de propriétés
904 @unnumberedsubsubsec Attribution de propriétés
905 @translationof On properties
907 Les arguments @code{layout} et @code{props} d'une commande de
908 @emph{markup} fournissent un contexte à l'interprétation du
909 @emph{markup} : taille de fonte, longueur de ligne, etc.
911 L'argument @code{layout} permet d'accéder aux propriétés définies dans
912 les blocs @code{\paper}, grâce à la fonction
913 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
914 identique à celle de la partition, est lue au travers de
917 (ly:output-def-lookup layout 'line-width)
920 L'argument @code{props} rend certaines propriétés accessibles aux
921 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
922 d'un @emph{markup} de titre d'ouvrage : toutes les variables
923 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
924 @code{props}, de telle sorte que le @emph{markup} de titrage de
925 l'ouvrage pourra accéder aux différents champs titre, compositeur, etc.
926 Ceci permet aussi de configurer le comportement d'une commande de
927 @emph{markup} : la taille des fontes, par exemple, est lue à
928 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
929 La fonction appelant une commande de @emph{markup} peut altérer la
930 valeur de la propriété taille des fontes et donc en modifier le
931 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
932 @code{define-markup-command}, permet de spécifier les propriétés devant
933 être lues parmi les arguments @code{props}.
935 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
936 commande de @emph{markup}, accéder aux différentes propriétés et les
940 @node Exemple commenté
941 @unnumberedsubsubsec Exemple commenté
942 @translationof A complete example
944 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
947 Commençons par construire quelque chose d'approximatif à l'aide d'un
948 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
949 indique la commande @code{\box}, qui semble ici appropriée.
951 @lilypond[quote,verbatim,ragged-right]
952 \markup \box \box HELLO
955 Dans un souci d'esthétique, nous aimerions que le texte et les
956 encadrements ne soient pas autant accolés. Selon la documentation de
957 @code{\box}, cette commande utilise la propriété @code{box-padding},
958 fixée par défaut à 0,2. Cette même documentation nous indique
959 aussi comment la modifier :
961 @lilypond[quote,verbatim,ragged-right]
962 \markup \box \override #'(box-padding . 0.6) \box A
965 L'espacement des deux liserés est cependant toujours trop réduit ;
966 modifions le à son tour :
968 @lilypond[quote,verbatim,ragged-right]
969 \markup \override #'(box-padding . 0.4) \box
970 \override #'(box-padding . 0.6) \box A
973 Vous conviendrez que recopier une telle définition de @emph{markup}
974 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
975 @emph{markup} @code{double-box} qui prendra un seul argument -- le
976 texte. Cette commande se chargera de dessiner les encadrements, en
977 tenant compte des espacements.
980 #(define-markup-command (double-box layout props text) (markup?)
981 "Dessine un double encadrement autour du texte."
982 (interpret-markup layout props
983 #@{\markup \override #'(box-padding . 0.4) \box
984 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
987 ou bien son équivalent
990 #(define-markup-command (double-box layout props text) (markup?)
991 "Dessine un double encadrement autour du texte."
992 (interpret-markup layout props
993 (markup #:override '(box-padding . 0.4) #:box
994 #:override '(box-padding . 0.6) #:box text)))
997 @code{text} est le nom de l'argument de notre commande, et
998 @code{markup?} son type -- l'argument sera identifié comme étant un
999 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
1000 plupart des commandes de @emph{markup}, construira un stencil à partir
1001 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
1002 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
1003 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
1004 transformation d'une expression @code{\markup} en expression Scheme est
1007 Notre commande personnalisée s'utilise ainsi :
1010 \markup \double-box A
1013 Il serait intéressant de rendre cette commande @code{double-box} plus
1014 souple : les valeurs de @code{box-padding} sont figées et ne
1015 peuvent être modifiées à l'envie. Pareillement, il serait bien de
1016 distinguer l'espacement entre les encadrements de l'espacement entre le
1017 texte et ses encadrements. Nous allons donc introduire une propriété
1018 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
1019 de gérer l'espacement des encadrements ; @code{box-padding} ne
1020 servira alors que pour l'espacement intérieur. Voici le code adapté à
1024 #(define-markup-command (double-box layout props text) (markup?)
1025 #:properties ((inter-box-padding 0.4)
1027 "Dessine un double encadrement autour du texte."
1028 (interpret-markup layout props
1029 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
1030 \override #`(box-padding . ,box-padding) \box
1034 Ainsi que son équivalent à partir de la macro @emph{markup} :
1037 #(define-markup-command (double-box layout props text) (markup?)
1038 #:properties ((inter-box-padding 0.4)
1040 "Dessine un double encadrement autour du texte."
1041 (interpret-markup layout props
1042 (markup #:override `(box-padding . ,inter-box-padding) #:box
1043 #:override `(box-padding . ,box-padding) #:box text)))
1046 C'est ici le mot-clé @code{#:properties} qui permet de lire les
1047 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
1048 l'argumenet @code{props} ; on leur a d'ailleurs fourni des valeurs
1049 par défaut au cas où elles ne seraient pas définies.
1051 Ces valeurs permettront alors d'adapter les propriétés de
1052 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
1053 aurez remarqué, dans l'argument @code{\override}, la présence de
1054 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
1055 permettent d'insérer une valeur variable au sein d'une expression
1058 Notre commande est maintenant prête à servir dans un @emph{markup}, et
1059 les encadrements sont repositionnables.
1061 @lilypond[quote,verbatim,ragged-right]
1062 #(define-markup-command (double-box layout props text) (markup?)
1063 #:properties ((inter-box-padding 0.4)
1065 "Draw a double box around text."
1066 (interpret-markup layout props
1067 #{\markup \override #`(box-padding . ,inter-box-padding) \box
1068 \override #`(box-padding . ,box-padding) \box
1071 \markup \double-box A
1072 \markup \override #'(inter-box-padding . 0.8) \double-box A
1073 \markup \override #'(box-padding . 1.0) \double-box A
1077 @node Adaptation d'une commande incorporée
1078 @unnumberedsubsubsec Adaptation d'une commande incorporée
1079 @translationof Adapting builtin commands
1081 Le meilleur moyen de construire ses propres commandes de @emph{markup}
1082 consiste à prendre exemple sur les commandes déjà incorporées. La
1083 plupart des commandes de @emph{markup} fournies avec LilyPond sont
1084 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
1086 Nous pourrions, par exemple, envisager d'adapter la commande
1087 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
1088 est définie la commande @code{\draw-line}, expurgée de sa
1092 (define-markup-command (draw-line layout props dest)
1095 #:properties ((thickness 1))
1096 "@dots{}documentation@dots{}"
1097 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1101 (make-line-stencil th 0 0 x y)))
1104 Avant de définir notre propre commande basée sur l'une de celles
1105 fournies par LilyPond, commençons par en recopier la définition, puis
1106 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
1107 supprimé sans risque ; il ne sert que lors de la génération de la
1108 documentation et n'est d'aucune utilité pour une commande personnalisée.
1111 (define-markup-command (draw-double-line layout props dest)
1113 #:properties ((thickness 1))
1114 "@dots{}documentation@dots{}"
1115 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1119 (make-line-stencil th 0 0 x y)))
1122 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
1123 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
1124 par défaut de 6 dixièmes :
1127 (define-markup-command (draw-double-line layout props dest)
1129 #:properties ((thickness 1)
1131 "@dots{}documentation@dots{}"
1135 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1136 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1137 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1139 @lilypond[quote,verbatim,ragged-right]
1140 #(define-markup-command (my-draw-line layout props dest)
1142 #:properties ((thickness 1)
1145 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1149 (w (/ line-gap 2.0))
1150 (x (cond ((= dx 0) w)
1152 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1153 (y (* (if (< (* dx dy) 0) 1 -1)
1156 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1157 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1158 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1160 \markup \my-draw-line #'(4 . 3)
1161 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1165 @node Définition d'une nouvelle commande de liste de markups
1166 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1167 @translationof New markup list command definition
1169 @cindex liste de markup, définition de commande
1170 @funindex define-markup-list-command
1171 @funindex interpret-markup-list
1173 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1174 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1175 la macro @code{define-markup-command} abordée à la rubrique
1176 @ref{Définition d'une nouvelle commande de markup}, à ceci près que
1177 cette dernière renvoie un seul stencil, non une liste de stencils.
1179 La fonction @code{interpret-markup-list}, à l'instar de la fonction
1180 @code{interpret-markup}, permet de convertir une liste de @emph{markups}
1181 en liste de stencils.
1183 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1184 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1185 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1186 par l'argument @code{props}.
1189 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1190 #:properties ((par-indent 2))
1191 (interpret-markup-list layout props
1192 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1195 La version purement Scheme est un peu plus complexe :
1197 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1198 #:properties ((par-indent 2))
1199 (interpret-markup-list layout props
1200 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1204 En dehors des habituels arguments @code{layout} et @code{props}, la
1205 commande de liste de @emph{markups} @code{paragraph} prend en argument
1206 une liste de @emph{markups} appelée @code{args}. Le prédicat des listes
1207 de @emph{markups} est @code{markup-list?}.
1209 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1210 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1211 @code{props}. En cas d'absence, la valeur par défaut sera
1212 de @code{2}. Ensuite est créée une liste de lignes justifiées
1213 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1214 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1215 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1216 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1217 interprétée par la fonction @code{interpret-markup-list}.
1219 Voici comment utiliser cette nouvelle commande de liste de
1225 The art of music typography is called \italic @{(plate) engraving.@}
1226 The term derives from the traditional process of music printing.
1227 Just a few decades ago, sheet music was made by cutting and stamping
1228 the music into a zinc or pewter plate in mirror image.
1230 \override-lines #'(par-indent . 4) \paragraph @{
1231 The plate would be inked, the depressions caused by the cutting
1232 and stamping would hold ink. An image was formed by pressing paper
1233 to the plate. The stamping and cutting was completely done by
1240 @node Contextes pour programmeurs
1241 @section Contextes pour programmeurs
1242 @translationof Contexts for programmers
1245 * Évaluation d'un contexte::
1246 * Application d'une fonction à tous les objets de mise en forme::
1250 @node Évaluation d'un contexte
1251 @subsection Évaluation d'un contexte
1252 @translationof Context evaluation
1254 @cindex appel de code durant l'interprétation
1255 @funindex \applyContext
1256 @funindex make-apply-context
1257 @funindex ly:context-property
1258 @funindex ly:context-set-property!
1259 @funindex ly:context-grob-definition
1260 @funindex ly:assoc-get
1261 @funindex ly:context-pushpop-property
1263 Un contexte peut être modifié, au moment même de son interprétation, par
1264 du code Scheme. La syntaxe consacrée au sein d'un bloc LilyPond est
1267 \applyContext @var{fonction}
1271 et, dans le cadre d'un code Scheme :
1274 (make-apply-context @var{fonction})
1277 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1278 unique argument : le contexte au sein duquel la commande
1279 @code{\applyContext} est appelée. Cette fonction peut accéder aussi
1280 bien aux propriétés de @emph{grob} (y compris modifiées par
1281 @code{\override} ou @code{\set}) qu'aux propriétés de contexte. Toute
1282 action entreprise par la fonction et qui dépendrait de l'état du
1283 contexte sera limitée à l'état de ce contexte @b{au moment de l'appel à
1284 la fonction}. Par ailleurs, les adaptations résultant d'un appel à
1285 @code{\applyContext} seront effectives jusqu'à ce qu'elles soient à
1286 nouveau directement modifiées ou bien annulées, quand bien même les
1287 conditions initiales dont elles dépendent auraient changé.
1289 Voici quelques fonctions Scheme utiles avec @code{\applyContext} :
1292 @item ly:context-property
1293 recherche la valeur d'une propriété de contexte,
1295 @item ly:context-set-property!
1296 détermine une propriété de contexte,
1298 @item ly:context-grob-definition
1300 recherche la valeur d'une propriété de @emph{grob},
1302 @item ly:context-pushpop-property
1303 réalise un @code{\temporary \override} ou un @code{\revert} sur une
1304 propriété de @emph{grob}.
1307 L'exemple suivant recherche la valeur en cours de @code{fontSize} puis
1310 @lilypond[quote,verbatim]
1314 (let ((fontSize (ly:context-property context 'fontSize)))
1315 (ly:context-set-property! context 'fontSize (+ fontSize 6))))
1325 L'exemple suivant recherche la couleur des objets @code{NoteHead},
1326 @code{Stem} et @code{Beam}, puis diminue pour chacun d'eux le degré de
1329 @lilypond[quote,verbatim]
1333 (define (desaturate-grob grob)
1334 (let* ((grob-def (ly:context-grob-definition context grob))
1335 (color (ly:assoc-get 'color grob-def black))
1336 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
1337 (ly:context-pushpop-property context grob 'color new-color)))
1338 (for-each desaturate-grob '(NoteHead Stem Beam)))
1342 g'8[ g] \desaturate g[ g] \desaturate g[ g]
1343 \override NoteHead.color = #darkred
1344 \override Stem.color = #darkred
1345 \override Beam.color = #darkred
1346 g[ g] \desaturate g[ g] \desaturate g[ g]
1350 Ceci pourrait tout à fait s'implémenter sous la forme d'une fonction
1351 musicale, afin d'en réduire les effets à un seul bloc de musique. Notez
1352 comment @code{ly:context-pushpop-property} est utilisé à la fois pour un
1353 @code{\temporary \override} et pour un @code{\revert} :
1355 @lilypond[quote,verbatim]
1357 #(define-music-function
1362 (define (desaturate-grob grob)
1363 (let* ((grob-def (ly:context-grob-definition context grob))
1364 (color (ly:assoc-get 'color grob-def black))
1365 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
1366 (ly:context-pushpop-property context grob 'color new-color)))
1367 (for-each desaturate-grob '(NoteHead Stem Beam)))
1371 (define (revert-color grob)
1372 (ly:context-pushpop-property context grob 'color))
1373 (for-each revert-color '(NoteHead Stem Beam)))
1377 \override NoteHead.color = #darkblue
1378 \override Stem.color = #darkblue
1379 \override Beam.color = #darkblue
1381 \desaturate { d c b a }
1387 @node Application d'une fonction à tous les objets de mise en forme
1388 @subsection Application d'une fonction à tous les objets de mise en forme
1389 @translationof Running a function on all layout objects
1391 @cindex appel de code sur des objets de mise en forme
1392 @cindex objets de mise en forme, appel de code
1393 @funindex \applyOutput
1395 La manière la plus souple d'affiner un objet consiste à utiliser la
1396 commande @code{\applyOutput}. Celle-ci va insérer un événement
1397 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1398 aussi bien à la syntaxe
1400 \applyOutput @var{Contexte} @var{procédure}
1404 \applyOutput @var{Contexte}.@var{Grob} @var{procédure}
1408 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1410 Lors de l'interprétation de cette commande, la fonction
1411 @code{@var{procédure}} est appelée pout tout objet de rendu (nommé
1412 @var{Grob} si celui-ci est spécifié) appartenant au contexte
1413 @code{@var{Contexte}} à cet instant précis, avec les arguments
1416 @item l'objet de rendu en lui-même,
1417 @item le contexte au sein duquel cet objet est créé,
1418 @item le contexte dans lequel @code{\applyOutput} est effectué.
1421 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1422 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1423 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1424 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1426 Voici une fonction utilisable avec la commande
1427 @code{\applyOutput} : elle « blanchit » la tête des notes se trouvant
1428 sur la ligne médiane ou bien directement à son contact.
1430 @lilypond[quote,verbatim,ragged-right]
1431 #(define (blanker grob grob-origin context)
1432 (if (< (abs (ly:grob-property grob 'staff-position)) 2)
1433 (set! (ly:grob-property grob 'transparent) #t)))
1436 a'4 e8 <<\applyOutput Voice.NoteHead #blanker a c d>> b2
1440 La @var{procédure} sera interprétée au niveau @code{Score} (partition)
1441 ou @code{Staff} (portée) dès lors que vous utiliserez l'une des syntaxes
1444 \applyOutput Score@dots{}
1445 \applyOutput Staff@dots{}
1449 @node Fonctions de rappel
1450 @section Fonctions de rappel
1451 @translationof Callback functions
1453 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1454 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1458 \override Stem.thickness = #2.0
1461 Une procédure Scheme peut aussi se charger de modifier des propriétés :
1463 @lilypond[fragment,verbatim,quote]
1464 \override Stem.thickness = #(lambda (grob)
1465 (if (= UP (ly:grob-property grob 'direction))
1468 \relative { c'' b a g b a g b }
1472 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1473 est nécessaire au processus de mise en forme.
1475 La majeure partie du procédé typographique consiste en la réalisation de
1476 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1477 utilisant particulièrement des rappels, nous mentionnerons
1481 Routine d'impression, construisant le dessin du symbole
1483 Routine effectuant le positionnement horizontal
1485 Routine calculant la largeur d'un objet
1488 La procédure prend un unique argument, en l'occurrence l'objet graphique
1491 Cette procédure, grâce à un appel à la fonction de rappel dévolue à
1492 cette propriété -- mentionnée dans la référence des propriétés internes
1493 et dans le fichier @file{define-grobs.scm} --, pourra accéder à la
1494 valeur usuelle de la propriété :
1498 \override Flag.X-offset = #(lambda (flag)
1499 (let ((default (ly:flag::calc-x-offset flag)))
1505 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1506 @emph{markup} consiste à utiliser la fonction
1507 @code{grob-interpret-markup}, comme ici :
1510 my-callback = #(lambda (grob)
1511 (grob-interpret-markup grob (markup "foo")))
1516 @n ode Code Scheme intégré
1517 @s ection Code Scheme intégré
1518 @t ranslationof Inline Scheme code
1520 À REVOIR : depuis la rédaction de cette section, LilyPond en est
1521 arrivé à un point tel que trouver un exemple @emph{simple} où l'on se
1522 retrouve obligé d'en venir à utiliser du code Scheme devient chose
1525 En attendant un remaniement de cette section, faisons comme si nous
1528 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1529 sa syntaxe. Par exemple, le code suivant produit une erreur de syntaxe
1530 (du moins, c'était le cas auparavant).
1533 F = \tweak font-size #-3 -\flageolet
1541 C'est en se servant du langage Scheme que l'on peut résoudre ce
1542 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1543 @ref{Ajout d'articulation à des notes (exemple)}, en
1544 particulier quant à l'emploi de @code{\displayMusic}.
1547 F = #(let ((m (make-music 'ArticulationEvent
1548 'articulation-type "flageolet")))
1549 (set! (ly:music-property m 'tweaks)
1550 (acons 'font-size -3
1551 (ly:music-property m 'tweaks)))
1560 Ici les propriétés @code{tweak} de l'objet flageolet nommé @samp{m}
1561 (créé au moyen de @code{make-music}) sont extraites par
1562 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1563 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1564 @code{acons}), et le résultat de cette opération est renvoyé par
1565 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1566 finale de @samp{m} lui-même.
1571 @node Retouches complexes
1572 @section Retouches complexes
1573 @translationof Difficult tweaks
1575 Certains réglages sont plus délicats que d'autres.
1579 L'un d'entre eux est l'apparence des objets dits « extenseurs »
1580 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1581 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1582 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1583 changement de ligne, ils sont dupliqués au début du ou des systèmes
1584 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1585 héritent toutes les propriétés, y compris les éventuelles commandes
1588 En d'autres termes, une commande @code{\override} affecte toujours les
1589 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1590 partie précédant ou suivant le changement de ligne, il faut intervenir
1591 directement dans le processus de mise en page.
1592 La fonction de rappel @code{after-line-breaking} contient toute
1593 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1594 déterminés, et que des objets graphiques ont été divisés sur des
1595 systèmes différents.
1597 Dans l'exemple suivant, on définit une nouvelle opération nommée
1598 @code{my-callback}. Cette opération
1602 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1604 dans l'affirmative, recherche les différents tronçons de l'objet
1606 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1609 dans l'affirmative, applique un espacement supplémentaire
1610 (@code{extra-offset}).
1613 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1614 de façon à ce que le deuxième tronçon d'une liaison divisée soit
1618 @lilypond[quote,verbatim,ragged-right]
1619 #(define (my-callback grob)
1621 ;; l'objet a-t-il été divisé ?
1622 (orig (ly:grob-original grob))
1624 ;; si oui, rechercher les tronçons frères (siblings)
1625 (siblings (if (ly:grob? orig)
1626 (ly:spanner-broken-into orig)
1629 (if (and (>= (length siblings) 2)
1630 (eq? (car (last-pair siblings)) grob))
1631 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1634 \override Tie.after-line-breaking =
1642 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1643 rappel @code{after-line-breaking} devra également appeler celle
1644 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1645 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1646 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1650 Pour des raisons d'ordre technique, certains objets ne peuvent être
1651 modifiés par @code{\override}. Parmi ceux-là, les objets
1652 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1653 @code{\overrideProperty} sert à les modifier, de façon similaire à
1654 @code{\once \override}, mais avec une syntaxe différente :
1658 Score.NonMusicalPaperColumn % Nom de l'objet
1659 . line-break-system-details % Nom de la propriété
1660 . next-padding % Nom de la sous-propriété (optionnel)
1664 Notez toutefois que la commande @code{\override} peut tout de même être
1665 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1666 bloc @code{\context}.
1671 @node Interfaces LilyPond Scheme
1672 @chapter Interfaces LilyPond Scheme
1673 @translationof LilyPond Scheme interfaces
1675 Ce chapitre aborde les différents outils fournis par LilyPond à
1676 l'intention des programmeurs en Scheme désireux d'obtenir des
1677 informations à partir et autour des fluxs de musique.
1679 TODO -- figure out what goes in here and how to organize it