@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
@ignore
- Translation of GIT committish: 44f8873e8cb9533ddb6713c5e79fe2edb59524c7
+ Translation of GIT committish: d46572826e777ed3e9fa4656535a6e9000f2ed9e
When revising a translation, copy the HEAD committish of the
version that you are working on. For details, see the Contributors'
Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.18"
+@c \version "2.19.2"
@c Translators: Valentin Villenave, Jean-Charles Malahieude
@c Translation checkers: Gilles Thibault
@node Blocs de code LilyPond
@section Blocs de code LilyPond
-@translationof Lilypond code blocks
+@translationof LilyPond code blocks
+
+@cindex code, blocs LilyPond
+@cindex LilyPond, bloc de code
+
+@funindex #@{ ... #@}
+@funindex $
+@funindex #
+
+L'utilisation de Scheme pour créer des expressions musicales peut
+s'avérer ardue, principalement à cause des imbrications et de la
+longueur du code Scheme qui en résulte. Dans le cas de tâches
+simples, on peut toutefois contourner une partie du problème en
+utilisant des blocs de code LilyPond, ce qui autorise la syntaxe
+habituelle de LilyPond au sein même de Scheme.
Les blocs de code LilyPond ressemblent à
+
@example
#@{ @var{du code LilyPond} #@}
@end example
-Ils peuvent s'utiliser partout où vous pouvez écrire du code Scheme.
-Le lecteur Scheme est en fait quelque peu adapté pour accepter des blocs
-de code LilyPond@tie{}; il est capable de traiter des expressions Scheme
-intégrées débutant par @code{$} ou@tie{}@code{#}.
+
+En voici un exemple basique :
+
+@lilypond[verbatim,quote]
+ritpp = #(define-event-function (parser location) ()
+ #{ ^"rit." \pp #}
+)
+
+{ c'4 e'4\ritpp g'2 }
+@end lilypond
+
+Les blocs de code LilyPond peuvent s'utiliser partout où vous pouvez
+écrire du code Scheme. Le lecteur Scheme est en fait quelque peu adapté
+pour accepter des blocs de code LilyPond ; il est capable de traiter des
+expressions Scheme intégrées débutant par @code{$} ou @code{#}.
+
+@cindex parser (fonction argument)
+@cindex location
Le lecteur Scheme extrait le bloc de code LilyPond et déclenche un appel
à l'analyseur grammatical de LilyPond (le @code{parser}) qui réalise en
expression Scheme imbriquée est exécutée dans l'environnement lexical du
bloc de code LilyPond, de telle sorte que vous avez accès aux variables
locales et aux paramètres de la fonction au moment même où le bloc de
-code LilyPond est écrit.
+code LilyPond est écrit. Les variables définies dans d'autres modules
+Scheme, tels ceux contenant les blocs @code{\header} ou @code{\layout},
+ne sont pas accessibles en tant que variables Scheme (préfixées par
+un @code{#}) mais en tant que variables LilyPond (préfixées par
+un @code{\}).
+
+Lorsque l'emplacement (@code{location} -- voir @ref{Fonctions Scheme})
+fait référence à un endroit valide dans la source -- ce qui est en
+général le cas au sein de fonctions musicales ou Scheme --, toute la
+musique générée au sein de ce bloc de code voit son @code{origine}
+établie à cet @emph{emplacement}.
Un bloc de code LilyPond peut contenir tout ce que vous pourriez mettre
à droite de l'assignation. Par ailleurs, un bloc LilyPond vide
@funindex define-scheme-function
-D'une manière générale, une fonction Scheme se définit ainsi@tie{}:
+D'une manière générale, une fonction Scheme se définit ainsi :
@example
fonction =
#(define-scheme-function
- (parser location @var{arg1} @var{arg2} @dots{})
- (@var{type1?} @var{type2?} @dots{})
+ (parser location @var{arg1} @var{arg2}@dots{})
+ (@var{type1?} @var{type2?}@dots{})
@var{corps})
@end example
l'analyseur grammatical puisse accéder aux blocs de code LilyPond
(@code{#@{}@dots{}@code{#@}}).
+@item @code{location}
+@tab doit être littéralement @code{location}, de telle sorte que soit
+accessible l'emplacement de l'objet dans la source, aux fins de
+transmettre aux messages d'erreur les fichier et numéro de ligne.
+
@item @code{@var{argN}}
@tab @var{n}ième argument
@item @code{@var{typeN?}}
@tab un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
-devra retourner @code{#t}. Certains de ces prédicats, comme nous le
-verrons plus loin, bénéficient d'un traitement particulier de la part du
-@emph{parser}. De même existe une forme spécifique --
-@code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
+devra retourner @code{#t}. Il existe aussi une forme spécifique --
+@code{(@emph{prédicat?} @emph{default})} -- qui permet de fournir des
argument optionnels. En l'absence d'argument réel au moment de l'appel
-de la fonction, c'est la valeur par défaut qui lui sera substituée. Les
+à la fonction, c'est la valeur par défaut qui lui sera substituée. Les
valeurs par défaut sont évaluées dès l'apparition de la définition, y
-compris dans le cas de blocs de code LilyPond@tie{}; vous devrez donc,
+compris dans le cas de blocs de code LilyPond ; vous devrez donc,
si ces valeurs par défaut ne peuvent être déterminées que plus tard,
mentionner une valeur spéciale que vous reconnaîtrez facilement.
Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois
fournir sa valeur par défaut, celle-ci sera considérée comme étant
@code{#f}. Les valeurs par défaut d'un @code{prédicat?} ne sont
-vérifiées ni au moment de la définition, ni à l'exécution@tie{}; il est
+vérifiées ni au moment de la définition, ni à l'exécution ; il est
de votre ressort de gérer les valeurs que vous spécifiez. Une valeur
par défaut constituée d'une expression musicale est recopiée dès la
définition de @code{origin} vers le paramètre @code{location}.
@tab une séquence de formules Scheme évaluées dans l'ordre, la dernière
servant de valeur de retour de la fonction. Il peut contenir des blocs
de code LilyPond, enchâssés dans des accolades et @emph{hashes} --
-@w{@code{#@{@dots{}#@}}}@tie{} -- comme indiqué à la rubrique
+@w{@code{#@{@dots{}#@}}} -- comme indiqué à la rubrique
@ref{Blocs de code LilyPond}. Au sein d'un bloc de code LilyPond, un
@code{#} permet de référencer des arguments de la fonction -- tel
@samp{#arg1} -- ou d'ouvrir une expression Scheme contenant les
arguments de la fonction -- par exemple @w{@samp{#(cons arg1 arg2)}}.
Dans le cas où une expression Scheme introduite par @code{#} ne vous
permet pas de parvenir à vos fins, vous pourriez devoir revenir à une
-expression Scheme @qq{immédiate} à l'aide d'un @code{$}, comme
+expression Scheme « immédiate » à l'aide d'un @code{$}, comme
@samp{$music}.
Lorsque votre fonction retourne une expression musicale, lui est
@end multitable
@noindent
-Certains types de prédicat font l'objet d'un traitement spécial de la
-part de l'analyseur grammatical, dans la mesure où il n'a aucun autre
-moyen de reconnaître efficacement les arguments. Il s'agit, à l'heure
-actuelle, de @code{ly:pitch?} et @code{ly:duration?}.
-
-Pour tous les autres prédicats, la recevabilité des arguments est
-déterminée par un appel effectif au prédicat après que LilyPond les a
-déjà converti en expression Scheme. Par voie de conséquence, l'argument
-peut tout à fait se libeller en syntaxe Scheme -- introduite par un
-@code{#} ou en tant que résultat d'un appel à une fonction Scheme. Par
-ailleurs, LilyPond convertira en Scheme un certain nombre de
-constructions purement LilyPond avant même d'en avoir vérifié le
-prédicat. C'est notamment le cas de la musique, des
-@emph{postévénements}, des chaînes simples (avec ou sans guillemets),
-des nombres, des @emph{markups} et listes de @emph{markups}, ainsi que
-des blocs @emph{score}, @emph{book}, @emph{bookpart}, ou qui définissent
-un contexte ou un format de sortie.
+La recevabilité des arguments est déterminée par un appel effectif au
+prédicat après que LilyPond les a déjà converti en expression Scheme.
+Par voie de conséquence, l'argument peut tout à fait se libeller en
+syntaxe Scheme -- introduite par un @code{#} ou en tant que résultat
+d'un appel à une fonction Scheme. Par ailleurs, LilyPond convertira en
+Scheme un certain nombre de constructions purement LilyPond avant même
+d'en avoir vérifié le prédicat. C'est notamment le cas de la musique,
+des @emph{postévénements}, des chaînes simples (avec ou sans
+guillemets), des nombres, des @emph{markups} et listes de
+@emph{markups}, ainsi que des blocs @emph{score}, @emph{book},
+@emph{bookpart}, ou qui définissent un contexte ou un format de sortie.
Il existe certaines formes d'expression, comme la plupart du temps où la
musique n'est pas bornée par des accolades, où LilyPond doit lire
telle expression devait, après évaluation du prédicat, faire l'objet
d'un argument optionnel, LilyPond n'aurait aucun moyen, à partir du
moment où il aura décidé que l'expression ne correspond pas au
-paramètre, de @qq{revenir en arrière}. C'est la raison pour laquelle
+paramètre, de « revenir en arrière ». C'est la raison pour laquelle
certaines formes musicales devraient être bornées par des accolades pour
que LilyPond puisse les reconnaître efficacement. Il existe d'autres
situations pour lesquelles LilyPond lèvera toute ambiguïté grâce aux
-fonctions de prédicat@tie{}: un @samp{-3} est-il un @emph{postévénement}
-de type doigté ou un nombre négatif@tie{}? Un @code{"a"@tie{}4} en mode
+fonctions de prédicat : un @samp{-3} est-il un @emph{postévénement}
+de type doigté ou un nombre négatif@tie{}? Un @code{"a" 4} en mode
paroles est-il une chaîne suivie d'un nombre ou bien un événement
-syllabe de durée @code{4}@tie{}? LilyPond répondra à ces questions
-après consultation du prédicat. Pour toutes ces raisons, nous vous
-enjoignons à éviter d'utiliser des prédicats permissifs tel que
-@code{scheme?}, dès que vous voulez les utiliser dans un but particulier
-plutôt que dans une fonction de portée générale.
+syllabe de durée @code{4} ? LilyPond répondra à ces questions
+par des interprétations successives du prédicat de l'argument, dans un
+ordre défini de sorte à minimiser les interprétations erronées et le
+besoin de lecture en avance.
+
+Un prédicat qui accepte par exemple aussi bien une expression musicale
+qu'une hauteur considèrera @code{c''} comme étant une hauteur plutôt
+qu'une expression musicale. Les durées ou @emph{postévénements} qui
+viennent juste après pourraient ne pas être cohérents avec cette
+interprétation. C'est la raison pour laquelle il vaut mieux éviter des
+prédicats par trop permissifs tel que @code{Scheme?} lorsque
+l'application fait plutôt appel à des type d'argument plus spécifiques.
Les différents types des prédicat propres à LilyPond sont recensés à
l'annexe @ruser{Types de prédicats prédéfinis}.
fait pas considérés comme optionnels, sauf à être suivis d'un argument
obligatoire.
-Une exception cependant à cette règle@tie{}: le fait de donner un
+Une exception cependant à cette règle : le fait de donner un
@code{\default} en tant qu'argument optionnel aura pour résultat que cet
argument et tous les autres arguments optionnels qui suivent seront
ignorés et remplacés par leur valeur par défaut. Il en va de même
Il arrive qu'une procédure soit exécutée pour réaliser une action, non
pour renvoyer une valeur. Certains langages de programmation, tels
le C et Scheme, utilisent des fonctions dans les deux cas et se
-débarrassent tout bonnement de la valeur renvoyée@tie{}; en règle
+débarrassent tout bonnement de la valeur renvoyée ; en règle
générale, il suffit que l'expression fasse office de déclaration, et
-d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur@tie{}:
+d'ignorer le résultat. C'est futé, mais pas sans risque d'erreur :
la plupart des compilateurs C actuels déclenchent un avertissement si
l'on se débarrasse de certaines expressions non @emph{void}. Pour de
nombreuses fonctions réalisant une action, les standards Scheme
(parser location)
()
(ly:set-option 'point-and-click #f))
-...
+@dots{}
\noPointAndClick % desactive le "pointer-cliquer"
@end example
L'utilisation d'un préfixe @code{\void} permet ainsi d'évaluer une
expression pour ses effets annexes sans interprétation d'une quelconque
-valeur de retour@tie{}:
+valeur de retour :
@example
\void #(hashq-set! une-table une-clé une-valeur)
@cindex musicale, fonction
Les @emph{fonctions musicales} sont des procédures Scheme capables de
-créer automatiquement des expressions musicales@tie{}; elles permettent
+créer automatiquement des expressions musicales ; elles permettent
de grandement simplifier un fichier source.
@menu
@funindex define-music-function
-Une fonction musicale se définit ainsi@tie{}:
+Une fonction musicale se définit ainsi :
@example
fonction =
#(define-music-function
- (parser location @var{arg1} @var{arg2} @dots{})
- (@var{type1?} @var{type2?} @dots{})
+ (parser location @var{arg1} @var{arg2}@dots{})
+ (@var{type1?} @var{type2?}@dots{})
@var{corps})
@end example
@item
En tant que post-événement, explicitement introduit par un indicateur de
-positionnement -- à savoir @code{-}, @code{^}, @w{ou @code{_}}. Notez
-bien que le renvoi d'un post-événement est valide lorsque la fonction
-musicale est appelée comme de la musique normale@tie{}; ceci amène à un
-résultat ressemblant à
-@example
-s 1*0-\fonction
-@end example
+positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@code{_}.
Dans ce cas particulier, vous ne pouvez utiliser une expression musicale
@emph{ouverte} en tant que dernier argument -- argument qui se
composerait d'une expression musicale susceptible d'accepter des
-post-événements additionnels.
+postévénements additionnels.
@item
En tant que partie d'un accord. L'expression musicale renvoyée doit
cellule}.
Cette paire peut se mentionner directement dans la fonction musicale à
-l'aide d'une variable @code{pair?}@tie{}:
+l'aide d'une variable @code{pair?} :
@example
manualBeam =
(parser location beg-end)
(pair?)
#@{
- \once \override Beam #'positions = #beg-end
+ \once \override Beam.positions = #beg-end
#@})
\relative c' @{
@end example
Autre manière de procéder, les nombres formant la paire sont transmis
-comme arguments séparés@tie{}; le code Scheme chargé de créer la paire
-pourra alors être inclus dans l'expression musicale@tie{}:
+comme arguments séparés ; le code Scheme chargé de créer la paire
+pourra alors être inclus dans l'expression musicale :
@lilypond[quote,verbatim,ragged-right]
manualBeam =
(parser location beg end)
(number? number?)
#{
- \once \override Beam #'positions = #(cons beg end)
+ \once \override Beam.positions = #(cons beg end)
#})
\relative c' {
}
@end lilypond
+@funindex \temporary
+@cindex temporaire, dérogation (override)
+@cindex dérogation temporaire (override)
+@cindex propriétés, retour à la valeur précédente
+
+L'entretien des propriétés peut se voir comme un empilement par
+propriété par objet par contexte. Les fonctions musicales peuvent
+nécessiter des dérogatoins pour une ou plusieurs propriétés pour la
+durée de la fonction, puis de revenir aux valeurs précédentes avant de
+quitter. Néanmoins, une dérogation normale va retirer de la pile -- ou
+dépiler -- et supprimer le sommet de la pile de la propriété avant
+d'y ajouter quoi que ce soit -- ou empiler -- ; la valeur précédente de
+la propriété est de fait perdue. Lorsque la valeur antérieure doit être
+préservée, l'instruction @code{\override} devra être préfixée d'un
+@code{\temporary}, comme ceci :
+
+@example
+\temporary \override @dots{}
+@end example
+
+L'utilisation d'un @code{\temporary} a pour effet d'effacer la propriété
+@code{pop-first} (@emph{commence par dépiler} normalement activée) de la
+dérogation ; la valeur antérieure ne sera alors pas supprimée de la pile
+de la propriété avant d'y empiler la nouvelle valeur. Lorsqu'un
+@code{\revert} viendra par la suite supprimer la valeur dérogatoire
+temporaire, réapparaitra la valeur antérieure.
+
+En d'autres termes, un @code{\revert} qui suit un @code{\temporary
+\override} pour la même propriété n'apporte rien. Ce principe est aussi
+valable pour une couple @code{\temporary} et @code{\undo} sur la même
+musique contenant des dérogations.
+
+Voici un exemple de fonction musicale utilisant cette fonctionnalité.
+La présence du @code{\temporary} permet de s'assurer qu'en sortant de la
+fonction, les propriétés @code{cross-staff} et @code{style} retrouveront
+les valeurs qu'elles avaient que ne soit appelée la fonction
+@code{crossStaff}. En l'absence de @code{\temporary}, ces propriétés
+auraient retrouvé leurs valeurs par défaut à la sortie de la fonction.
+
+@example
+crossStaff =
+#(define-music-function (parser location notes) (ly:music?)
+ (_i "Create cross-staff stems")
+ #@{
+ \temporary \override Stem.cross-staff = #cross-staff-connect
+ \temporary \override Flag.style = #'no-flag
+ #notes
+ \revert Stem.cross-staff
+ \revert Flag.style
+#@})
+@end example
+
@node De l'usage des mathématiques dans les fonctions
@subsection De l'usage des mathématiques dans les fonctions
(parser location mag)
(number?)
#{
- \override Stem #'length = #(* 7.0 mag)
- \override NoteHead #'font-size =
+ \override Stem.length = #(* 7.0 mag)
+ \override NoteHead.font-size =
#(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
#})
AltOff = {
- \revert Stem #'length
- \revert NoteHead #'font-size
+ \revert Stem.length
+ \revert NoteHead.font-size
}
\relative c' {
@noindent
Cette fonction pourrait tout à fait être réécrite de telle sorte qu'elle
-s'applique à une expression musicale@tie{}:
+s'applique à une expression musicale :
@lilypond[quote,verbatim,ragged-right]
withAlt =
(parser location mag music)
(number? ly:music?)
#{
- \override Stem #'length = #(* 7.0 mag)
- \override NoteHead #'font-size =
+ \override Stem.length = #(* 7.0 mag)
+ \override NoteHead.font-size =
#(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
- $music
- \revert Stem #'length
- \revert NoteHead #'font-size
+ #music
+ \revert Stem.length
+ \revert NoteHead.font-size
#})
\relative c' {
@translationof Functions without arguments
Dans la plupart des cas, une fonction dépourvue d'argument devrait
-être créée à l'aide d'une variable@tie{}:
+être créée à l'aide d'une variable :
@example
dolce = \markup@{ \italic \bold dolce @}
(parser location)
()
(if (eq? #t (ly:get-option 'display-bar-numbers))
- #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
+ #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
#@{#@}))
@end example
Une fonction musicale doit renvoyer une expression musicale. Toutefois,
une fonction musicale peut n'être exécutée que dans le but d'en retenir
-les effets annexes@tie{}; vous devrez alors utiliser une procédure
+les effets annexes ; vous devrez alors utiliser une procédure
@code{define-void-function}. Il peut cependant arriver que vous ayez
besoin d'une fonction qui, selon le cas, produise ou non (comme dans
l'exemple de la rubrique précédente) une expression musicale.
-L'utilisation d'un @code{#@{@tie{}#@}} vous permettra de renvoyer une
+L'utilisation d'un @code{#@{ #@}} vous permettra de renvoyer une
expression musicale @code{void}.
lorsque vous voulez écrire une commande de nuance, instruction qui
ne comporte habituellement pas d'indicateur de positionnement, comme
dans @code{c'\pp}. Voici de quoi vous permettre de mentionner n'importe
-quelle nuance@tie{}:
+quelle nuance :
@lilypond[quote,verbatim,ragged-right]
dyn=#(define-event-function (parser location arg) (markup?)
Vous pourriez obtenir le même résultat avec une fonction musicale, à
ceci près que chaque appel à la fonction devra être précédé d'un
-indicateur de positionnement, comme @code{c-\dyn@tie{}pfsss}.
+indicateur de positionnement, comme @code{c-\dyn pfsss}.
@node Fonctions pour markups
@cindex définition d'une commande markup
-La macro @code{markup} construit en Scheme des expressions @emph{markup}
-tout en disposant d'une syntaxe proche de celle de LilyPond. Par exemple,
+@funindex \displayScheme
+
+Les expressions @emph{markup} sont représentées en Scheme de manière
+interne par la macro @code{markup} :
+
+@example
+(markup @var{expression})
+@end example
+
+La commande @code{\displayScheme} permet d'obtenir la représentation en
+Scheme d'une expression @emph{markup} :
+
@example
-(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
- #:larger #:line ("foo" "bar" "baz")))
+\displayScheme
+\markup @{
+ \column @{
+ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
+ \larger \line @{ foo bar baz @}
+ @}
+@}
@end example
@noindent
-est équivalent à
+Compiler ce code renverra en console les lignes suivantes :
+
@example
-#@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
- \larger \line @{ foo bar baz @} @} #@}
+(markup
+ #:line
+ (#:column
+ (#:line
+ (#:bold (#:italic "hello") #:raise 0.4 "world")
+ #:larger
+ (#:line
+ (#:simple "foo" #:simple "bar" #:simple "baz")))))
@end example
+L'impression du @emph{markup} sera suspendue dès lors qu'apparaîtra un
+@w{@samp{\void \displayScheme @var{markup}}}. Tout comme pour la
+commande @code{\displayMusic}, le résultat de @code{\displayScheme} peut
+être sauvegardé dans un fichier séparé. Voir à ce sujet
+@ref{Affichage d'expressions musicales}.
+
@noindent
Vous pouvez constater les principales règles de traduction entre les
syntaxes respectives de LilyPond et de Scheme en matière de
@emph{markup}. Bien que le passage en syntaxe LilyPond grâce à
-@code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
+@code{#@{ @dots{} #@}} apporte de la souplesse, nous allons voir comment
utiliser la macro @code{markup} en Scheme exclusivement.
@quotation
@multitable @columnfractions .3 .3
@item @b{LilyPond} @tab @b{Scheme}
@item @code{\markup markup1} @tab @code{(markup markup1)}
-@item @code{\markup @{ markup1 markup2 ... @}} @tab
- @code{(markup markup1 markup2 ... )}
+@item @code{\markup @{ markup1 markup2@dots{} @}} @tab
+ @code{(markup markup1 markup2@dots{} )}
@item @code{\commande-markup} @tab @code{#:commande-markup}
@item @code{\variable} @tab @code{variable}
-@item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
+@item @code{\center-column @{ @dots{} @}} @tab
+ @code{#:center-column ( @dots{} )}
@item @code{chaîne} @tab @code{"chaîne"}
@item @code{#argument-scheme} @tab @code{argument-scheme}
@end multitable
@noindent
n'est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions
@code{make-line-markup}, @code{make-center-markup} ou
-@code{make-column-markup}@tie{}:
+@code{make-column-markup} :
@lisp
(markup (make-line-markup (fonction-qui-retourne-des-markups)))
@end example
Lorsque ce @emph{markup} est converti en objets imprimables (stencils),
-la fonction @code{raise-markup} est appelée ainsi@tie{}:
+la fonction @code{raise-markup} est appelée ainsi :
@example
(apply raise-markup
La fonction @code{raise-markup} commence par créer le stencil pour la
chaîne @code{text example}, puis remonte ce stencil d'un demi espace de
portée. Il s'agit là d'un exemple relativement simple, et nous en
-aborderons de plus complexes au fil des paragraphes suivants@tie{};
+aborderons de plus complexes au fil des paragraphes suivants ;
d'autres exemples se trouvent directement dans le fichier
@file{scm/define-markup-commands.scm}.
macro Scheme @code{define-markup-command}, placée en tête de fichier.
@lisp
-(define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
- (@var{arg1-type?} @var{arg2-type?} ...)
+(define-markup-command (@var{nom-commande} @var{layout} @var{props} @var{arg1} @var{arg2}@dots{})
+ (@var{arg1-type?} @var{arg2-type?}@dots{})
[ #:properties ((@var{propriété1} @var{valeur-par-défaut1})
- ...) ]
- ..corps de la commande..)
+ @dots{}) ]
+ @dots{}corps de la commande@dots{})
@end lisp
-Quelques commentaires sur les arguments@tie{}:
+Quelques commentaires sur les arguments :
@table @code
@item @var{nom-commande}
@code{props}, le mot-clé @code{#:properties} permet de spécifier ces
différentes propriétés ainsi que leur valeur par défaut.
-Les arguments se distinguent selon leur type@tie{}:
+Les arguments se distinguent selon leur type :
@itemize
@item un @emph{markup}, correspondant au type de prédicat
@code{markup?}@tie{};
la suite des arguments @code{layout} et @code{props}. Néanmoins, les
fonctions @emph{markup} qui ont en dernier argument un @emph{markup} ont
ceci de particulier qu'elles peuvent s'appliquer à des listes de
-@emph{markups}@tie{}; ceci résultera en une liste de @emph{markups} où
+@emph{markups} ; ceci résultera en une liste de @emph{markups} où
tous les éléments de la liste originelle se verront appliquer cette
fonction @emph{markup} avec ses arguments de tête.
Scheme en tant qu'arguments principaux d'une fonction @emph{markup} dont
le dernier argument est un @emph{markup}.
+@cindex markup macro
+@cindex macro de markup
+@funindex \markup
+@funindex interpret-markup
+
+Les commandes de @emph{markup} ont un cycle de vie relativement
+complexe. Le corps de la définition d'une commande de @emph{markup} est
+chargé de convertir les arguments de la commande en expression stencil
+qui sera alors renvoyée. Bien souvent, ceci s'accomplit par un appel à
+la fonction @code{interpret-markup}, en lui passant les arguments
+@var{layout} et @var{props}. Ces arguments ne seront en principe connus
+que bien plus tardivement dans le processus typographique. Lors de
+l'expansion d'une expression LilyPond @code{\markup} ou d'une macro
+Scheme @code{macro}, les expressions @emph{markup} auront déjà vu leurs
+composants assemblés en expressions @emph{markup}. L'évaluation et le
+contrôle du type des arguments à une commande de @emph{markup}
+n'interviennent qu'au moment de l'interprétation de @code{\markup} ou
+@code{markup}.
+
+Seule l'application de @code{interpret-markup} sur une expression
+@emph{markup} réalisera effectivement la conversion des expressions
+@emph{markup} en stencil, au travers de l'exécution du corps des
+fonctions @emph{markup}.
+
@node Attribution de propriétés
@unnumberedsubsubsec Attribution de propriétés
Les arguments @code{layout} et @code{props} d'une commande de
@emph{markup} fournissent un contexte à l'interprétation du
-@emph{markup}@tie{}: taille de fonte, longueur de ligne etc.
+@emph{markup} : taille de fonte, longueur de ligne etc.
L'argument @code{layout} permet d'accéder aux propriétés définies dans
les blocs @code{\paper}, grâce à la fonction
L'argument @code{props} rend certaines propriétés accessibles aux
commandes de @emph{markup}. Il en va ainsi lors de l'interprétation
-d'un @emph{markup} de titre d'ouvrage@tie{}: toutes les variables
+d'un @emph{markup} de titre d'ouvrage : toutes les variables
définies dans le bloc @code{\header} sont automatiquement ajoutées aux
@code{props}, de telle sorte que le @emph{markup} de titrage de
l'ouvrage pourra accéder aux différents champs titre, compositeur etc.
Ceci permet aussi de configurer le comportement d'une commande de
-@emph{markup}@tie{}: la taille des fontes, par exemple, est lue à
+@emph{markup} : la taille des fontes, par exemple, est lue à
partir de @code{props} plutôt que grâce à un argument @code{font-size}.
La fonction appelant une commande de @emph{markup} peut altérer la
valeur de la propriété taille des fontes et donc en modifier le
Dans un souci d'esthétique, nous aimerions que le texte et les
encadrements ne soient pas autant accolés. Selon la documentation de
@code{\box}, cette commande utilise la propriété @code{box-padding},
-fixée par défaut à@tie{}0,2. Cette même documentation nous indique
-aussi comment la modifier@tie{}:
+fixée par défaut à 0,2. Cette même documentation nous indique
+aussi comment la modifier :
@lilypond[quote,verbatim,ragged-right]
\markup \box \override #'(box-padding . 0.6) \box A
@end lilypond
-L'espacement des deux liserés est cependant toujours trop réduit@tie{};
-modifions le à son tour@tie{}:
+L'espacement des deux liserés est cependant toujours trop réduit ;
+modifions le à son tour :
@lilypond[quote,verbatim,ragged-right]
\markup \override #'(box-padding . 0.4) \box
"Dessine un double encadrement autour du texte."
(interpret-markup layout props
#@{\markup \override #'(box-padding . 0.4) \box
- \override #'(box-padding . 0.6) \box @{ $text @}#@}))
+ \override #'(box-padding . 0.6) \box @{ #text @}#@}))
@end lisp
ou bien son équivalent
transformation d'une expression @code{\markup} en expression Scheme est
des plus triviales.
-Notre commande personnalisée s'utilise ainsi@tie{}:
+Notre commande personnalisée s'utilise ainsi :
@example
\markup \double-box A
distinguer l'espacement entre les encadrements de l'espacement entre le
texte et ses encadrements. Nous allons donc introduire une propriété
supplémentaire, que nous appellerons @code{inter-box-padding}, chargée
-de gérer l'espacement des encadrements@tie{}; @code{box-padding} ne
+de gérer l'espacement des encadrements ; @code{box-padding} ne
servira alors que pour l'espacement intérieur. Voici le code adapté à
-ces évolutions@tie{}:
+ces évolutions :
@lisp
#(define-markup-command (double-box layout props text) (markup?)
(interpret-markup layout props
#@{\markup \override #`(box-padding . ,inter-box-padding) \box
\override #`(box-padding . ,box-padding) \box
- @{ $text @} #@}))
+ @{ #text @} #@}))
@end lisp
-Ainsi que son équivalent à partir de la macro @emph{markup}@tie{}:
+Ainsi que son équivalent à partir de la macro @emph{markup} :
@lisp
#(define-markup-command (double-box layout props text) (markup?)
Ces valeurs permettront alors d'adapter les propriétés de
@code{box-padding} utilisées par les deux commandes @code{\box}. Vous
aurez remarqué, dans l'argument @code{\override}, la présence de
-l'apostrophe inversée (@code{`}) et de la virgule@tie{}; elles vous
+l'apostrophe inversée (@code{`}) et de la virgule ; elles vous
permettent d'insérer une valeur variable au sein d'une expression
littérale.
(interpret-markup layout props
#{\markup \override #`(box-padding . ,inter-box-padding) \box
\override #`(box-padding . ,box-padding) \box
- { $text } #}))
+ { #text } #}))
\markup \double-box A
\markup \override #'(inter-box-padding . 0.8) \double-box A
Nous pourrions, par exemple, envisager d'adapter la commande
@code{\draw-line} pour dessiner plutôt une ligne double. Voici comment
est définie la commande @code{\draw-line}, expurgée de sa
-documentation@tie{}:
+documentation :
@lisp
(define-markup-command (draw-line layout props dest)
(number-pair?)
#:category graphic
#:properties ((thickness 1))
- "..documentation.."
+ "@dots{}documentation@dots{}"
(let ((th (* (ly:output-def-lookup layout 'line-thickness)
thickness))
(x (car dest))
Avant de définir notre propre commande basée sur l'une de celles
fournies par LilyPond, commençons par en recopier la définition, puis
attribuons lui un autre nom. Le mot-clé @code{#:category} peut être
-supprimé sans risque@tie{}; il ne sert que lors de la génération de la
+supprimé sans risque ; il ne sert que lors de la génération de la
documentation et n'est d'aucune utilité pour une commande personnalisée.
@lisp
(define-markup-command (draw-double-line layout props dest)
(number-pair?)
#:properties ((thickness 1))
- "..documentation.."
+ "@dots{}documentation@dots{}"
(let ((th (* (ly:output-def-lookup layout 'line-thickness)
thickness))
(x (car dest))
Nous ajoutons ensuite une propriété pour gérer l'écart entre les deux
lignes, que nous appelons @code{line-gap}, et lui attribuons une valeur
-par défaut de 6 dixièmes@tie{}:
+par défaut de 6 dixièmes :
@lisp
(define-markup-command (draw-double-line layout props dest)
(number-pair?)
#:properties ((thickness 1)
(line-gap 0.6))
- "..documentation.."
- ...
+ "@dots{}documentation@dots{}"
+ @dots{}
@end lisp
Nous ajoutons enfin le code qui dessinera nos deux lignes. Deux appels
à @code{make-line-stencil} permettrons de dessiner les lignes dont nous
-regrouperons les stencils à l'aide de @code{ly:stencil-add}@tie{}:
+regrouperons les stencils à l'aide de @code{ly:stencil-add} :
@lilypond[quote,verbatim,ragged-right]
#(define-markup-command (my-draw-line layout props dest)
@subsection Définition d'une nouvelle commande de liste de @emph{markups}
@translationof New markup list command definition
+@funindex define-markup-list-command
+@funindex interpret-markup-list
+
Une commande traitant une liste de @emph{markups} se définit à l'aide de
la macro Scheme @code{define-markup-list-command}, de manière analogue à
la macro @code{define-markup-command} abordée à la rubrique
@ref{Définition d'une nouvelle commande de markup} à ceci près que cette
dernière renvoie un seul stencil, non une liste de stencils.
+La fonction @code{interpret-markup-list}, à l'instar de la fonction
+@code{interpret-markup}, permet de convertir une liste de @emph{markups}
+en liste de stencils.
+
Dans l'exemple suivant, nous définissons @code{\paragraph}, une commande
de liste de @emph{markups}, qui renverra une liste de lignes justifiées
dont la première sera indentée. La largeur de l'alinéa sera récupérée
#(define-markup-list-command (paragraph layout props args) (markup-list?)
#:properties ((par-indent 2))
(interpret-markup-list layout props
- #@{\markuplist \justified-lines @{ \hspace #par-indent $args @} #@}))
+ #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
@end example
-La version purement Scheme est un peu plus complexe@tie{}:
+La version purement Scheme est un peu plus complexe :
@example
#(define-markup-list-command (paragraph layout props args) (markup-list?)
#:properties ((par-indent 2))
Pour commencer, la fonction récupère la taille de l'alinéa, propriété
ici dénommée @code{par-indent}, à partir de la liste de propriétés
@code{props}. En cas d'absence, la valeur par défaut sera
-de@tie{}@code{2}. Ensuite est créée une liste de lignes justifiées
+de @code{2}. Ensuite est créée une liste de lignes justifiées
grâce à la commande prédéfinie @code{\justified-lines}, liée à la
fonction @code{make-justified-lines-markup-list}. Un espace horizontal
est ajouté en tête, grâce à @code{\hspace} ou à la fonction
@end example
@code{@var{fonction}} est constitué d'une fonction Scheme comportant un
-unique argument@tie{}: le contexte au sein duquel la commande
+unique argument : le contexte au sein duquel la commande
@code{\applyContext} est appelée. Les lignes de code qui suivent auront
pour effet d'afficher à l'écran, en cours de compilation, le numéro de
mesure en cours.
(@rinternals{ApplyOutputEvent}) dans le contexte spécifié. Elle répond
à la syntaxe
@example
-\applyOutput @var{contexte} @var{procédure}
+\applyOutput @var{Contexte} @var{procédure}
@end example
@noindent
Lors de l'interprétation de cette commande, la fonction
@code{@var{procédure}} est appelée pout tout objet de rendu appartenant
-au contexte @code{@var{contexte}} à cet instant précis, avec les
-arguments suivants@tie{}:
+au contexte @code{@var{Contexte}} à cet instant précis, avec les
+arguments suivants :
@itemize
@item l'objet de rendu en lui-même,
@item le contexte au sein duquel cet objet est créé,
@rinternals{NoteHead}, et d'un objet @rinternals{Stem} pour une hampe.
Voici une fonction utilisable avec la commande
-@code{\applyOutput}@tie{}: elle @qq{blanchit} la tête des notes se
+@code{\applyOutput} : elle @qq{blanchit} la tête des notes se
trouvant sur la ligne médiane ou bien directement à son contact.
@lilypond[quote,verbatim,ragged-right]
}
@end lilypond
+La @var{procédure} sera interprétée au niveau @code{Score}
+(partition) ou @code{Staff} dès lors que vous utiliserez l'une des
+syntaxes
+
+@example
+\applyOutput #'Score #@var{procédure}
+\applyOutput #'Staff #@var{procédure}
+@end example
+
@node Fonctions de rappel
@section Fonctions de rappel
ici@tie{}:
@example
-\override Stem #'thickness = #2.0
+\override Stem.thickness = #2.0
@end example
Une procédure Scheme peut aussi se charger de modifier des
propriétés@tie{}:
@lilypond[fragment,verbatim,quote,relative=2]
-\override Stem #'thickness = #(lambda (grob)
+\override Stem.thickness = #(lambda (grob)
(if (= UP (ly:grob-property grob 'direction))
2.0
7.0))
La procédure prend un unique argument, en l'occurrence l'objet graphique
(le @emph{grob}).
+Cette procédure, grâce à un appel à la fonction de rappel dévolue à
+cette propriété -- mentionnée dans la référence des propriétés internes
+et dans le fichier @file{define-grobs.scm} --, pourra accéder à la
+valeur usuelle de la propriété :
+
+@example
+\relative c'' @{
+ \override Flag #'X-offset = #(lambda (flag)
+ (let ((default (ly:flag::calc-x-offset flag)))
+ (* default 4.0)))
+ c4. d8 a4. g8
+@}
+@end example
+
Dans le cas où la routine doit faire appel à plusieurs arguments, le
@emph{grob} en cours peut s'insérer à l'aide d'un @emph{grob} enchâssé.
Voici, à titre d'illustration, un réglage pour
-@code{AccidentalSuggestion}@tie{}:
+@code{AccidentalSuggestion} :
@example
`(X-offset .
Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
@emph{markup} consiste à utiliser la fonction
-@code{grob-interpret-markup}, comme ici@tie{}:
+@code{grob-interpret-markup}, comme ici :
@example
my-callback = #(lambda (grob)
@section Code Scheme intégré
@translationof Inline Scheme code
-À REVOIR : l'exemple de cette rubrique n'est pas des plus judicieux puisque
-@example
-F = -\tweak #'font-size #-3 -\flageolet
-@end example
-(notez le @samp{-} qui qualifie d'événement postérieur) fonctionne
-correctement dans ce cas d'espèce. En attendant un remaniement de cette
- section, faisons comme si nous l'ignorions.
+À REVOIR : depuis la rédaction de cette section, LilyPond en est
+arrivé à un point tel que trouver un exemple @emph{simple} où l'on se
+retrouve obligé d'en venir à utiliser du code Scheme devient chose
+ardue.
+
+En attendant un remaniement de cette section, faisons comme si nous
+l'ignorions.
L'inconvénient principal de la commande @code{\tweak} est la rigidité de
-sa syntaxe. Par exemple, le code suivant produit une erreur.
+sa syntaxe. Par exemple, le code suivant produit une erreur de syntaxe
+(du moins, c'était le cas auparavant).
@example
-F = \tweak #'font-size #-3 -\flageolet
+F = \tweak font-size #-3 -\flageolet
\relative c'' @{
c4^\F c4_\F
@end example
@noindent
-En d'autres termes, @code{\tweak} ne se comporte pas comme une
-articulation@tie{}: il ne peut notamment pas être accolé avec les
-symboles @samp{^} ou @samp{_}.
-
C'est en se servant du langage Scheme que l'on peut résoudre ce
problème. Dans cet exemple, on a recours aux méthodes décrites dans
@ref{Ajout d'articulation à des notes (exemple)}, en
(ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
\relative c'' {
- \override Tie #'after-line-breaking =
+ \override Tie.after-line-breaking =
#my-callback
c1 ~ \break
- c2 ~ c
+ c2 ~ 2
}
@end lilypond
modifiés par @code{\override}. Parmi ceux-là, les objets
@code{NonMusicalPaperColumn} et @code{PaperColumn}. La commande
@code{\overrideProperty} sert à les modifier, de façon similaire à
-@code{\once \override} mais avec une syntaxe différente@tie{}:
+@code{\once \override} mais avec une syntaxe différente :
@example
\overrideProperty
-#"Score.NonMusicalPaperColumn" % Nom de l'objet
-#'line-break-system-details % Nom de la propriété
-#'((next-padding . 20)) % Valeur
+Score.NonMusicalPaperColumn % Nom de l'objet
+ . line-break-system-details % Nom de la propriété
+ . next-padding % Nom de la sous-propriété (optionnel)
+ . #20 % Valeur
@end example
Notez toutefois que la commande @code{\override} peut tout de même être
informations à partir et autour des fluxs de musique.
TODO -- figure out what goes in here and how to organize it
-
projects / lilypond.git / blobdiff