@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
@ignore
- Translation of GIT committish: 29d5e0a64d0eee69e4ebee1e76e4df26ae58190b
+ Translation of GIT committish: e3c6bd65c8db492728d2f1f3a791bcf6bde056e4
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.17.6"
+@c \version "2.19.2"
@c Translators: Valentin Villenave, Jean-Charles Malahieude
@c Translation checkers: Gilles Thibault
* Fonctions pour markups::
* Contextes pour programmeurs::
* Fonctions de rappel::
-* Code Scheme intégré::
* Retouches complexes::
@end menu
@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 ; vous devrez donc,
si ces valeurs par défaut ne peuvent être déterminées que plus tard,
@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.
-
-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
-au-delà de cette même expression afin d'en déterminer la fin. Si une
-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
-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 : 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} ? 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.
+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 situations pour lesquelles LilyPond lèvera toute
+ambiguïté grâce aux 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} ? 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 viendront modifier 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}.
@subsection Utilisation de fonctions musicales
@translationof Music function usage
-Une fonction musicale peut prendre place en différents endroits.
-Certaines restrictions s'appliqueront selon l'endroit où elle est
-utilisée, de telle sorte que l'analyse syntaxique soit sans ambiguïté.
-Le résultat renvoyé par une fonction musicale doit être compatible avec
-le contexte dans lequel elle est appelée.
+Une « fonction musicale » doit impérativement renvoyer une expression
+répondant au prédicat @code{ly:music?}. Ceci a pour conséquence
+d'autoriser l'appel à une fonction musicale en tant qu'argument de type
+@code{ly:music?} dans le cadre de l'appel à une autre fonction musicale.
+
+Certaines restrictions s'appliqueront selon le contexte où une fonction
+musicale est utilisée, de telle sorte que l'analyse syntaxique soit sans
+ambiguïté.
@itemize
@item
-Dans une expression musicale de haut niveau@tie{}: aucune restriction.
+Dans une expression musicale de haut niveau, aucun postévénement n'est
+toléré.
@item
-En tant que post-événement, explicitement introduit par un indicateur de
-positionnement -- à savoir @code{-}, @code{^}, ou@tie{}@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 ; ceci amène à un
-résultat ressemblant à
-@example
-s 1*0-\fonction
-@end example
-
-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.
+Lorsqu'une fonction musicale -- contrairement à une fonction
+événementielle -- renvoie une expression de type postévénement, LilyPond
+requiert son introduction par un indicateur de positionnement -- à
+savoir @code{-}, @code{^} ou @code{_} -- de telle sorte que le
+postévénement produit par l'appel à cette fonction s'intègre
+correctement dans l'expression environnante.
@item
-En tant que partie d'un accord. L'expression musicale renvoyée doit
+En tant que partie d'un accord, l'expression musicale renvoyée doit
être du type @code{rhythmic-event}, et plus particulièrement un
@code{NoteEvent}.
@end itemize
@noindent
-Les règles spécifiques en matière d'arguments de fin rendent possible
-l'écriture de fonctions polymorphes telles que @code{\tweak}, qui
-peuvent s'appliquer à différentes constructions.
+Des fonctions « polymorphes » telles que @code{\tweak} peuvent
+s'appliquer aux postévénements, constituants d'accord et expressions de
+haut niveau.
@node Fonctions de substitution simple
de @code{markup} pour manipuler des chaînes de caractères, ce qui est
particulièrement pratique lorsque vous créez votre propre commande de
@emph{markup} -- voir
-@ref{Définition d'une nouvelle commande de markup}.
+@ref{Définition d'une nouvelle commande de markup}.
@knownissues
L'argument @var{markup-list} des commandes @code{#:line},
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
@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
interprétée par la fonction @code{interpret-markup-list}.
Voici comment utiliser cette nouvelle commande de liste de
-@emph{markups}@tie{}:
+@emph{markups} :
@example
\markuplist @{
\paragraph @{
@cindex appel de code durant l'interprétation
@funindex \applyContext
+@funindex make-apply-context
+@funindex ly:context-property
+@funindex ly:context-set-property!
+@funindex ly:context-grob-definition
+@funindex ly:assoc-get
+@funindex ly:context-pushpop-property
Un contexte peut être modifié, au moment même de son interprétation, par
-du code Scheme. La syntaxe consacrée en pareil cas est
+du code Scheme. La syntaxe consacrée au sein d'un bloc LilyPond est
+
@example
\applyContext @var{fonction}
@end example
+@noindent
+et, dans le cadre d'un code Scheme :
+
+@example
+(make-apply-context @var{fonction})
+@end example
+
@code{@var{fonction}} est constitué d'une fonction Scheme comportant un
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.
+@code{\applyContext} est appelée. Cette fonction peut accéder aussi
+bien aux propriétés de @emph{grob} (y compris modifiées par
+@code{\override} ou @code{\set}) qu'aux propriétés de contexte. Toute
+action entreprise par la fonction et qui dépendrait de l'état du
+contexte sera limitée à l'état de ce contexte @b{au moment de l'appel à
+la fonction}. Par ailleurs, les adaptations résultant d'un appel à
+@code{\applyContext} seront effectives jusqu'à ce qu'elles soient à
+nouveau directement modifiées ou bien annulées, quand bien même les
+conditions initiales dont elles dépendent auraient changé.
+
+Voici quelques fonctions Scheme utiles avec @code{\applyContext} :
-@example
+@table @code
+@item ly:context-property
+recherche la valeur d'une propriété de contexte,
+
+@item ly:context-set-property!
+détermine une propriété de contexte,
+
+@item ly:context-grob-definition
+@itemx ly:assoc-get
+recherche la valeur d'une propriété de @emph{grob},
+
+@item ly:context-pushpop-property
+réalise un @code{\temporary@tie{}\override} ou un @code{\revert} sur une
+propriété de @emph{grob}.
+@end table
+
+L'exemple suivant recherche la valeur en cours de @code{fontSize} puis
+la double :
+
+@lilypond[quote,verbatim]
+doubleFontSize =
\applyContext
- #(lambda (x)
- (format #t "\nNous en sommes à la mesure ~a.\n"
- (ly:context-property x 'currentBarNumber)))
-@end example
+ #(lambda (context)
+ (let ((fontSize (ly:context-property context 'fontSize)))
+ (ly:context-set-property! context 'fontSize (+ fontSize 6))))
+
+{
+ \set fontSize = -3
+ b'4
+ \doubleFontSize
+ b'
+}
+@end lilypond
+
+L'exemple suivant recherche la couleur des objets @code{NoteHead},
+@code{Stem} et @code{Beam}, puis diminue pour chacun d'eux le degré de
+saturation.
+
+@lilypond[quote,verbatim]
+desaturate =
+\applyContext
+ #(lambda (context)
+ (define (desaturate-grob grob)
+ (let* ((grob-def (ly:context-grob-definition context grob))
+ (color (ly:assoc-get 'color grob-def black))
+ (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
+ (ly:context-pushpop-property context grob 'color new-color)))
+ (for-each desaturate-grob '(NoteHead Stem Beam)))
+
+\relative g' {
+ \time 3/4
+ g8[ g] \desaturate g[ g] \desaturate g[ g]
+ \override NoteHead.color = #darkred
+ \override Stem.color = #darkred
+ \override Beam.color = #darkred
+ g[ g] \desaturate g[ g] \desaturate g[ g]
+}
+@end lilypond
+
+Ceci pourrait tout à fait s'implémenter sous la forme d'une fonction
+musicale, afin d'en réduire les effets à un seul bloc de musique. Notez
+comment @code{ly:context-pushpop-property} est utilisé à la fois pour un
+@code{\temporary@tie{}\override} et pour un @code{\revert} :
+
+@lilypond[quote,verbatim]
+desaturate =
+#(define-music-function
+ (parser location music) (ly:music?)
+ #{
+ \applyContext
+ #(lambda (context)
+ (define (desaturate-grob grob)
+ (let* ((grob-def (ly:context-grob-definition context grob))
+ (color (ly:assoc-get 'color grob-def black))
+ (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
+ (ly:context-pushpop-property context grob 'color new-color)))
+ (for-each desaturate-grob '(NoteHead Stem Beam)))
+ #music
+ \applyContext
+ #(lambda (context)
+ (define (revert-color grob)
+ (ly:context-pushpop-property context grob 'color))
+ (for-each revert-color '(NoteHead Stem Beam)))
+ #})
+
+\relative g' {
+ \override NoteHead.color = #darkblue
+ \override Stem.color = #darkblue
+ \override Beam.color = #darkblue
+ g8 a b c
+ \desaturate { d c b a }
+ g b d b g2
+}
+@end lilypond
@node Application d'une fonction à tous les objets de mise en forme
@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
+(partition) ou @code{Staff} (portée) dès lors que vous utiliserez l'une
+des syntaxes
@example
\applyOutput #'Score #@var{procédure}
La procédure prend un unique argument, en l'occurrence l'objet graphique
(le @emph{grob}).
-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} :
+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
-`(X-offset .
- ,(ly:make-simple-closure
- `(,+
- ,(ly:make-simple-closure
- (list ly:self-alignment-interface::centered-on-x-parent))
- ,(ly:make-simple-closure
- (list ly:self-alignment-interface::x-aligned-on-self)))))
-@end example
-
-@noindent
-Ici, aussi bien @code{ly:self-alignment-interface::x-aligned-on-self}
-que @code{ly:self-alignment-interface::centered-on-x-parent} font appel
-à l'argument @emph{grob}. La fonction @code{+} a pour effet
-d'additionner les résultats. L'ensemble est inclus dans un
-@code{ly:make-simple-closure} de telle sorte que l'addition s'exécute de
-façon correcte
-
-Dans les faits, l'utilisation d'une unique procédure en tant que valeur
-d'une propriété revient à écrire
-
-@example
-(ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
+\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
-@noindent
-Le @code{ly:make-simple-closure} intérieur fournit le @emph{grob} en
-argument à la procédure @var{proc}, l'extérieur s'assure que le résultat
-de la fonction sera bien renvoyé, non pas l'objet @code{simple-closure}.
-
Au sein d'un @emph{callback}, le meilleur moyen d'évaluer un
@emph{markup} consiste à utiliser la fonction
@code{grob-interpret-markup}, comme ici :
@end example
-@node Code Scheme intégré
-@section Code Scheme intégré
-@translationof Inline Scheme code
+@ignore
+@n ode Code Scheme intégré
+@s ection Code Scheme intégré
+@t ranslationof 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
@end example
@noindent
-En d'autres termes, @code{\tweak} ne se comporte pas comme une
-articulation : 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
@code{set!}. Le dernier élément, dans ce bloc @code{let}, est la valeur
finale de @samp{m} lui-même.
+@end ignore
+
@node Retouches complexes
@section Retouches complexes
\override Tie.after-line-breaking =
#my-callback
c1 ~ \break
- c2 ~ c
+ c2 ~ 2
}
@end lilypond
projects / lilypond.git / blobdiff