@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
@ignore
- Translation of GIT committish: 76de7e168dbc9ffc7671d99663c5ce50dae42abb
+ Translation of GIT committish: 9034fc53a974a6d006157ebcf52f091a85be30f5
When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.15.10"
@c Translators: Valentin Villenave, Jean-Charles Malahieude
@c Translation checkers: Gilles Thibault
LilyPond est conçu pour engendrer, par défaut, des partitions de la
plus haute qualité. Cependant, on peut parfois avoir à modifier cette
-mise en page par défaut. Celle-ci est réglée par tout un ensemble de
-@qq{leviers et manettes}, dont ce chapitre ne cherche pas à faire
-l'inventaire exhaustif. Le propos est plutôt ici de mettre en évidence
-les différents groupes auxquels s'apparentent ces contrôles, et d'expliquer
-comment trouver le bon levier pour obtenir tel ou tel effet en particulier.
+mise en forme par défaut. Celle-ci est réglée par tout un ensemble de
+@qq{leviers et manettes} plus connus sous le terme de @qq{propriétés},
+dont ce chapitre ne cherche pas à faire l'inventaire exhaustif -- le
+chapitre @rlearning{Retouche de partition} du manuel d'initiation vous
+en propose un aperçu. Le propos est plutôt ici de mettre en évidence
+les différents groupes auxquels s'apparentent ces contrôles, et
+d'expliquer comment trouver le bon levier pour obtenir tel ou tel effet
+en particulier.
@cindex Référence des propriétés internes
-Les moyens de contrôle des différents réglages sont décrits dans un document
-séparé, la
-@iftex
-référence des propriétés internes
-@end iftex
-@ifnottex
-@ref{Top,Référence des propriétés internes,,lilypond-internals}.
-@end ifnottex
-Ce guide répertorie toutes les variables, fonctions et autres options que
-LilyPond met à votre disposition. Il est consultable
+Les moyens de contrôle des différents réglages sont décrits dans un
+document séparé, @rinternalsnamed{Top,la référence des propriétés
+internes}. Ce guide répertorie toutes les variables, fonctions et
+autres options que LilyPond met à votre disposition. Il est consultable
@c leave the @uref as one long line.
-@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,en@tie{}ligne},
-au format HTML, mais est également inclus dans la documentation
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/internals/,en@tie{}ligne},
+au format HTML@tie{}; il est également inclus dans la documentation
fournie avec le logiciel.
-Il est quatre domaines dans lesquels on peut modifier les réglages par
-défaut :
-
-@itemize @bullet
-@item
-La notation automatique, ce qui revient à modifier la manière dont les
-éléments de notation sont automatiquement créés -- par exemple, les
-règles de ligature.
-
-@item
-L'apparence, qui se rapporte aux objets pris individuellement -- ainsi
-de la direction des hampes, du placement des indications textuelles.
-
-@item
-Les contextes, qui recouvrent la manière dont les évènements musicaux
-sont représentés sous forme de notation -- par exemple, le fait
-d'attribuer un chiffre de mesure distinct à chaque portée.
-
-@item
-La mise en page, autrement dit les marges, l'espacement, la taille du
-papier ; tous ces facteurs font l'objet des chapitres
-@ref{Généralités en matière d'entrée et sortie} et @ref{Gestion de l'espace}.
-@end itemize
-
-En sous-main, LilyPond se sert du langage Scheme (un dérivé du LISP) comme
-infrastructure. Modifier les choix de mise en page revient à pénétrer dans
-les entrailles du programme, et de ce fait requiert l'emploi du Scheme.
-Les fragments de Scheme, dans un fichier @code{.ly}, sont introduits par le
-caractère @q{hash}, (@code{#}, improprement surnommé @q{dièse}).@footnote{Le
-@rlearning{Tutoriel Scheme} fournit quelques notions de base pour saisir
-des nombres, des listes, des chaînes de caractères ou des symboles, en
-Scheme.}
-
+En sous-main, LilyPond se sert du langage Scheme (un dérivé du LISP)
+comme infrastructure. Modifier les choix de mise en page revient à
+pénétrer dans les entrailles du programme, et de ce fait requiert
+l'emploi du Scheme. Les fragments de Scheme, dans un fichier
+@file{.ly}, sont introduits par le caractère @emph{hash} (@code{#}),
+improprement surnommé @qq{dièse}.
+@footnote{Le @rextend{Tutoriel Scheme} fournit quelques notions de base
+pour saisir des nombres, des listes, des chaînes de caractères ou des
+symboles, en Scheme.}
@menu
* Contextes d'interprétation::
-* En quoi consiste la référence du programme::
+* En quoi consiste la référence des propriétés internes::
* Modification de propriétés::
* Propriétés et contextes utiles::
* Retouches avancées::
+* Utilisation de fonctions musicales::
@end menu
+
@node Contextes d'interprétation
@section Contextes d'interprétation
@translationof Interpretation contexts
* Modification des greffons de contexte::
* Modification des réglages par défaut d'un contexte::
* Définition de nouveaux contextes::
-* Alignement des contextes::
+* Ordonnancement des contextes::
@end menu
@rlearning{Contextes et graveurs}.
Fichiers d'initialisation :
-@file{ly/@/engraver@/-init@/.ly},
-@file{ly/@/performer@/-init@/.ly}.
+@file{ly/engraver-init.ly},
+@file{ly/performer-init.ly}.
Morceaux choisis :
-@rlsr{Contexts and engravers}.
+@rlsrnamed{Contexts and engravers, Contextes et graveurs}.
Référence des propriétés internes :
@rinternals{Contexts},
@c TODO Describe propagation of property values -td
+Les contextes sont hiérarchisés :
@menu
* Score -- le père de tous les contextes::
@node Score -- le père de tous les contextes
@unnumberedsubsubsec Score -- le père de tous les contextes
-@translationof Score - the master of all contexts @c external
+@translationof Score - the master of all contexts
+
+Il s'agit en l'occurrence du contexte le plus élevé, autrement dit le
+plus important, en matière de notation. En effet, c'est au niveau de la
+partition -- @emph{score} en anglais -- que se gèrent le temps et la
+tonalité@tie{}; c'est donc là qu'il faut s'assurer que les différents
+éléments, tels les clefs, métriques et armures sont bien répercutés sur
+toutes les portées.
-@untranslated
+Dès lors que LilyPond rencontre un bloc @code{\score@tie{}@{@dots{}@}}
+ou @code{\layout@tie{}@{@dots{}@}}, se crée implicitement un contexte
+@code{Score}.
@node Contextes de haut niveau -- les systèmes
@unnumberedsubsubsec Contextes de haut niveau -- les systèmes
-@translationof Top-level contexts - staff containers @c external
+@translationof Top-level contexts - staff containers
+
+De nombreuses partitions sont écrites sur plus d'une portée. Ces
+portées peuvent être regroupées de différentes manières.
+
+@strong{@emph{StaffGroup}}
-@untranslated
+Le groupe de portées est attaché par un crochet, et les barres de mesure
+sont d'un seul tenant, de la première à la dernière portée. Le
+@code{StaffGroup} constitue le regroupement le plus simple.
+
+@strong{@emph{ChoirStaff}}
+
+Ce regroupement est identique au @code{StaffGroup}, à ceci près que les
+barres de mesure ne traversent pas l'espace inter-portées.
+
+@strong{@emph{GrandStaff}}
+
+Le groupe de portées est attaché par une accolade sur la gauche, et les
+barres de mesure sont d'un seul tenant.
+
+@strong{@emph{PianoStaff}}
+
+Ce regroupement est identique au @code{GrandStaff}, à ceci près que le
+nom de l'instrument sera directement attaché au système.
@node Contextes de niveau intermédiaire -- les portées
@unnumberedsubsubsec Contextes de niveau intermédiaire -- les portées
-@translationof Intermediate-level contexts - staves @c external
+@translationof Intermediate-level contexts - staves
+
+@strong{@emph{Staff}}
+
+La portée prend en charge les clefs, barres de mesure, armures et les
+altérations accidentelles. Un contexte @code{Staff} peut contenir
+plusieurs contextes @code{Voice}.
+
+@strong{@emph{RhythmicStaff}}
+
+De même nature qu'un @code{Staff}, mais destiné à n'imprimer que du
+rythme. Quelle que soit la hauteur, les notes seront imprimées sur une
+même et unique ligne.
+
+@strong{@emph{TabStaff}}
+
+Ce contexte permet de générer des tablatures. La mise en forme par
+défaut correspond à une tablature pour guitare, sur six lignes.
+
+@strong{@emph{DrumStaff}}
+
+Contexte dévolu tout spécialement aux parties de percussion@tie{}; il
+peut contenir plusieurs @code{DrumVoice}.
+
+@strong{@emph{VaticanaStaff}}
+
+Identique au contexte @code{Staff}, à ceci près qu'il est tout
+particulièrement adapté au grégorien.
-@untranslated
+@strong{@emph{MensuralStaff}}
+
+Identique au contexte @code{Staff}, à ceci près qu'il est tout
+particulièrement adapté au style mensural de musique ancienne.
@node Contextes de bas niveau -- les voix
@unnumberedsubsubsec Contextes de bas niveau -- les voix
-@translationof Bottom-level contexts - voices @c external
+@translationof Bottom-level contexts - voices
+
+Les contextes de niveau @qq{voix} initialisent un certain nombre de
+propriétés et activent les graveurs appropriés. S'agissant de contextes
+du plus bas niveau, ils ne sauraient contenir d'autre contexte.
+
+@strong{@emph{Voice}}
+
+Correspond à une voix positionnée sur une portée. Le contexte
+@code{Voice} s'occupe des indications de nuance, des hampes, des
+ligatures, des scripts placés au-dessus ou au-dessous de la portée, des
+différentes liaisons et des silences. Lorsque plusieurs voix doivent
+cohabiter sur la même portée, il est indispensable de les instancier
+explicitement.
+
+@strong{@emph{VaticanaVoice}}
+
+Fonctionnant comme le contexte @code{Voice}, il est tout
+particulièrement destiné à gérer le grégorien.
+
+@strong{@emph{MensuralVoice}}
+
+Fonctionnant comme le contexte @code{Voice}, il est tout
+particulièrement adapté aux musiques anciennes.
+
+@strong{@emph{Lyrics}}
+
+Correspond à une voix contenant des paroles. Le contexte @code{Lyrics}
+gère l'impression d'une ligne de paroles.
+
+@strong{@emph{DrumVoice}}
+
+Contexte de voix dévolu à une portée de percussions.
+
+@strong{@emph{FiguredBass}}
+
+Contexte prenant en charge les objets @code{BassFigure} -- la basse
+chiffrée -- créés à partir de ce qui a été saisi en mode
+@code{\figuremode}.
+
+@strong{@emph{TabVoice}}
+
+Contexte de voix dévolu au contexte @code{TabStaff}, il est
+habituellement créé explicitement.
-@untranslated
+@strong{@emph{CueVoice}}
+
+Contexte de voix utilisé essentiellement dans le cadre de citations
+ajoutées à une portée -- voir @ref{Mise en forme d'une citation}. Il
+est habituellement créé explicitement.
+
+@strong{@emph{ChordNames}}
+
+Permet d'imprimer des noms d'accord.
+
+@ignore
+TODO
+
+Then the following, which I don't know what to do with:
+
+ * GregorianTranscriptionVoice
+ * GregorianTranscriptionStaff
+
+ * FretBoards
+ Engraves fretboards from chords. Not easy... Not
+documented.
+ There is now some documentation on FretBoards in the NR, under
+ instrument-specific notation -- cds.
+
+ * NoteNames
+
+ * Global
+ Hard coded entry point for LilyPond. Cannot be tuned.
+ * Devnull
+ Silently discards all musical information given to this
+context.
+
+@end ignore
@node Création d'un contexte
@subsection Création d'un contexte
-@translationof Creating contexts @c external
+@translationof Creating contexts
+
+@c TODO more complete descriptions rather than learning style
+
+Lorsqu'une partition ne comporte qu'une portée avec une seule voix, les
+contextes sont créés automatiquement. Dès que la structure s'étoffe, il
+devient nécessaire de les créer explicitement, en suivant l'une des
+trois méthodes suivantes@tie{}:
+
+@itemize
-@untranslated
+@item
+La commande la plus simple à utiliser est @code{\new}@tie{}; c'est aussi
+la plus courte. Elle se place juste avant une expression musicale et se
+libelle ainsi@tie{}:
+
+@funindex \new
+@cindex nouveau contexte
+@cindex contexte, création
+
+@example
+\new @var{type} @var{expression_musicale}
+@end example
+
+@noindent
+où @var{type} est le nom d'un contexte (par ex. @code{Staff} ou
+@code{Voice}). Cette commande crée un nouveau contexte et y interprète
+le contenu de l'@var{expression_musicale}.
+
+C'est ce qui se passe lorsqu'une partition comporte plusieurs
+portées@tie{}: chaque partie qui doit apparaître sur une portée
+spécifique est précédée d'un @code{\new@tie{}Staff}.
+
+@lilypond[quote,verbatim,relative=2,ragged-right]
+<<
+ \new Staff { c4 c }
+ \new Staff { d4 d }
+>>
+@end lilypond
+
+La commande @code{\new} vous permet aussi d'attribuer un nom au
+contexte que vous créez.
+
+@example
+\new @var{type} = @var{nom} @var{musique}
+@end example
+Le nom que vous spécifiez ne pourra être utilisé que s'il n'a pas déjà
+été attribué à un autre contexte.
+
+@funindex \context
+@item
+Tout comme @code{\new}, la commande @code{\context} affectera une
+expression musicale à un objet contextuel@tie{}; elle lui attribuera de
+surcroît un nom. La commande @code{\context} s'emploie de la façon
+suivante@tie{}:
+
+@example
+\context @var{type} = @var{nom} @var{musique}
+@end example
+
+LilyPond va dans un premier temps vérifier l'existence d'un contexte du
+type @var{type} appelé @var{nom}. En l'absence d'un tel contexte,
+LilyPond crée un nouveau contexte du nom que vous avez spécifié. Cette
+procédure est tout à fait pertinente lorsque vous faites appel à ce
+contexte particulier par la suite. Prenons le cas d'un chant@tie{}:
+nous commençons par nommer la ligne mélodique,
+
+@example
+\context Voice = "@b{tenor}" @var{musique}
+@end example
+
+@noindent
+de telle sorte que le texte s'aligne correctement sur les notes@tie{}:
+
+@example
+\new Lyrics \lyricsto "@b{tenor}" @var{paroles}
+@end example
+
+@noindent
+
+L'une des autres utilisations de contextes explicitement nommés consiste
+à fusionner deux expressions musicales dans un même contexte. Dans
+l'exemple qui suit, notes et articulations sont saisies indépendamment.
+
+@example
+music = @{ c4 c4 @}
+arts = @{ s4-. s4-> @}
+@end example
+
+Elles sont ensuite fusionnées par affectation au même contexte
+@code{Voice}.
+
+@example
+<<
+ \new Staff \context Voice = "A" \music
+ \context Voice = "A" \arts
+>>
+@end example
+@lilypond[quote,ragged-right]
+music = { c4 c4 }
+arts = { s4-. s4-> }
+\relative c'' <<
+ \new Staff \context Voice = "A" \music
+ \context Voice = "A" \arts
+>>
+@end lilypond
+
+Grâce à ce mécanisme, vous pouvez tout à fait générer une version
+@qq{Urtext} (édition originale) et optionnellement ajouter distinctement
+des articulations à ces mêmes notes.
+
+@cindex création de contextes
+
+@item
+Voici une troisième manière de créer un contexte@tie{}:
+
+@example
+\context @var{type} @var{musique}
+@end example
+
+@noindent
+Très comparable à une déclaration @code{\context@tie{}=@tie{}@var{nom}},
+cette méthode permet de s'affranchir du type de contexte.
+
+Cette variante s'utilise lorsque les expression musicales peuvent être
+interprétées à différents niveaux, comme par exemple lorsque intervient
+la commande @code{\applyOutput} -- pour de plus amples détails, voir
+@rextend{Application d'une fonction à tous les objets de mise en forme}.
+En l'absence de @code{\context} explicite, LilyPond considère qu'il
+s'agit de @code{Voice}.
+
+@example
+\applyOutput #'@var{contexte} #@var{fonction} % s'applique à Voice
+@end example
+
+Vous devrez respecter ces formulations si votre fonction doit
+s'interpréter au niveau @code{Score} ou @code{Staff}@tie{}:
+
+@example
+\applyOutput #'Score #@var{fonction}
+\applyOutput #'Staff #@var{fonction}
+@end example
+
+@end itemize
@node Conservation d'un contexte
@subsection Conservation d'un contexte
-@translationof Keeping contexts alive @c external
+@translationof Keeping contexts alive
+
+@cindex contextes, maintien actif
+@cindex contextes, durée de vie
+
+En règle générale, un contexte disparaît dès qu'il n'y a plus rien à
+faire. Autrement dit, un contexte @code{Voice} disparaît dès après le
+dernier événement qu'il contient, et un contexte @code{Staff} dès que
+les contextes @code{Voice} qu'il supporte ne contiennent plus rien.
+Ceci peut avoir des conséquences néfastes lorsqu'il est fait référence à
+un contexte alors disparu, comme dans le cas d'un changement de portée
+introduit par la commande @code{\change}, l'association de paroles à
+l'aide de la commande @code{\lyricsto} ou si des événements surviennent
+à nouveau pour ce contexte précédemment actif.
+
+Une exception cependant à cette règle@tie{}: en présence d'un contexte
+@code{Staff} ou dans une construction @code{<<...>>}, un seul des
+contextes @code{Voice} inclus restera actif jusqu'à la fin du contexte
+@code{Staff} ou de la construction @code{<<...>>}, y compris s'il y
+a des @qq{trous}. Le contexte alors persistant sera le premier
+rencontré dans la construction @code{@{...@}} sans tenir compte des
+éventuels @code{<<...>>} qu'elle pourrait contenir.
+
+Un contexte restera actif dès lors qu'il s'y passera toujours quelque
+chose. Un contexte @code{Staff} restera actif si l'une des voix qu'il
+supporte est toujours active. L'un des moyens de s'en assurer
+consiste à ajouter des silences invisibles parallèlement à la musique.
+Vous devrez les ajouter dans tous les contextes @code{Voice} qui doivent
+rester actifs. Nous vous conseillons, lorsque plusieurs voix
+interviennent de manière sporadique, de toutes les maintenir actives
+plutôt que de vous fier aux exceptions mentionnées plus haut.
+
+Dans l'exemple suivant, les deux voix A et B sont maintenues actives
+jusqu'à la fin du morceau@tie{}:
+
+@lilypond[quote,verbatim]
+musicA = \relative c'' { d4 d d d }
+musicB = \relative c'' { g4 g g g }
+keepVoicesAlive = {
+ <<
+ \new Voice = "A" { s1*5 } % Keep Voice "A" alive for 5 bars
+ \new Voice = "B" { s1*5 } % Keep Voice "B" alive for 5 bars
+ >>
+}
+
+music = {
+ \context Voice = "A" {
+ \voiceOneStyle
+ \musicA
+ }
+ \context Voice = "B" {
+ \voiceTwoStyle
+ \musicB
+ }
+ \context Voice = "A" { \musicA }
+ \context Voice = "B" { \musicB }
+ \context Voice = "A" { \musicA }
+}
+
+\score {
+ \new Staff <<
+ \keepVoicesAlive
+ \music
+ >>
+}
+@end lilypond
-@untranslated
+@cindex paroles, alignement sur une mélodie épisodique
+
+L'exemple suivant illustre la manière d'écrire selon cette méthode une
+mélodie discontinue à laquelle se rattachent des paroles. Dans la
+réalité, mélodie et accompagnement feraient l'objet de portées séparées.
+
+@lilypond[quote,verbatim]
+melody = \relative c'' { a4 a a a }
+accompaniment = \relative c' { d4 d d d }
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+\score {
+ <<
+ \new Staff = "music" {
+ <<
+ \new Voice = "melody" {
+ \voiceOne
+ s1*4 % Keep Voice "melody" alive for 4 bars
+ }
+ {
+ \new Voice = "accompaniment" {
+ \voiceTwo
+ \accompaniment
+ }
+ <<
+ \context Voice = "melody" { \melody }
+ \context Voice = "accompaniment" { \accompaniment }
+ >>
+ \context Voice = "accompaniment" { \accompaniment }
+ <<
+ \context Voice = "melody" { \melody }
+ \context Voice = "accompaniment" { \accompaniment }
+ >>
+ }
+ >>
+ }
+ \new Lyrics \with { alignAboveContext = #"music" }
+ \lyricsto "melody" { \words }
+ >>
+}
+@end lilypond
+
+Une autre méthode, qui s'avère plus productive dans nombre de cas,
+consiste à maintenir active la ligne mélodique en y insérant des
+silences invisibles tout au long de l'accompagnement@tie{}:
+
+@lilypond[quote,verbatim]
+melody = \relative c'' {
+ s1 % skip a bar
+ a4 a a a
+ s1 % skip a bar
+ a4 a a a
+}
+accompaniment = \relative c' {
+ d4 d d d
+ d4 d d d
+ d4 d d d
+ d4 d d d
+}
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+
+\score {
+ <<
+ \new Staff = "music" {
+ <<
+ \new Voice = "melody" {
+ \voiceOne
+ \melody
+ }
+ \new Voice = "accompaniment" {
+ \voiceTwo
+ \accompaniment
+ }
+ >>
+ }
+ \new Lyrics \with { alignAboveContext = #"music" }
+ \lyricsto "melody" { \words }
+ >>
+}
+@end lilypond
@node Modification des greffons de contexte
@subsection Modification des greffons de contexte
@translationof Modifying context plug-ins
+@c TODO Should this be Modifying engravers or Modifying contexts?
+
Les contextes, tels que @code{Score} ou @code{Staff}, ne contiennent
-pas que des propriétés ; ils mettent également en œuvre certains
-sous-programmes (@q{plug-ins}, pour employer le terme consacré) nommés
-@q{graveurs} (@q{engravers}, pour reprendre le terme anglais).
+pas que des propriétés@tie{}; ils mettent également en œuvre certains
+sous-programmes (@emph{plug-ins} pour employer le terme consacré) nommés
+@qq{graveurs} (@emph{engravers} pour reprendre le terme anglais).
Ces sous-programmes sont chargés de créer les différents éléments de
-notation :
-On trouve ainsi dans le contexte @code{Voice}, un graveur
-@code{Note_head_engraver},
-chargé des têtes de notes, et dans le contexte @code{Staff}, un graveur
-@code{Key_signature_engraver}, chargé de l'armure.
+notation@tie{}: on trouve ainsi dans le contexte @code{Voice} un graveur
+@code{Note_heads_engraver}, chargé des têtes de notes et, dans le
+contexte @code{Staff}, un graveur @code{Key_engraver}, chargé de
+l'armure.
Vous trouverez une description exhaustive de chaque graveur dans
@ifhtml
@rinternals{Engravers and Performers}.
@end ifhtml
@ifnothtml
-Program reference @expansion{} Translation @expansion{} Engravers.
+Référence des propriétés internes @expansion{} Translation @expansion{} Engravers.
@end ifnothtml
Chaque contexte mentionné dans
@ifhtml
@rinternals{Contexts}
@end ifhtml
@ifnothtml
-Program reference @expansion{} Translation @expansion{} Context.
+Référence des propriétés internes @expansion{} Translation @expansion{} Context.
@end ifnothtml
répertorie les graveurs mis en œuvre.
-
On peut faire, au moyen de ces graveurs, sa propre @qq{cuisine}, en
modifiant les contextes à volonté.
-
-Lorsque un contexte est créé, par la commande @code{\new} ou @code{\context}, on peut
-y adjoindre un bloc @code{\with} (en anglais @q{avec}), dans lequel il est possible
-d'ajouter (commande @code{\consists}) ou d'enlever (commande @code{\remove})
-des graveurs :
+Lorsqu'un contexte est créé, par la commande @code{\new} ou
+@code{\context}, on peut y adjoindre un bloc @code{\with} (en anglais
+@qq{avec}), dans lequel il est possible d'ajouter (commande
+@code{\consists}) ou d'enlever (commande @code{\remove}) des
+graveurs@tie{}:
@funindex \with
@end example
@noindent
-Ici les points de suspension @dots{} devront être remplacés par les noms
+Ici les points de suspension @dots{} devront être remplacés par le nom
des graveurs désirés. Dans l'exemple suivant, on enlève du contexte
-@code{Staff}, le chiffre de mesure (graveur @code{Time_signature_engraver})
+@code{Staff}, la métrique (graveur @code{Time_signature_engraver})
et la clé (graveur @code{Clef_engraver}).
-@lilypond[quote,relative=1,verbatim,fragment]
+@lilypond[quote,relative=1,verbatim]
<<
\new Staff {
f2 g
jusqu'à la fin de la partition. L'espacement s'en trouve également
affecté, ce qui peut être ou non l'effet recherché. Une méthode plus
sophistiquée aurait été de rendre ces objets transparents (voir
-@rlearning{Visibilité et couleur des objets}).
+@rlearning{Visibilité et couleur des objets}).
Dans l'exemple suivant, voici une mise en pratique plus utile. En temps
-normal, les barres de mesure et la métrique sont synchronisées verticalement
-dans toute la partition. Les graveurs qui en sont responsables se nomment
-@code{Timing_translator} et @code{Default_bar_line_engraver}.
-En les enlevant du contexte @code{Score} pour les attribuer au contexte
-@code{Staff}, chaque portée peut désormais avoir sa propre métrique.
+normal, les barres de mesure et la métrique sont synchronisées
+verticalement dans toute la partition. Les graveurs qui en sont
+responsables se nomment @code{Timing_translator} et
+@code{Default_bar_line_engraver}. En les enlevant du contexte
+@code{Score} pour les attribuer au contexte @code{Staff}, chaque portée
+peut désormais avoir sa propre métrique.
@cindex polymétrique, partition
-@cindex Chiffres de mesure multiples
-
-@lilypond[quote,relative=1,ragged-right,verbatim,fragment]
-\new Score \with {
- \remove "Timing_translator"
- \remove "Default_bar_line_engraver"
-} <<
+@cindex chiffres de mesure multiples
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff \with {
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
+ } {
+ \time 3/4
+ c4 c c c c c
+ }
\new Staff \with {
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
} {
- \time 3/4
+ \time 2/4
c4 c c c c c
}
- \new Staff \with {
- \consists "Timing_translator"
- \consists "Default_bar_line_engraver"
- } {
- \time 2/4
- c4 c c c c c
- }
>>
+\layout {
+ \context {
+ \Score
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
+ }
+ }
+}
@end lilypond
+En règle générale, l'ordre dans lequel les graveurs sont mentionnés
+importe peu. Il se peut toutefois qu'un graveur écrive une propriété
+qui sera interprétée par un autre, ou qu'un graveur crée un objet
+graphique qui sera traité par un autre@tie{}; l'ordre d'apparition de
+ces graveurs prendra alors tout son importance.
-@c deprecated node: delete. --fv
-@ignore
-@n ode Retouches de mise en forme au sein des contextes
-@s ubsection Retouches de mise en forme au sein des contextes
-@t ranslationof Layout tunings within contexts
+Pour information, les ordonnancements suivants sont importants@tie{}:
+le @code{Bar_engraver} devrait toujours être le premier@tie{}; le
+@code{New_fingering_engraver} doit toujours précéder le
+@code{Script_column_engraver}. Nous vous conseillons, pour les autres,
+de vérifier les éventuelles dépendances.
-Chaque contexte est chargé de créer plusieurs types d'objets graphiques.
-Il contient également les réglages nécessaires pour chacun de ces objets.
-Si l'on modifie ces réglages, les objets n'auront plus la même apparence.
-La syntaxe employée pour ce faire est
-@example
-\override @var{contexte}.@var{objet} #'@var{propriété} = #@var{valeur}
-@end example
+@node Modification des réglages par défaut d'un contexte
+@subsection Modification des réglages par défaut d'un contexte
+@translationof Changing context default settings
-Ici @var{objet} est un objet graphique, tel que @code{Stem} (les hampes)
-ou @code{NoteHead} (les têtes de note) ; @var{propriété} est une variable
-(désignée par un symbole, ce qui explique l'apostrophe) employée par le système
-de mise en page. La sous-section @ref{Élaboration d'une retouche} vous
-aidera à savoir quoi mettre à la place de @var{objet}, @var{propriété} et
-@var{valeur} ; notre propos n'est ici que d'examiner l'emploi de cette commande.
+La personnalisation des réglages par défaut d'un contexte, qu'il
+s'agisse de @code{Score}, @code{Staff} ou @code{Voice}, peut se réaliser
+indépendamment de la musique dans un bloc @code{\layout} -- placé dans
+le bloc @code{\score} auquel ces modifications doivent s'appliquer -- au
+moyen de la commande @code{\context}.
-La commande suivante :
+Point n'est besoin d'utiliser la commande
+@code{\set@tie{}@var{contexte}} lorsque les réglages par défaut d'un
+contexte sont ainsi modifiés@tie{}:
-@verbatim
-\override Staff.Stem #'thickness = #4.0
-@end verbatim
+@c KEEP LY
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Petite police, hampes épaisses, sans métrique" a a a
+ a a a a
+ }
+ \layout {
+ \context {
+ \Staff
+ fontSize = #-4
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+ }
+ }
+}
+@end lilypond
-@noindent
-rend les hampes plus épaisses (la valeur par défaut est 1.3, ce qui signifie qu'elles
-sont 1,3 fois plus épaisses que les lignes de la portée). Dans la mesure où nous avons
-indiqué @code{Staff} comme contexte, ce réglage ne s'appliquera qu'à la portée courante ;
-les autres portées demeureront intactes.
+Le raccourci @code{\Staff} invoque les définitions inhérentes au
+contexte @code{Staff}, de façon à ce qu'elles puissent être modifiées.
+Ces nouvelles spécifications affecteront toutes les portées (tous les
+contextes @code{Staff}) de ce bloc @code{\score}.
+Les adaptations peuvent aussi bien se faire au niveau du contexte
+@code{Score} qu'au niveau de tous les contextes @code{Voice}.
-@lilypond[quote,verbatim,relative=2,fragment]
-c4
-\override Staff.Stem #'thickness = #4.0
-c4
-c4
-c4
-@end lilypond
+Il est possible de stocker des modifications de contexte dans un
+identificateur. Sa définition devra être précédée de l'instruction
+@code{\with}.
-La commande @code{\override} modifie donc la définition de l'objet @code{Stem}
-dans le contexte @code{Staff} ; toutes les hampes qui suivent seront affectées.
+@lilypond[quote,verbatim]
+blubb = \with {
+ fontSize = #-4
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+}
-Tout comme avec la commande @code{\set}, l'argument @var{contexte} peut être omis, auquel
-cas le contexte par défaut (ici, @code{Voice}) sera employé. La commande @code{\once}
-permet de n'appliquer la modification qu'une seule fois.
+bla = \with {
+ fontSize = #3
+ \override Stem #'thickness = #-2.0
+}
-@lilypond[quote,fragment,verbatim,relative=2]
-c4
-\once \override Stem #'thickness = #4.0
-c4
-c4
+melody = \relative c'' {
+ a4 a a a |
+ a4 a a a |
+}
+
+\score {
+ <<
+ \new Staff <<
+ \melody
+ s1*0^"Small, thicker stems, no time signature"
+ >>
+ \new Staff \bla <<
+ \melody
+ s1*0^"Different"
+ >>
+ >>
+ \layout {
+ \context {
+ \Staff
+ \blubb
+ }
+ }
+}
@end lilypond
-La commande @code{\override} doit être entrée @emph{avant} l'objet concerné.
-Ainsi, lorsque l'on veut altérer un objet qui se prolonge, tel qu'une liaison,
-une ligature ou tout autre objet dit @emph{Spanner}, la commande @code{\override}
-doit être saisie avant que l'objet soit créé.
+@c TODO: add \with in here.
-@lilypond[quote,fragment,verbatim,relative=2]
-\override Slur #'thickness = #3.0
-c8[( c
-\override Beam #'thickness = #0.6
-c8 c])
+
+@node Définition de nouveaux contextes
+@subsection Définition de nouveaux contextes
+@translationof Defining new contexts
+
+@cindex contexte, création
+@cindex graveur, affectation à un contexte
+
+@funindex \alias
+@funindex alias
+@funindex \name
+@funindex name
+@funindex \type
+@funindex type
+@funindex \consists
+@funindex consists
+@funindex \accepts
+@funindex accepts
+@funindex \denies
+@funindex denies
+
+Les contextes tels que @code{Staff} ou @code{Voice} sont faits
+de briques de construction empilées. En combinant divers graveurs,
+il est possible de créer de nouveaux types de contextes.
+
+Dans l'exemple suivant on construit, de zéro, un nouveau contexte très
+semblable à @code{Voice}, mais qui n'imprime que des têtes de notes en
+forme de barre oblique au centre de la portée. Un tel contexte peut
+servir, par exemple, à indiquer un passage improvisé dans un morceau de
+jazz.
+
+@c KEEP LY
+@lilypond[quote,ragged-right]
+\layout { \context {
+ \name ImproVoice
+ \type "Engraver_group"
+ \consists "Note_heads_engraver"
+ \consists "Rhythmic_column_engraver"
+ \consists "Text_engraver"
+ \consists Pitch_squash_engraver
+ squashedPosition = #0
+ \override NoteHead #'style = #'slash
+ \override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
+ \alias Voice
+}
+\context { \Staff
+ \accepts "ImproVoice"
+}}
+
+\relative c'' {
+ a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
+ c4 c^"dévêtez-vous" c_"tout en jouant :)" c }
+ a1
+}
@end lilypond
-@noindent
-Dans cet exemple, la liaison (@emph{Slur}) est épaissie, mais non la ligature
-(@emph{Beam}). En effet, le code qui lui est relatif n'a pas été inséré avant le début de
-la ligature, et demeure donc sans effet.
-De même que la commande @code{\unset}, la commande @code{\revert} défait
-ce qui a été fait par une commande @code{\override}. Tout comme avec @code{\unset},
-elle ne peut annuler que les réglages effectués dans le même contexte.
-Ainsi dans l'exemple suivant, la commande @code{\revert} est sans effet.
+On a rassemblé les réglages dans un bloc @code{\context}, lui-même placé
+dans le bloc @code{\layout}@tie{}:
@example
-\override Voice.Stem #'thickness = #4.0
-\revert Staff.Stem #'thickness
+\layout @{
+ \context @{
+ @dots{}
+ @}
+@}
@end example
-Il existe, à l'intérieur même de certaines propriétés, des options que l'on
-nomme @q{sous-propriétés}. La syntaxe est alors
+En lieu et place des points (@dots{}), voici les éléments à
+saisir@tie{}:
+
+Tout d'abord, il convient de donner un nom à notre nouveau
+contexte@tie{}:
-@c leave this as a long long
@example
-\override @var{contexte}.@var{objet} #'@var{propriété} #'@var{sous-propriété} = #@var{valeur}
+\name ImproVoice
@end example
-@noindent
-Ainsi, par exemple :
+Comme il est très semblable à @code{Voice}, nous souhaitons que
+toutes les commandes associées au @code{Voice} déjà existant restent
+valables. D'où nécessité de la commande @code{\alias}, qui va
+l'associer au contexte @code{Voice}@tie{}:
@example
-\override Stem #'(details beamed-lengths) = #'(4 4 3)
+\alias Voice
@end example
-
-@seealso
-Référence du programme : @rinternals{OverrideProperty}, @rinternals{RevertProperty},
-@rinternals{PropertySet}, @rinternals{Backend}, et
-@rinternals{All layout objects}.
-
-
-@knownissues
-
-La sous-couche Scheme ne vérifie pas la saisie des propriétés de façon
-très stricte. Des références cycliques dans des valeurs Scheme peuvent
-de ce fait interrompre, ou faire planter le programme -- ou bien les deux.
-@end ignore
-
-@node Modification des réglages par défaut d'un contexte
-@subsection Modification des réglages par défaut d'un contexte
-@translationof Changing context default settings
-
-Les réglages montrés dans les sous-sections @ref{La commande de fixation (set)}, @ref{Modification des greffons de contexte} et
-@ref{Retouches de mise en forme au sein des contextes} peuvent également être saisis indépendamment
-de la musique dans le bloc @code{\layout}, au moyen de la commande @code{\context} :
-
-@example
-\layout @{
- @dots{}
- \context @{
- \Staff
-
- \set fontSize = #-2
- \override Stem #'thickness = #4.0
- \remove "Time_signature_engraver"
- @}
-@}
-@end example
-
-Le raccourci @code{\Staff} invoque les définitions inhérentes au contexte
-@code{Staff}, de façon à ce qu'elles puissent être modifiées.
-
-Les lignes suivantes affecteront toutes les portées (tous les contextes @code{Staff})
-dans la partition.
-@example
-\set fontSize = #-2
-\override Stem #'thickness = #4.0
-\remove "Time_signature_engraver"
-@end example
-
-@noindent
-Les autres contextes peuvent être modifiés de même manière.
-
-La commande @code{\set}, dans le bloc @code{\layout}, est facultative ; aussi
-les lignes suivantes produiront-elles le même effet.
-
-@example
-\context @{
- @dots{}
- fontSize = #-2
-@}
-@end example
-
-
-@knownissues
-
-Il est impossible de stocker des modifications de contexte dans un identificateur.
-
-Le raccourci @code{\RemoveEmptyStaffContext} détruit tous les réglages
-du contexte @code{\Staff}. Pour modifier des propriétés de portées gouvernées
-par @code{\RemoveEmptyStaffContext}, il faut le faire impérativement @emph{après}
-avoir invoqué @code{\RemoveEmptyStaffContext} :
-
-@example
-\layout @{
- \context @{
- \RemoveEmptyStaffContext
-
- \override Stem #'thickness = #4.0
- @}
-@}
-@end example
-
-
-@node Définition de nouveaux contextes
-@subsection Définition de nouveaux contextes
-@translationof Defining new contexts
-
-Les contextes tels que @code{Staff} ou @code{Voice} sont faits
-de briques de constructions empilées. En combinant divers graveurs,
-il est possible de créer de nouveaux types de contextes.
-
-Dans l'exemple suivant, on construit, de zéro, un nouveau contexte très
-semblable à @code{Voice}, mais qui n'imprime que des têtes de notes en forme
-de barres obliques au centre de la portée. Un tel contexte, par exemple, peut
-servir à indiquer un passage improvisé dans un morceau de jazz.
-
-@c KEEP LY
-@lilypond[quote,ragged-right]
-\layout { \context {
- \name ImproVoice
- \type "Engraver_group"
- \consists "Note_heads_engraver"
- \consists "Rhythmic_column_engraver"
- \consists "Text_engraver"
- \consists Pitch_squash_engraver
- squashedPosition = #0
- \override NoteHead #'style = #'slash
- \override Stem #'transparent = ##t
- \alias Voice
-}
-\context { \Staff
- \accepts "ImproVoice"
-}}
-
-\relative c'' {
- a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
- c4 c^"dévêtez-vous" c_"tout en jouant :)" c }
- a1
-}
-@end lilypond
-
-
-On a rassemblé les réglages dans un bloc @code{\context}, lui-même dans
-le bloc @code{\layout} :
-
-@example
-\layout @{
- \context @{
- @dots{}
- @}
-@}
-@end example
-
-En lieu et place des points (@dots{}), voici les éléments à saisir :
-
-@itemize @bullet
-@item Tout d'abord, il convient de donner un nom @code{\name} à notre nouveau contexte :
-
-@example
-\name ImproVoice
-@end example
-
-@item Comme il est très semblable à @code{Voice}, nous souhaitons que toutes les
-commandes associées au @code{Voice} déjà existant, restent valables. D'où nécessité
-de la commande @code{\alias}, qui va l'associer au contexte @code{Voice} :
-
-@example
-\alias Voice
-@end example
-
-@item Ce contexte doit pouvoir imprimer des notes, et des indications textuelles ;
-on ajoute donc les graveurs appropriés.
+Ce contexte doit pouvoir imprimer des notes et des indications
+textuelles@tie{}; on ajoute donc les graveurs appropriés@tie{}:
@example
\consists Note_heads_engraver
\consists Text_engraver
@end example
-@item Cependant, on veut que les notes s'affichent toutes au centre de la portée :
+Cependant, on veut que les notes s'affichent toutes au centre de
+la portée@tie{}:
@example
\consists Pitch_squash_engraver
squashedPosition = #0
@end example
-@noindent
-Le graveur @rinternals{Pitch_squash_engraver} intercepte les notes créées par
-@rinternals{Note_heads_engraver}, et les @q{écrase} pour qu'elles aient toutes la
-même position verticale, définie par @code{squashedPosition} : ici il s'agit de la
-valeur@tie{}@code{0}, c'est-à-dire la ligne du milieu.
+Le graveur @rinternals{Pitch_squash_engraver} intercepte les notes
+créées par le @rinternals{Note_heads_engraver}, et les @qq{écrase} pour
+qu'elles aient toutes la même position verticale, définie par
+@code{squashedPosition}@tie{}: ici il s'agit de la valeur@tie{}@code{0},
+c'est-à-dire la ligne du milieu.
-@item On veut que les notes aient la forme d'une barre oblique, sans aucune hampe :
+On veut que les notes aient la forme d'une barre oblique, sans
+aucune hampe@tie{}:
@example
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+\override Flag #'transparent = ##t
@end example
-@item Afin que tous ces graveurs puissent travailler de concert, on leur adjoint un
-sous-programme spécial, introduit par la commande @code{\type} : il s'agit de
-@code{Engraver_group},
+Afin que tous ces graveurs puissent travailler de concert, on leur
+adjoint un sous-programme spécial, introduit par la commande
+@code{\type}@tie{}: il s'agit de @code{Engraver_group},
@example
\type "Engraver_group"
@end example
-@end itemize
-
-Récapitulons -- on se retrouve avec le bloc suivant :
+Récapitulons@tie{}; on se retrouve avec le bloc suivant@tie{}:
@example
\context @{
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
@}
@end example
@funindex \accepts
+
Ce n'est pas tout. En effet, on veut intégrer le nouveau contexte
@code{ImproVoice} dans la hiérarchie des contextes. Tout comme le
contexte @code{Voice}, sa place est au sein du contexte @code{Staff}.
Nous allons donc modifier le contexte @code{Staff},
-au moyen de la commande @code{\accepts} :
+au moyen de la commande @code{\accepts}@tie{}:
@example
\context @{
@end example
@funindex \denies
-Le contraire de @code{\accepts} est @code{\denies},
-qui est parfois utile lorsque l'on recycle des définitions de
-contextes déjà existantes.
+
+Le contraire de @code{\accepts} est @code{\denies}@tie{}; il est parfois
+utile lorsque l'on recycle des définitions de contextes déjà existantes.
Enfin, tout cela doit prendre place dans le bloc @code{\layout},
-comme suit :
+comme suit@tie{}:
@example
\layout @{
@}
@end example
-On peut alors saisir la musique, comme dans l'exemple plus haut :
+On peut alors saisir la musique, comme dans l'exemple plus haut@tie{}:
@example
\relative c'' @{
@end example
-@node Alignement des contextes
-@subsection Alignement des contextes
-@translationof Aligning contexts
+@node Ordonnancement des contextes
+@subsection Ordonnancement des contextes
+@translationof Context layout order
+@cindex contextes, ordonnancement
-Il est possible d'aligner verticalement chaque nouveau contexte,
-en-dessous ou au-dessus, par exemple dans le cas de musique vocale
-(@rlearning{Ensemble vocal}) ou d'@qq{ossias}.
+@funindex \accepts
+@funindex \denies
-@cindex ossia
-@findex alignAboveContext
-@findex alignBelowContext
+Les contextes viennent en principe se positionner selon leur ordre
+d'apparition dans le fichier source. Lorsque plusieurs contextes sont
+imbriqués, le contexte englobant supportera les différents contextes
+mentionnés dans le fichier source, à la stricte condition qu'ils soient
+dûment @qq{agréés}. Les contextes imbriqués qui ne font pas partie de
+la @qq{liste d'agréments} du contexte englobant se retrouveront en
+dessous de celui-ci au lieu d'y être imbriqués.
+
+La liste des @qq{agréments} d'un contexte se gère à l'aide des
+instructions @code{\accepts} et @code{\denies} -- @code{\accepts} pour
+ajouter un contexte à la liste, et @code{\denies} pour retirer
+l'agrément. Il est par exemple peu conventionnel que les accords nommés
+apparaissent dans un contexte @code{Staff}@tie{}; autrement dit, le
+contexte @code{ChordNames} ne fait pas partie de la @qq{liste
+d'agréments} du contexte @code{Staff} par défaut. Néanmoins, et s'il
+devait en être ainsi, vous pourriez le spécifier.
+
+
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
+ }
+}
+@end lilypond
-@lilypond[quote,ragged-right]
-ossia = { f4 f f f }
-\score{
- \relative c' \new Staff = "main" {
- c4 c c c
- <<
- \new Staff \with { alignAboveContext = #"main" } \ossia
- { d8 f d f d f d f }
- >>
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
+ }
+ \layout {
+ \context {
+ \Staff
+ \accepts "ChordNames"
+ }
}
}
@end lilypond
+L'instruction @code{\denies} permet, lorsqu'un nouveau contexte reprend
+les définitions d'un contexte existant, d'en ajuster les composantes.
+C'est par exemple le cas du contexte @code{VaticanaStaff}, réplique du
+contexte @code{Staff} au sein duquel le contexte @code{VaticanaVoice} se
+substitue au contexte @code{Voice} dans la @qq{liste d'agrément}.
+
+Gardez à l'esprit que, face à une instruction qui ne s'appliquerait à
+aucun contexte déjà existant, LilyPond créera un nouveau contexte
+implicite. Ceci peut engendrer une nouvelle portée ou une autre
+partition.
+
+
+@seealso
+Manuel d'utilisation :
+@rprogram{Apparition d'une portée supplémentaire}.
+
+Fichiers d'initialisation :
+@file{ly/engraver-init.ly}.
+
@node En quoi consiste la référence des propriétés internes
@section En quoi consiste la référence des propriétés internes
@translationof Explaining the Internals Reference
-
@menu
-* Navigation dans la référence du programme::
+* Navigation dans les références du programme::
* Interfaces de rendu::
* Détermination de la propriété d'un objet graphique (grob)::
* Conventions de nommage::
@end menu
-@node Navigation dans la référence du programme
-@subsection Navigation dans la référence du programme
+@node Navigation dans les références du programme
+@subsection Navigation dans les références du programme
@translationof Navigating the program reference
-Comment, par exemple, déplacer le doigté dans le fragment suivant ?
+@c TODO remove this (it's in the LM)
+@c Replace with more factual directions
-@lilypond[quote,fragment,relative=2,verbatim]
+Comment, par exemple, déplacer le doigté dans le fragment suivant@tie{}?
+
+@lilypond[quote,relative=2,verbatim]
c-2
\stemUp
f
@end lilypond
Sur la page de la documentation relative aux doigtés, c'est-à-dire
-@ref{Doigtés}, se trouve l'indication suivante :
+@ref{Doigtés}, se trouve l'indication suivante@tie{}:
-@seealso
-Référence du programme : @rinternals{Fingering}.
+@quotation
+@strong{Voir aussi}
+Référence des propriétés internes : @rinternals{Fingering}.
+@end quotation
@c outdated info; probably will delete.
@ignore
@end ignore
@ifnothtml
-Ladite référence est disponible au format HTML, ce qui rend la navigation bien
-plus aisée. Il est possible soit de la lire en ligne, soit de la télécharger
-dans ce format. La démarche présentée ici sera plus difficle à comprendre
-dans un document au format PDF.
+Ladite référence est disponible au format HTML, ce qui rend la
+navigation bien plus aisée. Il est possible soit de la lire en ligne,
+soit de la télécharger dans ce format. La démarche présentée ici sera
+plus difficile à comprendre dans un document au format PDF.
@end ifnothtml
Suivons le lien @rinternals{Fingering}. En haut de la nouvelle page,
(@code{Fingering} en anglais) @emph{sont créées par les graveurs
@rinternals{Fingering_engraver} et @rinternals{New_fingering_engraver}.}
-En suivant derechef les liens propres à la référence du programme, on suit en fait
-le cheminement qui aboutit à la création de la partition :
+En suivant derechef les liens propres à la référence du programme, on
+suit en fait le cheminement qui aboutit à la création de la
+partition@tie{}:
-@itemize @bullet
+@itemize
@item @rinternals{Fingering}:
@rinternals{Fingering} objects are created by:
@rinternals{FingeringEvent}
@end itemize
-Ce cheminement se produit, bien sûr, en sens inverse : nous sommes ici partis
-du résultat, et avons abouti aux évènements (en anglais @q{Events}) engendrés
-par le fichier d'entrée. L'inverse est également possible : on peut partir d'un
-évènement, et suivre le cheminement de LilyPond qui aboutit à la création d'un
-ou plusieurs objets graphiques.
+Ce cheminement se produit, bien sûr, en sens inverse@tie{}: nous sommes
+ici partis du résultat, et avons abouti aux évènements (en anglais
+@emph{Events}) engendrés par le fichier d'entrée. L'inverse est
+également possible@tie{}: on peut partir d'un évènement, et suivre le
+cheminement de LilyPond qui aboutit à la création d'un ou plusieurs
+objets graphiques.
-La référence du programme peut également se parcourir comme un document normal.
-On y trouve des chapitres tels que
+La référence des propriétés internes peut également se parcourir comme
+un document normal. On y trouve des chapitres tels que
@ifhtml
@rinternals{Music definitions},
@end ifhtml
@ifnothtml
@code{Music definitions}
@end ifnothtml
-@rinternals{Translation}, ou encore @rinternals{Backend}. Chaque chapitre
-recense toutes les définitions employées, et les propriétés sujettes à
-ajustements.
+@rinternals{Translation}, ou encore @rinternals{Backend}. Chaque
+chapitre recense toutes les définitions employées, et les propriétés
+sujettes à ajustements.
@c -- what about adding a link to the glossary here ? -vv
-@ignore
-La Référence du programme n'est pas traduite en français -- notamment du fait
-qu'elle est en évolution constante, tout comme LilyPond. En revanche, les termes
-musicaux font l'objet d'un @commentfairelelien{glossaire} fort utile pour les utilisateurs
+La Référence des propriétés internes n'est pas traduite en français --
+notamment du fait qu'elle est en évolution constante, tout comme
+LilyPond. En revanche, les termes musicaux font l'objet d'un
+@rglosnamed{Top, glossaire} fort utile pour les utilisateurs
francophones.
-@end ignore
@node Interfaces de rendu
@cindex rendu, interfaces de
@cindex objets graphiques
-Tous les éléments de notation sont considérés comme des objets graphiques
-(en anglais @q{Graphical Object}, d'où le diminutif @emph{Grob}).
-Chaque objet est doté d'un certain nombre de propriétés (l'épaisseur du trait,
-l'orientation, etc.), et lié à d'autres objets.
-Le fonctionnement de ces objets est décrit en détail dans @rinternals{grob-interface}.
+Tous les éléments de notation sont considérés comme des objets
+graphiques (en anglais @emph{Graphical Object}, d'où le diminutif
+@emph{Grob}). Chaque objet est doté d'un certain nombre de propriétés
+(l'épaisseur du trait, l'orientation, etc.), et lié à d'autres objets.
+Le fonctionnement de ces objets est décrit en détail dans
+@rinternals{grob-interface}.
-Prenons l'exemple des doigtés (en anglais @q{Fingering}).
-La page @code{Fingering} de la Référence du programme établit une liste de définitions
-propres à ce type d'objets :
+Prenons l'exemple des doigtés (en anglais @emph{Fingering}). La page
+@code{Fingering} de la Référence des propriétés internes établit une
+liste de définitions propres à ce type d'objet@tie{}:
@quotation
@code{padding} (dimension, in staff space):
@end quotation
@noindent
-Ce qui signifie que les doigtés doivent être maintenus à une certaine distance (@emph{padding})
-des notes : 0,5 unités @emph{staff-space} (espace de portée).
+Ce qui signifie que les doigtés doivent être maintenus à une certaine
+distance (@emph{padding}) des notes@tie{}: 0,5 unités @emph{staff-space}
+(espace de portée).
+Chaque objet peut avoir plusieurs attributs, en tant qu'élément
+typographique ou musical. Ainsi, un doigté (objet @emph{Fingering})
+possède les attributs suivants@tie{}:
-Chaque objet peut avoir plusieurs attributs, en tant qu'élément typographique
-ou musical. Ainsi, un doigté (objet @q{Fingering}) possède les attributs suivants :
-
-@itemize @bullet
+@itemize
@item
-Sa taille ne dépend pas de l'espacement horizontal, contrairement aux liaisons ou ligatures.
+Sa taille ne dépend pas de l'espacement horizontal, contrairement aux
+liaisons ou ligatures.
@item
C'est du texte -- un texte vraiment court, certes.
@item
-Ce texte est imprimé au moyen d'une fonte, contrairement aux liaisons ou ligatures.
+Ce texte est imprimé au moyen d'une fonte, contrairement aux liaisons ou
+ligatures.
@item
-Sur l'axe horizontal, le centre de ce symbole doit être aligné avec le centre de la note.
+Sur l'axe horizontal, le centre de ce symbole doit être aligné avec le
+centre de la note.
@item
-Sur l'axe vertical, le symbole doit être proche de la note et de la portée.
+Sur l'axe vertical, le symbole doit être proche de la note et de la
+portée.
@item
-Sur l'axe vertical encore, il doit également s'ordonner avec les éventuels
-autres symboles, ponctuations, ou éléments textuels.
+Sur l'axe vertical encore, il doit également s'ordonner avec les
+éventuels autres symboles, ponctuations ou éléments textuels.
@end itemize
-Faire appliquer ces différents attributs est le rôle des @emph{interfaces},
-que l'on trouve en bas de la page @rinternals{Fingering}.
+Faire appliquer ces différents attributs est le rôle des
+@emph{interfaces}, que l'on trouve en bas de la page
+@rinternals{Fingering}.
@quotation
This object supports the following interfaces:
En français,
@quotation
-Cet objet admet les interfaces suivantes :
+Cet objet admet les interfaces suivantes@tie{}:
@end quotation
-Suit la liste des interfaces en question, présentées comme autant de liens,
-qui conduisent sur les pages dédiées à chacune d'entre elles.
-Chaque interface est dotée d'un certain nombre de propriétés, dont certaines
-peuvent être modifiées, et d'autres non (les @q{Internal properties}, ou
-propriétés internes).
+Suit la liste des interfaces en question, présentées comme autant de
+liens qui conduisent aux pages dédiées à chacune d'entre elles.
+Chaque interface est dotée d'un certain nombre de propriétés, dont
+certaines peuvent être modifiées, et d'autres non (les @emph{Internal
+properties}, ou propriétés internes).
Pour aller encore plus loin, plutôt que de simplement parler de l'objet
-@code{Fingering}, ce qui ne nous avance pas à grand chose, on peut aller explorer
-son âme même, dans les fichiers source de LilyPond (voir
-@rlearning{Autres sources de documentation}), en l'occurence le fichier
-@file{scm/@/define@/-grobs@/.scm} :
+@code{Fingering}, ce qui ne nous avance pas à grand chose, on peut aller
+explorer son âme même, dans les fichiers source de LilyPond (voir
+@rlearning{Autres sources de documentation}), en l'occurrence le fichier
+@file{scm/define-grobs.scm}@tie{}:
@example
(Fingering
(script-priority . 100)
(stencil . ,ly:text-interface::print)
(direction . ,ly:script-interface::calc-direction)
- (font-encoding . fetaNumber)
+ (font-encoding . fetaText)
(font-size . -5) ; don't overlap when next to heads.
(meta . ((class . Item)
(interfaces . (finger-interface
@end example
@noindent
-@dots{}où l'on découvre que l'objet @code{Fingering} n'est rien de plus qu'un
-amas de variables et de réglages. La page de la Référence du programme est
-en fait directement engendrée par cette définition.
+@dots{}où l'on découvre que l'objet @code{Fingering} n'est rien de plus
+qu'un amas de variables et de réglages. La page de la Référence des
+propriétés internes est en fait directement engendrée par cette
+définition.
@node Détermination de la propriété d'un objet graphique (grob)
@subsection Détermination de la propriété d'un objet graphique (grob)
@translationof Determining the grob property
+@c TODO remove this (it's in the LM)
+@c Replace with more factual directions
-Nous voulions changer la position du chiffre @b{2} dans le fragment suivant :
+Nous voulions changer la position du chiffre @b{2} dans le fragment
+suivant@tie{}:
-@lilypond[quote,fragment,relative=2,verbatim]
+@lilypond[quote,relative=2,verbatim]
c-2
\stemUp
f
@end lilypond
-Dans la mesure où le @b{2} est placé, verticalement, à proximité de la note qui lui
-correspond, nous allons devoir trouver l'interface en charge de ce placement, qui se
-trouve être @code{side-position-interface}. Sur la page de cette interface, on
-peut lire :
+Dans la mesure où le @b{2} est placé, verticalement, à proximité de la
+note qui lui correspond, nous allons devoir trouver l'interface en
+charge de ce placement, qui se trouve être
+@code{side-position-interface}. Sur la page de cette interface, on peut
+lire@tie{}:
@quotation
@code{side-position-interface}
@code{side-position-interface}
Placer l'objet affecté à proximité d'autres objets. La propriété
-@code{direction} indique où placer l'objet (à droite ou à gauche,
+@code{direction} indique où positionner l'objet (à droite ou à gauche,
en haut ou en bas).
@end quotation
@cindex padding
@noindent
-En-dessous de cette description se trouve décrite la variable @code{padding} :
+En dessous de cette description se trouve décrite la variable
+@code{padding}@tie{}:
@quotation
@table @code
@end quotation
@noindent
-En augmentant la valeur de @code{padding}, on peut donc éloigner le doigté de la
-note. La commande suivante insère trois unités d'espace vide entre la note et le doigté :
+En augmentant la valeur de @code{padding}, on peut donc éloigner le
+doigté de la note. La commande suivante insère trois unités d'espace
+vide entre la note et le doigté@tie{}:
@example
\once \override Voice.Fingering #'padding = #3
@end example
-En ajoutant cette commande avant la création du doigté (de l'objet @q{Fingering}),
-donc avant @code{c2}, on obtient le résultat suivant :
+En ajoutant cette commande avant la création du doigté (de l'objet
+@code{Fingering}), donc avant @code{c2}, on obtient le résultat
+suivant@tie{}:
-@lilypond[quote,relative=2,fragment,verbatim]
+@lilypond[quote,relative=2,verbatim]
\once \override Voice.Fingering #'padding = #3
c-2
\stemUp
f
@end lilypond
-
Dans le cas présent, le réglage intervient dans le contexte @code{Voice},
-ce qui pouvait également se déduire de la Référence du programme, où la page
-du graveur @rinternals{Fingering_engraver} indique :
+ce qui pouvait également se déduire de la Référence des propriétés
+internes, où la page du graveur @rinternals{Fingering_engraver}
+indique@tie{}:
@quotation
Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
@noindent
Ce qui signifie
@quotation
-Le graveur Fingering_engraver fait partie des contextes : @dots{} @rinternals{Voice}
+Le graveur Fingering_engraver fait partie des contextes@tie{}: @dots{}
+@rinternals{Voice}
@end quotation
@node Conventions de nommage
@subsection Conventions de nommage
-@translationof Naming conventions @c external
+@translationof Naming conventions
-@untranslated
+Afin de s'y retrouver plus aisément et d'éviter les erreurs de frappe,
+voici quelques conventions en matière de nommage@tie{}:
+
+@itemize
+@item fonctions scheme :
+ minuscule-avec-trait-d-union (y compris noms en mot-unique)
+@item fonctions scheme :
+ ly:plus-style-scheme
+@item événements, classes et propriétés musicaux :
+ identique-aux-fonctions-scheme
+@item interfaces d'objet graphique :
+ style-scheme
+@item propriétés d'arrière plan :
+ style-scheme (mais X et Y pour les axes)
+@item contextes (ainsi que MusicExpressions et grobs) :
+ Capitale initiale ou Camélisation (CamelCase)
+@item propriétés de contexte :
+ minusculeSuivieDeCamélisation
+@item graveurs :
+ Capitale_initiale_puis_minuscules_séparées_par_un_souligné
+@end itemize
+
+Les questions que vous devez vous poser sont@tie{}:
+@itemize
+@item Qu'est-ce qui relève des conventions, et qu'est-ce qui relève de
+la règle@tie{}?
+@item Qu'est-ce qui relève des règles du langage sous-jacent, et
+qu'est-ce qui est propre à LilyPond@tie{}?
+@end itemize
@node Modification de propriétés
@menu
* Vue d'ensemble de la modification des propriétés::
* La commande de fixation (set)::
-* La commande de dérogation (@emph{override})::
-* Élaboration d'une retouche::
-* La commande d'affinage (@emph{tweak})::
+* La commande de dérogation (override)::
+* La commande d'affinage (tweak)::
* set ou override::
+* Modification de listes associatives::
@end menu
@node Vue d'ensemble de la modification des propriétés
@subsection Vue d'ensemble de la modification des propriétés
-@translationof Overview of modifying properties @c external
+@translationof Overview of modifying properties
+
+Chaque contexte est chargé de créer plusieurs types d'objets graphiques.
+Il contient également les réglages nécessaires pour chacun de ces
+objets. Si l'on modifie ces réglages, les objets n'auront plus la même
+apparence.
+
+Les contextes comportent deux types différents de propriétés@tie{}: des
+propriétés de contexte et des propriétés d'objet graphique. Les
+propriétés de contexte sont celles qui s'appliqueront globalement au
+contexte en tant que tel@tie{}; elles gèrent la manière dont le contexte
+apparaîtra. Les propriétés d'objet graphique, par contre, s'appliquent
+à des types particuliers d'objet qui apparaissent dans le contexte en
+question.
+
+Les commandes @code{\set} et @code{\unset} permettent de modifier les
+valeurs des propriétés de contexte. Les commandes @code{\override} et
+@code{\revert} permettent de modifier les valeurs des propriétés des
+objets graphiques.
+
+@ignore
+La syntaxe employée pour ce faire est
+
+@example
+\override @var{contexte}.@var{objet} #'@var{propriété} = #@var{valeur}
+@end example
+
+Ici @var{objet} est un objet graphique, tel que @code{Stem} (les hampes)
+ou @code{NoteHead} (les têtes de note)@tie{}; @var{propriété} est une
+variable (désignée par un symbole, ce qui explique l'apostrophe)
+employée par le système de mise en page. La sous-section
+@ref{Élaboration d'une retouche} vous aidera à savoir quoi mettre à la
+place de @var{objet}, @var{propriété} et @var{valeur}@tie{}; notre
+propos n'est ici que d'examiner l'emploi de cette commande.
+
+La commande suivante@tie{}:
+
+@verbatim
+\override Staff.Stem #'thickness = #4.0
+@end verbatim
+
+@noindent
+rend les hampes plus épaisses (la valeur par défaut est 1.3, ce qui
+signifie qu'elles sont 1,3 fois plus épaisses que les lignes de la
+portée). Dans la mesure où nous avons indiqué @code{Staff} comme
+contexte, ce réglage ne s'appliquera qu'à la portée courante@tie{}; les
+autres portées demeureront intactes.
+
+
+@lilypond[quote,verbatim,relative=2,fragment]
+c4
+\override Staff.Stem #'thickness = #4.0
+c4
+c4
+c4
+@end lilypond
+
+La commande @code{\override} modifie donc la définition de l'objet
+@code{Stem} dans le contexte @code{Staff}@tie{}; toutes les hampes qui
+suivent seront affectées. Tout comme avec la commande @code{\set},
+l'argument @var{contexte} peut être omis, auquel cas le contexte par
+défaut (ici, @code{Voice}) sera employé. La commande @code{\once}
+permet de n'appliquer la modification qu'une seule fois.
+
+@lilypond[quote,fragment,verbatim,relative=2]
+c4
+\once \override Stem #'thickness = #4.0
+c4
+c4
+@end lilypond
+
+La commande @code{\override} doit être entrée @emph{avant} l'objet
+concerné. Ainsi, lorsque l'on veut altérer un objet qui se prolonge,
+tel qu'une liaison, une ligature ou tout autre objet dit @emph{Spanner},
+la commande @code{\override} doit être saisie avant que l'objet soit
+créé.
+
+@lilypond[quote,fragment,verbatim,relative=2]
+\override Slur #'thickness = #3.0
+c8[( c
+\override Beam #'beam-thickness = #0.6
+c8 c])
+@end lilypond
+
+@noindent
+Dans cet exemple, la liaison (@emph{Slur}) est épaissie, mais non la
+ligature (@emph{Beam}). En effet, le code qui lui est relatif n'a pas
+été inséré avant le début de la ligature, et demeure donc sans effet.
+
+De même que la commande @code{\unset}, la commande @code{\revert} défait
+ce qui a été fait par une commande @code{\override}. Tout comme avec
+@code{\unset}, elle ne peut annuler que les réglages effectués dans le
+même contexte. Ainsi dans l'exemple suivant, la commande @code{\revert}
+est sans effet.
+
+@example
+\override Voice.Stem #'thickness = #4.0
+\revert Staff.Stem #'thickness
+@end example
+
+Il existe, à l'intérieur même de certaines propriétés, des options que
+l'on nomme @q{sous-propriétés}. La syntaxe est alors
+
+@c leave this as a long long
+@example
+\override @var{contexte}.@var{objet} #'@var{propriété} #'@var{sous-propriété} = #@var{valeur}
+@end example
+
+@noindent
+Ainsi, par exemple@tie{}:
+
+@example
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
+@end example
+
+@end ignore
-@untranslated
+@seealso
+Référence des propriétés internes :
+@rinternals{Backend},
+@rinternals{All layout objects},
+@rinternals{OverrideProperty},
+@rinternals{RevertProperty},
+@rinternals{PropertySet}.
+
+
+@knownissues
+
+La sous-couche Scheme ne vérifie pas la saisie des propriétés de façon
+très stricte. Des références cycliques dans des valeurs Scheme peuvent
+de ce fait interrompre ou faire planter le programme -- ou bien les
+deux.
@node La commande de fixation (set)
-@subsection La commande @code{\set}
+@subsection La commande de fixation @code{@bs{}set}
@translationof The set command
@cindex propriétés
-@funindex \set
@cindex modifier des propriétés
+@funindex \set
Chaque contexte peut avoir plusieurs @emph{propriétés}, c'est-à-dire
-des variables qu'il inclut. Ces dernières peuvent être modifiées @qq{à la volée},
-c'est-à-dire pendant que la compilation s'accomplit. C'est là le rôle de la
-commande @code{\set}.
+des variables qu'il inclut. Ces dernières peuvent être modifiées @qq{à
+la volée}, c'est-à-dire pendant que la compilation s'accomplit. C'est
+là le rôle de la commande @code{\set}.
@example
\set @var{contexte}.@var{propriété} = #@var{valeur}
@end example
-Ainsi :
-@lilypond[quote,verbatim,relative=2,fragment]
+Dans la mesure où @var{valeur} est constituée d'un objet Scheme, elle
+doit être précédée du caractère@tie{}@code{#}.
+
+Les propriétés des contextes se libellent sous la forme
+@code{minusculeMajuscule}. Leur rôle consiste principalement à traduire
+la musique en notation@tie{}: par exemple, @code{localKeySignature}
+déterminera quand imprimer une altération accidentelle, et
+@code{measurePosition} quand imprimer une barre de mesure. La valeur
+des propriétés des contextes peuvent évoluer au fur et à mesure que l'on
+avance dans le morceau -- @code{measurePosition} en est l'illustration
+parfaite.
+
+Ainsi la propriété de contexte @code{skipBars} permet de condenser les
+mesures vides de notes, en des silences multimesures. Il s'agit d'un
+objet Scheme, auquel on attribue la valeur booléenne @qq{vrai},
+c'est-à-dire la lettre @code{#t} pour @qq{True} en anglais@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
R1*2
\set Score.skipBars = ##t
R1*2
@end lilypond
-Cette commande permet de condenser les mesures vides de notes, en des silences
-multi-mesures. Il s'agit d'un objet Scheme, auquel on attribue la valeur booléenne
-@q{vrai}, c'est-à-dire la lettre @code{#t} pour @q{True} en anglais.
-
-Ce changement étant appliqué @q{à la volée}, il n'affecte que le second groupe de notes.
-
-Si l'argument @var{contexte} n'est pas spécifié, alors la propriété cherchera à s'appliquer
-dans le contexte le plus restreint où elle est employée : le plus souvent
- @code{ChordNames}, @code{Voice}, ou @code{Lyrics}. Dans l'exemple suivant,
+Si l'argument @var{contexte} n'est pas spécifié, alors la propriété
+cherchera à s'appliquer dans le contexte le plus restreint où elle est
+employée@tie{}: le plus souvent @code{ChordNames}, @code{Voice} ou
+@code{Lyrics}.
-@lilypond[quote,verbatim,relative=2,fragment]
-c8 c c c
-\set autoBeaming = ##f
-c8 c c c
+@lilypond[quote,verbatim,relative=2]
+\set Score.autoBeaming = ##f
+<<
+ {
+ e8 e e e
+ \set autoBeaming = ##t
+ e8 e e e
+ } \\ {
+ c8 c c c c8 c c c
+ }
+>>
@end lilypond
-@noindent
-aucun argument @var{contexte} n'a été donné à la commande @code{\set}.
-De ce fait, les ligatures automatiques sont désactivées dans le
-contexte actuel, c'est-à-dire @rinternals{Voice}. Notez que le
-contexte le plus restreint n'est pas toujours le bon,
-et peut ne pas contenir la propriété qui vous intéresse : ainsi, la propriété
-@code{skipBars}, évoquée plus haut, ne relève pas du contexte @code{Voice},
-et le code suivant ne fonctionnera pas.
+Ce changement étant appliqué @qq{à la volée}, il n'affecte que le second
+groupe de notes.
-@lilypond[quote,verbatim,relative=2,fragment]
+Notez que le contexte le plus restreint n'est pas toujours le bon, et
+peut ne pas contenir la propriété qui vous intéresse@tie{}: ainsi, la
+propriété @code{skipBars}, évoquée plus haut, ne relève pas du contexte
+@code{Voice}, mais du contexte @code{Score} -- le code suivant ne
+fonctionnera pas.
+
+@lilypond[quote,verbatim,relative=2]
R1*2
\set skipBars = ##t
R1*2
@end lilypond
-Les contextes s'organisent de façon hiérarchique : aussi, lorsqu'un contexte de niveau
-supérieur est spécifié (par exemple @code{Staff}), la propriété sera modifée dans
-tous les contextes inférieurs (tous les contextes @code{Voice}, par exemple)
-qu'il contient.
+Les contextes s'organisent de façon hiérarchique@tie{}: aussi, lorsqu'un
+contexte de niveau supérieur est spécifié (par exemple @code{Staff}), la
+propriété sera modifiée dans tous les contextes inférieurs (tous les
+contextes @code{Voice}, par exemple) qu'il contient.
@funindex \unset
-La commande @code{\unset} permet d'annuler la définition d'une propriété :
+La commande @code{\unset} permet d'annuler la définition d'une
+propriété@tie{}:
@example
\unset @var{contexte}.@var{propriété}
@end example
@noindent
-si et seulement si cette propriété à été définie dans ce @var{contexte}
-précis ; ainsi,
-
-@example
-\set Staff.autoBeaming = ##f
-@end example
-
-@noindent
-même s'il s'applique à tous les contextes @code{Voice} contenus dans le
-contexte @code{Staff}, ne peut être annulé au niveau @code{Voice}. Le code
-suivant sera sans effet.
-
-@example
-\unset Voice.autoBeaming
-@end example
-
-@noindent
-En d'autres termes, la commande @code{\unset} doit impérativement être
-accompagnée du même contexte que la commande @code{\set} d'origine.
-Pour annuler l'effet, dans notre exemple, de @code{Staff.autoBeaming = ##f},
-il faut donc entrer :
-@example
-\unset Staff.autoBeaming
-@end example
+si et seulement si cette propriété a été définie dans ce @var{contexte}
+précis. En d'autres termes, la commande @code{\unset} doit
+impérativement affecter le même contexte que la commande @code{\set}
+d'origine, même en cas d'imbrication.
-Si l'on se trouve dans le contexte le plus restreint, il n'est pas obligatoire,
-là encore, de spécifier le @var{contexte}. Ainsi, les deux lignes suivantes sont équivalentes.
+@lilypond[quote,verbatim,relative=2]
+\set Score.autoBeaming = ##t
+<<
+ {
+ \unset autoBeaming
+ e8 e e e
+ \unset Score.autoBeaming
+ e8 e e e
+ } \\ {
+ c8 c c c c8 c c c
+ }
+>>
+@end lilypond
+Si l'on se trouve dans le contexte le plus restreint, il n'est pas
+obligatoire, là encore, de spécifier le @var{contexte}. Ainsi, les deux
+lignes suivantes sont équivalentes.
@example
\set Voice.autoBeaming = ##t
\set autoBeaming = ##t
@end example
-
@cindex \once
-Pour modifier une propriété de façon à ce qu'elle ne s'applique qu'une seule fois,
-il convient d'employer la commande @code{\once} :
-@lilypond[quote,verbatim,relative=2,fragment]
+Pour modifier une propriété de façon à ce que l'accommodement ne
+s'applique qu'une seule fois, il convient d'adjoindre l'instruction
+@code{\once} à la commande @code{\set}@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
c4
\once \set fontSize = #4.7
c4
Ici le changement de taille est annulé aussitôt après la note concernée.
-La référence du programme contient une description exhaustive de toutes les
-propriétés contexte par contexte : voir
+La référence des propriétés internes contient une description exhaustive
+de toutes les propriétés, contexte par contexte@tie{}: voir
@ifhtml
@rinternals{Tunable context properties}.
@end ifhtml
@end ifnothtml
-@node La commande de dérogation (@emph{override})
-@subsection La commande @code{\override}
-@translationof The override command
+@seealso
+Référence des propriétés internes :
+@rinternals{Tunable context properties}.
-La commande @code{\override} permet de modifier la mise en page
-en détail. Examinons son utilisation concrètementet dans les détails.
-La syntaxe de cette commande ressemble généralement à :
-@example
-\override @var{contexte}.@var{objet} #'@var{propriété} = #@var{valeur}
+@node La commande de dérogation (override)
+@subsection La commande de dérogation @code{@bs{}override}
+@translationof The override command
+
+@cindex grob, propriétés
+@cindex objet graphique, propriétés
+@cindex propriétés d'un grob
+@cindex propriétés d'objet graphique
+
+@funindex \override
+
+La commande @code{\override} permet de modifier la mise en forme des
+objets graphiques. Les descriptions d'objet graphique, dont les noms
+commencent par une majuscule, puis comprennent une ou plusieurs
+majuscules (de style @code{TotoTata}), contiennent les réglages @qq{par
+défaut} pour les objets graphiques. Ces réglages sont sous forme de
+liste Scheme@tie{}; on peut les consulter dans le fichier
+@file{scm/define-grobs.scm}.
+
+@code{\override} est en fait un raccourci@tie{}:
+
+@example
+\override @var{contexte}.@var{NomObjet} #'@var{propriété} = #@var{valeur}
@end example
-La propriété @var{propriété} de l'objet @var{objet}, appartenant au contexte
-@var{contexte}, se voit ainsi attribuer la valeur @var{valeur}.
+@noindent
+plus ou moins équivalent à
+
+@c leave this long line -gp
+@example
+\set @var{contexte}.@var{NomObjet} =
+ #(cons (cons '@var{propriété} @var{valeur})
+ <valeur antérieure de @var{contexte}.@var{NomObjet}>)
+@end example
+
+La valeur de @var{contexte}.@var{NomObjet} (une liste associative, ou
+@emph{alist}) permet d'initialiser les propriétés des objets un par un.
+Les objets eux-mêmes ont leurs propriétés, dont les noms, dans la
+tradition du langage Scheme, comprennent un trait d'union
+(@code{toto-titi}). Ces propriétés internes changent constamment au
+cours de la mise en page@tie{}: en fait, la gravure d'une page n'est
+autre que le calcul de toutes ces propriétés au moyen de fonctions de
+rappel.
+
+Nous pouvons donc par exemple accroître l'épaisseur des hampes en jouant
+sur la propriété @code{thickness} de l'objet @code{stem}@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
+c4 c
+\override Voice.Stem #'thickness = #3.0
+c4 c
+@end lilypond
+
+Lorsqu'aucun contexte n'est spécifié dans une clause @code{\override},
+celle-ci s'appliquera au contexte le plus bas@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
+{ \override Staff.Stem #'thickness = #3.0
+ <<
+ {
+ e4 e
+ \override Stem #'thickness = #0.5
+ e4 e
+ } \\ {
+ c4 c c c
+ }
+ >>
+}
+@end lilypond
+
+@cindex annulation d'un override
+@cindex override, annulation des effets
+@funindex \revert
+
+Les effets d'un @code{\override} prennent fin à l'aide de l'instruction
+@code{\revert}@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
+c4
+\override Voice.Stem #'thickness = #3.0
+c4 c
+\revert Voice.Stem #'thickness
+c4
+@end lilypond
+Les effets d'un @code{\override} ou d'un @code{\revert} s'appliquent dès
+l'endroit où ils apparaissent, et à tous les objets dans le contexte
+mentionné@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
+{
+ <<
+ {
+ e4
+ \override Staff.Stem #'thickness = #3.0
+ e4 e e
+ } \\ {
+ c4 c c
+ \revert Staff.Stem #'thickness
+ c4
+ }
+ >>
+}
+@end lilypond
-@c deprecated node. Delete. --fv
-@node Élaboration d'une retouche
-@subsection Élaboration d'une retouche
-@translationof Constructing a tweak
+@cindex override ponctuel
+@funindex \once
+
+L'instruction @code{\override} doit être précédée d'un @code{\once} dès
+lors que les effets de l'accommodement ne concernent que l'événement qui
+la suit directement@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
+{
+ <<
+ {
+ \override Stem #'thickness = #3.0
+ e4 e e e
+ } \\ {
+ c4
+ \once \override Stem #'thickness = #3.0
+ c4 c c
+ }
+ >>
+}
+@end lilypond
+@ignore
Les commandes permettant de modifier l'apparence de la partition
ressemblent en général à
@end example
@noindent
-Pour élaborer un réglage de ce type, on a besoin de connaître précisément :
+Pour élaborer un réglage de ce type, on a besoin de connaître
+précisément@tie{}:
@itemize
-@item le contexte : ici @code{Voice} (la voix).
-@item l'objet à affecter : ici @code{Stem} (les hampes).
-@item la propriété à modifier : ici @code{thickness} (l'épaisseur du trait).
-@item la valeur désirée : ici @code{3.0} (par défaut, elle est de 1.3).
+@item le contexte@tie{}: ici @code{Voice} (la voix).
+@item l'objet à affecter@tie{}: ici @code{Stem} (les hampes).
+@item la propriété à modifier@tie{}: ici @code{thickness} (l'épaisseur
+du trait).
+@item la valeur désirée@tie{}: ici @code{3.0} (par défaut, elle est de
+1.3).
@end itemize
Certaines @q{sous-propriétés} sont parfois contenues dans une propriété.
-La commande devient alors :
+La commande devient alors@tie{}:
@example
\override Stem #'(details beamed-lengths) = #'(4 4 3)
@funindex \override
Pour bien des propriétés, quel que soit le type de valeur requise,
-attribuer la valeur @q{faux} (@code{##f} en Scheme) reviendra à désactiver
-complètement l'action de la propriété qui se trouve ainsi purement
-ignorée par LilyPond. Cela peut s'avérer fort utile pour des propriétés
-causant des désagréments.
+attribuer la valeur @q{faux} (@code{##f} en Scheme) reviendra à
+désactiver complètement l'action de la propriété qui se trouve ainsi
+purement ignorée par LilyPond. Cela peut s'avérer fort utile pour des
+propriétés causant des désagréments.
-@c such announcements are to be avoided -vv
-@ignore
-We demonstrate how to glean this information from the notation manual
-and the program reference.
@end ignore
-@node La commande d'affinage (@emph{tweak})
-@subsection La commande @code{\tweak}
-@translationof The tweak command
+@seealso
+
+Référence des propriétés internes :
+@rinternals{Backend}
+@node La commande d'affinage (tweak)
+@subsection La commande d'affinage @code{@bs{}tweak}
+@translationof The tweak command
+
+@cindex retouche (tweak)
+@cindex affinage (tweak)
+@cindex tweak (retouche, affinage)
@funindex \tweak
+L'utilisation d'un @code{\override} pour modifier les propriétés d'un
+objet graphique affectera toutes les instances de l'objet en question au
+sein du contexte, et ce dès son apparition. Il peut parfois être
+préférable de n'affecter qu'un seul objet en particulier plutôt que tous
+les objets du contexte. C'est là rôle de l'instruction @code{\tweak},
+dont la syntaxe est@tie{}:
+
+@example
+\tweak #'@code{objet-propriété} #@code{valeur}
+@end example
+
+La commande @code{\tweak} s'applique à l'objet qui apparaît
+immédiatement après @code{valeur}.
+
+@ignore
Dans certains cas, on peut passer par un raccourci pour arranger les
-objets graphiques. Lorsqu'un objet est directement engendré par un élément distinct
-du fichier source, on peut utiliser la commande @code{\tweak}.
+objets graphiques. Lorsqu'un objet est directement engendré par un
+élément distinct du fichier source, on peut utiliser la commande
+@code{\tweak}.
-Dans l'accord suivant, les notes sont modifiées une par une :
+Dans l'accord suivant, les notes sont modifiées une par une@tie{}:
-@lilypond[relative=2,fragment,verbatim,ragged-right]
+@lilypond[relative=2,verbatim,ragged-right]
<
c
- \tweak #'color #red d
+ \tweak #'color #red
+ d
g
- \tweak #'duration-log #1 a
->4-\tweak #'padding #10 -.
+ \tweak #'duration-log #1
+ a
+>4
+-\tweak #'padding #8
+-^
@end lilypond
Comme on peut le voir, les propriétés sont ici modifiées directement
-en même temps que les objets sont saisis. Il n'est plus besoin de spécifier ni
-le nom de l'objet (@emph{grob}), ni le contexte dans lequel cela doit s'appliquer.
-
-Ce procédé ne marche que pour des objets directement liés aux évènements
-(@rinternals{Event}) du fichier source. Par exemple :
+en même temps que les objets sont saisis. Il n'est plus besoin de
+spécifier ni le nom de l'objet (@emph{grob}), ni le contexte dans lequel
+cela doit s'appliquer. Ce procédé ne marche que pour des objets
+directement liés aux évènements (@rinternals{Event}) du fichier source.
+Par exemple@tie{}:
@itemize @bullet
-@item Les têtes de notes au sein d'un accord, qui sont directement engendrées par
-les hauteurs indiquées
-@item Les signes d'articulation, engendrés par les indications de ponctuation.
+@item Les têtes de notes au sein d'un accord, qui sont directement
+engendrées par les hauteurs indiquées
+
+@item Les signes d'articulation, engendrés par les indications de
+ponctuation.
@end itemize
-En revanche, les hampes ou les altérations sont engendrées par les têtes de notes,
-et non par des évènements dans le fichier source. De même pour les clés, qui ne
-sont pas directement engendrées par le fichier source, mais plutôt par le
-changement d'une propriété interne.
+En revanche, les hampes ou les altérations sont engendrées par les têtes
+de notes, et non par des évènements dans le fichier source. De même
+pour les clés, qui ne sont pas directement engendrées par le fichier
+source, mais plutôt par le changement d'une propriété interne.
-En fait, très peu d'objets passent @emph{directement} du code source à la partition.
-Une note toute simple, par exemple @code{c4}, fait l'objet d'un traitement et n'est donc
-pas directement rendue ; c'est pourquoi le code suivant ne sera d'aucun effet :
+En fait, très peu d'objets passent @emph{directement} du code source à
+la partition. Une note toute simple, par exemple @code{c4}, fait l'objet
+d'un traitement et n'est donc pas directement rendue@tie{}; c'est
+pourquoi le code suivant ne sera d'aucun effet@tie{}:
@example
\tweak #'color #red c4
@end example
@noindent
-Voir pour plus de détails @ref{Affichage d'expressions musicales}.
+Voir pour plus de détails
+@rextend{Affichage d'expressions musicales}.
+@end ignore
+
+Pour une introduction à la syntaxe et l'utilisation des retouches, voir
+le chapitre @rlearning{Méthodes de retouche}.
+
+Lorsque plusieurs éléments de même nature surviennent au même instant,
+il devient impossible d'utiliser l'instruction @code{\override} pour
+n'en modifier qu'un seul individuellement, d'où l'intérêt de la commande
+@code{\tweak}. Entre autres éléments qui sont susceptibles de se
+produire au même instant, nous citerons@tie{}:
+
+@c TODO expand to include any further uses of \tweak
+@itemize
+@item les têtes de notes au sein d'un accord,
+@item les signes d'articulation,
+@item les liaisons de prolongation sur des notes d'un accord,
+@item les crochets de nolets démarrant au même instant
+@end itemize
+
+@c TODO add examples of these
+
+Dans l'exemple suivant, l'une des têtes de note de l'accord est
+colorisée, et l'aspect d'une autre est changé.
+
+@lilypond[relative=2,verbatim,quote]
+< c
+ \tweak #'color #red
+ d
+ g
+ \tweak #'duration-log #1
+ a
+> 4
+@end lilypond
+
+L'instruction @code{\tweak} permet aussi de modifier l'aspect d'une
+liaison@tie{}:
+
+@lilypond[verbatim,quote,relative=1]
+c-\tweak #'thickness #5 ( d e f)
+@end lilypond
+
+La commande @code{\tweak} ne sera pleinement fonctionnelle que si elle
+est directement rattachée à l'objet auquel elle doit s'appliquer alors
+que le fichier source est converti en flux musical. LilyPond peut
+parfois être amené à ajouter d'autres éléments au flux musical lors de
+la phase d'analyse. C'est la raison pour laquelle, puisque LilyPond
+peut insérer une note dans un accord alors qu'elle n'en fait pas partie
+explicitement, il est impératif d'adopter une construction d'accord
+lorsque l'instruction @code{\tweak} concerne une note isolée@tie{}:
+
+@lilypond[relative=2,verbatim,quote]
+\tweak #'color #red c4
+<\tweak #'color #red c>4
+@end lilypond
+
+La commande @code{\tweak} ne saurait servir à modifier un élément qui ne
+serait pas explicitement mentionné dans le fichier source. C'est
+notamment le cas des hampes, ligatures ou altérations, dans la mesure où
+elles seront ultérieurement générées et après les têtes de note, plutôt
+qu'au fil des éléments musicaux saisis. La commande @code{\tweak} ne
+peut non plus servir à modifier clefs ou métriques, puisqu'elles seront
+immanquablement séparées du @code{\tweak} par l'insertion automatique
+d'autres éléments requis pour spécifier le contexte.
+
+Plusieurs commandes @code{\tweak} en enfilade permettent d'affecter un
+même élément de notation@tie{}:
+
+@lilypond[verbatim,quote,relative=1]
+c
+-\tweak #'style #'dashed-line
+-\tweak #'dash-fraction #0.2
+-\tweak #'thickness #3
+-\tweak #'color #red
+ \glissando
+f'
+@end lilypond
+
+Vous pouvez examiner le flux musical généré par une portion de votre
+fichier source, y compris les éléments automatiquement insérés, en
+suivant les indications portées à la rubrique
+@rextend{Affichage d'expressions musicales}. Ceci s'avère tout à fait
+approprié pour déterminer ce qui peut se modifier à l'aide d'un
+@code{\tweak} ou bien vous aider à rectifier votre source de telle sorte
+que le @code{\tweak} produise ses effets.
+
+
+@seealso
+Manuel d'initiation :
+@rlearning{Méthodes de retouche}.
+
+Manuel d'extension :
+@rextend{Affichage d'expressions musicales}.
+
+
+@knownissues
+
+@cindex tweak et identificateur
+La commande @code{\tweak} ne peut s'utiliser dans une variable.
+
+@cindex tweaks et paroles
+La commande @code{\tweak} est inopérante en mode @code{\lyricmode}.
+
+@cindex tweaking control points
+@cindex control points, tweaking
+Lorsqu'il y a plusieurs liaisons de prolongation dans un accord, la
+commande @code{\tweak} ne s'applique qu'à la première.
@node set ou override
@subsection @code{\set} ou @code{\override}
@translationof set versus override
+@c TODO -- This section is probably unnecessary now.
-Si les propriétés peuvent être modifiées de deux façons, par les commandes
-@code{\set} et @code{\override}, c'est qu'il y a deux types de propriétés.
+@ignore
+Si les propriétés peuvent être modifiées de deux façons, par les
+commandes @code{\set} et @code{\override}, c'est qu'il y a deux types de
+propriétés.
-Les contextes peuvent avoir des propriétés, dont les noms commencent par une
-minuscule puis comprennent une ou plusieurs majuscules (de style
-@code{totoTutu}). Elles ont surtout trait
-à la notation des éléments musicaux : par exemple, @code{localKeySignature} permet
-de choisir s'il faut ou non imprimer une altération, ou @code{measurePosition} permet
-de choisir quand il faut imprimer une barre de mesure. Ces propriétés de contextes
-sont appelées à changer au long de l'interprétation de la partition :
-@code{measurePosition} en est un exemple évident. Ces propriétés doivent
-être modifiées avec la commande @code{\set}.
+La propriété @code{fontSize} est une exception@tie{}: c'est un
+raccourci, qui équivaudrait à saisir @w{@code{\override @dots{}
+#'font-size}} pour tous les objets textuels. Dans la mesure où il
+s'agit d'une manipulation très courante, une propriété spéciale a été
+créée. Elle doit être modifiée avec la commande @code{\set}.
-Il existe un type particulier de propriétés : les descriptions
-d'éléments. Ces propriétés, dont les noms commencent par une majuscule, puis comprennent
-une ou plusieurs majuscules (de style @code{TotoTata}), contiennent les réglages
-@q{par défaut} pour les objets graphiques. Ces réglages sont sous forme de liste Scheme ; on
-peut les consulter dans le fichier @file{scm/@/define@/-grobs@/.scm}.
-Les descriptions d'éléments doivent être modifiées avec la commande @code{\override}.
+@end ignore
-@code{\override} est en fait un raccourci :
+
+@node Modification de listes associatives
+@subsection Modification de listes associatives
+@translationof Modifying alists
+
+Certaines propriétés configurables par l'utilisateur se présentent en
+interne comme étant des listes associatives -- les puristes diront des
+@emph{alists}. Une @emph{alist} est en fait constituée de plusieurs
+paires de @emph{clés} et @emph{valeurs}@tie{}; sa structure ressemble
+à@tie{}:
@example
-\override @var{contexte}.@var{objet} #'@var{propriété} = #@var{valeur}
+'((@var{clé1} . @var{valeur1})
+ (@var{clé2} . @var{valeur2})
+ (@var{clé3} . @var{valeur3})
+ @dots{})
@end example
-@noindent
-est plus ou moins l'équivalent de
+Dans le cas où cette liste représente les propriétés d'un objet
+graphique ou bien l'une des variables du bloc @code{\paper}, chaque clé
+peut être modifiée individuellement sans que cela n'affecte les autres.
+
+Par exemple, pour réduire l'espacement entre deux portées adjacentes
+d'un même système, on utilisera la propriété @code{staff-staff-spacing}
+qui est attachée à l'objet graphique @code{StaffGrouper}. Cette
+propriété est constituée d'une liste de quatre clés@tie{}:
+@code{basic-distance}, @code{minimum-distance}, @code{padding} et
+@code{stretchability}. Ses réglages par défaut tels que mentionnés à la
+rubrique @emph{Backend} de la référence des propriétés internes -- voir
+@rinternals{StaffGrouper} -- sont@tie{}:
-@c leave this long line -gp
@example
-\set @var{contexte}.@var{objet} #'@var{propriété} = #(cons (cons '@var{propriété} @var{valeur}) <valeur précédente de @var{contexte})
+'((basic-distance . 9)
+ (minimum-distance . 7)
+ (padding . 1)
+ (stretchability . 5))
@end example
-La valeur de @code{context} (la liste Scheme, ou @q{alist}) sert à initialiser
-les propriétés des objets un par un. Les objets eux-même ont leurs propriétés,
-dont les noms, dans la tradition du langage Scheme, comprennent un trait d'union
-(@code{toto-titi}). Ces propriétés internes changent constamment au cours de la mise
-en page : en fait, la gravure d'une page n'est autre que le calcul de toutes
-ces propriétés, au moyen de fonctions de rappel.
+Afin de rapprocher nos deux portées, il suffit de réduire la valeur
+(@code{9}) de la clé @code{basic-distance} au niveau de celle de la clé
+@code{minimum-distance} (@code{7}). La modification d'une seule clé
+individuellement peut se réaliser sous la forme d'une @emph{déclaration
+imbriquée}@tie{}:
+
+@lilypond[quote,verbatim]
+% default space between staves
+\new PianoStaff <<
+ \new Staff { \clef treble c''1 }
+ \new Staff { \clef bass c1 }
+>>
+
+% reduced space between staves
+\new PianoStaff \with {
+ % this is the nested declaration
+ \override StaffGrouper #'staff-staff-spacing #'basic-distance = #7
+} <<
+ \new Staff { \clef treble c''1 }
+ \new Staff { \clef bass c1 }
+>>
+@end lilypond
+
+Le recours à une déclaration imbriquée touchera la clé indiquée
+(@code{basic-distance} dans l'exemple ci-dessus) sans pour autant
+modifier les autres clés de la propriété considérée.
+
+Considérons maintenant que nous souhaitions que les portées soient le
+plus proche possible les unes des autres, à la limite du chevauchement.
+Il suffirait de mettre les quatre clés à zéro. Nous pourrions saisir
+quatre déclarations, chacune d'elles touchant une clé. Nous pouvons
+tout aussi bien redéfinir la propriété en une seule clause, sous la
+forme d'une liste associative@tie{}:
+
+@lilypond[quote,verbatim]
+\new PianoStaff \with {
+ \override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 0)
+ (minimum-distance . 0)
+ (padding . 0)
+ (stretchability . 0))
+} <<
+ \new Staff { \clef treble c''1 }
+ \new Staff { \clef bass c1 }
+>>
+@end lilypond
-La propriété @code{fontSize} est une exception : c'est un raccourci, qui équivaudrait
-à saisir @code{\override @dots{} #'font-size} pour tous les objets
-textuels. Dans la mesure où il s'agit d'une manipulation très
-courante, une propriété spéciale a été créée. Elle doit
-être modifiée avec la commande @code{\set}.
+N'oubliez pas que dès lors qu'une clé n'apparaît pas dans la liste, elle
+retourne à sa valeur @emph{sauf-mention-contraire}. Autrement dit, dans
+le cas de @code{staff-staff-spacing} qui nous occupe, toutes les clés
+non mentionnées seront ramenées à zéro -- à l'exception de
+@code{stretchability} qui prend par défaut la valeur de
+@code{basic-distance}. Les deux assertions suivantes sont donc
+équivalentes.
+
+@example
+\override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 7))
+
+\override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 7)
+ (minimum-distance . 0)
+ (padding . 0)
+ (stretchability . 7))
+@end example
+L'une des conséquences, parfois involontaire, de ceci est la suppression
+de réglages standards effectués par un fichier d'initialisation chargé à
+chaque compilation de votre fichier source. Dans l'exemple précédent,
+les réglages standards de @code{padding} et @code{minimum-distance},
+tels que déterminés par @file{scm/define-grobs.scm}, se voient ramenés à
+leur valeur @emph{si-non-définie}@tie{}; autrement dit, les deux clés
+sont mises à zéro. La définition d'une propriété ou d'une variable sous
+forme de liste associative, quelle qu'en soit la taille, réinitialisera
+toujours les clés non mentionnées à leur valeur @emph{si-non-définie}.
+Si telle n'est pas votre intention, nous vous recommandons alors de
+régler la valeur des clés individuellement par des déclarations
+imbriquées.
+
+@warning{Les déclarations imbriquées ne sont pas fonctionnelles dans le
+cas des listes associatives des propriétés de contexte -- telles
+@code{beamExceptions}, @code{keySignature},
+@code{timeSignatureSettings}, etc. Ces propriétés ne sont modifiables
+qu'au travers d'une complète redéfinition de leur liste associative.}
@node Propriétés et contextes utiles
* Modes de saisie::
* Direction et positionnement::
* Distances et unités de mesure::
-* Propriétés des lignes de portée::
+* Propriétés des symboles de la portée::
* Extenseurs et prolongateurs::
* Visibilité des objets::
* Styles de ligne::
@node Modes de saisie
@subsection Modes de saisie
-@translationof Input modes @c external
+@translationof Input modes
-@untranslated
+La manière dont sera interprétée la notation contenue dans un fichier
+source dépend du mode affecté à la saisie.
+
+@strong{Mode accords}
+
+Ce mode, activé par la commande @code{\chordmode}, permet d'interpréter
+les saisies comme étant des accords, qui seront imprimés sous forme
+de notes sur une portée -- voir @ref{Notation des accords}.
+
+Le mode accords s'active aussi par la commande @code{\chords}, qui
+créera un contexte @code{ChordNames}. Les saisies, interprétées comme
+étant des accords, seront alors rendues sous forme nominale dans ce
+contexte @code{ChordNames} -- voir @ref{Impression des noms d'accord}.
+
+@strong{Mode percussions}
+
+Ce mode, activé par la commande @code{\drummode}, permet d'interpréter
+les saisies comme étant de la notation pour percussions -- voir
+@ref{Notation de base pour percussions}.
+
+Le mode percussions s'active aussi par la commande @code{\drums}, qui
+créera un contexte @code{DrumStaff}. Les saisies, interprétées comme
+étant de la notation pour percussions, seront alors rendues sous
+forme symbolique sur une portée de percussions -- voir
+@ref{Notation de base pour percussions}.
+
+@strong{Mode figures}
+
+Ce mode, activé par la commande @code{\figuremode}, permet d'interpréter
+les saisies comme étant de la basse chiffrée (ou figurée) -- voir
+@ref{Saisie de la basse chiffrée}.
+
+Le mode figures s'active aussi par la commande @code{\figures}, qui
+créera un contexte @code{FiguredBass}. Les saisies interprétées comme
+étant de la basse chiffrée, seront alors rendues sous forme symbolique
+dans le contexte @code{FiguredBass} -- voir
+@ref{Introduction à la basse chiffrée}.
+
+@strong{Mode frets et tablatures}
+
+Il n'existe pas de mode spécifique pour saisir des symboles de fret ou
+de tablature.
+
+Notes ou accords saisis en mode note puis affectés à un contexte
+@code{TabStaff} seront rendus sous forme de diagramme de tablature --
+voir @ref{Tablatures par défaut}.
+
+Deux options différentes permettent d'obtenir des diagrammes de fret en
+surplomb d'une portée@tie{}: directement à l'aide d'un contexte
+@code{FretBoards} -- voir @ref{Tablatures automatiques} -- ou en
+attachant aux notes des @emph{markups} créés par la commande
+@code{\fret-diagram} -- voir @ref{Tablatures sous forme d'étiquette}.
+
+@strong{Mode paroles}
+
+Ce mode, activé par la commande @code{\lyricmode}, permet d'interpréter
+les saisies comme étant des syllabes, ayant éventuellement une durée, et
+des indications habituelles aux paroles -- voir @ref{Musique vocale}.
+
+Le mode paroles s'active aussi par la commande @code{\addlyrics}, qui
+créera un contexte @code{Lyrics} et ajoutera implicitement une commande
+@code{\lyricsto} afin d'associer les paroles qui suivent à la musique
+précédemment saisie.
+
+@strong{Mode @emph{markup}}
+
+Ce mode, activé par la commande @code{\markup}, permet d'interpréter les
+saisies comme étant des @emph{markups} (annotations ou étiquettes) --
+voir @rusernamed{Text markup commands,Commandes pour le mode markup}.
+
+
+@c silly work-around for texinfo broken-ness
+@c (@strong{Note...} causes a spurious cross-reference in Info)
+@b{Mode notes}
+
+Le mode notes est le mode par défaut dans LilyPond. Il peut aussi
+s'activer par la commande @code{\notemode}. Les saisies seront
+interprétées comme étant des hauteurs, durées, @emph{markups}, etc. qui
+seront rendues sous forme de notation musicale sur une portée.
+
+Nul n'est besoin de spécifier le mode notes de manière explicite, hormis
+dans certaines situations particulières, notamment lorsque vous êtes en
+mode paroles, accords, ou tout autre mode, et que vous deviez insérer
+un élément qui ne serait disponible que grâce à la syntaxe du mode
+notes.
+
+Il en va ainsi lorsque, par exemple, vous voulez ajouter une indication
+de nuance au numéro de couplet d'un chant choral@tie{}:
+
+@lilypond[verbatim,relative=2,quote]
+{ c4 c4 c4 c4 }
+\addlyrics {
+ \notemode{\set stanza = \markup{ \dynamic f 1. } }
+ To be sung loudly
+}
+\addlyrics {
+ \notemode{\set stanza = \markup{ \dynamic p 2. } }
+ To be sung quietly
+}
+@end lilypond
@node Direction et positionnement
@subsection Direction et positionnement
-@translationof Direction and placement @c external
+@translationof Direction and placement
+
+En matière de typographie musicale, l'orientation et le positionnement
+de nombreux éléments est affaire de goût. Par exemple, les hampes
+peuvent être ascendantes ou descendantes, les paroles, nuances ou autres
+indications d'expression peuvent apparaître au-dessus ou en dessous de
+la portée, les indications textuelles s'alignent tantôt par la gauche,
+tantôt par la droite, ou être centrées. La plupart de ces choix peuvent
+être laissés à l'appréciation de LilyPond. Il peut être préférable,
+dans certains cas, d'imposer l'orientation ou le positionnement des
+éléments.
+
+@strong{Indicateurs de position d'une articulation}
+
+Certains positionnements sont opérés par défaut -- toujours au-dessus ou
+toujours en dessous (nuances ou points d'orgue) -- alors que d'autres
+alterneront selon l'orientation des hampes (liaisons ou accents).
+
+@c TODO Add table showing these
+
+Le positionnement par défaut peut être outrepassé à l'aide d'un
+@emph{indicateur de positionnement}, qui vient s'insérer juste avant
+l'articulation. LilyPond met à votre disposition trois indicateurs de
+positionnement@tie{}: @code{^} (pour @qq{au-dessus}), @code{_} (pour
+@qq{au-dessous}), et @code{-} (pour @qq{appliquer le positionnement par
+défaut}). L'indicateur de positionnement n'est pas obligatoire@tie{};
+LilyPond considère alors qu'il y a un @code{-}. Un indicateur de
+positionnement est cependant @strong{obligatoire} dans les cas
+suivants@tie{}:
-@untranslated
+@itemize
+@item une commande @code{\tweak},
+@item une commande @code{\markup},
+@item une commande @code{\tag},
+@item les indications de corde, par exemple @code{-"corde"},
+@item les indications de doigté, par exemple @w{@code{-1}},
+@item les raccourcis d'articulation, par exemple @w{@code{-.}},
+@w{@code{->}} ou @w{@code{--}}.
+@end itemize
+
+Les indicateurs de positionnement n'affectent que la note qui suit@tie{}:
+
+@lilypond[verbatim,quote,relative=2]
+c2( c)
+c2_( c)
+c2( c)
+c2^( c)
+@end lilypond
+
+@strong{La propriété @code{direction}}
+
+Le positionnement ou l'orientation de nombreux objets de rendu est géré
+par la propriété @code{direction}.
+
+La propriété @code{direction} peut prendre la valeur @code{1}, qui
+signifie @qq{ascendant} ou @qq{au-dessus}, ou @w{@code{-1}}, qui
+signifie @qq{descendant} ou @qq{au-dessous}. Les symboliques @code{UP}
+et @code{DOWN} peuvent remplacer respectivement @code{1} et
+@w{@code{-1}}. Les valeurs @code{0} ou @code{CENTER} permettent de
+réaffecter à la propriété @code{direction} son comportement par défaut.
+Certaines commandes prédéfinies permettent par ailleurs de spécifier un
+comportement en matière d'orientation ou positionnement@tie{}; elles
+sont de la forme
+
+@noindent
+@code{\xxxUp}, @code{\xxxDown}, @code{\xxxNeutral}
+
+@noindent
+auquel cas @code{\xxxNeutral} signifie @qq{retour au comportement par
+défaut} -- voir @rlearning{Objets inclus dans la portée}.
+
+Dans quelques cas particuliers, comme l'indication d'un @emph{arpeggio},
+la valeur affectée à la propriété @code{direction} déterminera si
+l'objet doit se placer à gauche ou à droite de son parent. Un
+@w{@code{-1}} ou @code{LEFT} signifiera alors @qq{sur la gauche}, et un
+@code{1} ou @code{RIGHT} @qq{sur la droite}. Comme de bien entendu, un
+@code{0} ou @code{CENTER} signifiera @qq{appliquer le positionnement par
+défaut}.
+
+@ignore
+These all have side-axis set to #X
+AmbitusAccidental - direction has no effect
+Arpeggio - works
+StanzaNumber - not tried
+TrillPitchAccidental - not tried
+TrillPitchGroup - not tried
+@end ignore
+
+Notez que ces commandes resteront effectives jusqu'à ce qu'elles soient
+annulées.
+
+@lilypond[verbatim,quote,relative=2]
+c2( c)
+\slurDown
+c2( c)
+c2( c)
+\slurNeutral
+c2( c)
+@end lilypond
@node Distances et unités de mesure
@subsection Distances et unités de mesure
-@translationof Distances and measurements @c external
+@translationof Distances and measurements
+
+@cindex distance absolue
+@cindex distance relative
+@cindex distance extensible
+
+@funindex \mm
+@funindex \cm
+@funindex \in
+@funindex \pt
+
+LilyPond considère deux types de distances@tie{}: les distances absolues
+et les distances relatives ou extensibles.
+
+Les distances absolues permettent de spécifier les marges, indentations
+et autres détails de mise en page@tie{}; elles s'expriment par défaut en
+millimètres. Vous pouvez utiliser d'autres systèmes de mesure, dès lors
+que la quantité est suivie de la mesure@tie{}: @code{\mm}, @code{\cm},
+@code{\in}@tie{}(pouces) ou @code{\pt}@tie{}(points, 1/72,27 pouce).
+Les mesures de mise en page peuvent aussi s'exprimer en unité extensible
+de portée @code{\staff-space} (voir ci-après). Pour plus d'information
+concernant la mise en page, voir la rubrique
+@ref{Mise en forme de la page}.
+
+Les distances relatives ou extensibles s'expriment toujours en
+@qq{espace de portée} ou, plus rarement, en @qq{demi espace de portée}.
+L'espace de portée correspond à la distance qui sépare deux lignes
+adjacentes d'une portée. Sa valeur par défaut est déterminée
+globalement par la taille de portée. Elle peut aussi s'ajuster
+ponctuellement en jouant sur la propriété @code{staff-space} de l'objet
+@code{StaffSymbol}. Les distances relatives s'ajustent automatiquement
+dès qu'une modification de la taille globale de portée ou bien de la
+propriété @code{staff-space} du @code{StaffSymbol} intervient.
+Cependant, les tailles de fonte ne s'ajusteront automatiquement que si
+la modification touche la taille globale des portées. La taille globale
+de portée permet ainsi de gérer l'aspect général de la partition --
+voir @ref{Définition de la taille de portée}.
+
+@funindex magstep
+
+Lorsque seulement une portion de partition doit apparaître dans une
+taille, comme par exemple une portée d'ossia ou une note de bas de page,
+influer sur la taille globale de portée affecterait l'intégralité de la
+partition. Il convient donc dans ce cas de modifier à la fois la
+propriété @code{staff-space} du @code{StaffSymbol} et la taille des
+fontes. La fonction Scheme @code{magstep} est tout spécialement chargée
+d'adapter une modification du @code{staff-space} aux fontes. Pour de
+plus amples informations, reportez-vous à la rubrique
+@rlearning{Longueur et épaisseur des objets}.
+
+
+@seealso
+Manuel d'initiation :
+@rlearning{Longueur et épaisseur des objets}.
-@untranslated
+Manuel de notation :
+@ref{Définition de la taille de portée},
+@ref{Mise en forme de la page}.
-@node Propriétés des lignes de portée
-@subsection Propriétés des lignes de portée
-@translationof Staff symbol properties @c external
+@node Propriétés des symboles de la portée
+@subsection Propriétés des symboles de la portée
+@translationof Staff symbol properties
-@untranslated
+@cindex ajustement des symboles de portée
+@cindex dessin des symboles de portée
+@cindex symboles de portée, dessin
+
+@c TODO Extend or remove this section. See also NR 1.6.2 Staff symbol
+@c Need to think of uses for these properties. Eg 'line-positions
+@c is used in a snippet to thicken centre line.
+@c If retained, add @ref to here in 1.6.2 -td
+
+L'emplacement vertical et le nombre de lignes d'une portée se
+définissent conjointement. Comme l'illustre l'exemple suivant, le
+positionnement des notes n'est en rien influencé par le positionnement
+des lignes de la portée.
+
+@warning{La propriété @code{'line-positions} écrase la propriété
+@code{'line-count}. Le nombre de lignes d'une portée est implicitement
+défini par le nombre d'éléments dans la liste des valeurs de
+@code{'line-positions}.}
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+ \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+La largeur d'une portée, exprimée en espace de portée, peut être figée.
+L'espacement des objets inclus dans cette portée ne sera en rien affecté
+par ce réglage.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+ \override StaffSymbol #'width = #23
+}
+{ a4 e' f b | d1 }
+@end lilypond
@node Extenseurs et prolongateurs
@subsection Extenseurs et prolongateurs
-@translationof Spanners @c external
+@translationof Spanners
-@untranslated
+De nombreux objets de notation musicale s'étendent sur plusieurs notes,
+voire même sur plusieurs mesures. Il en va ainsi des liaisons,
+ligatures, crochets de nolet, crochets de reprise, crescendos, trilles
+ou glissandos. Ces objets, que l'on englobe sous l'appellation
+@qq{d'extenseur}, sont pourvus de propriétés spécifiques destinées à
+contrôler leur apparence et leur comportement. Un certain nombre de ces
+propriétés sont communes à tous les extenseurs, d'autres n'affectent que
+certains d'entre eux.
+
+Tout extenseur dispose de la @code{spanner-interface}. Quelques uns,
+tout particulièrement ceux chargés de dessiner une ligne droite entre
+deux objets, disposent aussi de la @code{line-spanner-interface}.
@unnumberedsubsubsec Utilisation de @code{spanner-interface}
+@translationof Using the @code{spanner-interface}
+
+Cette interface fournit deux propriétés qui s'appliquent à certains
+extenseurs.
+
+@strong{@i{La propriété @code{minimum-length}}}
+
+La longueur minimale d'un extenseur est déterminée par la propriété
+@code{minimum-length}. Au plus sa valeur est élevée, au plus
+l'espacement des notes qui le bornent sera grand. Forcer sa valeur
+restera néanmoins sans effet pour un certain nombre d'extenseurs dont la
+longueur dépend d'autres considérations. Voici quelques exemples de
+mise en œuvre de cette propriété.
+
+@ignore
+Cette propriété est pleinement fonctionnelle pour @tie{}:
+ Tie (liaison de prolongation)
+ MultiMeasureRest (silence multimesures)
+ Hairpin (soufflet)
+ Slur (liaison d'articulation)
+ PhrasingSlur (liaison de phrasé)
+
+Cette propriété est fonctionnelle en présence d'un @emph{callback}@tie{}:
+ Glissando
+ Beam (ligature)
+
+Cette propriété est sans effet sur@tie{}:
+ LyricSpace
+ LyricHyphen
+ LyricExtender
+ TextSpanner
+ System
+
+@end ignore
+
+@lilypond[verbatim,quote,relative=2]
+a~a
+a
+% increase the length of the tie
+-\tweak #'minimum-length #5
+~a
+@end lilypond
+
+@lilypond[verbatim,quote,relative=2]
+a1
+\compressFullBarRests
+R1*23
+% increase the length of the rest bar
+\once \override MultiMeasureRest #'minimum-length = #20
+R1*23
+a1
+@end lilypond
+
+@lilypond[verbatim,quote,relative=2]
+a \< a a a \!
+% increase the length of the hairpin
+\override Hairpin #'minimum-length = #20
+a \< a a a \!
+@end lilypond
+
+Cette propriété permet aussi de jouer sur l'envergure d'une liaison
+d'articulation ou de phrasé.
+
+@lilypond[verbatim,quote,relative=2]
+a( a)
+a
+-\tweak #'minimum-length #5
+( a)
+
+a\( a\)
+a
+-\tweak #'minimum-length #5
+\( a\)
+@end lilypond
+
+Certains objets requièrent un appel explicite à la procédure
+@code{set-spacing-rods} pour que la propriété @code{minimum-length}
+produise ses effets. La propriété @code{set-spacing-rods} doit alors
+prendre pour valeur @code{ly:spanner::set-spacing-rods}. Par exemple, la
+longueur minimale d'un glissando ne pourra être forcée tant que la
+propriété @code{springs-and-rods} n'est pas définie@tie{}:
+
+@lilypond[verbatim,quote,relative=1]
+% default
+e \glissando c'
+
+% not effective alone
+\once \override Glissando #'minimum-length = #20
+e, \glissando c'
+
+% effective only when both overrides are present
+\once \override Glissando #'minimum-length = #20
+\once \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
+e, \glissando c'
+@end lilypond
+
+Il en va de même pour l'objet @code{Beam} (ligature)@tie{}:
+
+@lilypond[verbatim,quote,relative=1]
+% not effective alone
+\once \override Beam #'minimum-length = #20
+e8 e e e
+
+% effective only when both overrides are present
+\once \override Beam #'minimum-length = #20
+\once \override Beam #'springs-and-rods = #ly:spanner::set-spacing-rods
+e8 e e e
+@end lilypond
+
+@strong{@i{La propriété @code{to-barline}}}
+
+La seconde propriété fournie par la @code{spanner-interface} est
+@code{to-barline}. Elle est activée par défaut, raison pour laquelle
+les soufflets et autres extenseurs finissant sur la première note d'une
+mesure s'arrêtent visuellement au niveau de la barre de mesure qui la
+précède. Le fait de désactiver la propriété @code{to-barline} aura pour
+effet de prolonger l'extenseur au delà de la barre de mesure et jusqu'à
+la note qui le borne@tie{}:
+
+@lilypond[verbatim,quote,relative=2]
+a \< a a a a \! a a a \break
+\override Hairpin #'to-barline = ##f
+a \< a a a a \! a a a
+@end lilypond
+
+Cette propriété n'est pas opérationnelle pour tous les extenseurs. Il
+serait en effet quelque peu surprenant de l'activer (lui affecter
+@code{#t}) dans le cas d'une liaison d'articulation ou de phrasé@tie{}!
+
+
@unnumberedsubsubsec Utilisation de @code{line-spanner-interface}
+@translationof Using the @code{line-spanner-interface}
+
+Un certain nombre d'objets disposent de la propriété
+@code{line-spanner-interface}, entre autres@tie{}:
+
+@itemize
+@item @code{DynamicTextSpanner}
+@item @code{Glissando}
+@item @code{TextSpanner}
+@item @code{TrillSpanner}
+@item @code{VoiceFollower}
+@end itemize
+
+La routine en charge de dessiner le stencil de ces extenseurs est
+@code{ly:line-interface::print}. Elle va déterminer les deux points
+extrêmes et dessiner entre eux une ligne du style requis. Bien que la
+localisation des deux bornes de l'extenseur soit calculée à la volée,
+vous pouvez cependant forcer leur ordonnée (coordonnée-Y). Les
+propriétés que vous devrez ajuster résident au deuxième niveau dans la
+hiérarchie, mais la syntaxe de la commande @code{\override} nécessaire
+demeure relativement simple@tie{}:
+
+@lilypond[relative=2,quote,verbatim]
+e2 \glissando b
+\once \override Glissando #'(bound-details left Y) = #3
+\once \override Glissando #'(bound-details right Y) = #-2
+e2 \glissando b
+@end lilypond
+
+La propriété @code{Y} est valorisée en unités de @code{staff-space}, la
+ligne médiane de la portée correspondant au point zéro. Pour le
+glissando qui nous occupe, il s'agit du @code{Y} à l'aplomb
+(coordonnée-X) du centre de la tête de chacune des deux notes, si tant
+est que la ligne doive s'étendre entre ces deux points.
+
+Si le @code{Y} n'est pas défini, sa valeur sera calculée en fonction de
+la position verticale du point d'attachement de l'extenseur.
+
+Dans le cas où l'extenseur est interrompu par un saut de ligne, les
+terminaisons à cet endroit se gèrent grâce aux sous-clés
+@code{left-broken} et @code{right-broken} de @code{bound-details}, comme
+ci-dessous@tie{}:
+
+@lilypond[relative=2,ragged-right,verbatim,quote]
+\override Glissando #'breakable = ##t
+\override Glissando #'(bound-details right-broken Y) = #-3
+c1 \glissando \break
+f1
+@end lilypond
+
+Les sous-propriétés @code{left} et @code{right} du @code{bound-details}
+disposent d'autres clés modifiables de la même manière que
+@code{Y}@tie{}:
+
+@table @code
+@item Y
+Détermine l'ordonnée (coordonnée-Y) de la terminaison, avec un
+décalage en @code{staff-space} par rapport à la ligne médiane de la
+portée. Il s'agit par défaut du centre de l'objet d'attachement, qui
+est le centre vertical de la tête de note pour un glissando.
+
+En ce qui concerne les extenseurs horizontaux, tels ceux comportant du
+texte ou les trilles, il est fixé à@tie{}@code{0}.
+
+@item attach-dir
+Détermine le début et la fin de la ligne sur l'axe des abscisses,
+relativement à l'objet de rattachement. Une valeur de @w{@code{-1}} (ou
+@code{LEFT}) aura pour effet de commencer ou terminer la ligne sur la
+gauche de la tête de note de rattachement.
+
+@item X
+Il s'agit de l'abscisse (coordonnée-X) absolue de la terminaison. Elle
+se calcule à la volée, et son forçage n'apporte rien de plus.
+
+@item stencil
+Les extenseurs linéaires peuvent commencer ou finir par un symbole,
+enregistré dans cette sous-propriété. Elle est conçue pour un usage
+interne, aussi nous vous conseillons de plutôt recourir à @code{text}.
+
+@item text
+Il s'agit d'un @emph{markup} qui se poursuivra par l'extenseur. C'est la
+sous-propriété utilisée pour ajouter @i{cresc.}, @i{tr} ou autre texte à
+un extenseur horizontal.
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+\override TextSpanner #'(bound-details left text)
+ = \markup { \small \bold Slower }
+c2\startTextSpan b c a\stopTextSpan
+@end lilypond
+
+@item stencil-align-dir-y
+@item stencil-offset
+Lorsqu'aucune de ces deux sous-propriétés n'est définie, le stencil est
+simplement positionné à l'extrémité, centré sur la ligne telle que
+définie par les sous-propriétés @code{X} et @code{Y}. L'utilisation de
+@code{stencil-align-dir-y} ou @code{stencil-offset} permettra d'aligner
+le symbole verticalement par rapport au coin de la ligne@tie{}:
+
+@lilypond[relative=1,quote,verbatim]
+\override TextSpanner
+ #'(bound-details left stencil-align-dir-y) = #-2
+\override TextSpanner
+ #'(bound-details right stencil-align-dir-y) = #UP
+
+\override TextSpanner
+ #'(bound-details left text) = #"ggg"
+\override TextSpanner
+ #'(bound-details right text) = #"hhh"
+c4^\startTextSpan c c c \stopTextSpan
+@end lilypond
+
+Vous n'aurez pas manqué de constater qu'une valeur négative place le
+texte @emph{en haut} -- contrairement à ce que l'on serait en droit
+d'attendre. Ceci est dû au fait que la valeur @w{@code{-1}} ou
+@code{DOWN} signifie @qq{aligner le bord @emph{inférieur} du texte sur
+la ligne d'extension}. Une valeur égale à@tie{}@code{1} ou @code{UP}
+alignera le sommet du texte sur cette ligne d'extension.
+
+@item arrow
+L'activation de cette sous-propriété (lui affecter @code{#t}) ajoutera
+à l'extenseur une terminaison en flèche.
+
+@item padding
+Cette sous-propriété contrôle l'espace qui doit séparer l'extrémité de
+la ligne et la fin réelle de l'extenseur. Sans ce @qq{décalage}, le
+trait indiquant un glissando commencerait et finirait au beau milieu de
+chacune des têtes de note.
+
+@end table
+
+La fonction @code{\endSpanners} permet d'interrompre l'extenseur qui
+vient dès la note suivante. Autrement dit, il ne s'étendra que sur une
+seule note, ou jusqu'à la prochaine barre de mesure si @code{to-barline}
+a été activé et que survient une barre avant la note suivante.
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+\endSpanners
+c2 \startTextSpan c2 c2
+\endSpanners
+c2 \< c2 c2
+@end lilypond
+
+L'utilisation de @code{\endSpanners} permet de s'affranchir d'insérer un
+@code{\stopTextSpan} pour clôturer un @code{\startTextSpan} ou un
+@code{\!} pour terminer un soufflet.
+
+
+@seealso
+Référence des propriétés internes :
+@rinternals{Glissando},
+@rinternals{line-spanner-interface},
+@rinternals{TextSpanner},
+@rinternals{TrillSpanner},
+@rinternals{VoiceFollower}.
+
+
@node Visibilité des objets
@subsection Visibilité des objets
-@translationof Visibility of objects @c external
+@translationof Visibility of objects
+
+@cindex objets, visibilité
+@cindex grobs, visibilité
+@cindex visibilité d'objets
-@untranslated
+La visibilité des objets de rendu se contrôle de quatre façons
+différentes@tie{}: vous pouvez supprimer leur stencil, les rendre
+transparents, les coloriser en blanc ou bien encore forcer leur
+propriété @code{break-visibility}. Les trois premières options peuvent
+s'appliquer à tous les objets, la dernière étant réservée aux objets
+@emph{changeables}. Le Manuel d'initiation contient une introduction à
+ces quatre techniques, à la rubrique
+@rlearning{Visibilité et couleur des objets}.
+LilyPond met en œuvre quelques techniques particulières adaptées à
+certains objets@tie{}; elles sont couvertes par une rubrique spécifique.
@menu
* Suppression des stencils::
@node Suppression des stencils
@unnumberedsubsubsec Suppression des stencils
-@translationof Removing the stencil @c external
-
-@untranslated
+@translationof Removing the stencil
+
+@cindex stencil, suppression
+
+Tout objet de rendu se voit attribuer une propriété @code{stencil}.
+Elle est par défaut définie par la fonction chargée de dessiner cet
+objet. Lorsque cette propriété est désactivée de force -- en lui
+attribuant la valeur @code{#f} -- aucune fonction ne sera appelée@tie{};
+l'objet ne sera donc pas dessiné. Le retour au comportement par défaut
+s'opère à l'aide d'un @code{\revert}.
+
+@lilypond[quote,verbatim,relative=1]
+a1 a
+\override Score.BarLine #'stencil = ##f
+a a
+\revert Score.BarLine #'stencil
+a a a
+@end lilypond
@node Transparence des objets
@unnumberedsubsubsec Transparence des objets
-@translationof Making objects transparent @c external
+@translationof Making objects transparent
+
+@cindex transparent, objet
-@untranslated
+Tout objet de rendu dispose d'une propriété de transparence, qui est par
+défaut définie à @code{#f}. Le fait de l'activer rendra l'objet
+transparent tout en préservant la place qu'il occupe.
+
+@lilypond[quote,verbatim,relative=2]
+a4 a
+\once \override NoteHead #'transparent = ##t
+a a
+@end lilypond
@node Blanchiment des objets
@unnumberedsubsubsec Blanchiment des objets
-@translationof Painting objects white @c external
+@translationof Painting objects white
+
+@cindex objets, couleur
+@cindex couleur d'objet
+@cindex layers
+@cindex calque
+@cindex impression, ordre
+@cindex surimpression d'objets
+@cindex objets, surimpression
+@cindex grobs, superposition
+
+Tout objet de rendu dispose d'une propriété couleur, par défaut définie
+à @code{black} (noir). Le fait de la forcer à @code{white} (blanc)
+rendra l'objet indistinct du fond blanc. Néanmoins, lorsque cet objet
+en recouvre d'autres, la couleur de leurs points de jonction dépendra de
+l'ordre dans lequel ils sont dessinés, ce qui peut laisser apparaître
+un fantôme de l'objet blanchi comme ci-dessous@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+a1
+@end lilypond
-@untranslated
+Cet inconvénient peut être évité en modifiant l'ordre dans lequel les
+objets sont dessinés. Chaque objet de rendu dispose d'une propriété
+@code{layer} (calque ou niveau) à laquelle est affecté un nombre entier.
+Les objets ayant la plus faible valeur sont dessinés en premier, puis
+les autres, de telle sorte qu'un objet ayant une valeur plus élevée les
+recouvrira. La plupart des objet ont un @code{layer} valorisé
+à@tie{}@code{1} -- quelques uns, dont @code{StaffSymbol} et
+@code{BarLine}, ont une valeur à@tie{}@code{0}. L'ordre d'impression
+d'objets ayant une même valeur de @code{layer} est indéterminé.
+
+La clef de l'exemple précédent a par défaut un @code{layer}
+à@tie{}@code{1}@tie{}; elle est donc dessinée après les lignes de la
+portée -- @code{layer} valorisé par défaut à@tie{}@code{0} -- et donc
+les recouvre. Pour changer cet état de fait, l'objet @code{Clef} doit
+avoir un @code{layer} de valeur inférieure, disons @w{@code{-1}}, pour
+pouvoir être dessiné avant.
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+\override Staff.Clef #'layer = #-1
+a1
+@end lilypond
@node Utilisation de break-visibility
@unnumberedsubsubsec Utilisation de break-visibility
-@translationof Using break-visibility @c external
+@translationof Using break-visibility
+
+@cindex break-visibility
+
+La plupart des objets de rendu ne sont imprimés qu'une seule fois@tie{};
+certains cependant, tels les barres de mesure, clefs, métriques ou
+armures, apparaîtront deux fois lors d'un saut de ligne -- une première
+fois en fin de ligne, puis à nouveau au début de la ligne suivante. Ces
+objets, que l'on peut traiter de @emph{changeables} (@emph{breakable} en
+anglais) disposent de la propriété @code{break-visibility} spécialement
+chargée de contrôler leur visibilité aux trois endroits où il sont
+susceptibles d'apparaître@tie{}: en début de ligne, en cours de ligne ou
+en fin de ligne -- si tant est qu'un changement s'y produise.
+
+Par exemple, la métrique est imprimée par défaut au début de la première
+ligne, et nulle part ailleurs. En cas de modification, une nouvelle
+métrique sera imprimée à l'endroit du changement. Dans le cas où ce
+changement intervient en fin de ligne, la nouvelle métrique s'imprime au
+début de la ligne suivante, et une métrique @qq{de précaution} viendra
+se placer au bout de la ligne précédente.
+
+Ce comportement est géré par la propriété @code{break-visibility}, dont
+vous trouverez une explication à la rubrique
+@rlearning{Visibilité et couleur des objets}. Cette propriété est
+constituée d'un vecteur de trois booléens qui, dans l'ordre, déterminent
+si l'objet sera imprimé à la fin, en cours, et au début d'une ligne --
+on pourrait aussi dire avant un saut de ligne, là où il n'y a pas de
+saut de ligne, et après un saut de ligne.
+
+Les huit combinaisons possibles sont aussi disponibles sous la forme de
+fonctions prédéfinies, regroupées dans le fichier
+@file{scm/output-lib.scm}. Le tableau suivant vous les présente@tie{};
+les trois dernières colonnes indiquent l'endroit où l'objet sera visible.
+
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t. )}} {apres} {apres} {apres}
+@headitem Forme @tab Forme @tab Avant @tab Hors @tab Après
+@headitem fonctionnelle @tab vectorielle @tab saut @tab saut @tab saut
+
+@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab oui @tab oui @tab oui
+@item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab non @tab non @tab oui
+@item @code{center-visible} @tab @code{'#(#f #t #f)} @tab non @tab oui @tab non
+@item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab oui @tab non @tab non
+@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab oui @tab oui @tab non
+@item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab oui @tab non @tab oui
+@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab non @tab oui @tab oui
+@item @code{all-invisible} @tab @code{'#(#f #f #f)} @tab non @tab non @tab non
+@end multitable
+
+Les réglages par défaut de la propriété @code{break-visibility}
+diffèrent selon l'objet de rendu. Le tableau suivant présente, pour la
+plupart des objets comportant la propriété @code{break-visibility},
+ces réglages par défaut.
+
+@multitable @columnfractions .3 .3 .4
+
+@headitem Objet de rendu @tab Contexte habituel @tab Réglage par défaut
+
+@c omit Ambitus as it appears not to be affected by break-visibility -td
+@c @item @code{Ambitus} @tab as specified @tab @code{begin-of-line-visible}
+@item @code{BarLine} @tab @code{Score} @tab calculé
+@item @code{BarNumber} @tab @code{Score} @tab @code{begin-of-line-visible}
+@c omit the following item until it can be explained -td
+@c @item @code{BreakAlignGroup} @tab @code{Score} @tab calculé
+@item @code{BreathingSign} @tab @code{Voice} @tab @code{begin-of-line-invisible}
+@item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible}
+@item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible}
+@c omit KeyCancellation until it can be explained -td
+@c @item @code{KeyCancellation} @tab ?? @tab @code{begin-of-line-invisible}
+@item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@c omit LeftEdge until it can be explained -td
+@c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible}
+@item @code{OctavateEight} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@item @code{RehearsalMark} @tab @code{Score} @tab @code{end-of-line-invisible}
+@item @code{TimeSignature} @tab @code{Staff} @tab @code{all-visible}
+
+@end multitable
+
+Voici un exemple d'utilisation de la forme vectorielle pour contrôler la
+visibilité des barres de mesure@tie{}:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+f4 g a b
+f4 g a b
+% Remove bar line at the end of the current line
+\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
+\break
+f4 g a b
+f4 g a b
+@end lilypond
-@untranslated
+Lors d'un forçage de @code{break-visibility} sous une forme vectorielle,
+les trois éléments doivent impérativement être mentionnés. Ces formes
+vectorielles ne sont d'ailleurs pas prises en charge par tous les objets
+de rendu, et certaines combinaisons peuvent entraîner des erreurs@tie{};
+nous citerons entre autres@tie{}:
+
+@itemize @bullet
+@item Une barre de mesure ne peut s'imprimer en début de ligne.
+@item Un numéro de mesure ne peut apparaître au début de la première
+ligne, à moins d'être différent de@tie{}1.
+@item Clef -- voir ci-après.
+@item Les répétitions en pourcentage sont soit toutes imprimées, soit
+aucune. Vous devrez utiliser @code{begin-of-line-invisible} pour les
+voir et @code{all-invisible} pour les masquer.
+@item Armure -- voir ci-après.
+@item Indication d'octaviation -- voir ci-après.
+@end itemize
@node Considérations spécifiques
@unnumberedsubsubsec Considérations spécifiques
-@translationof Special considerations @c external
+@translationof Special considerations
+
+@strong{@emph{Visibilité après changement explicite}}
+
+@cindex armure, visibilité après changement explicite
+@cindex explicitKeySignatureVisibility
+@cindex clef, visibilité après changement explicite
+@cindex explicitClefVisibility
+
+La propriété @code{break-visibility} contrôle la visibilité des armures
+ou changements de clef en début de ligne uniquement, donc après un saut.
+Elle ne produit aucun effet sur la visibilité d'une armure ou d'une clef
+après un changement explicite de tonalité ou de clef, ni en cours, ni en
+fin de ligne. Dans l'exemple suivant, l'armure est présente même après
+le passage en si bémol majeur malgré l'activation de
+@code{all-invisible} (@emph{tous invisibles}).
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+% Try to remove all key signatures
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+La visibilité lors de ces changements explicites d'armure ou de clef est
+géré respectivement par les propriétés
+@code{explicitKeySignatureVisibility} et @code{explicitClefVisibility}.
+Leur fonctionnement est en tout point identique à celui de la propriété
+@code{break-visibility} -- forme vectorielle à trois éléments ou forme
+fonctionnelle comme indiqué ci-avant. Toutes deux sont attachées au
+contexte @code{Staff} (la portée) et non directement aux objets de
+rendu@tie{}; elles sont de ce fait introduites par une instruction
+@code{\set}. Leur valeur par défaut est de toujours imprimer les objets
+-- réglage sur @code{all-visible}. Ces deux propriétés gèrent
+uniquement la visibilité des armures et clefs lors d'un changement
+explicite, et en dehors d'un début de ligne@tie{}; il faudra en pareil
+cas forcer la @code{break-visibility} de ces objets pour les supprimer.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+@strong{@emph{Visibilité des altérations de précaution}}
+
+L'impression d'altérations de précaution au moment d'un changement
+explicite de tonalité sera annulée dès lors que vous aurez désactivé la
+propriété @code{printKeyCancellation} du contexte @code{Staff}@tie{}:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
-@untranslated
+Avec de tels réglages particuliers, seules les altérations accidentelles
+permettront d'indiquer le changement de tonalité.
+
+@c TODO Add visibility of cautionary accidentals before notes
+
+@strong{@emph{Barres de mesure automatiques}}
+
+@cindex automaticBars
+@cindex barres de mesure, suppression
+
+La désactivation de la propriété @code{automaticBars}, qui réside dans
+le contexte @code{Score}, permet de s'affranchir d'imprimer
+automatiquement les barres de mesure@tie{}; seules seront imprimées les
+barres explicitées à l'aide de la commande @code{\bar}. Néanmoins, et
+contrairement à ce qui se passe avec la commande @code{\cadenzaOn}, le
+compteur de numéro de mesure continuera de s'incrémenter. Les barres
+s'imprimeront à nouveau, au niveau où en est le compteur, dès que la
+propriété @code{automaticBars} sera réactivée. Gardez à l'esprit que
+les sauts de ligne, lorsque cette propriété est désactivée, ne peuvent
+intervenir qu'à l'occasion d'un @code{\bar} explicite.
+
+@c TODO Add example
+
+@strong{@emph{Clefs octaviées}}
+
+@cindex octaviation, visibilité de la clef
+@cindex visibilité d'un clef octaviée
+@cindex clef, visibilité de l'octaviation
+
+L'indication d'octaviation d'une clef est produite par l'objet de rendu
+@code{OctavateEight}. Sa visibilité étant gérée par héritage direct de
+l'objet @code{Clef}, nul n'est besoin de forcer un quelconque
+@code{break-visibility} au niveau des objets @code{OctavateEight} pour
+éliminer une indication d'octaviation lorsque la clef est invisible.
+
+Lors d'un changement explicite de clef, la propriété
+@code{explicitClefVisibility} gère à la fois le symbole de la clef et
+l'indication d'octaviation qui lui est attachée.
+
+
+@seealso
+Manuel d'initiation :
+@rlearning{Visibilité et couleur des objets}
@node Styles de ligne
@subsection Styles de ligne
-@translationof Line styles @c external
+@translationof Line styles
+
+Certaines indications portées à l'attention de l'exécutant -- tels
+@i{rallentando}, @i{accelerando} et @i{trilles} -- apparaissent sous la
+forme d'un texte qui peut s'étendre sur plusieurs mesures à l'aide d'une
+ligne parfois pointillée ou ondulée.
+
+En matière de dessin du texte et des lignes, ces indications font appel
+aux mêmes routines que le glissando@tie{}; leur comportement peut donc
+être affiné selon les mêmes préceptes, au moyen de la routine
+@code{ly:line-interface::print} qui est tout spécialement chargée de
+dessiner les extenseurs. Cette routine détermine l'emplacement exact
+des deux points extrêmes de l'extenseur, puis trace une ligne du style
+demandé entre ces deux points.
+
+L'exemple ci-dessous indique les différents styles de ligne disponibles,
+ainsi que la manière de les spécifier.
+
+@lilypond[relative=2,ragged-right,verbatim,quote]
+d2 \glissando d'2
+\once \override Glissando #'style = #'dashed-line
+d,2 \glissando d'2
+\override Glissando #'style = #'dotted-line
+d,2 \glissando d'2
+\override Glissando #'style = #'zigzag
+d,2 \glissando d'2
+\override Glissando #'style = #'trill
+d,2 \glissando d'2
+@end lilypond
+
+Les points d'ancrage de l'extension sont calculés à la volée pour chaque
+objet graphique, mais rien ne vous empêche de les forcer@tie{}:
+
+@c TODO Complete
+@lilypond[relative=2,ragged-right,verbatim,quote]
+e2 \glissando f
+\once \override Glissando #'(bound-details right Y) = #-2
+e2 \glissando f
+@end lilypond
+
+La valeur de @code{Y} est ainsi fixée à @w{@code{-2}} en ce qui concerne
+la borne droite. Il en irait de même pour la borne gauche en spécifiant
+@code{left} (gauche) au lieu de @code{right} (droite).
+
+En l'absence de réglage du @code{Y}, celui-ci est calculé à partir de
+l'emplacement vertical des points d'attache gauche et droit de
+l'extenseur.
-@untranslated
+De plus amples informations quant à l'ajustement des extenseurs font
+l'objet de la rubrique @ref{Extenseurs et prolongateurs}.
@node Rotation des objets
@subsection Rotation des objets
-@translationof Rotating objects @c external
-
-@untranslated
+@translationof Rotating objects
+Qu'il s'agisse des objets de rendu ou d'éléments textuels sous forme de
+@emph{markup}, vous pouvez les faire pivoter selon vos désirs et à
+partir de n'importe quel point. La méthode diffère cependant selon ce
+que vous désirez manipuler.
@menu
* Rotation des objets de mise en forme::
* Rotation des étiquettes::
@end menu
+
@node Rotation des objets de mise en forme
@unnumberedsubsubsec Rotation des objets de mise en forme
-@translationof Rotating layout objects @c external
+@translationof Rotating layout objects
+
+Tout objet de rendu disposant de la @code{grob-interface} est
+susceptible de pivoter, grâce à la propriété @code{rotation}. Celle-ci
+prend en argument une liste de trois éléments@tie{}: l'angle de rotation
+-- dans le sens inverse des aiguilles d'une montre -- ainsi que les
+coordonnées @code{x} et @code{y} du point appartenant à l'objet en
+question et à partir duquel doit s'effectuer cette rotation. L'angle
+est exprimé en degrés, les coordonnées en espaces de portée.
-@untranslated
+L'angle et les coordonnées ne peuvent se déterminer que par tâtonnement.
+
+@cindex soufflet penché
+
+Il existe assez peu de situation où faire pivoter un objet de mise en
+forme soit réellement opportun@tie{}; en voici une@tie{}:
+
+@lilypond[quote,verbatim,relative=1]
+g4\< e' d' f\!
+\override Hairpin #'rotation = #'(20 -1 0)
+g,,4\< e' d' f\!
+@end lilypond
@node Rotation des étiquettes
@unnumberedsubsubsec Rotation des étiquettes
-@translationof Rotating markup @c external
+@translationof Rotating markup
+
+Tout texte faisant l'objet d'un @emph{markup} peut pivoter selon
+n'importe quel angle, à l'aide de la commande @code{\rotate}. Celle-ci
+prend deux arguments@tie{}: l'angle de rotation exprimé en degrés --
+dans le sens inverse des aiguilles d'une montre -- et le texte à
+basculer.
+@c ne vois comment traduire -jcm
+@ignore
+The extents of the text are not rotated: they take
+their values from the extremes of the x and y coordinates of the
+rotated text.
+@end ignore
+Dans l'exemple ci-dessous, la propriété @code{outside-staff-priority} à
+été fixée à @code{#f} afin de désactiver l'évitement automatique des
+collisions qui pourrait repousser certains textes trop haut.
-@untranslated
+@c KEEP LY
+@lilypond[quote,verbatim,relative=1]
+\override TextScript #'outside-staff-priority = ##f
+g4^\markup { \rotate #30 "un sol" }
+b^\markup { \rotate #30 "un si" }
+des^\markup { \rotate #30 "un ré bémol" }
+fis^\markup { \rotate #30 "un fa dièse" }
+@end lilypond
@node Retouches avancées
@section Retouches avancées
-@translationof Advanced tweaks @c external
-
-@untranslated
+@translationof Advanced tweaks
+Nous allons voir, au fil des paragraphes qui suivent, différentes
+approches permettant de fignoler l'apparence d'une partition.
@menu
* Alignement des objets::
* Regroupement vertical d'objets graphiques::
* Modification des stencils::
* Modification de l'allure des éléments::
+* Conteneurs requalifiants::
@end menu
-@node Alignement des objets
-@subsection Alignement des objets
-@translationof Aligning objects @c external
+@seealso
+Manuel d'initiation :
+@rlearning{Autres sources de documentation},
+@rlearning{Retouche de partition}.
+
+Manuel de notation :
+@ref{En quoi consiste la référence des propriétés internes},
+@ref{Modification de propriétés}.
+
+Fichiers d'initialisation :
+@file{scm/define-grobs.scm}.
-@untranslated
+Morceaux choisis :
+@rlsrnamed{Tweaks and overrides,Retouches}.
+Manuel d'extension :
+@rextend{Interfaces pour programmeurs}.
+
+Référence des propriétés internes :
+@rinternals{All layout objects}.
+
+
+@node Alignement des objets
+@subsection Alignement des objets
+@translationof Aligning objects
+
+Les objets graphiques disposant des interfaces
+@code{self-alignment-interface} ou @code{side-position-interface}
+peuvent s'aligner par rapport à un objet précédemment positionné, ce de
+différentes manières. Ces objets sont référencés aux rubriques
+@rinternals{self-alignment-interface} et
+@rinternals{side-position-interface}.
+
+Tous les objets graphiques ont un point de référence, une étendue
+horizontale et une étendue verticale. L'étendue horizontale est
+représentée par une paire de nombres indiquant l'écart entre le point de
+référence et les bords gauche et droit -- l'écart à gauche étant
+négatif. L'étendue verticale est représentée par une paire de nombres
+indiquant l'écart entre le point de référence et les bords inférieur et
+supérieur -- l'écart vers le bas étant négatif.
+
+La position d'un objet sur la portée est donnée par la valeur des
+propriétés @code{X-offset} et @code{Y-offset}. La valeur de
+@code{X-offset} indique l'écart en abscisse (coordonnée X) par rapport
+au point de référence de l'objet parent@tie{}; la valeur de
+@code{Y-offset} indique l'écart par rapport à la ligne médiane de la
+portée. Les valeurs de @code{X-offset} et @code{Y-offset} peuvent être
+fournies arbitrairement, ou bien être calculé par des procédures
+spécifiques qui détermineront l'alignement par rapport à l'objet parent.
+
+@warning{Nombre d'objets sont affectés par des considérations
+spécifiques en matière de positionnement@tie{}; jouer sur les valeurs de
+@code{X-offset} ou @code{Y-offset} se révélera inefficace en pareil
+cas, même si l'objet dispose de la @code{self-alignment-interface}.
+Fixer arbitrairement les propriétés @code{X-offset} ou @code{Y-offset}
+annihilera alors les effets de la propriété @code{self-alignment}
+correspondante.}
+
+Par exemple, une altération peut se repositionner verticalement grâce à
+son @code{Y-offset}@tie{}; toute modification de son @code{X-offset}
+restera par contre sans effet.
+
+Les indications de repère s'alignent sur des objets de rupture -- tels
+les barres de mesure, clefs, métriques et armures. Certaines propriétés
+spécifiques -- dépendant de la @code{break-aligned-interface} --
+permettent de gérer le positionnement des indications de repère sur ces
+objets.
@menu
-* Détermination directe de @code{X-offset} et @code{Y-offset}::
-* Utilisation de @code{side-position-interface}::
-* Utilisation de @code{self-alignment-interface}::
-* Utilisation de @code{break-aligned-interface}::
+* Détermination directe de X-offset et Y-offset::
+* Utilisation de side-position-interface::
+* Utilisation de self-alignment-interface::
+* Utilisation de break-aligned-interface::
@end menu
-@node Détermination directe de @code{X-offset} et @code{Y-offset}
+@seealso
+Manuel d'extension :
+@rextend{Fonctions de rappel}.
+
+
+@node Détermination directe de X-offset et Y-offset
@unnumberedsubsubsec Détermination directe de @code{X-offset} et @code{Y-offset}
-@translationof Setting @code{X-offset} and @code{Y-offset} directly @c external
+@translationof Setting X-offset and Y-offset directly
+
+Vous pouvez fournir, pour de nombreux objets, des valeurs numériques aux
+propriétés @code{X-offset} et @code{Y-offset}. Voici par exemple une
+note avec indication du doigté tout d'abord avec un positionnement par
+défaut, puis repositionnement par modification successive du
+@code{X-offset} et du @code{Y-offset}.
+
+@lilypond[verbatim,quote,relative=2]
+a-3
+a
+-\tweak #'X-offset #0
+-\tweak #'Y-offset #0
+-3
+a
+-\tweak #'X-offset #-1
+-\tweak #'Y-offset #1
+-3
+@end lilypond
-@untranslated
+@c TODO write more
-@node Utilisation de @code{side-position-interface}
+@node Utilisation de side-position-interface
@unnumberedsubsubsec Utilisation de @code{side-position-interface}
-@translationof Using the @code{side-position-interface} @c external
+@translationof Using the side-position-interface
-@untranslated
+Un objet disposant de la @code{side-position-interface} peut se voir
+accolé à son voisin de telle sorte que les bords des deux objets se
+touchent. Un tel objet peut se positionner au-dessus, en dessous, à
+droite ou à gauche de son parent. Ce parent ne saurait être
+stipulé@tie{}; il est déterminé par l'ordre d'apparition des éléments
+dans le flux des saisies. La plupart de ces objets ont pour parent une
+tête de note.
+Les valeurs des propriétés @code{side-axis} et @code{direction}
+détermineront l'endroit où viendra se positionner l'objet, selon les
+préceptes suivants@tie{}:
-@node Utilisation de @code{self-alignment-interface}
+@c TODO add an example of each to the table
+
+@multitable @columnfractions .3 .3 .3
+@headitem Propriété @tab Propriété @tab Positionnement
+@headitem @code{side-axis} @tab @code{direction} @tab
+
+@item @code{0} @tab @code{-1} @tab gauche
+@item @code{0} @tab @code{1} @tab droite
+@item @code{1} @tab @code{-1} @tab en dessous
+@item @code{1} @tab @code{1} @tab au-dessus
+
+@end multitable
+
+Pour un @code{side-axis} à @code{0}, le @code{X-offset} devrait engager
+la procédure @code{ly:side-position-interface::x-aligned-side}.
+Celle-ci renverra la valeur adéquate de @code{X-offset} permettant
+d'accoler l'objet sur la droite ou sur la gauche de son parent, selon la
+valeur de @code{direction}.
+
+Pour un @code{side-axis} à @code{1}, le @code{Y-offset} devrait engager
+la procédure @code{ly:side-position-interface::y-aligned-side}.
+Celle-ci renverra la valeur adéquate de @code{Y-offset} permettant
+d'accoler l'objet au-dessus ou en dessous de son parent, selon la
+valeur de @code{direction}.
+
+@c TODO Add examples
+
+
+@node Utilisation de self-alignment-interface
@unnumberedsubsubsec Utilisation de @code{self-alignment-interface}
-@translationof Using the @code{self-alignment-interface} @c external
+@translationof Using the self-alignment-interface
+
+@emph{Réalignement d'objets horizontalement}
+
+L'alignement horizontal d'un objet disposant de la
+@code{self-alignment-interface} dépend de la valeur de sa propriété
+@code{self-alignment-X}, si tant est que la propriété @code{X-offset} de
+cet objet engage la procédure
+@code{ly:self-alignment-interface::x-aligned-on-self}.
+La propriété @code{self-alignment-X} peut contenir un nombre réel,
+l'unité de base étant la moitié de l'étendue horizontale de l'objet.
+Une valeur négative décalera l'objet vers la droite, une valeur positive
+vers la gauche. La valeur@tie{}@code{0} permet de centrer l'objet sur
+le point de référence de son parent. Une valeur de@tie{}@w{@code{-1}}
+alignera le bord gauche de l'objet sur le point de référence de son
+parent, et une valeur de@tie{}@code{1} alignera le bord droit de l'objet
+sur le point de référence de son parent. Les valeurs symboliques
+@code{LEFT}, @code{CENTER} et @code{RIGHT} correspondent respectivement
+à@tie{}@w{@code{-1}}, @code{0} et @code{1}.
+
+En règle générale, la valeur de @code{self-alignment-X} se modifie à
+l'aide d'une commande @code{\override}. Le recours à la commande
+@code{\tweak} permet de traiter séparément plusieurs annotations
+affectées à une même note@tie{}:
+
+@lilypond[quote,verbatim,relative=1]
+a'
+-\tweak #'self-alignment-X #-1
+^"left-aligned"
+-\tweak #'self-alignment-X #0
+^"center-aligned"
+-\tweak #'self-alignment-X #RIGHT
+^"right-aligned"
+-\tweak #'self-alignment-X #-2.5
+^"aligned further to the right"
+@end lilypond
-@untranslated
+
+@emph{Réalignement d'objets verticalement}
+
+L'alignement vertical suit le même principe@tie{}: la propriété
+@code{Y-offset} doit alors engager la procédure
+@code{ly:self-alignment-interface::y-aligned-on-self}. Toutefois, il
+arrive bien souvent que d'autres mécanismes interviennent dans
+l'alignement vertical. La valeur de @code{Y-offset} n'étant que
+l'une des variables qui seront prises en compte, l'ajustement pour
+certains objets peut se révéler fastidieux. L'unité de base est
+relativement réduite, puisqu'elle est de la moitié de l'étendue
+verticale de l'objet@tie{}; le nombre à fournir en argument pourrait
+donc être relativement élevé. Une valeur de@tie{}@w{@code{-1}}
+alignera le bord inférieur de l'objet sur le point de référence de son
+parent, et une valeur de@tie{}@code{1} alignera le bord supérieur de
+l'objet sur le point de référence de son parent. La
+valeur@tie{}@code{0} permet de centrer l'objet sur le point de référence
+de son parent. Les valeurs symboliques @code{DOWN}, @code{CENTER} et
+@code{UP} correspondent respectivement à@tie{}@w{@code{-1}}, @code{0} et
+@code{1}.
+
+
+@emph{Réalignement d'objets sur les deux axes}
+
+Définir à la fois @code{X-offset} et @code{Y-offset} permet de réaligner
+un objet sur les deux axes.
+
+Dans l'exemple ci-dessous, nous ajustons l'indication de doigté de telle
+sorte qu'elle se place au plus près de la tête de note.
+
+@lilypond[quote,verbatim,relative=2]
+a
+-\tweak #'self-alignment-X #0.5 % move horizontally left
+-\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
+-\tweak #'self-alignment-Y #-1 % move vertically up
+-3 % third finger
+@end lilypond
-@unnumberedsubsubsec Utilisation des procédures @code{aligned-on-parent}
-@unnumberedsubsubsec Utilisation des procédures @code{centered-on-parent}
-@node Utilisation de @code{break-aligned-interface}
+@ignore
+@unnumberedsubsubsec Utilisation de @code{aligned-on-parent}
+
+@c Cannot document as they do not seem to operate consistently on all objects -td
+@c TODO investigate further
+
+The @code{aligned-on-parent} procedures are used in the same way
+as the @code{aligned-on-self} procedures, they difference being
+that they permit an object to be aligned with the @emph{edges} of
+the parent rather than the parent's reference point. The following
+example shows the difference:
+
+@c TODO Add example
+
+@lilypond[verbatim,quote]
+@end lilypond
+
+@end ignore
+
+
+@ignore
+@c unnumberedsubsubsec Utilisation de @code{centered-on-parent}
+
+@c Cannot document as they do not seem to operate consistently on all objects -td
+@c TODO investigate further
+
+@end ignore
+
+@c TODO The align-interface, BassFigureAlignment and VerticalAlignment
+
+
+@node Utilisation de break-aligned-interface
@unnumberedsubsubsec Utilisation de @code{break-aligned-interface}
-@translationof Using the @code{break-alignable-interface} @c external
+@translationof Using the break-alignable-interface
+
+@cindex alignement sur un objet
+@cindex break-align-symbols
+
+Indications de repère et numéros de mesure peuvent s'aligner sur des
+objets de notation autres qu'une barre de mesure. Parmi ces objets,
+nous citerons @code{ambitus}, @code{breathing-sign}, @code{clef},
+@code{custos}, @code{staff-bar}, @code{left-edge},
+@code{key-cancellation}, @code{key-signature}, et @code{time-signature}.
+
+Ces indications et numéros de mesure sont par défaut centrés
+horizontalement au-dessus de l'objet@tie{}:
+
+@lilypond[verbatim,quote,relative=1]
+% The rehearsal mark will be centered above the Clef
+\override Score.RehearsalMark #'break-align-symbols = #'(clef)
+\key a \major
+\clef treble
+\mark "↓"
+e1
+% The rehearsal mark will be centered above the Time Signature
+\override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
+\key a \major
+\clef treble
+\time 3/4
+\mark "↓"
+e2.
+% The rehearsal mark will be centered above the Breath Mark
+\override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign)
+\key a \major
+\clef treble
+\time 4/4
+e1
+\breathe
+\mark "↓"
+@end lilypond
+
+Les différents objets sur lesquels l'alignement pourrait intervenir
+seront regroupés dans une liste. Si l'un des objets est invisible à
+l'endroit voulu, en raison d'un réglage de @code{break-visibility} ou
+bien par forçage de la visibilité des armures et clefs, le repère ou le
+numéro de mesure viendra s'aligner sur le premier élément de cette liste
+qui soit visible. Dans le cas où aucun objet de la liste n'est visible,
+l'alignement se fera sur la barre de mesure ou, dans le cas où la barre
+de mesure est invisible, à l'endroit même où la barre prendrait place.
+
+@lilypond[verbatim,quote,relative=1]
+% The rehearsal mark will be centered above the Key Signature
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef treble
+\mark "↓"
+e1
+% The rehearsal mark will be centered above the Clef
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef bass
+\mark "↓"
+gis,,1
+% The rehearsal mark will be centered above the Bar Line
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.explicitClefVisibility = #all-invisible
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef treble
+\mark "↓"
+e''1
+@end lilypond
-@untranslated
+L'alignement d'un repère sur un objet de notation peut se modifier,
+comme l'illustre l'exemple suivant. Toutefois, si la partition comporte
+plusieurs portées, ce réglage devra apparaître dans chacune des portées.
+
+@lilypond[verbatim,quote,relative=1]
+% The RehearsalMark will be centered above the Key Signature
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+\key a \major
+\clef treble
+\time 4/4
+\mark "↓"
+e1
+% The RehearsalMark will be aligned with the left edge of the Key Signature
+\once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
+\mark "↓"
+\key a \major
+e1
+% The RehearsalMark will be aligned with the right edge of the Key Signature
+\once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
+\key a \major
+\mark "↓"
+e1
+@end lilypond
+
+Le bord gauche d'un repère peut se décaler arbitrairement sur la gauche
+ou la droite. La valeur est exprimée en espaces de portée.
+
+@lilypond[verbatim,quote,relative=1]
+% The RehearsalMark will be aligned with the left edge of the Key Signature
+% and then shifted right by 3.5 staff-spaces
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+\once \override Score.KeySignature #'break-align-anchor = #3.5
+\key a \major
+\mark "↓"
+e1
+% The RehearsalMark will be aligned with the left edge of the Key Signature
+% and then shifted left by 2 staff-spaces
+\once \override Score.KeySignature #'break-align-anchor = #-2
+\key a \major
+\mark "↓"
+e1
+@end lilypond
@node Regroupement vertical d'objets graphiques
@subsection Regroupement vertical d'objets graphiques
@translationof Vertical grouping of grobs
+@c TODO Expand this section
+
Les objets @code{VerticalAlignment} et @code{VerticalAxisGroup}
travaillent de concert. Comme leurs noms anglais l'indiquent,
@code{VerticalAxisGroup} regroupe différents objets tels que les portées
-(@code{Staff}), les paroles (@code{Lyrics}) et ainsi de suite ; puis
-@code{VerticalAlignment} synchronise verticalement ces différents groupes.
-En général, il n'y a qu'un seul @code{VerticalAlignment} pour l'ensemble
-de la partition, mais chaque contexte @code{Staff}, @code{Lyrics}, etc.
-possède son propre @code{VerticalAxisGroup}.
+(@code{Staff}), les paroles (@code{Lyrics}) et ainsi de suite@tie{};
+puis @code{VerticalAlignment} synchronise verticalement ces différents
+groupes. En général, il n'y a qu'un seul @code{VerticalAlignment} pour
+l'ensemble de la partition, mais chaque contexte @code{Staff},
+@code{Lyrics}, etc. possède son propre @code{VerticalAxisGroup}.
@node Modification des stencils
@subsection Modification des stencils
-@translationof Modifying stencils @c external
+@translationof Modifying stencils
+
+Tout objet de rendu dispose d'une propriété @code{stencil} attachée à la
+@code{grob-interface}. En règle générale, cette propriété référence
+par défaut une fonction spécifique à l'objet et taillée sur mesure pour
+fournir le symbole qui va le représenter dans l'output. Par exemple,
+le réglage standard de la propriété @code{stencil} de l'objet
+@code{MultiMeasureRest} est @code{ly:multi-measure-rest::print}.
+
+Le symbole standard d'un objet quel qu'il soit peut être remplacé à
+partir du moment où la propriété @code{stencil} référence une procédure
+différente et écrite à cet effet. Ceci requiert une bonne maîtrise du
+fonctionnement interne de LilyPond, mais est grandement facilité dans
+bien des cas et permet d'obtenir le résultat escompté.
+
+En effet, rien ne nous interdit, à partir de la propriété
+@code{stencil}, d'appeler la procédure qui génère du texte,
+@code{ly:text-interface::print} en l'occurrence, et d'adjoindre à l'objet
+une propriété @code{text} qui contiendra, sous forme de @emph{markup},
+le symbole à dessein. Grâce à l'extrême flexibilité des @emph{markups},
+vous pourrez parvenir à bien des choses -- voir à ce sujet
+@ref{Éléments graphiques dans du texte formaté}.
+
+C'est la technique employée ici, où l'une des têtes de note est
+remplacée par une croix inscrite dans un cercle@tie{}:
+
+@lilypond[verbatim,quote]
+XinO = {
+ \once \override NoteHead #'stencil = #ly:text-interface::print
+ \once \override NoteHead #'text = \markup {
+ \combine
+ \halign #-0.7 \draw-circle #0.85 #0.2 ##f
+ \musicglyph #"noteheads.s2cross"
+ }
+}
+\relative c'' {
+ a a \XinO a a
+}
+@end lilypond
+
+Tous les glyphes de la fonte Feta sont accessibles à l'aide de la
+commande de @emph{markup} @code{\musicglyph} -- voir
+@ref{La fonte Feta}.
-@untranslated
+@c TODO Add inserting eps files or ref to later
+
+@c TODO Add inserting Postscript or ref to later
+
+
+@seealso
+Manuel de notation :
+@ref{Text markup commands},
+@ref{Éléments graphiques dans du texte formaté},
+@ref{La fonte Feta},
+@ref{Mise en forme du texte}.
@node Modification de l'allure des éléments
* Modification des liaisons::
@end menu
+
@node Modification des liaisons
@unnumberedsubsubsec Modification des liaisons
-@translationof Modifying ties and slurs @c external
+@translationof Modifying ties and slurs
+
+@cindex liaison, modification
+@cindex Bézier, points de contrôle d'une courbe
+@cindex points de contrôle, courbe de Bézier
+
+Les liaisons, qu'elles soient de prolongation, d'articulation ou de
+phrasé, sont dessinées sous la forme de courbes de Bézier de degré
+trois. Lorsque l'aspect de la liaison automatiquement calculé n'est pas
+satisfaisant, il peut être modifié manuellement, en fournissant
+explicitement les quatre points de contrôle qui permettront de définir
+cette courbe.
+
+Quatre points définissent une courbe de Bézier cubique. Les premier et
+quatrième points sont les points de départ et d'arrivée de la
+courbe@tie{}; les deux autres points de contrôle -- P1 et P2 -- en
+détermineront l'allure. La courbe se trace en partant du point P0, en
+se dirigeant vers P1 et en arrivant au point P3 selon la direction
+@w{P2-P3}. La courbe est à l'intérieur de l'enveloppe convexe des
+points de contrôle.
+
+Voici par exemple une liaison de prolongation dont l'allure n'est pas
+des plus heureuses, même en optant pour un @code{\tieDown}.
+
+@lilypond[verbatim,quote,relative=1]
+<<
+ { e1~ e }
+\\
+ { r4 <g c,> <g c,> <g c,> }
+>>
+@end lilypond
+
+L'un des moyens d'améliorer cette liaison consiste à modifier
+manuellement ses quatre points de contrôle.
+
+Les coordonnées des points de contrôle sont données en unités d'espace
+de portée. L'abscisse est relative au point de référence de la note de
+départ de la liaison@tie{}; l'ordonnée est relative à la ligne médiane
+de la portée. Les différentes coordonnées sont entrées sous la forme
+d'une liste de quatre paires de nombres décimaux (ou nombres réels).
+L'une des manières de procéder consiste à tout d'abord estimer les
+coordonnées des deux extrémités puis, par tâtonnement, déterminer les
+deux points intermédiaires.
+
+Remarque intéressante au sujet des courbes@tie{}: une courbe sera
+symétrique si ses points de contrôle sont symétriques. L'une des
+propriétés avantageuses des courbes de Bézier est que leur
+transformation -- déplacement, rotation ou échelonnement -- est
+réalisable en simplement corrigeant de manière identique ses points de
+contrôle.
+
+Pour l'exemple qui nous occupe, l'adaptation suivante nous permet
+d'obtenir un résultat plutôt satisfaisant. Notez bien l'endroit où
+cette adaptation est stipulée@tie{}: juste avant la note de départ de la
+liaison.
+
+@lilypond[verbatim,quote,relative=1]
+<<
+ {
+ \once \override Tie
+ #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
+ e1 ~ e
+ }
+\\
+ { r4 <g c,> <g c,> <g c,> }
+>>
+@end lilypond
+
+@knownissues
+Lorsque plusieurs liaisons, quelle qu'en soit la nature, commencent au
+même moment, jouer sur la propriété @code{control-points} est
+impossible, et la commande @code{\tweak} inefficace. Vous pouvez
+néanmoins influer sur la propriété @code{tie-configuration} de l'objet
+@code{TieColumn} pour déterminer la ligne de départ et l'orientation.
+
+@seealso
+Référence des propriétés internes :
+@rinternals{TieColumn}.
+
+
+@node Conteneurs requalifiants
+@subsection Conteneurs requalifiants
+@translationof Unpure-pure containers
+
+@cindex Scheme, pure containers
+@cindex Scheme, unpure containers
+@cindex pure containers, Scheme
+@cindex unpure containers, Scheme
+@cindex espacement horizontal, affinage
+
+Les conteneurs requalifiants permettent de faciliter le calcul des
+espacements en cas de modification du @emph{Y-axis} -- plus
+particulièrement les composantes @code{Y-offset} et @code{Y-extent} -- à
+l'aide d'une fonction scheme en lieu et place de valeurs.
+
+L'envergure verticale (@code{Y-extent}) de certains objets dépend de la
+propriété @code{stencil}@tie{}; jouer sur leur stencil requiert alors une
+intervention supplémentaire au niveau du @code{Y-extent} à l'aide d'un
+conteneur transitoire. Lorsqu'une fonction affecte un @code{Y-offset} ou
+un @code{Y-extent}, cela déclenche la détermination des sauts de ligne
+de manière anticipée dans la séquence des traitements. Il en résulte
+que cette opération n'est en fait pas exécutée@tie{}; elle renvoie
+habituellement @code{0} ou @code{'(0 . 0)}, ce qui peut engendrer des
+collisions. Une fonction @qq{pure} évitera d'avorter la construction
+des propriétés ou objets, qui de ce fait verront leurs arguments liés à
+la verticalité (@code{Y-axis}) correctement évalués.
+
+Il existe actuellement une trentaine de fonctions que l'on peut
+qualifier de @qq{pures}. Le recours à un conteneur transitoire permet
+de requalifier une fonction de telle sorte qu'elle soit reconnue comme
+@qq{pure} et soit donc évaluée @strong{avant} détermination des sauts de
+ligne -- l'espacement horizontal sera de fait ajusté en temps et en heure.
+La fonction @qq{impure} sera ensuite évaluée @strong{après} le
+positionnement des sauts de ligne.
+
+@warning{Il n'est pas toujours facile d'avoir l'assurance qu'une
+fonction soit qualifiée de @qq{pure}@tie{}; aussi nous vous recommandons
+d'éviter d'utiliser les objets @code{Beam} or @code{VerticalAlignment}
+lorsque vous désirez en créer une.}
+
+Un conteneur requalifiant se construit selon la syntaxe
+
+@code{(ly:make-unpure-pure-container f0 f1)}
+
+où @code{f0} est une fonction prenant @var{n} arguments (@var{n >= 1}),
+le premier devant être l'objet en question@tie{}; il s'agit de la
+fonction dont le résultat sera réutilisé. @var{f1} est la fonction qui
+sera qualifiée de @qq{pure}. Elle prend @var{n + 2} arguments, le
+premier devant être lui aussi l'objet en question, et les second et
+troisième étant respectivement les @qq{point de départ} (@var{start}) et
+@qq{point d'arrivée} (@var{end}).
+
+@var{start} et @var{end} sont dans tous les cas des valeurs fictives qui
+trouveront leur utilité dans le cas d'objets de type @code{Spanner},
+tels les soufflets (@code{Hairpin}) ou barres de ligature (@code{Beam}),
+en retournant les différentes estimations de hauteur basées sur leurs
+début et fin d'extension.
+
+Viennent ensuite les autres arguments de la fonction initiale @code{f0}
+-- autrement dit aucun si @var{n = 1}.
+
+Les résultats de la deuxième fonction (@code{f1}) permettent une
+approximation des valeurs qui seront ensuite utilisées par la fonction
+initiale aux fins d'ajustement lors des phases ultérieures d'espacement.
+
+@lilypond[verbatim,quote,ragged-right]
+#(define (square-line-circle-space grob)
+(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
+ (notename (ly:pitch-notename pitch)))
+ (if (= 0 (modulo notename 2))
+ (make-circle-stencil 0.5 0.0 #t)
+ (make-filled-box-stencil '(0 . 1.0)
+ '(-0.5 . 0.5)))))
+
+squareLineCircleSpace = {
+ \override NoteHead #'stencil = #square-line-circle-space
+}
+
+smartSquareLineCircleSpace = {
+ \squareLineCircleSpace
+ \override NoteHead #'Y-extent =
+ #(ly:make-unpure-pure-container
+ ly:grob::stencil-height
+ (lambda (grob start end) (ly:grob::stencil-height grob)))
+}
+
+\new Voice \with { \remove "Stem_engraver" }
+\relative c'' {
+ \squareLineCircleSpace
+ cis4 ces cisis c
+ \smartSquareLineCircleSpace
+ cis4 ces cisis c
+}
+@end lilypond
+
+La première mesure de l'exemple ci-dessus ne fait pas appel à un
+conteneur requalifiant@tie{}; le moteur d'espacement n'a donc aucune
+connaissance de la largeur des têtes de note et ne peut empêcher
+qu'elles chevauchent les altérations. Dans la deuxième mesure, par
+contre, le recours à un conteneur requalifiant informe le moteur
+d'espacement de la largeur des têtes de note@tie{}; les collisions sont
+alors évitées du fait de l'espace réservé à chacune des têtes.
+
+Lorsqu'il s'agit de calculs simples, les fonctions, tant pour la partie
+@qq{pure} que pour la partie @qq{impure}, peuvent être identiques au
+détail près du nombre d'arguments utilisés ou du domaine d'intervention.
+
+@warning{Le fait de qualifier une fonction de @qq{pure} alors qu'elle ne
+l'est pas peut générer des résultats imprévisibles.}
+
+
+@node Utilisation de fonctions musicales
+@section Utilisation de fonctions musicales
+@translationof Using music functions
+
+@c TODO -- add @seealso, etc. to these subsections
+
+Une adaptation ou un affinage qui devient récurrent parce que doit
+s'appliquer à différentes expressions musicales peut faire l'objet d'une
+@emph{fonction musicale}. Nous ne traiterons ici que des fonctions de
+@emph{substitution}, dont le but est de substituer une variable en un
+bout de code LilyPond. D'autres fonctions, plus complexes, sont
+abordées au chapitre @rextend{Fonctions musicales}.
+
+@menu
+* Syntaxe d'une fonction de substitution::
+* Exemples de fonction de substitution::
+@end menu
+
+
+@node Syntaxe d'une fonction de substitution
+@subsection Syntaxe d'une fonction de substitution
+@translationof Substitution function syntax
+
+La rédaction d'une fonction chargée de substituer du code LilyPond à une
+variable est chose relativement aisée. Une telle fonction est de la forme
+
+@example
+fonction =
+#(define-music-function
+ (parser location @var{arg1} @var{arg2} @dots{})
+ (@var{type1?} @var{type2?} @dots{})
+ #@{
+ @var{@dots{}musique@dots{}}
+ #@})
+@end example
+
+@noindent
+où
+
+@multitable @columnfractions .33 .66
+@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}}
+doit renvoyer @code{#t}.
+
+@item @code{@var{@dots{}musique@dots{}}}
+@tab du code LilyPond tout ce qu'il y a de plus ordinaire, avec des
+@code{$} (là où seule une construction LilyPond est autorisée) et des
+@code{#} (lorsqu'il s'agit d'une valeur en Scheme ou d'un argument de
+fonction musicale) pour référencer les arguments (par ex. @samp{#arg1}).
+@end multitable
+
+Les arguments @code{parser} et @code{location} sont obligatoires@tie{};
+ils sont utilisés dans certaines situations évoluées, comme indiqué dans
+le manuel d'extension des fonctionnalités à au chapitre
+@rextend{Fonctions musicales}. Assurez-vous bien de ne pas les omettre
+dans vos fonctions de substitution.
+
+La liste des types de prédicat est elle aussi obligatoire. Voici
+quelques uns des types de prédicat les plus utilisés dans les fonctions
+musicales@tie{}:
+
+@example
+boolean?
+cheap-list? @emph{(au lieu de }@q{list?}@emph{, pour accélérer le traitement)}
+ly:duration?
+ly:music?
+ly:pitch?
+markup?
+number?
+pair?
+string?
+symbol?
+@end example
+
+@noindent
+Une liste plus fournie est disponible à l'annexe
+@ref{Types de prédicats prédéfinis}. Vous pouvez par ailleurs définir
+vos propres types de prédicat.
+
+
+@seealso
+
+Manuel de notation :
+@ref{Types de prédicats prédéfinis}.
+
+Manuel d'extension :
+@rextend{Fonctions musicales}.
+
+Fichiers d'initialisation :
+@file{lily/music-scheme.cc},
+@file{scm/c++.scm},
+@file{scm/lily.scm}.
+
+
+@node Exemples de fonction de substitution
+@subsection Exemples de fonction de substitution
+@translationof Substitution function examples
+
+La présente rubrique regroupe quelques exemples de fonction
+substitutive. Le propos est ici d'illustrer les possibilités qu'offrent
+les fonctions de substitution simple.
+
+Dans ce premier exemple, nous définissons une fonction dans le but de
+simplifier le réglage du décalage d'une annotation (un
+@code{TextScript}).
+
+@lilypond[quote,verbatim,ragged-right]
+padText =
+#(define-music-function
+ (parser location padding)
+ (number?)
+ #{
+ \once \override TextScript #'padding = #padding
+ #})
+
+\relative c''' {
+ c4^"piu mosso" b a b
+ \padText #1.8
+ c4^"piu mosso" d e f
+ \padText #2.6
+ c4^"piu mosso" fis a g
+}
+@end lilypond
+
+Nous pouvons utiliser autre chose que des nombres au sein d'une
+fonction, y compris une expression musicale@tie{}:
+
+@c TODO: use a better example (the music argument is redundant).
+
+@lilypond[quote,verbatim,ragged-right]
+custosNote =
+#(define-music-function
+ (parser location note)
+ (ly:music?)
+ #{
+ \once \override Voice.NoteHead #'stencil =
+ #ly:text-interface::print
+ \once \override Voice.NoteHead #'text =
+ \markup \musicglyph #"custodes.mensural.u0"
+ \once \override Voice.Stem #'stencil = ##f
+ $note
+ #})
+
+\relative c' { c4 d e f \custosNote g }
+@end lilypond
+
+Une fonction de substitution peut traiter plusieurs argument@tie{}:
+
+@lilypond[quote,verbatim,ragged-right]
+tempoPadded =
+#(define-music-function
+ (parser location padding tempotext)
+ (number? string?)
+ #{
+ \once \override Score.MetronomeMark #'padding = #padding
+ \tempo \markup { \bold #tempotext }
+ #})
+
+\relative c'' {
+ \tempo \markup { "Low tempo" }
+ c4 d e f g1
+ \tempoPadded #4.0 #"High tempo"
+ g4 f e d c1
+}
+@end lilypond
-@untranslated
+@c TODO: add appropriate @@ref's here.
projects / lilypond.git / blobdiff