1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 29d5e0a64d0eee69e4ebee1e76e4df26ae58190b
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @c Translators: Valentin Villenave, Jean-Charles Malahieude
14 @c Translation checkers: Gilles Thibault
16 @node Interfaces pour programmeurs
17 @chapter Interfaces pour programmeurs
18 @translationof Interfaces for programmers
20 Scheme permet de réaliser des affinages très pointus. Si vous ne
21 connaissez rien de Scheme, vous en aurez un aperçu au travers de notre
22 @ref{Tutoriel Scheme}.
25 * Blocs de code LilyPond::
27 * Fonctions musicales::
28 * Fonctions événementielles::
29 * Fonctions pour markups::
30 * Contextes pour programmeurs::
31 * Fonctions de rappel::
32 * Code Scheme intégré::
33 * Retouches complexes::
37 @node Blocs de code LilyPond
38 @section Blocs de code LilyPond
39 @translationof LilyPond code blocks
41 @cindex code, blocs LilyPond
42 @cindex LilyPond, bloc de code
48 L'utilisation de Scheme pour créer des expressions musicales peut
49 s'avérer ardue, principalement à cause des imbrications et de la
50 longueur du code Scheme qui en résulte. Dans le cas de tâches
51 simples, on peut toutefois contourner une partie du problème en
52 utilisant des blocs de code LilyPond, ce qui autorise la syntaxe
53 habituelle de LilyPond au sein même de Scheme.
55 Les blocs de code LilyPond ressemblent à
58 #@{ @var{du code LilyPond} #@}
61 En voici un exemple basique :
63 @lilypond[verbatim,quote]
64 ritpp = #(define-event-function (parser location) ()
71 Les blocs de code LilyPond peuvent s'utiliser partout où vous pouvez
72 écrire du code Scheme. Le lecteur Scheme est en fait quelque peu adapté
73 pour accepter des blocs de code LilyPond ; il est capable de traiter des
74 expressions Scheme intégrées débutant par @code{$} ou @code{#}.
76 @cindex parser (fonction argument)
79 Le lecteur Scheme extrait le bloc de code LilyPond et déclenche un appel
80 à l'analyseur grammatical de LilyPond (le @code{parser}) qui réalise en
81 temps réel l'interprétation de ce bloc de code LilyPond. Toute
82 expression Scheme imbriquée est exécutée dans l'environnement lexical du
83 bloc de code LilyPond, de telle sorte que vous avez accès aux variables
84 locales et aux paramètres de la fonction au moment même où le bloc de
85 code LilyPond est écrit. Les variables définies dans d'autres modules
86 Scheme, tels ceux contenant les blocs @code{\header} ou @code{\layout},
87 ne sont pas accessibles en tant que variables Scheme (préfixées par
88 un @code{#}) mais en tant que variables LilyPond (préfixées par
91 Lorsque l'emplacement (@code{location} -- voir @ref{Fonctions Scheme})
92 fait référence à un endroit valide dans la source -- ce qui est en
93 général le cas au sein de fonctions musicales ou Scheme --, toute la
94 musique générée au sein de ce bloc de code voit son @code{origine}
95 établie à cet @emph{emplacement}.
97 Un bloc de code LilyPond peut contenir tout ce que vous pourriez mettre
98 à droite de l'assignation. Par ailleurs, un bloc LilyPond vide
99 correspond à une expression fantôme, et un bloc LilyPond de multiples
100 événements musicaux sera transformé en une expression de musique
104 @node Fonctions Scheme
105 @section Fonctions Scheme
106 @translationof Scheme functions
108 @cindex Scheme, fonctions (syntaxe LilyPond)
110 Les @emph{fonctions Scheme} sont des procédures Scheme chargées de créer
111 des expressions Scheme à partir de code rédigé selon la syntaxe de
112 LilyPond. Elles peuvent être appelées en de nombreux endroits, à l'aide
113 d'un @code{#}, où spécifier une valeur en syntaxe Scheme est autorisé.
114 Bien que Scheme dispose de fonctions en propre, nous nous intéresserons,
115 au fil des paragraphes qui suivent, aux fonctions @emph{syntaxiques},
116 autrement dit des fonctions qui reçoivent des arguments libellés dans la
120 * Définition de fonctions Scheme::
121 * Utilisation de fonctions Scheme::
122 * Fonctions Scheme fantômes::
125 @node Définition de fonctions Scheme
126 @subsection Définition de fonctions Scheme
127 @translationof Scheme function definitions
129 @funindex define-scheme-function
131 D'une manière générale, une fonction Scheme se définit ainsi :
135 #(define-scheme-function
136 (parser location @var{arg1} @var{arg2}@dots{})
137 (@var{type1?} @var{type2?}@dots{})
144 @multitable @columnfractions .33 .66
146 @tab doit être littéralement @code{parser}, de telle sorte que
147 l'analyseur grammatical puisse accéder aux blocs de code LilyPond
148 (@code{#@{}@dots{}@code{#@}}).
150 @item @code{location}
151 @tab doit être littéralement @code{location}, de telle sorte que soit
152 accessible l'emplacement de l'objet dans la source, aux fins de
153 transmettre aux messages d'erreur les fichier et numéro de ligne.
155 @item @code{@var{argN}}
156 @tab @var{n}ième argument
158 @item @code{@var{typeN?}}
159 @tab un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
160 devra retourner @code{#t}. Certains de ces prédicats, comme nous le
161 verrons plus loin, bénéficient d'un traitement particulier de la part du
162 @emph{parser}. De même existe une forme spécifique --
163 @code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
164 argument optionnels. En l'absence d'argument réel au moment de l'appel
165 de la fonction, c'est la valeur par défaut qui lui sera substituée. Les
166 valeurs par défaut sont évaluées dès l'apparition de la définition, y
167 compris dans le cas de blocs de code LilyPond ; vous devrez donc,
168 si ces valeurs par défaut ne peuvent être déterminées que plus tard,
169 mentionner une valeur spéciale que vous reconnaîtrez facilement.
170 Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
171 fournir sa valeur par défaut, celle-ci sera considérée comme étant
172 @code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
173 vérifiées ni au moment de la définition, ni à l'exécution ; il est
174 de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
175 par défaut constituée d'une expression musicale est recopiée dès la
176 définition de @code{origin} vers le paramètre @code{location}.
178 @item @code{@var{corps}}
179 @tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
180 servant de valeur de retour de la fonction. Il peut contenir des blocs
181 de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
182 @w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
183 @ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
184 @code{#} permet de référencer des arguments de la fonction -- tel
185 @samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
186 arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
187 Dans le cas où une expression Scheme introduite par @code{#} ne vous
188 permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
189 expression Scheme « immédiate » à l'aide d'un @code{$}, comme
192 Lorsque votre fonction retourne une expression musicale, lui est
193 attribuée la valeur @code{origin}.
197 Certains types de prédicat font l'objet d'un traitement spécial de la
198 part de l'analyseur grammatical, dans la mesure où il n'a aucun autre
199 moyen de reconnaître efficacement les arguments. Il s'agit, à l'heure
200 actuelle, de @code{ly:pitch?} et @code{ly:duration?}.
202 Pour tous les autres prédicats, la recevabilité des arguments est
203 déterminée par un appel effectif au prédicat après que LilyPond les a
204 déjà converti en expression Scheme. Par voie de conséquence, l'argument
205 peut tout à fait se libeller en syntaxe Scheme -- introduite par un
206 @code{#} ou en tant que résultat d'un appel à une fonction Scheme. Par
207 ailleurs, LilyPond convertira en Scheme un certain nombre de
208 constructions purement LilyPond avant même d'en avoir vérifié le
209 prédicat. C'est notamment le cas de la musique, des
210 @emph{postévénements}, des chaînes simples (avec ou sans guillemets),
211 des nombres, des @emph{markups} et listes de @emph{markups}, ainsi que
212 des blocs @emph{score}, @emph{book}, @emph{bookpart}, ou qui définissent
213 un contexte ou un format de sortie.
215 Il existe certaines formes d'expression, comme la plupart du temps où la
216 musique n'est pas bornée par des accolades, où LilyPond doit lire
217 au-delà de cette même expression afin d'en déterminer la fin. Si une
218 telle expression devait, après évaluation du prédicat, faire l'objet
219 d'un argument optionnel, LilyPond n'aurait aucun moyen, à partir du
220 moment où il aura décidé que l'expression ne correspond pas au
221 paramètre, de @qq{revenir en arrière}. C'est la raison pour laquelle
222 certaines formes musicales devraient être bornées par des accolades pour
223 que LilyPond puisse les reconnaître efficacement. Il existe d'autres
224 situations pour lesquelles LilyPond lèvera toute ambiguïté grâce aux
225 fonctions de prédicat : un @samp{-3} est-il un @emph{postévénement}
226 de type doigté ou un nombre négatif@tie{}? Un @code{"a" 4} en mode
227 paroles est-il une chaîne suivie d'un nombre ou bien un événement
228 syllabe de durée @code{4} ? LilyPond répondra à ces questions
229 après consultation du prédicat. Pour toutes ces raisons, nous vous
230 enjoignons à éviter d'utiliser des prédicats permissifs tel que
231 @code{scheme?}, dès que vous voulez les utiliser dans un but particulier
232 plutôt que dans une fonction de portée générale.
234 Les différents types des prédicat propres à LilyPond sont recensés à
235 l'annexe @ruser{Types de prédicats prédéfinis}.
239 @ruser{Types de prédicats prédéfinis}.
241 Fichiers d'initialisation :
242 @file{lily/music-scheme.cc},
247 @node Utilisation de fonctions Scheme
248 @subsection Utilisation de fonctions Scheme
249 @translationof Scheme function usage
251 Vous pouvez appeler une fonction Scheme pratiquement partout où une
252 expression Scheme derrière un @code{#} peut prendre place. Vous appelez
253 une fonction Scheme en faisant précéder son nom d'un @code{\}, et en le
254 faisant suivre de ses arguments. Lorsqu'un prédicat d'argument
255 optionnel ne correspond pas à un argument, LilyPond l'ignore ainsi que
256 tous les arguments optionnels qui suivent, les remplaçant par leur
257 valeur par défaut, et @qq{sauvegarde} en tant que prochain argument
258 obligatoire l'argument qui ne correspondait pas. Dans la mesure où
259 l'argument sauvegardé doit servir, les argument optionnels ne sont en
260 fait pas considérés comme optionnels, sauf à être suivis d'un argument
263 Une exception cependant à cette règle : le fait de donner un
264 @code{\default} en tant qu'argument optionnel aura pour résultat que cet
265 argument et tous les autres arguments optionnels qui suivent seront
266 ignorés et remplacés par leur valeur par défaut. Il en va de même
267 lorsqu'aucun argument obligatoire ne suit, du fait que @code{\default}
268 ne requiert pas de sauvegarde. C'est d'ailleurs ainsi que fonctionnent
269 les commandes @code{mark} et @code{key}, qui retrouvent leur
270 comportement par défaut lorsque vous les faites suivre d'un
273 En plus de là où une expression Scheme est requise, il y a quelques
274 endroits où des expressions @code{#} sont acceptées et évaluées
275 uniquement pour leurs effets annexes. Il s'agit, dans la plupart des
276 cas, d'endroits où une affectation serait tout à fait envisageable.
278 Dans la mesure où il n'est pas bon de renvoyer une valeur qui pourrait
279 être mal interprétée dans certains contextes, nous vous enjoignons à
280 utiliser des fonctions Scheme normales uniquement dans les cas où vous
281 renvoyez toujours une valeur utile, et une fonction fantôme -- voir
282 @ref{Fonctions Scheme fantômes} -- dans le cas contraire.
285 @node Fonctions Scheme fantômes
286 @subsection Fonctions Scheme fantômes
287 @translationof Void scheme functions
289 @cindex @emph{void}, fonction
290 @cindex fantôme, fonction
292 @funindex define-void-function
295 Il arrive qu'une procédure soit exécutée pour réaliser une action, non
296 pour renvoyer une valeur. Certains langages de programmation, tels
297 le C et Scheme, utilisent des fonctions dans les deux cas et se
298 débarrassent tout bonnement de la valeur renvoyée ; en règle
299 générale, il suffit que l'expression fasse office de déclaration, et
300 d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
301 la plupart des compilateurs C actuels déclenchent un avertissement si
302 l'on se débarrasse de certaines expressions non @emph{void}. Pour de
303 nombreuses fonctions réalisant une action, les standards Scheme
304 déclarent que la valeur de retour est indéfinie. L'interpréteur Guile
305 qu'utilise le Scheme de LilyPond dispose d'une valeur unique
306 @code{*unspecified*} qu'il retourne alors, en règle générale -- notamment
307 lorsqu'on utilise @code{set!} directement sur une variable -- mais
308 malheureusement pas toujours.
310 Une fonction LilyPond définie à l'aide de la clause
311 @code{define-void-function} vous apporte l'assurance que c'est cette
312 valeur spéciale -- la seule valeur qui satisfasse au prédicat
313 @code{void?} -- qui sera retournée.
317 #(define-void-function
320 (ly:set-option 'point-and-click #f))
322 \noPointAndClick % desactive le "pointer-cliquer"
325 L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
326 expression pour ses effets annexes sans interprétation d'une quelconque
330 \void #(hashq-set! une-table une-clé une-valeur)
333 Vous serez alors assuré que LilyPond ne tentera pas d'affecter un sens à
334 la valeur de retour, à quelque endroit qu'elle ressorte. Ceci est aussi
335 opérationnel dans le cadre de fonctions musicales telles que
336 @code{\displayMusic}.
339 @node Fonctions musicales
340 @section Fonctions musicales
341 @translationof Music functions
343 @cindex musicale, fonction
345 Les @emph{fonctions musicales} sont des procédures Scheme capables de
346 créer automatiquement des expressions musicales ; elles permettent
347 de grandement simplifier un fichier source.
350 * Définition de fonctions musicales::
351 * Utilisation de fonctions musicales::
352 * Fonctions de substitution simple::
353 * Fonctions de substitution intermédiaires::
354 * De l'usage des mathématiques dans les fonctions::
355 * Fonctions dépourvues d'argument::
356 * Fonctions musicales fantômes::
360 @node Définition de fonctions musicales
361 @subsection Définition de fonctions musicales
362 @translationof Music function definitions
364 @cindex fonction musicale, définition
366 @funindex define-music-function
368 Une fonction musicale se définit ainsi :
372 #(define-music-function
373 (parser location @var{arg1} @var{arg2}@dots{})
374 (@var{type1?} @var{type2?}@dots{})
379 de manière similaire aux @ref{Définition de fonctions Scheme, fonctions
380 Scheme}. La plupart du temps, le @code{corps} sera constitué d'un
381 @ref{Blocs de code LilyPond, bloc de code Lilypond}.
383 Les différents types des prédicat sont recensés à l'annexe
384 @ruser{Types de prédicats prédéfinis}.
388 @ruser{Types de prédicats prédéfinis}.
390 Fichiers d'initialisation :
391 @file{lily/music-scheme.cc},
396 @node Utilisation de fonctions musicales
397 @subsection Utilisation de fonctions musicales
398 @translationof Music function usage
400 Une fonction musicale peut prendre place en différents endroits.
401 Certaines restrictions s'appliqueront selon l'endroit où elle est
402 utilisée, de telle sorte que l'analyse syntaxique soit sans ambiguïté.
403 Le résultat renvoyé par une fonction musicale doit être compatible avec
404 le contexte dans lequel elle est appelée.
408 Dans une expression musicale de haut niveau@tie{}: aucune restriction.
411 En tant que post-événement, explicitement introduit par un indicateur de
412 positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@code{_}. Notez
413 bien que le renvoi d'un post-événement est valide lorsque la fonction
414 musicale est appelée comme de la musique normale ; ceci amène à un
415 résultat ressemblant à
420 Dans ce cas particulier, vous ne pouvez utiliser une expression musicale
421 @emph{ouverte} en tant que dernier argument -- argument qui se
422 composerait d'une expression musicale susceptible d'accepter des
423 post-événements additionnels.
426 En tant que partie d'un accord. L'expression musicale renvoyée doit
427 être du type @code{rhythmic-event}, et plus particulièrement un
432 Les règles spécifiques en matière d'arguments de fin rendent possible
433 l'écriture de fonctions polymorphes telles que @code{\tweak}, qui
434 peuvent s'appliquer à différentes constructions.
437 @node Fonctions de substitution simple
438 @subsection Fonctions de substitution simple
439 @translationof Simple substitution functions
441 Une fonction de substitution simple renvoie une expression musicale
442 écrite au format LilyPond et contient des arguments au format de
443 l'expression résultante. Vous en trouverez une description détaillée à
444 la rubrique @ruser{Exemples de fonction de substitution}.
447 @node Fonctions de substitution intermédiaires
448 @subsection Fonctions de substitution intermédiaires
449 @translationof Intermediate substitution functions
451 Une fonction de substitution intermédiaire est une fonction dont
452 l'expression musicale résultante mélangera du code Scheme au code
455 Certaines commandes @code{\override} nécessitent un argument
456 supplémentaire constitué d'une paire de nombres, appelée @emph{cons
457 cell} en Scheme -- que l'on pourrait traduire par @qq{construction de
460 Cette paire peut se mentionner directement dans la fonction musicale à
461 l'aide d'une variable @code{pair?} :
465 #(define-music-function
466 (parser location beg-end)
469 \once \override Beam.positions = #beg-end
473 \manualBeam #'(3 . 6) c8 d e f
477 Autre manière de procéder, les nombres formant la paire sont transmis
478 comme arguments séparés ; le code Scheme chargé de créer la paire
479 pourra alors être inclus dans l'expression musicale :
481 @lilypond[quote,verbatim,ragged-right]
483 #(define-music-function
484 (parser location beg end)
487 \once \override Beam.positions = #(cons beg end)
491 \manualBeam #3 #6 c8 d e f
496 @cindex temporaire, dérogation (override)
497 @cindex dérogation temporaire (override)
498 @cindex propriétés, retour à la valeur précédente
500 L'entretien des propriétés peut se voir comme un empilement par
501 propriété par objet par contexte. Les fonctions musicales peuvent
502 nécessiter des dérogatoins pour une ou plusieurs propriétés pour la
503 durée de la fonction, puis de revenir aux valeurs précédentes avant de
504 quitter. Néanmoins, une dérogation normale va retirer de la pile -- ou
505 dépiler -- et supprimer le sommet de la pile de la propriété avant
506 d'y ajouter quoi que ce soit -- ou empiler -- ; la valeur précédente de
507 la propriété est de fait perdue. Lorsque la valeur antérieure doit être
508 préservée, l'instruction @code{\override} devra être préfixée d'un
509 @code{\temporary}, comme ceci :
512 \temporary \override @dots{}
515 L'utilisation d'un @code{\temporary} a pour effet d'effacer la propriété
516 @code{pop-first} (@emph{commence par dépiler} normalement activée) de la
517 dérogation ; la valeur antérieure ne sera alors pas supprimée de la pile
518 de la propriété avant d'y empiler la nouvelle valeur. Lorsqu'un
519 @code{\revert} viendra par la suite supprimer la valeur dérogatoire
520 temporaire, réapparaitra la valeur antérieure.
522 En d'autres termes, un @code{\revert} qui suit un @code{\temporary
523 \override} pour la même propriété n'apporte rien. Ce principe est aussi
524 valable pour une couple @code{\temporary} et @code{\undo} sur la même
525 musique contenant des dérogations.
527 Voici un exemple de fonction musicale utilisant cette fonctionnalité.
528 La présence du @code{\temporary} permet de s'assurer qu'en sortant de la
529 fonction, les propriétés @code{cross-staff} et @code{style} retrouveront
530 les valeurs qu'elles avaient que ne soit appelée la fonction
531 @code{crossStaff}. En l'absence de @code{\temporary}, ces propriétés
532 auraient retrouvé leurs valeurs par défaut à la sortie de la fonction.
536 #(define-music-function (parser location notes) (ly:music?)
537 (_i "Create cross-staff stems")
539 \temporary \override Stem.cross-staff = #cross-staff-connect
540 \temporary \override Flag.style = #'no-flag
542 \revert Stem.cross-staff
548 @node De l'usage des mathématiques dans les fonctions
549 @subsection De l'usage des mathématiques dans les fonctions
550 @translationof Mathematics in functions
552 Une fonction musicale peut requérir, en plus d'une simple substitution,
553 une part de programmation en Scheme.
555 @lilypond[quote,verbatim,ragged-right]
557 #(define-music-function
558 (parser location mag)
561 \override Stem.length = #(* 7.0 mag)
562 \override NoteHead.font-size =
563 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
568 \revert NoteHead.font-size
573 \AltOn #1.5 c c \AltOff c2
578 Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
579 s'applique à une expression musicale :
581 @lilypond[quote,verbatim,ragged-right]
583 #(define-music-function
584 (parser location mag music)
587 \override Stem.length = #(* 7.0 mag)
588 \override NoteHead.font-size =
589 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
592 \revert NoteHead.font-size
596 c2 \withAlt #0.5 { c4 c }
597 \withAlt #1.5 { c c } c2
602 @node Fonctions dépourvues d'argument
603 @subsection Fonctions dépourvues d'argument
604 @translationof Functions without arguments
606 Dans la plupart des cas, une fonction dépourvue d'argument devrait
607 être créée à l'aide d'une variable :
610 dolce = \markup@{ \italic \bold dolce @}
613 Il peut, dans certains cas particuliers, s'avérer utile de créer une
614 fonction sans argument comme ici,
618 #(define-music-function
621 (if (eq? #t (ly:get-option 'display-bar-numbers))
622 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
627 de manière à pouvoir afficher les numéros de mesure grâce à un appel à
628 cette fonction. En pareil cas, vous devrez invoquer @command{lilypond}
629 en respectant la syntaxe
632 lilypond -d display-bar-numbers MONFICHIER.ly
636 @node Fonctions musicales fantômes
637 @subsection Fonctions musicales fantômes
638 @translationof Void music functions
640 Une fonction musicale doit renvoyer une expression musicale. Toutefois,
641 une fonction musicale peut n'être exécutée que dans le but d'en retenir
642 les effets annexes ; vous devrez alors utiliser une procédure
643 @code{define-void-function}. Il peut cependant arriver que vous ayez
644 besoin d'une fonction qui, selon le cas, produise ou non (comme dans
645 l'exemple de la rubrique précédente) une expression musicale.
646 L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
647 expression musicale @code{void}.
650 @node Fonctions événementielles
651 @section Fonctions événementielles
652 @translationof Event functions
654 @funindex define-event-function
655 @cindex événementielle, fonction
657 L'utilisation d'une fonction musicale pour placer un événement requiert
658 l'insertion d'un indicateur de position, ce qui peut ne pas correspondre
659 à la syntaxe de la construction à remplacer. C'est par exemple le cas
660 lorsque vous voulez écrire une commande de nuance, instruction qui
661 ne comporte habituellement pas d'indicateur de positionnement, comme
662 dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
665 @lilypond[quote,verbatim,ragged-right]
666 dyn=#(define-event-function (parser location arg) (markup?)
667 (make-dynamic-script arg))
668 \relative c' { c\dyn pfsss }
671 Vous pourriez obtenir le même résultat avec une fonction musicale, à
672 ceci près que chaque appel à la fonction devra être précédé d'un
673 indicateur de positionnement, comme @code{c-\dyn pfsss}.
676 @node Fonctions pour markups
677 @section Fonctions pour @emph{markups}
678 @translationof Markup functions
680 Les @emph{markups} sont implémentés au travers de fonctions Scheme
681 spécifiques qui produisent des objets @code{Stencil} comprenant un
682 certain nombre d'arguments.
685 * Construction d'un markup en Scheme::
686 * Fonctionnement interne des markups::
687 * Définition d'une nouvelle commande de markup::
688 * Définition d'une nouvelle commande de liste de markups::
692 @node Construction d'un markup en Scheme
693 @subsection Construction d'un @emph{markup} en Scheme
694 @translationof Markup construction in Scheme
696 @cindex définition d'une commande markup
698 @funindex \displayScheme
700 Les expressions @emph{markup} sont représentées en Scheme de manière
701 interne par la macro @code{markup} :
704 (markup @var{expression})
707 La commande @code{\displayScheme} permet d'obtenir la représentation en
708 Scheme d'une expression @emph{markup} :
714 \line @{ \bold \italic "hello" \raise #0.4 "world" @}
715 \larger \line @{ foo bar baz @}
721 Compiler ce code renverra en console les lignes suivantes :
728 (#:bold (#:italic "hello") #:raise 0.4 "world")
731 (#:simple "foo" #:simple "bar" #:simple "baz")))))
734 L'impression du @emph{markup} sera suspendue dès lors qu'apparaîtra un
735 @w{@samp{\void \displayScheme @var{markup}}}. Tout comme pour la
736 commande @code{\displayMusic}, le résultat de @code{\displayScheme} peut
737 être sauvegardé dans un fichier séparé. Voir à ce sujet
738 @ref{Affichage d'expressions musicales}.
741 Vous pouvez constater les principales règles de traduction entre les
742 syntaxes respectives de LilyPond et de Scheme en matière de
743 @emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
744 @code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
745 utiliser la macro @code{markup} en Scheme exclusivement.
748 @multitable @columnfractions .3 .3
749 @item @b{LilyPond} @tab @b{Scheme}
750 @item @code{\markup markup1} @tab @code{(markup markup1)}
751 @item @code{\markup @{ markup1 markup2@dots{} @}} @tab
752 @code{(markup markup1 markup2@dots{} )}
753 @item @code{\commande-markup} @tab @code{#:commande-markup}
754 @item @code{\variable} @tab @code{variable}
755 @item @code{\center-column @{ @dots{} @}} @tab
756 @code{#:center-column ( @dots{} )}
757 @item @code{chaîne} @tab @code{"chaîne"}
758 @item @code{#argument-scheme} @tab @code{argument-scheme}
762 L'intégralité du langage Scheme est accessible à l'intérieur même de la
763 macro @code{markup}. Vous pouvez ainsi appeler des fonctions à partir
764 de @code{markup} pour manipuler des chaînes de caractères, ce qui est
765 particulièrement pratique lorsque vous créez votre propre commande de
766 @emph{markup} -- voir
767 @ref{Définition d'une nouvelle commande de markup}.
770 L'argument @var{markup-list} des commandes @code{#:line},
771 @code{#:center} ou @code{#:column} ne saurait être une variable ni le
772 résultat de l'appel à une fonction.
775 (markup #:line (fonction-qui-retourne-des-markups))
779 n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
780 @code{make-line-markup}, @code{make-center-markup} ou
781 @code{make-column-markup} :
784 (markup (make-line-markup (fonction-qui-retourne-des-markups)))
788 @node Fonctionnement interne des markups
789 @subsection Fonctionnement interne des @emph{markups}
790 @translationof How markups work internally
792 Dans un @emph{markup} tel que
795 \raise #0.5 "text example"
799 @code{\raise} représente en fait la fonction @code{raise-markup}.
800 L'expression @emph{markup} est enregistrée sous la forme
803 (list raise-markup 0.5 (list simple-markup "text example"))
806 Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
807 la fonction @code{raise-markup} est appelée ainsi :
812 @var{liste des alists de propriété}
814 @var{le @emph{markup} "text example"})
817 La fonction @code{raise-markup} commence par créer le stencil pour la
818 chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
819 portée. Il s'agit là d'un exemple relativement simple, et nous en
820 aborderons de plus complexes au fil des paragraphes suivants ;
821 d'autres exemples se trouvent directement dans le fichier
822 @file{scm/define-markup-commands.scm}.
825 @node Définition d'une nouvelle commande de markup
826 @subsection Définition d'une nouvelle commande de @emph{markup}
827 @translationof New markup command definition
829 Nous allons étudier dans ce qui suit la manière de définir une nouvelle
830 commande de @emph{markup}.
833 * Syntaxe d'une commande markup::
834 * Attribution de propriétés::
836 * Adaptation d'une commande incorporée::
840 @node Syntaxe d'une commande markup
841 @unnumberedsubsubsec Syntaxe d'une commande @emph{markup}
842 @translationof Markup command definition syntax
844 Une commande de @emph{markup} personnalisée se définit à l'aide de la
845 macro Scheme @code{define-markup-command}, placée en tête de fichier.
848 (define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2}@dots{})
849 (@var{arg1-type?} @var{arg2-type?}@dots{})
850 [ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
852 @dots{}corps de la commande@dots{})
855 Quelques commentaires sur les arguments :
858 @item @var{nom-commande}
859 le nom que vous attribuez à votre commande de @emph{markup}.
861 la définition du @qq{layout} -- son formatage.
863 une liste de listes associatives, comprenant toutes les propriétés actives.
865 le @var{ième} argument de la commande.
866 @item @var{argi-type?}
867 un type de prédicat pour le @var{ième} argument.
870 Si la commande utilise des propriétés à partir des arguments
871 @code{props}, le mot-clé @code{#:properties} permet de spécifier ces
872 différentes propriétés ainsi que leur valeur par défaut.
874 Les arguments se distinguent selon leur type :
876 @item un @emph{markup}, correspondant au type de prédicat
877 @code{markup?}@tie{};
878 @item une liste de @emph{markups}, correspondant au type de prédicat
879 @code{markup-list?}@tie{};
880 @item tout autre objet Scheme, correspondant au types de prédicat tels
881 que @code{list?}, @code{number?}, @code{boolean?}, etc.
884 Il n'existe aucune restriction quant à l'ordre des arguments fournis à
885 la suite des arguments @code{layout} et @code{props}. Néanmoins, les
886 fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
887 ceci de particulier qu'elles peuvent s'appliquer à des listes de
888 @emph{markups} ; ceci résultera en une liste de @emph{markups} où
889 tous les éléments de la liste originelle se verront appliquer cette
890 fonction @emph{markup} avec ses arguments de tête.
892 La réplication des arguments de tête dans le but d'appliquer une
893 fonction @emph{markup} à une liste de markups est économique,
894 principalement lorsqu'il s'agit d'arguments Scheme. Vous éviterez
895 ainsi d'éventuelles pertes de performance en utilisant des arguments
896 Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
897 le dernier argument est un @emph{markup}.
900 @node Attribution de propriétés
901 @unnumberedsubsubsec Attribution de propriétés
902 @translationof On properties
904 Les arguments @code{layout} et @code{props} d'une commande de
905 @emph{markup} fournissent un contexte à l'interprétation du
906 @emph{markup} : taille de fonte, longueur de ligne etc.
908 L'argument @code{layout} permet d'accéder aux propriétés définies dans
909 les blocs @code{\paper}, grâce à la fonction
910 @code{ly:output-def-lookup}. Par exemple, la longueur de ligne,
911 identique à celle de la partition, est lue au travers de
914 (ly:output-def-lookup layout 'line-width)
917 L'argument @code{props} rend certaines propriétés accessibles aux
918 commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
919 d'un @emph{markup} de titre d'ouvrage : toutes les variables
920 définies dans le bloc @code{\header} sont automatiquement ajoutées aux
921 @code{props}, de telle sorte que le @emph{markup} de titrage de
922 l'ouvrage pourra accéder aux différents champs titre, compositeur etc.
923 Ceci permet aussi de configurer le comportement d'une commande de
924 @emph{markup} : la taille des fontes, par exemple, est lue à
925 partir de @code{props} plutôt que grâce à un argument @code{font-size}.
926 La fonction appelant une commande de @emph{markup} peut altérer la
927 valeur de la propriété taille des fontes et donc en modifier le
928 comportement. L'utilisation du mot-clé @code{#:properties}, attaché à
929 @code{define-markup-command}, permet de spécifier les propriétés devant
930 être lues parmi les arguments @code{props}.
932 L'exemple proposé à la rubrique suivante illustre comment, au sein d'une
933 commande de @emph{markup}, accéder aux différentes propriétés et les
937 @node Exemple commenté
938 @unnumberedsubsubsec Exemple commenté
939 @translationof A complete example
941 Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un
944 Commençons par construire quelque chose d'approximatif à l'aide d'un
945 simple @emph{markup}. La lecture de @ruser{Commandes pour markup} nous
946 indique la commande @code{\box}, qui semble ici appropriée.
948 @lilypond[quote,verbatim,ragged-right]
949 \markup \box \box HELLO
952 Dans un souci d'esthétique, nous aimerions que le texte et les
953 encadrements ne soient pas autant accolés. Selon la documentation de
954 @code{\box}, cette commande utilise la propriété @code{box-padding},
955 fixée par défaut à 0,2. Cette même documentation nous indique
956 aussi comment la modifier :
958 @lilypond[quote,verbatim,ragged-right]
959 \markup \box \override #'(box-padding . 0.6) \box A
962 L'espacement des deux liserés est cependant toujours trop réduit ;
963 modifions le à son tour :
965 @lilypond[quote,verbatim,ragged-right]
966 \markup \override #'(box-padding . 0.4) \box
967 \override #'(box-padding . 0.6) \box A
970 Vous conviendrez que recopier une telle définition de @emph{markup}
971 deviendra vite fastidieux. C'est pourquoi nous écrivons la commande de
972 @emph{markup} @code{double-box} qui prendra un seul argument -- le
973 texte. Cette commande se chargera de dessiner les encadrements, en
974 tenant compte des espacements.
977 #(define-markup-command (double-box layout props text) (markup?)
978 "Dessine un double encadrement autour du texte."
979 (interpret-markup layout props
980 #@{\markup \override #'(box-padding . 0.4) \box
981 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
984 ou bien son équivalent
987 #(define-markup-command (double-box layout props text) (markup?)
988 "Dessine un double encadrement autour du texte."
989 (interpret-markup layout props
990 (markup #:override '(box-padding . 0.4) #:box
991 #:override '(box-padding . 0.6) #:box text)))
994 @code{text} est le nom de l'argument de notre commande, et
995 @code{markup?} son type -- l'argument sera identifié comme étant un
996 @emph{markup}. La fonction @code{interpret-markup}, utilisée dans la
997 plupart des commandes de @emph{markup}, construira un stencil à partir
998 de @code{layout}, @code{props} et un @emph{markup}. Dans la seconde
999 variante, ce @emph{markup} sera construit à l'aide de la macro Scheme
1000 @code{markup} -- voir @ref{Construction d'un markup en Scheme}. La
1001 transformation d'une expression @code{\markup} en expression Scheme est
1004 Notre commande personnalisée s'utilise ainsi :
1007 \markup \double-box A
1010 Il serait intéressant de rendre cette commande @code{double-box} plus
1011 souple@tie{}: les valeurs de @code{box-padding} sont figées et ne
1012 peuvent être modifiées à l'envie. Pareillement, il serait bien de
1013 distinguer l'espacement entre les encadrements de l'espacement entre le
1014 texte et ses encadrements. Nous allons donc introduire une propriété
1015 supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
1016 de gérer l'espacement des encadrements ; @code{box-padding} ne
1017 servira alors que pour l'espacement intérieur. Voici le code adapté à
1021 #(define-markup-command (double-box layout props text) (markup?)
1022 #:properties ((inter-box-padding 0.4)
1024 "Dessine un double encadrement autour du texte."
1025 (interpret-markup layout props
1026 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
1027 \override #`(box-padding . ,box-padding) \box
1031 Ainsi que son équivalent à partir de la macro @emph{markup} :
1034 #(define-markup-command (double-box layout props text) (markup?)
1035 #:properties ((inter-box-padding 0.4)
1037 "Dessine un double encadrement autour du texte."
1038 (interpret-markup layout props
1039 (markup #:override `(box-padding . ,inter-box-padding) #:box
1040 #:override `(box-padding . ,box-padding) #:box text)))
1043 C'est ici le mot-clé @code{#:properties} qui permet de lire les
1044 propriétés @code{inter-box-padding} et @code{box-padding} à partir de
1045 l'argumenet @code{props}@tie{}; on leur a d'ailleurs fourni des valeurs
1046 par défaut au cas où elles ne seraient pas définies.
1048 Ces valeurs permettront alors d'adapter les propriétés de
1049 @code{box-padding} utilisées par les deux commandes @code{\box}. Vous
1050 aurez remarqué, dans l'argument @code{\override}, la présence de
1051 l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
1052 permettent d'insérer une valeur variable au sein d'une expression
1055 Notre commande est maintenant prête à servir dans un @emph{markup}, et
1056 les encadrements sont repositionnables.
1058 @lilypond[quote,verbatim,ragged-right]
1059 #(define-markup-command (double-box layout props text) (markup?)
1060 #:properties ((inter-box-padding 0.4)
1062 "Draw a double box around text."
1063 (interpret-markup layout props
1064 #{\markup \override #`(box-padding . ,inter-box-padding) \box
1065 \override #`(box-padding . ,box-padding) \box
1068 \markup \double-box A
1069 \markup \override #'(inter-box-padding . 0.8) \double-box A
1070 \markup \override #'(box-padding . 1.0) \double-box A
1074 @node Adaptation d'une commande incorporée
1075 @unnumberedsubsubsec Adaptation d'une commande incorporée
1076 @translationof Adapting builtin commands
1078 Le meilleur moyen de construire ses propres commandes de @emph{markup}
1079 consiste à prendre exemple sur les commandes déjà incorporées. La
1080 plupart des commandes de @emph{markup} fournies avec LilyPond sont
1081 répertoriées dans le fichier @file{scm/define-markup-commands.scm}.
1083 Nous pourrions, par exemple, envisager d'adapter la commande
1084 @code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
1085 est définie la commande @code{\draw-line}, expurgée de sa
1089 (define-markup-command (draw-line layout props dest)
1092 #:properties ((thickness 1))
1093 "@dots{}documentation@dots{}"
1094 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1098 (make-line-stencil th 0 0 x y)))
1101 Avant de définir notre propre commande basée sur l'une de celles
1102 fournies par LilyPond, commençons par en recopier la définition, puis
1103 attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
1104 supprimé sans risque ; il ne sert que lors de la génération de la
1105 documentation et n'est d'aucune utilité pour une commande personnalisée.
1108 (define-markup-command (draw-double-line layout props dest)
1110 #:properties ((thickness 1))
1111 "@dots{}documentation@dots{}"
1112 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
1116 (make-line-stencil th 0 0 x y)))
1119 Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
1120 lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
1121 par défaut de 6 dixièmes :
1124 (define-markup-command (draw-double-line layout props dest)
1126 #:properties ((thickness 1)
1128 "@dots{}documentation@dots{}"
1132 Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
1133 à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
1134 regrouperons les stencils à l'aide de @code{ly:stencil-add} :
1136 @lilypond[quote,verbatim,ragged-right]
1137 #(define-markup-command (my-draw-line layout props dest)
1139 #:properties ((thickness 1)
1142 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1146 (w (/ line-gap 2.0))
1147 (x (cond ((= dx 0) w)
1149 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1150 (y (* (if (< (* dx dy) 0) 1 -1)
1153 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1154 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1155 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1157 \markup \my-draw-line #'(4 . 3)
1158 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1162 @node Définition d'une nouvelle commande de liste de markups
1163 @subsection Définition d'une nouvelle commande de liste de @emph{markups}
1164 @translationof New markup list command definition
1166 Une commande traitant une liste de @emph{markups} se définit à l'aide de
1167 la macro Scheme @code{define-markup-list-command}, de manière analogue à
1168 la macro @code{define-markup-command} abordée à la rubrique
1169 @ref{Définition d'une nouvelle commande de markup} à ceci près que cette
1170 dernière renvoie un seul stencil, non une liste de stencils.
1172 Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
1173 de liste de @emph{markups}, qui renverra une liste de lignes justifiées
1174 dont la première sera indentée. La largeur de l'alinéa sera récupérée
1175 par l'argument @code{props}.
1178 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1179 #:properties ((par-indent 2))
1180 (interpret-markup-list layout props
1181 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1184 La version purement Scheme est un peu plus complexe :
1186 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1187 #:properties ((par-indent 2))
1188 (interpret-markup-list layout props
1189 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1193 En dehors des habituels arguments @code{layout} et @code{props}, la
1194 commande de liste de @emph{markups} @code{paragraph} prend en argument
1195 une liste de @emph{markups} appelé @code{args}. Le prédicat des listes
1196 de @emph{markups} est @code{markup-list?}.
1198 Pour commencer, la fonction récupère la taille de l'alinéa, propriété
1199 ici dénommée @code{par-indent}, à partir de la liste de propriétés
1200 @code{props}. En cas d'absence, la valeur par défaut sera
1201 de @code{2}. Ensuite est créée une liste de lignes justifiées
1202 grâce à la commande prédéfinie @code{\justified-lines}, liée à la
1203 fonction @code{make-justified-lines-markup-list}. Un espace horizontal
1204 est ajouté en tête, grâce à @code{\hspace} ou à la fonction
1205 @code{make-hspace-markup}. Enfin, la liste de @emph{markups} est
1206 interprétée par la fonction @code{interpret-markup-list}.
1208 Voici comment utiliser cette nouvelle commande de liste de
1209 @emph{markups}@tie{}:
1213 The art of music typography is called \italic @{(plate) engraving.@}
1214 The term derives from the traditional process of music printing.
1215 Just a few decades ago, sheet music was made by cutting and stamping
1216 the music into a zinc or pewter plate in mirror image.
1218 \override-lines #'(par-indent . 4) \paragraph @{
1219 The plate would be inked, the depressions caused by the cutting
1220 and stamping would hold ink. An image was formed by pressing paper
1221 to the plate. The stamping and cutting was completely done by
1228 @node Contextes pour programmeurs
1229 @section Contextes pour programmeurs
1230 @translationof Contexts for programmers
1233 * Évaluation d'un contexte::
1234 * Application d'une fonction à tous les objets de mise en forme::
1238 @node Évaluation d'un contexte
1239 @subsection Évaluation d'un contexte
1240 @translationof Context evaluation
1242 @cindex appel de code durant l'interprétation
1243 @funindex \applyContext
1245 Un contexte peut être modifié, au moment même de son interprétation, par
1246 du code Scheme. La syntaxe consacrée en pareil cas est
1248 \applyContext @var{fonction}
1251 @code{@var{fonction}} est constitué d'une fonction Scheme comportant un
1252 unique argument : le contexte au sein duquel la commande
1253 @code{\applyContext} est appelée. Les lignes de code qui suivent auront
1254 pour effet d'afficher à l'écran, en cours de compilation, le numéro de
1260 (format #t "\nNous en sommes à la mesure ~a.\n"
1261 (ly:context-property x 'currentBarNumber)))
1265 @node Application d'une fonction à tous les objets de mise en forme
1266 @subsection Application d'une fonction à tous les objets de mise en forme
1267 @translationof Running a function on all layout objects
1269 @cindex appel de code sur des objets de mise en forme
1270 @funindex \applyOutput
1272 La manière la plus souple d'affiner un objet consiste à utiliser la
1273 commande @code{\applyOutput}. Celle-ci va insérer un événement
1274 (@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
1277 \applyOutput @var{Contexte} @var{procédure}
1281 où @code{@var{procédure}} est une fonction Scheme à trois arguments.
1283 Lors de l'interprétation de cette commande, la fonction
1284 @code{@var{procédure}} est appelée pout tout objet de rendu appartenant
1285 au contexte @code{@var{Contexte}} à cet instant précis, avec les
1286 arguments suivants :
1288 @item l'objet de rendu en lui-même,
1289 @item le contexte au sein duquel cet objet est créé,
1290 @item et le contexte dans lequel @code{\applyOutput} est effectué.
1293 De plus, ce qui est à l'origine de l'objet de rendu -- l'expression
1294 musicale ou l'objet qui l'a générée -- se retrouve en tant que propriété
1295 d'objet @code{cause}. Il s'agit, pour une tête de note, d'un événement
1296 @rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
1298 Voici une fonction utilisable avec la commande
1299 @code{\applyOutput} : elle @qq{blanchit} la tête des notes se
1300 trouvant sur la ligne médiane ou bien directement à son contact.
1302 @lilypond[quote,verbatim,ragged-right]
1303 #(define (blanker grob grob-origin context)
1304 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1305 (< (abs (ly:grob-property grob 'staff-position)) 2))
1306 (set! (ly:grob-property grob 'transparent) #t)))
1309 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1313 La @var{procédure} sera interprétée au niveau @code{Score}
1314 (partition) ou @code{Staff} dès lors que vous utiliserez l'une des
1318 \applyOutput #'Score #@var{procédure}
1319 \applyOutput #'Staff #@var{procédure}
1323 @node Fonctions de rappel
1324 @section Fonctions de rappel
1325 @translationof Callback functions
1327 Certaines propriétés, entre autres @code{thickness} ou @code{direction},
1328 peuvent voir leur valeur figée à l'aide d'un @code{\override} comme
1332 \override Stem.thickness = #2.0
1335 Une procédure Scheme peut aussi se charger de modifier des
1338 @lilypond[fragment,verbatim,quote,relative=2]
1339 \override Stem.thickness = #(lambda (grob)
1340 (if (= UP (ly:grob-property grob 'direction))
1347 Dans ce cas, la procédure est exécutée dès que la valeur de la propriété
1348 est nécessaire au processus de mise en forme.
1350 La majeure partie du procédé typographique consiste en la réalisation de
1351 tels rappels (@emph{callbacks} en anglais). Entre autres propriétés
1352 utilisant particulièrement des rappels, nous mentionnerons
1356 Routine d'impression, construisant le dessin du symbole
1358 Routine effectuant le positionnement horizontal
1360 Routine calculant la largeur d'un objet
1363 La procédure prend un unique argument, en l'occurrence l'objet graphique
1366 Dans le cas où la routine doit faire appel à plusieurs arguments, le
1367 @emph{grob} en cours peut s'insérer à l'aide d'un @emph{grob} enchâssé.
1368 Voici, à titre d'illustration, un réglage pour
1369 @code{AccidentalSuggestion} :
1373 ,(ly:make-simple-closure
1375 ,(ly:make-simple-closure
1376 (list ly:self-alignment-interface::centered-on-x-parent))
1377 ,(ly:make-simple-closure
1378 (list ly:self-alignment-interface::x-aligned-on-self)))))
1382 Ici, aussi bien @code{ly:self-alignment-interface::x-aligned-on-self}
1383 que @code{ly:self-alignment-interface::centered-on-x-parent} font appel
1384 à l'argument @emph{grob}. La fonction @code{+} a pour effet
1385 d'additionner les résultats. L'ensemble est inclus dans un
1386 @code{ly:make-simple-closure} de telle sorte que l'addition s'exécute de
1389 Dans les faits, l'utilisation d'une unique procédure en tant que valeur
1390 d'une propriété revient à écrire
1393 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1397 Le @code{ly:make-simple-closure} intérieur fournit le @emph{grob} en
1398 argument à la procédure @var{proc}, l'extérieur s'assure que le résultat
1399 de la fonction sera bien renvoyé, non pas l'objet @code{simple-closure}.
1401 Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
1402 @emph{markup} consiste à utiliser la fonction
1403 @code{grob-interpret-markup}, comme ici :
1406 my-callback = #(lambda (grob)
1407 (grob-interpret-markup grob (markup "foo")))
1411 @node Code Scheme intégré
1412 @section Code Scheme intégré
1413 @translationof Inline Scheme code
1415 À REVOIR : l'exemple de cette rubrique n'est pas des plus judicieux puisque
1417 F = -\tweak font-size #-3 -\flageolet
1419 (notez le @samp{-} qui qualifie d'événement postérieur) fonctionne
1420 correctement dans ce cas d'espèce. En attendant un remaniement de cette
1421 section, faisons comme si nous l'ignorions.
1423 L'inconvénient principal de la commande @code{\tweak} est la rigidité de
1424 sa syntaxe. Par exemple, le code suivant produit une erreur.
1427 F = \tweak font-size #-3 -\flageolet
1435 En d'autres termes, @code{\tweak} ne se comporte pas comme une
1436 articulation : il ne peut notamment pas être accolé avec les
1437 symboles @samp{^} ou @samp{_}.
1439 C'est en se servant du langage Scheme que l'on peut résoudre ce
1440 problème. Dans cet exemple, on a recours aux méthodes décrites dans
1441 @ref{Ajout d'articulation à des notes (exemple)}, en
1442 particulier quant à l'emploi de @code{\displayMusic}.
1445 F = #(let ((m (make-music 'ArticulationEvent
1446 'articulation-type "flageolet")))
1447 (set! (ly:music-property m 'tweaks)
1448 (acons 'font-size -3
1449 (ly:music-property m 'tweaks)))
1458 Ici les propriétés @code{tweak} de l'objet flageolet nommé
1459 @samp{m} (créé au moyen de @code{make-music}) sont extraites par
1460 @code{ly:music-property}, une nouvelle valeur de la taille de fonte
1461 est ajoutée à la liste de ses propriétés (grâce à la fonction Scheme
1462 @code{acons}), et le résultat de cette opération est renvoyé par
1463 @code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
1464 finale de @samp{m} lui-même.
1467 @node Retouches complexes
1468 @section Retouches complexes
1469 @translationof Difficult tweaks
1471 Certains réglages sont plus délicats que d'autres.
1475 L'un d'entre eux est l'apparence des objets dits @qq{extenseurs}
1476 (@emph{spanner}), qui s'étendent horizontalement, tels que les liaisons.
1477 Si, en principe, un seul de ces objets est créé à la fois et peut donc
1478 être modifié de façon habituelle, lorsque ces objets doivent enjamber un
1479 changement de ligne, ils sont dupliqués au début du ou des systèmes
1480 suivants. Comme ces objets sont des clones de l'objet d'origine, ils en
1481 héritent toutes les propriétés, y compris les éventuelles commandes
1484 En d'autres termes, une commande @code{\override} affecte toujours les
1485 deux extrémités d'un objet @emph{spanner}. Pour ne modifier que la
1486 partie précédant ou suivant le changement de ligne, il faut intervenir
1487 directement dans le processus de mise en page.
1488 La fonction de rappel @code{after-line-breaking} contient toute
1489 l'opération Scheme effectuée lorsque les sauts de lignes ont été
1490 déterminés, et que des objets graphiques ont été divisés sur des
1491 systèmes différents.
1493 Dans l'exemple suivant, on définit une nouvelle opération nommée
1494 @code{my-callback}. Cette opération
1498 détermine si l'objet a été divisé à l'occasion d'un changement de ligne
1500 dans l'affirmative, recherche les différents morceaux de l'objet
1502 vérifie si l'objet considéré est bien la deuxième moitié d'un objet
1505 dans l'affirmative, applique un espacement supplémentaire
1506 (@code{extra-offset}).
1509 On ajoute cette procédure à l'objet @rinternals{Tie} (liaison de tenue),
1510 de façon à ce que le deuxième morceau d'une liaison divisée soit
1514 @lilypond[quote,verbatim,ragged-right]
1515 #(define (my-callback grob)
1517 ;; l'objet a-t-il été divisé ?
1518 (orig (ly:grob-original grob))
1520 ;; si oui, rechercher les morceaux frères (siblings)
1521 (siblings (if (ly:grob? orig)
1522 (ly:spanner-broken-into orig)
1525 (if (and (>= (length siblings) 2)
1526 (eq? (car (last-pair siblings)) grob))
1527 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1530 \override Tie.after-line-breaking =
1538 Lorsque cette astuce va être appliquée, notre nouvelle fonction de
1539 rappel @code{after-line-breaking} devra également appeler celle
1540 d'origine (@code{after-line-breaking}), si elle existe. Ainsi, pour
1541 l'utiliser dans le cas d'un crescendo (objet @code{Hairpin}), il faudra
1542 également appeler @code{ly:spanner::kill-zero-spanned-time}.
1546 Pour des raisons d'ordre technique, certains objets ne peuvent être
1547 modifiés par @code{\override}. Parmi ceux-là, les objets
1548 @code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
1549 @code{\overrideProperty} sert à les modifier, de façon similaire à
1550 @code{\once \override} mais avec une syntaxe différente :
1554 Score.NonMusicalPaperColumn % Nom de l'objet
1555 . line-break-system-details % Nom de la propriété
1556 . next-padding % Nom de la sous-propriété (optionnel)
1560 Notez toutefois que la commande @code{\override} peut tout de même être
1561 appliquée à @code{NonMusicalPaperColumn} et @code{PaperColumn} dans un
1562 bloc @code{\context}.
1567 @node Interfaces LilyPond Scheme
1568 @chapter Interfaces LilyPond Scheme
1569 @translationof LilyPond Scheme interfaces
1571 Ce chapitre aborde les différents outils fournis par LilyPond à
1572 l'intention des programmeurs en Scheme désireux d'obtenir des
1573 informations à partir et autour des fluxs de musique.
1575 TODO -- figure out what goes in here and how to organize it