1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: e2f786e15c2f1c7e71518c5e2d134bc31fd587f8
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 (parser location) ()
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 @cindex parser (fonction argument)
78 Le lecteur Scheme extrait le bloc de code LilyPond et déclenche un appel
79 à l'analyseur grammatical de LilyPond (le @code{parser}) qui réalise en
80 temps réel l'interprétation de ce bloc de code LilyPond. Toute
81 expression Scheme imbriquée est exécutée dans l'environnement lexical du
82 bloc de code LilyPond, de telle sorte que vous avez accès aux variables
83 locales et aux paramètres de la fonction au moment même où le bloc de
84 code LilyPond est écrit. Les variables définies dans d'autres modules
85 Scheme, tels ceux contenant les blocs @code{\header} ou @code{\layout},
86 ne sont pas accessibles en tant que variables Scheme (préfixées par
87 un @code{#}) mais en tant que variables LilyPond (préfixées par
90 Lorsque l'emplacement (@code{location} -- voir @ref{Fonctions Scheme})
91 fait référence à un endroit valide dans la source -- ce qui est en
92 général le cas au sein de fonctions musicales ou Scheme --, toute la
93 musique générée au sein de ce bloc de code voit son @code{origine}
94 établie à cet @emph{emplacement}.
96 Un bloc de code LilyPond peut contenir tout ce que vous pourriez mettre
97 à droite de l'assignation. Par ailleurs, un bloc LilyPond vide
98 correspond à une expression fantôme, et un bloc LilyPond de multiples
99 événements musicaux sera transformé en une expression de musique
103 @node Fonctions Scheme
104 @section Fonctions Scheme
105 @translationof Scheme functions
107 @cindex Scheme, fonctions (syntaxe LilyPond)
109 Les @emph{fonctions Scheme} sont des procédures Scheme chargées de créer
110 des expressions Scheme à partir de code rédigé selon la syntaxe de
111 LilyPond. Elles peuvent être appelées en de nombreux endroits, à l'aide
112 d'un @code{#}, où spécifier une valeur en syntaxe Scheme est autorisé.
113 Bien que Scheme dispose de fonctions en propre, nous nous intéresserons,
114 au fil des paragraphes qui suivent, aux fonctions @emph{syntaxiques},
115 autrement dit des fonctions qui reçoivent des arguments libellés dans la
119 * Définition de fonctions Scheme::
120 * Utilisation de fonctions Scheme::
121 * Fonctions Scheme fantômes::
124 @node Définition de fonctions Scheme
125 @subsection Définition de fonctions Scheme
126 @translationof Scheme function definitions
128 @funindex define-scheme-function
130 D'une manière générale, une fonction Scheme se définit ainsi :
134 #(define-scheme-function
135 (parser location @var{arg1} @var{arg2}@dots{})
136 (@var{type1?} @var{type2?}@dots{})
143 @multitable @columnfractions .33 .66
145 @tab doit être littéralement @code{parser}, de telle sorte que
146 l'analyseur grammatical puisse accéder aux blocs de code LilyPond
147 (@code{#@{}@dots{}@code{#@}}).
149 @item @code{location}
150 @tab doit être littéralement @code{location}, de telle sorte que soit
151 accessible l'emplacement de l'objet dans la source, aux fins de
152 transmettre aux messages d'erreur les fichier et numéro de ligne.
154 @item @code{@var{argN}}
155 @tab @var{n}ième argument
157 @item @code{@var{typeN?}}
158 @tab un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
159 devra retourner @code{#t}. Il existe aussi une forme spécifique --
160 @code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
161 argument optionnels. En l'absence d'argument réel au moment de l'appel
162 à la fonction, c'est la valeur par défaut qui lui sera substituée. Les
163 valeurs par défaut sont évaluées dès l'apparition de la définition, y
164 compris dans le cas de blocs de code LilyPond ; vous devrez donc,
165 si ces valeurs par défaut ne peuvent être déterminées que plus tard,
166 mentionner une valeur spéciale que vous reconnaîtrez facilement.
167 Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
168 fournir sa valeur par défaut, celle-ci sera considérée comme étant
169 @code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
170 vérifiées ni au moment de la définition, ni à l'exécution ; il est
171 de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
172 par défaut constituée d'une expression musicale est recopiée dès la
173 définition de @code{origin} vers le paramètre @code{location}.
175 @item @code{@var{corps}}
176 @tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
177 servant de valeur de retour de la fonction. Il peut contenir des blocs
178 de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
179 @w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
180 @ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
181 @code{#} permet de référencer des arguments de la fonction -- tel
182 @samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
183 arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
184 Dans le cas où une expression Scheme introduite par @code{#} ne vous
185 permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
186 expression Scheme « immédiate » à l'aide d'un @code{$}, comme
189 Lorsque votre fonction retourne une expression musicale, lui est
190 attribuée la valeur @code{origin}.
194 La recevabilité des arguments est déterminée par un appel effectif au
195 prédicat après que LilyPond les a déjà converti en expression Scheme.
196 Par voie de conséquence, l'argument peut tout à fait se libeller en
197 syntaxe Scheme -- introduite par un @code{#} ou en tant que résultat
198 d'un appel à une fonction Scheme. Par ailleurs, LilyPond convertira en
199 Scheme un certain nombre de constructions purement LilyPond avant même
200 d'en avoir vérifié le prédicat. C'est notamment le cas de la musique,
201 des @emph{postévénements}, des chaînes simples (avec ou sans
202 guillemets), des nombres, des @emph{markups} et listes de
203 @emph{markups}, ainsi que des blocs @emph{score}, @emph{book},
204 @emph{bookpart}, ou qui définissent un contexte ou un format de sortie.
206 Il existe certaines situations pour lesquelles LilyPond lèvera toute
207 ambiguïté grâce aux fonctions de prédicat : un @samp{-3} est-il un
208 @emph{postévénement} de type doigté ou un nombre négatif@tie{}? Un
209 @code{"a" 4} en mode paroles est-il une chaîne suivie d'un nombre ou
210 bien un événement syllabe de durée @code{4} ? LilyPond répondra à ces
211 questions par des interprétations successives du prédicat de l'argument,
212 dans un ordre défini de sorte à minimiser les interprétations erronées
213 et le besoin de lecture en avance.
215 Un prédicat qui accepte par exemple aussi bien une expression musicale
216 qu'une hauteur considèrera @code{c''} comme étant une hauteur plutôt
217 qu'une expression musicale. Les durées ou @emph{postévénements} qui
218 viennent juste après viendront modifier cette interprétation. C'est la
219 raison pour laquelle il vaut mieux éviter des prédicats par trop
220 permissifs tel que @code{Scheme?} lorsque l'application fait plutôt
221 appel à des type d'argument plus spécifiques.
223 Les différents types des prédicat propres à LilyPond sont recensés à
224 l'annexe @ruser{Types de prédicats prédéfinis}.
228 @ruser{Types de prédicats prédéfinis}.
230 Fichiers d'initialisation :
231 @file{lily/music-scheme.cc},
236 @node Utilisation de fonctions Scheme
237 @subsection Utilisation de fonctions Scheme
238 @translationof Scheme function usage
240 Vous pouvez appeler une fonction Scheme pratiquement partout où une
241 expression Scheme derrière un @code{#} peut prendre place. Vous appelez
242 une fonction Scheme en faisant précéder son nom d'un @code{\}, et en le
243 faisant suivre de ses arguments. Lorsqu'un prédicat d'argument
244 optionnel ne correspond pas à un argument, LilyPond l'ignore ainsi que
245 tous les arguments optionnels qui suivent, les remplaçant par leur
246 valeur par défaut, et @qq{sauvegarde} en tant que prochain argument
247 obligatoire l'argument qui ne correspondait pas. Dans la mesure où
248 l'argument sauvegardé doit servir, les argument optionnels ne sont en
249 fait pas considérés comme optionnels, sauf à être suivis d'un argument
252 Une exception cependant à cette règle : le fait de donner un
253 @code{\default} en tant qu'argument optionnel aura pour résultat que cet
254 argument et tous les autres arguments optionnels qui suivent seront
255 ignorés et remplacés par leur valeur par défaut. Il en va de même
256 lorsqu'aucun argument obligatoire ne suit, du fait que @code{\default}
257 ne requiert pas de sauvegarde. C'est d'ailleurs ainsi que fonctionnent
258 les commandes @code{mark} et @code{key}, qui retrouvent leur
259 comportement par défaut lorsque vous les faites suivre d'un
262 En plus de là où une expression Scheme est requise, il y a quelques
263 endroits où des expressions @code{#} sont acceptées et évaluées
264 uniquement pour leurs effets annexes. Il s'agit, dans la plupart des
265 cas, d'endroits où une affectation serait tout à fait envisageable.
267 Dans la mesure où il n'est pas bon de renvoyer une valeur qui pourrait
268 être mal interprétée dans certains contextes, nous vous enjoignons à
269 utiliser des fonctions Scheme normales uniquement dans les cas où vous
270 renvoyez toujours une valeur utile, et une fonction fantôme -- voir
271 @ref{Fonctions Scheme fantômes} -- dans le cas contraire.
274 @node Fonctions Scheme fantômes
275 @subsection Fonctions Scheme fantômes
276 @translationof Void scheme functions
278 @cindex @emph{void}, fonction
279 @cindex fantôme, fonction
281 @funindex define-void-function
284 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
285 pour renvoyer une valeur. Certains langages de programmation, tels
286 le C et Scheme, utilisent des fonctions dans les deux cas et se
287 débarrassent tout bonnement de la valeur renvoyée ; en règle
288 générale, il suffit que l'expression fasse office de déclaration, et
289 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
290 la plupart des compilateurs C actuels déclenchent un avertissement si
291 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
292 nombreuses fonctions réalisant une action, les standards Scheme
293 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
294 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
295 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
296 lorsqu'on utilise @code{set!} directement sur une variable -- mais
297 malheureusement pas toujours.
299 Une fonction LilyPond définie à l'aide de la clause
300 @code{define-void-function} vous apporte l'assurance que c'est cette
301 valeur spéciale -- la seule valeur qui satisfasse au prédicat
302 @code{void?} -- qui sera retournée.
306 #(define-void-function
309 (ly:set-option 'point-and-click #f))
311 \noPointAndClick % desactive le "pointer-cliquer"
314 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
315 expression pour ses effets annexes sans interprétation d'une quelconque
319 \void #(hashq-set! une-table une-clé une-valeur)
322 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
323 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
324 opérationnel dans le cadre de fonctions musicales telles que
325 @code{\displayMusic}.
328 @node Fonctions musicales
329 @section Fonctions musicales
330 @translationof Music functions
332 @cindex musicale, fonction
334 Les @emph{fonctions musicales} sont des procédures Scheme capables de
335 créer automatiquement des expressions musicales ; elles permettent
336 de grandement simplifier un fichier source.
339 * Définition de fonctions musicales::
340 * Utilisation de fonctions musicales::
341 * Fonctions de substitution simple::
342 * Fonctions de substitution intermédiaires::
343 * De l'usage des mathématiques dans les fonctions::
344 * Fonctions dépourvues d'argument::
345 * Fonctions musicales fantômes::
349 @node Définition de fonctions musicales
350 @subsection Définition de fonctions musicales
351 @translationof Music function definitions
353 @cindex fonction musicale, définition
355 @funindex define-music-function
357 Une fonction musicale se définit ainsi :
361 #(define-music-function
362 (parser location @var{arg1} @var{arg2}@dots{})
363 (@var{type1?} @var{type2?}@dots{})
368 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
369 Scheme}. La plupart du temps, le @code{corps} sera constitué d'un
370 @ref{Blocs de code LilyPond, bloc de code Lilypond}.
372 Les différents types des prédicat sont recensés à l'annexe
373 @ruser{Types de prédicats prédéfinis}.
377 @ruser{Types de prédicats prédéfinis}.
379 Fichiers d'initialisation :
380 @file{lily/music-scheme.cc},
385 @node Utilisation de fonctions musicales
386 @subsection Utilisation de fonctions musicales
387 @translationof Music function usage
389 Une fonction musicale peut prendre place en différents endroits.
390 Certaines restrictions s'appliqueront selon l'endroit où elle est
391 utilisée, de telle sorte que l'analyse syntaxique soit sans ambiguïté.
392 Le résultat renvoyé par une fonction musicale doit être compatible avec
393 le contexte dans lequel elle est appelée.
397 Dans une expression musicale de haut niveau@tie{}: aucune restriction.
400 En tant que post-événement, explicitement introduit par un indicateur de
401 positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@code{_}.
403 Dans ce cas particulier, vous ne pouvez utiliser une expression musicale
404 @emph{ouverte} en tant que dernier argument -- argument qui se
405 composerait d'une expression musicale susceptible d'accepter des
406 postévénements additionnels.
409 En tant que partie d'un accord. L'expression musicale renvoyée doit
410 être du type @code{rhythmic-event}, et plus particulièrement un
415 Les règles spécifiques en matière d'arguments de fin rendent possible
416 l'écriture de fonctions polymorphes telles que @code{\tweak}, qui
417 peuvent s'appliquer à différentes constructions.
420 @node Fonctions de substitution simple
421 @subsection Fonctions de substitution simple
422 @translationof Simple substitution functions
424 Une fonction de substitution simple renvoie une expression musicale
425 écrite au format LilyPond et contient des arguments au format de
426 l'expression résultante. Vous en trouverez une description détaillée à
427 la rubrique @ruser{Exemples de fonction de substitution}.
430 @node Fonctions de substitution intermédiaires
431 @subsection Fonctions de substitution intermédiaires
432 @translationof Intermediate substitution functions
434 Une fonction de substitution intermédiaire est une fonction dont
435 l'expression musicale résultante mélangera du code Scheme au code
438 Certaines commandes @code{\override} nécessitent un argument
439 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
440 cell} en Scheme -- que l'on pourrait traduire par @qq{construction de
443 Cette paire peut se mentionner directement dans la fonction musicale à
444 l'aide d'une variable @code{pair?} :
448 #(define-music-function
449 (parser location beg-end)
452 \once \override Beam.positions = #beg-end
456 \manualBeam #'(3 . 6) c8 d e f
460 Autre manière de procéder, les nombres formant la paire sont transmis
461 comme arguments séparés ; le code Scheme chargé de créer la paire
462 pourra alors être inclus dans l'expression musicale :
464 @lilypond[quote,verbatim,ragged-right]
466 #(define-music-function
467 (parser location beg end)
470 \once \override Beam.positions = #(cons beg end)
474 \manualBeam #3 #6 c8 d e f
479 @cindex temporaire, dérogation (override)
480 @cindex dérogation temporaire (override)
481 @cindex propriétés, retour à la valeur précédente
483 L'entretien des propriétés peut se voir comme un empilement par
484 propriété par objet par contexte. Les fonctions musicales peuvent
485 nécessiter des dérogatoins pour une ou plusieurs propriétés pour la
486 durée de la fonction, puis de revenir aux valeurs précédentes avant de
487 quitter. Néanmoins, une dérogation normale va retirer de la pile -- ou
488 dépiler -- et supprimer le sommet de la pile de la propriété avant
489 d'y ajouter quoi que ce soit -- ou empiler -- ; la valeur précédente de
490 la propriété est de fait perdue. Lorsque la valeur antérieure doit être
491 préservée, l'instruction @code{\override} devra être préfixée d'un
492 @code{\temporary}, comme ceci :
495 \temporary \override @dots{}
498 L'utilisation d'un @code{\temporary} a pour effet d'effacer la propriété
499 @code{pop-first} (@emph{commence par dépiler} normalement activée) de la
500 dérogation ; la valeur antérieure ne sera alors pas supprimée de la pile
501 de la propriété avant d'y empiler la nouvelle valeur. Lorsqu'un
502 @code{\revert} viendra par la suite supprimer la valeur dérogatoire
503 temporaire, réapparaitra la valeur antérieure.
505 En d'autres termes, un @code{\revert} qui suit un @code{\temporary
506 \override} pour la même propriété n'apporte rien. Ce principe est aussi
507 valable pour une couple @code{\temporary} et @code{\undo} sur la même
508 musique contenant des dérogations.
510 Voici un exemple de fonction musicale utilisant cette fonctionnalité.
511 La présence du @code{\temporary} permet de s'assurer qu'en sortant de la
512 fonction, les propriétés @code{cross-staff} et @code{style} retrouveront
513 les valeurs qu'elles avaient que ne soit appelée la fonction
514 @code{crossStaff}. En l'absence de @code{\temporary}, ces propriétés
515 auraient retrouvé leurs valeurs par défaut à la sortie de la fonction.
519 #(define-music-function (parser location notes) (ly:music?)
520 (_i "Create cross-staff stems")
522 \temporary \override Stem.cross-staff = #cross-staff-connect
523 \temporary \override Flag.style = #'no-flag
525 \revert Stem.cross-staff
531 @node De l'usage des mathématiques dans les fonctions
532 @subsection De l'usage des mathématiques dans les fonctions
533 @translationof Mathematics in functions
535 Une fonction musicale peut requérir, en plus d'une simple substitution,
536 une part de programmation en Scheme.
538 @lilypond[quote,verbatim,ragged-right]
540 #(define-music-function
541 (parser location mag)
544 \override Stem.length = #(* 7.0 mag)
545 \override NoteHead.font-size =
546 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
551 \revert NoteHead.font-size
556 \AltOn #1.5 c c \AltOff c2
561 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
562 s'applique à une expression musicale :
564 @lilypond[quote,verbatim,ragged-right]
566 #(define-music-function
567 (parser location mag music)
570 \override Stem.length = #(* 7.0 mag)
571 \override NoteHead.font-size =
572 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
575 \revert NoteHead.font-size
579 c2 \withAlt #0.5 { c4 c }
580 \withAlt #1.5 { c c } c2
585 @node Fonctions dépourvues d'argument
586 @subsection Fonctions dépourvues d'argument
587 @translationof Functions without arguments
589 Dans la plupart des cas, une fonction dépourvue d'argument devrait
590 être créée à l'aide d'une variable :
593 dolce = \markup@{ \italic \bold dolce @}
596 Il peut, dans certains cas particuliers, s'avérer utile de créer une
597 fonction sans argument comme ici,
601 #(define-music-function
604 (if (eq? #t (ly:get-option 'display-bar-numbers))
605 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
610 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
611 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
612 en respectant la syntaxe
615 lilypond -d display-bar-numbers MONFICHIER.ly
619 @node Fonctions musicales fantômes
620 @subsection Fonctions musicales fantômes
621 @translationof Void music functions
623 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
624 une fonction musicale peut n'être exécutée que dans le but d'en retenir
625 les effets annexes ; vous devrez alors utiliser une procédure
626 @code{define-void-function}. Il peut cependant arriver que vous ayez
627 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
628 l'exemple de la rubrique précédente) une expression musicale.
629 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
630 expression musicale @code{void}.
633 @node Fonctions événementielles
634 @section Fonctions événementielles
635 @translationof Event functions
637 @funindex define-event-function
638 @cindex événementielle, fonction
640 L'utilisation d'une fonction musicale pour placer un événement requiert
641 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
642 à la syntaxe de la construction à remplacer. C'est par exemple le cas
643 lorsque vous voulez écrire une commande de nuance, instruction qui
644 ne comporte habituellement pas d'indicateur de positionnement, comme
645 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
648 @lilypond[quote,verbatim,ragged-right]
649 dyn=#(define-event-function (parser location arg) (markup?)
650 (make-dynamic-script arg))
651 \relative c' { c\dyn pfsss }
654 Vous pourriez obtenir le même résultat avec une fonction musicale, à
655 ceci près que chaque appel à la fonction devra être précédé d'un
656 indicateur de positionnement, comme @code{c-\dyn pfsss}.
659 @node Fonctions pour markups
660 @section Fonctions pour @emph{markups}
661 @translationof Markup functions
663 Les @emph{markups} sont implémentés au travers de fonctions Scheme
664 spécifiques qui produisent des objets @code{Stencil} comprenant un
665 certain nombre d'arguments.
668 * Construction d'un markup en Scheme::
669 * Fonctionnement interne des markups::
670 * Définition d'une nouvelle commande de markup::
671 * Définition d'une nouvelle commande de liste de markups::
675 @node Construction d'un markup en Scheme
676 @subsection Construction d'un @emph{markup} en Scheme
677 @translationof Markup construction in Scheme
679 @cindex définition d'une commande markup
681 @funindex \displayScheme
683 Les expressions @emph{markup} sont représentées en Scheme de manière
684 interne par la macro @code{markup} :
687 (markup @var{expression})
690 La commande @code{\displayScheme} permet d'obtenir la représentation en
691 Scheme d'une expression @emph{markup} :
697 \line @{ \bold \italic "hello" \raise #0.4 "world" @}
698 \larger \line @{ foo bar baz @}
704 Compiler ce code renverra en console les lignes suivantes :
711 (#:bold (#:italic "hello") #:raise 0.4 "world")
714 (#:simple "foo" #:simple "bar" #:simple "baz")))))
717 L'impression du @emph{markup} sera suspendue dès lors qu'apparaîtra un
718 @w{@samp{\void \displayScheme @var{markup}}}. Tout comme pour la
719 commande @code{\displayMusic}, le résultat de @code{\displayScheme} peut
720 être sauvegardé dans un fichier séparé. Voir à ce sujet
721 @ref{Affichage d'expressions musicales}.
724 Vous pouvez constater les principales règles de traduction entre les
725 syntaxes respectives de LilyPond et de Scheme en matière de
726 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
727 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
728 utiliser la macro @code{markup} en Scheme exclusivement.
731 @multitable @columnfractions .3 .3
732 @item @b{LilyPond} @tab @b{Scheme}
733 @item @code{\markup markup1} @tab @code{(markup markup1)}
734 @item @code{\markup @{ markup1 markup2@dots{} @}} @tab
735 @code{(markup markup1 markup2@dots{} )}
736 @item @code{\commande-markup} @tab @code{#:commande-markup}
737 @item @code{\variable} @tab @code{variable}
738 @item @code{\center-column @{ @dots{} @}} @tab
739 @code{#:center-column ( @dots{} )}
740 @item @code{chaîne} @tab @code{"chaîne"}
741 @item @code{#argument-scheme} @tab @code{argument-scheme}
745 L'intégralité du langage Scheme est accessible à l'intérieur même de la
746 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
747 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
748 particulièrement pratique lorsque vous créez votre propre commande de
749 @emph{markup} -- voir
750 @ref{Définition d'une nouvelle commande de markup}.
753 L'argument @var{markup-list} des commandes @code{#:line},
754 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
755 résultat de l'appel à une fonction.
758 (markup #:line (fonction-qui-retourne-des-markups))
762 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
763 @code{make-line-markup}, @code{make-center-markup} ou
764 @code{make-column-markup} :
767 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
771 @node Fonctionnement interne des markups
772 @subsection Fonctionnement interne des @emph{markups}
773 @translationof How markups work internally
775 Dans un @emph{markup} tel que
778 \raise #0.5 "text example"
782 @code{\raise} représente en fait la fonction @code{raise-markup}.
783 L'expression @emph{markup} est enregistrée sous la forme
786 (list raise-markup 0.5 (list simple-markup "text example"))
789 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
790 la fonction @code{raise-markup} est appelée ainsi :
795 @var{liste des alists de propriété}
797 @var{le @emph{markup} "text example"})
800 La fonction @code{raise-markup} commence par créer le stencil pour la
801 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
802 portée. Il s'agit là d'un exemple relativement simple, et nous en
803 aborderons de plus complexes au fil des paragraphes suivants ;
804 d'autres exemples se trouvent directement dans le fichier
805 @file{scm/define-markup-commands.scm}.
808 @node Définition d'une nouvelle commande de markup
809 @subsection Définition d'une nouvelle commande de @emph{markup}
810 @translationof New markup command definition
812 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
813 commande de @emph{markup}.
816 * Syntaxe d'une commande markup::
817 * Attribution de propriétés::
819 * Adaptation d'une commande incorporée::
823 @node Syntaxe d'une commande markup
824 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
825 @translationof Markup command definition syntax
827 Une commande de @emph{markup} personnalisée se définit à l'aide de la
828 macro Scheme @code{define-markup-command}, placée en tête de fichier.
831 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2}@dots{})
832 (@var{arg1-type?} @var{arg2-type?}@dots{})
833 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
835 @dots{}corps de la commande@dots{})
838 Quelques commentaires sur les arguments :
841 @item @var{nom-commande}
842 le nom que vous attribuez à votre commande de @emph{markup}.
844 la définition du @qq{layout} -- son formatage.
846 une liste de listes associatives, comprenant toutes les propriétés actives.
848 le @var{ième} argument de la commande.
849 @item @var{argi-type?}
850 un type de prédicat pour le @var{ième} argument.
853 Si la commande utilise des propriétés à partir des arguments
854 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
855 différentes propriétés ainsi que leur valeur par défaut.
857 Les arguments se distinguent selon leur type :
859 @item un @emph{markup}, correspondant au type de prédicat
860 @code{markup?}@tie{};
861 @item une liste de @emph{markups}, correspondant au type de prédicat
862 @code{markup-list?}@tie{};
863 @item tout autre objet Scheme, correspondant au types de prédicat tels
864 que @code{list?}, @code{number?}, @code{boolean?}, etc.
867 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
868 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
869 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
870 ceci de particulier qu'elles peuvent s'appliquer à des listes de
871 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
872 tous les éléments de la liste originelle se verront appliquer cette
873 fonction @emph{markup} avec ses arguments de tête.
875 La réplication des arguments de tête dans le but d'appliquer une
876 fonction @emph{markup} à une liste de markups est économique,
877 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
878 ainsi d'éventuelles pertes de performance en utilisant des arguments
879 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
880 le dernier argument est un @emph{markup}.
883 @cindex macro de markup
885 @funindex interpret-markup
887 Les commandes de @emph{markup} ont un cycle de vie relativement
888 complexe. Le corps de la définition d'une commande de @emph{markup} est
889 chargé de convertir les arguments de la commande en expression stencil
890 qui sera alors renvoyée. Bien souvent, ceci s'accomplit par un appel à
891 la fonction @code{interpret-markup}, en lui passant les arguments
892 @var{layout} et @var{props}. Ces arguments ne seront en principe connus
893 que bien plus tardivement dans le processus typographique. Lors de
894 l'expansion d'une expression LilyPond @code{\markup} ou d'une macro
895 Scheme @code{macro}, les expressions @emph{markup} auront déjà vu leurs
896 composants assemblés en expressions @emph{markup}. L'évaluation et le
897 contrôle du type des arguments à une commande de @emph{markup}
898 n'interviennent qu'au moment de l'interprétation de @code{\markup} ou
901 Seule l'application de @code{interpret-markup} sur une expression
902 @emph{markup} réalisera effectivement la conversion des expressions
903 @emph{markup} en stencil, au travers de l'exécution du corps des
904 fonctions @emph{markup}.
907 @node Attribution de propriétés
908 @unnumberedsubsubsec Attribution de propriétés
909 @translationof On properties
911 Les arguments @code{layout} et @code{props} d'une commande de
912 @emph{markup} fournissent un contexte à l'interprétation du
913 @emph{markup} : taille de fonte, longueur de ligne etc.
915 L'argument @code{layout} permet d'accéder aux propriétés définies dans
916 les blocs @code{\paper}, grâce à la fonction
917 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
918 identique à celle de la partition, est lue au travers de
921 (ly:output-def-lookup layout 'line-width)
924 L'argument @code{props} rend certaines propriétés accessibles aux
925 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
926 d'un @emph{markup} de titre d'ouvrage : toutes les variables
927 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
928 @code{props}, de telle sorte que le @emph{markup} de titrage de
929 l'ouvrage pourra accéder aux différents champs titre, compositeur etc.
930 Ceci permet aussi de configurer le comportement d'une commande de
931 @emph{markup} : la taille des fontes, par exemple, est lue à
932 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
933 La fonction appelant une commande de @emph{markup} peut altérer la
934 valeur de la propriété taille des fontes et donc en modifier le
935 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
936 @code{define-markup-command}, permet de spécifier les propriétés devant
937 être lues parmi les arguments @code{props}.
939 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
940 commande de @emph{markup}, accéder aux différentes propriétés et les
944 @node Exemple commenté
945 @unnumberedsubsubsec Exemple commenté
946 @translationof A complete example
948 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
951 Commençons par construire quelque chose d'approximatif à l'aide d'un
952 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
953 indique la commande @code{\box}, qui semble ici appropriée.
955 @lilypond[quote,verbatim,ragged-right]
956 \markup \box \box HELLO
959 Dans un souci d'esthétique, nous aimerions que le texte et les
960 encadrements ne soient pas autant accolés. Selon la documentation de
961 @code{\box}, cette commande utilise la propriété @code{box-padding},
962 fixée par défaut à 0,2. Cette même documentation nous indique
963 aussi comment la modifier :
965 @lilypond[quote,verbatim,ragged-right]
966 \markup \box \override #'(box-padding . 0.6) \box A
969 L'espacement des deux liserés est cependant toujours trop réduit ;
970 modifions le à son tour :
972 @lilypond[quote,verbatim,ragged-right]
973 \markup \override #'(box-padding . 0.4) \box
974 \override #'(box-padding . 0.6) \box A
977 Vous conviendrez que recopier une telle définition de @emph{markup}
978 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
979 @emph{markup} @code{double-box} qui prendra un seul argument -- le
980 texte. Cette commande se chargera de dessiner les encadrements, en
981 tenant compte des espacements.
984 #(define-markup-command (double-box layout props text) (markup?)
985 "Dessine un double encadrement autour du texte."
986 (interpret-markup layout props
987 #@{\markup \override #'(box-padding . 0.4) \box
988 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
991 ou bien son équivalent
994 #(define-markup-command (double-box layout props text) (markup?)
995 "Dessine un double encadrement autour du texte."
996 (interpret-markup layout props
997 (markup #:override '(box-padding . 0.4) #:box
998 #:override '(box-padding . 0.6) #:box text)))
1001 @code{text} est le nom de l'argument de notre commande, et
1002 @code{markup?} son type -- l'argument sera identifié comme étant un
1003 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
1004 plupart des commandes de @emph{markup}, construira un stencil à partir
1005 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
1006 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
1007 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
1008 transformation d'une expression @code{\markup} en expression Scheme est
1011 Notre commande personnalisée s'utilise ainsi :
1014 \markup \double-box A
1017 Il serait intéressant de rendre cette commande @code{double-box} plus
1018 souple@tie{}: les valeurs de @code{box-padding} sont figées et ne
1019 peuvent être modifiées à l'envie. Pareillement, il serait bien de
1020 distinguer l'espacement entre les encadrements de l'espacement entre le
1021 texte et ses encadrements. Nous allons donc introduire une propriété
1022 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
1023 de gérer l'espacement des encadrements ; @code{box-padding} ne
1024 servira alors que pour l'espacement intérieur. Voici le code adapté à
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
1038 Ainsi que son équivalent à partir de la macro @emph{markup} :
1041 #(define-markup-command (double-box layout props text) (markup?)
1042 #:properties ((inter-box-padding 0.4)
1044 "Dessine un double encadrement autour du texte."
1045 (interpret-markup layout props
1046 (markup #:override `(box-padding . ,inter-box-padding) #:box
1047 #:override `(box-padding . ,box-padding) #:box text)))
1050 C'est ici le mot-clé @code{#:properties} qui permet de lire les
1051 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
1052 l'argumenet @code{props}@tie{}; on leur a d'ailleurs fourni des valeurs
1053 par défaut au cas où elles ne seraient pas définies.
1055 Ces valeurs permettront alors d'adapter les propriétés de
1056 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
1057 aurez remarqué, dans l'argument @code{\override}, la présence de
1058 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
1059 permettent d'insérer une valeur variable au sein d'une expression
1062 Notre commande est maintenant prête à servir dans un @emph{markup}, et
1063 les encadrements sont repositionnables.
1065 @lilypond[quote,verbatim,ragged-right]
1066 #(define-markup-command (double-box layout props text) (markup?)
1067 #:properties ((inter-box-padding 0.4)
1069 "Draw a double box around text."
1070 (interpret-markup layout props
1071 #{\markup \override #`(box-padding . ,inter-box-padding) \box
1072 \override #`(box-padding . ,box-padding) \box
1075 \markup \double-box A
1076 \markup \override #'(inter-box-padding . 0.8) \double-box A
1077 \markup \override #'(box-padding . 1.0) \double-box A
1081 @node Adaptation d'une commande incorporée
1082 @unnumberedsubsubsec Adaptation d'une commande incorporée
1083 @translationof Adapting builtin commands
1085 Le meilleur moyen de construire ses propres commandes de @emph{markup}
1086 consiste à prendre exemple sur les commandes déjà incorporées. La
1087 plupart des commandes de @emph{markup} fournies avec LilyPond sont
1088 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
1090 Nous pourrions, par exemple, envisager d'adapter la commande
1091 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
1092 est définie la commande @code{\draw-line}, expurgée de sa
1096 (define-markup-command (draw-line layout props dest)
1099 #:properties ((thickness 1))
1100 "@dots{}documentation@dots{}"
1101 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1105 (make-line-stencil th 0 0 x y)))
1108 Avant de définir notre propre commande basée sur l'une de celles
1109 fournies par LilyPond, commençons par en recopier la définition, puis
1110 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
1111 supprimé sans risque ; il ne sert que lors de la génération de la
1112 documentation et n'est d'aucune utilité pour une commande personnalisée.
1115 (define-markup-command (draw-double-line layout props dest)
1117 #:properties ((thickness 1))
1118 "@dots{}documentation@dots{}"
1119 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1123 (make-line-stencil th 0 0 x y)))
1126 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
1127 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
1128 par défaut de 6 dixièmes :
1131 (define-markup-command (draw-double-line layout props dest)
1133 #:properties ((thickness 1)
1135 "@dots{}documentation@dots{}"
1139 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1140 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1141 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1143 @lilypond[quote,verbatim,ragged-right]
1144 #(define-markup-command (my-draw-line layout props dest)
1146 #:properties ((thickness 1)
1149 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1153 (w (/ line-gap 2.0))
1154 (x (cond ((= dx 0) w)
1156 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1157 (y (* (if (< (* dx dy) 0) 1 -1)
1160 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1161 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1162 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1164 \markup \my-draw-line #'(4 . 3)
1165 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1169 @node Définition d'une nouvelle commande de liste de markups
1170 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1171 @translationof New markup list command definition
1173 @funindex define-markup-list-command
1174 @funindex interpret-markup-list
1176 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1177 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1178 la macro @code{define-markup-command} abordée à la rubrique
1179 @ref{Définition d'une nouvelle commande de markup} à ceci près que cette
1180 dernière renvoie un seul stencil, non une liste de stencils.
1182 La fonction @code{interpret-markup-list}, à l'instar de la fonction
1183 @code{interpret-markup}, permet de convertir une liste de @emph{markups}
1184 en liste de stencils.
1186 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1187 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1188 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1189 par l'argument @code{props}.
1192 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1193 #:properties ((par-indent 2))
1194 (interpret-markup-list layout props
1195 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1198 La version purement Scheme est un peu plus complexe :
1200 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1201 #:properties ((par-indent 2))
1202 (interpret-markup-list layout props
1203 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1207 En dehors des habituels arguments @code{layout} et @code{props}, la
1208 commande de liste de @emph{markups} @code{paragraph} prend en argument
1209 une liste de @emph{markups} appelé @code{args}. Le prédicat des listes
1210 de @emph{markups} est @code{markup-list?}.
1212 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1213 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1214 @code{props}. En cas d'absence, la valeur par défaut sera
1215 de @code{2}. Ensuite est créée une liste de lignes justifiées
1216 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1217 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1218 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1219 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1220 interprétée par la fonction @code{interpret-markup-list}.
1222 Voici comment utiliser cette nouvelle commande de liste de
1223 @emph{markups}@tie{}:
1227 The art of music typography is called \italic @{(plate) engraving.@}
1228 The term derives from the traditional process of music printing.
1229 Just a few decades ago, sheet music was made by cutting and stamping
1230 the music into a zinc or pewter plate in mirror image.
1232 \override-lines #'(par-indent . 4) \paragraph @{
1233 The plate would be inked, the depressions caused by the cutting
1234 and stamping would hold ink. An image was formed by pressing paper
1235 to the plate. The stamping and cutting was completely done by
1242 @node Contextes pour programmeurs
1243 @section Contextes pour programmeurs
1244 @translationof Contexts for programmers
1247 * Évaluation d'un contexte::
1248 * Application d'une fonction à tous les objets de mise en forme::
1252 @node Évaluation d'un contexte
1253 @subsection Évaluation d'un contexte
1254 @translationof Context evaluation
1256 @cindex appel de code durant l'interprétation
1257 @funindex \applyContext
1259 Un contexte peut être modifié, au moment même de son interprétation, par
1260 du code Scheme. La syntaxe consacrée en pareil cas est
1262 \applyContext @var{fonction}
1265 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1266 unique argument : le contexte au sein duquel la commande
1267 @code{\applyContext} est appelée. Les lignes de code qui suivent auront
1268 pour effet d'afficher à l'écran, en cours de compilation, le numéro de
1274 (format #t "\nNous en sommes à la mesure ~a.\n"
1275 (ly:context-property x 'currentBarNumber)))
1279 @node Application d'une fonction à tous les objets de mise en forme
1280 @subsection Application d'une fonction à tous les objets de mise en forme
1281 @translationof Running a function on all layout objects
1283 @cindex appel de code sur des objets de mise en forme
1284 @funindex \applyOutput
1286 La manière la plus souple d'affiner un objet consiste à utiliser la
1287 commande @code{\applyOutput}. Celle-ci va insérer un événement
1288 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1291 \applyOutput @var{Contexte} @var{procédure}
1295 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1297 Lors de l'interprétation de cette commande, la fonction
1298 @code{@var{procédure}} est appelée pout tout objet de rendu appartenant
1299 au contexte @code{@var{Contexte}} à cet instant précis, avec les
1300 arguments suivants :
1302 @item l'objet de rendu en lui-même,
1303 @item le contexte au sein duquel cet objet est créé,
1304 @item et le contexte dans lequel @code{\applyOutput} est effectué.
1307 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1308 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1309 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1310 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1312 Voici une fonction utilisable avec la commande
1313 @code{\applyOutput} : elle @qq{blanchit} la tête des notes se
1314 trouvant sur la ligne médiane ou bien directement à son contact.
1316 @lilypond[quote,verbatim,ragged-right]
1317 #(define (blanker grob grob-origin context)
1318 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1319 (< (abs (ly:grob-property grob 'staff-position)) 2))
1320 (set! (ly:grob-property grob 'transparent) #t)))
1323 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1327 La @var{procédure} sera interprétée au niveau @code{Score}
1328 (partition) ou @code{Staff} dès lors que vous utiliserez l'une des
1332 \applyOutput #'Score #@var{procédure}
1333 \applyOutput #'Staff #@var{procédure}
1337 @node Fonctions de rappel
1338 @section Fonctions de rappel
1339 @translationof Callback functions
1341 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1342 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1346 \override Stem.thickness = #2.0
1349 Une procédure Scheme peut aussi se charger de modifier des
1352 @lilypond[fragment,verbatim,quote,relative=2]
1353 \override Stem.thickness = #(lambda (grob)
1354 (if (= UP (ly:grob-property grob 'direction))
1361 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1362 est nécessaire au processus de mise en forme.
1364 La majeure partie du procédé typographique consiste en la réalisation de
1365 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1366 utilisant particulièrement des rappels, nous mentionnerons
1370 Routine d'impression, construisant le dessin du symbole
1372 Routine effectuant le positionnement horizontal
1374 Routine calculant la largeur d'un objet
1377 La procédure prend un unique argument, en l'occurrence l'objet graphique
1380 Cette procédure, grâce à un appel à la fonction de rappel dévolue à
1381 cette propriété -- mentionnée dans la référence des propriétés internes
1382 et dans le fichier @file{define-grobs.scm} --, pourra accéder à la
1383 valeur usuelle de la propriété :
1387 \override Flag #'X-offset = #(lambda (flag)
1388 (let ((default (ly:flag::calc-x-offset flag)))
1394 Dans le cas où la routine doit faire appel à plusieurs arguments, le
1395 @emph{grob} en cours peut s'insérer à l'aide d'un @emph{grob} enchâssé.
1396 Voici, à titre d'illustration, un réglage pour
1397 @code{AccidentalSuggestion} :
1401 ,(ly:make-simple-closure
1403 ,(ly:make-simple-closure
1404 (list ly:self-alignment-interface::centered-on-x-parent))
1405 ,(ly:make-simple-closure
1406 (list ly:self-alignment-interface::x-aligned-on-self)))))
1410 Ici, aussi bien @code{ly:self-alignment-interface::x-aligned-on-self}
1411 que @code{ly:self-alignment-interface::centered-on-x-parent} font appel
1412 à l'argument @emph{grob}. La fonction @code{+} a pour effet
1413 d'additionner les résultats. L'ensemble est inclus dans un
1414 @code{ly:make-simple-closure} de telle sorte que l'addition s'exécute de
1417 Dans les faits, l'utilisation d'une unique procédure en tant que valeur
1418 d'une propriété revient à écrire
1421 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1425 Le @code{ly:make-simple-closure} intérieur fournit le @emph{grob} en
1426 argument à la procédure @var{proc}, l'extérieur s'assure que le résultat
1427 de la fonction sera bien renvoyé, non pas l'objet @code{simple-closure}.
1429 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1430 @emph{markup} consiste à utiliser la fonction
1431 @code{grob-interpret-markup}, comme ici :
1434 my-callback = #(lambda (grob)
1435 (grob-interpret-markup grob (markup "foo")))
1440 @n ode Code Scheme intégré
1441 @s ection Code Scheme intégré
1442 @t ranslationof Inline Scheme code
1444 À REVOIR : depuis la rédaction de cette section, LilyPond en est
1445 arrivé à un point tel que trouver un exemple @emph{simple} où l'on se
1446 retrouve obligé d'en venir à utiliser du code Scheme devient chose
1449 En attendant un remaniement de cette section, faisons comme si nous
1452 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1453 sa syntaxe. Par exemple, le code suivant produit une erreur de syntaxe
1454 (du moins, c'était le cas auparavant).
1457 F = \tweak font-size #-3 -\flageolet
1465 C'est en se servant du langage Scheme que l'on peut résoudre ce
1466 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1467 @ref{Ajout d'articulation à des notes (exemple)}, en
1468 particulier quant à l'emploi de @code{\displayMusic}.
1471 F = #(let ((m (make-music 'ArticulationEvent
1472 'articulation-type "flageolet")))
1473 (set! (ly:music-property m 'tweaks)
1474 (acons 'font-size -3
1475 (ly:music-property m 'tweaks)))
1484 Ici les propriétés @code{tweak} de l'objet flageolet nommé
1485 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
1486 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1487 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1488 @code{acons}), et le résultat de cette opération est renvoyé par
1489 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1490 finale de @samp{m} lui-même.
1495 @node Retouches complexes
1496 @section Retouches complexes
1497 @translationof Difficult tweaks
1499 Certains réglages sont plus délicats que d'autres.
1503 L'un d'entre eux est l'apparence des objets dits @qq{extenseurs}
1504 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1505 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1506 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1507 changement de ligne, ils sont dupliqués au début du ou des systèmes
1508 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1509 héritent toutes les propriétés, y compris les éventuelles commandes
1512 En d'autres termes, une commande @code{\override} affecte toujours les
1513 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1514 partie précédant ou suivant le changement de ligne, il faut intervenir
1515 directement dans le processus de mise en page.
1516 La fonction de rappel @code{after-line-breaking} contient toute
1517 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1518 déterminés, et que des objets graphiques ont été divisés sur des
1519 systèmes différents.
1521 Dans l'exemple suivant, on définit une nouvelle opération nommée
1522 @code{my-callback}. Cette opération
1526 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1528 dans l'affirmative, recherche les différents morceaux de l'objet
1530 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1533 dans l'affirmative, applique un espacement supplémentaire
1534 (@code{extra-offset}).
1537 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1538 de façon à ce que le deuxième morceau d'une liaison divisée soit
1542 @lilypond[quote,verbatim,ragged-right]
1543 #(define (my-callback grob)
1545 ;; l'objet a-t-il été divisé ?
1546 (orig (ly:grob-original grob))
1548 ;; si oui, rechercher les morceaux frères (siblings)
1549 (siblings (if (ly:grob? orig)
1550 (ly:spanner-broken-into orig)
1553 (if (and (>= (length siblings) 2)
1554 (eq? (car (last-pair siblings)) grob))
1555 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1558 \override Tie.after-line-breaking =
1566 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1567 rappel @code{after-line-breaking} devra également appeler celle
1568 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1569 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1570 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1574 Pour des raisons d'ordre technique, certains objets ne peuvent être
1575 modifiés par @code{\override}. Parmi ceux-là, les objets
1576 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1577 @code{\overrideProperty} sert à les modifier, de façon similaire à
1578 @code{\once \override} mais avec une syntaxe différente :
1582 Score.NonMusicalPaperColumn % Nom de l'objet
1583 . line-break-system-details % Nom de la propriété
1584 . next-padding % Nom de la sous-propriété (optionnel)
1588 Notez toutefois que la commande @code{\override} peut tout de même être
1589 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1590 bloc @code{\context}.
1595 @node Interfaces LilyPond Scheme
1596 @chapter Interfaces LilyPond Scheme
1597 @translationof LilyPond Scheme interfaces
1599 Ce chapitre aborde les différents outils fournis par LilyPond à
1600 l'intention des programmeurs en Scheme désireux d'obtenir des
1601 informations à partir et autour des fluxs de musique.
1603 TODO -- figure out what goes in here and how to organize it