@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-

@ignore
   Translation of GIT committish: 18cf09c1f24d22eeb0cdc187dec0af734d60cfc8

   When revising a translation, copy the HEAD committish of the
   version that you are working on.  For details, see the Contributors'
   Guide, node Updating translation committishes..
@end ignore

@c \version "2.19.22"

@c Translators: Valentin Villenave, Nicolas Klutchnikoff, Damien Heurtebise
@c Translation checkers: J.-C. Malahieude, John Mandereau
@c Translation status: post-GDP

@node Tweaking output
@chapter Retouche de partition

Ce chapitre indique comment modifier le résultat obtenu.
LilyPond offre de nombreuses possibilités de réglages, permettant
théoriquement de modifier chaque élément de votre partition.


@node Tweaking basics
@section Retouches élémentaires

LilyPond regroupe sous le terme de « retouches » (@emph{tweaks} en
anglais) les différents moyens dont dispose l'utilisateur pour
intervenir sur l'interprétation du fichier d'entrée et pour modifier
l'apparence du fichier de sortie. Certaines retouches sont très simples
à mettre en œuvre ; d'autres sont plus complexes. Mais à elles toutes,
elles permettent d'obtenir tout ce qu'on veut en matière de musique
imprimée.

Dans ce chapitre, nous traitons des concepts de base nécessaires pour
comprendre l'art de la retouche. Puis nous présentons de nombreuses
commandes déjà prêtes, qu'il suffit de recopier pour obtenir un résultat
identique dans vos partitions ; nous en profitons pour expliquer comment
ces commandes ont été construites, si bien que vous pouvez apprendre par
la même occasion à développer vos propres retouches.

Avant de vous lancer dans ce chapitre, il peut être utile de revoir la
section @ref{Contexts and engravers}, dans la mesure où les contextes,
graveurs et autres propriétés qui y sont décrits, sont indispensables
pour comprendre et construire les retouches.


@node Objects and interfaces
@subsection Objets et interfaces

@cindex objet
@cindex grob
@cindex spanner
@cindex extenseur
@cindex interface
@cindex propriétés des objets
@cindex objet, propriétés
@cindex objet de rendu
@cindex rendu, objets de

Toute retouche implique que l'on modifie les opérations internes et les
structures du programme LilyPond. Nous allons donc, pour commencer,
présenter certains termes qui servent à décrire ces opérations internes
et ces structures.

Le terme « Objet » est un terme générique qui fait référence à une
multitude de structures internes mises en place par LilyPond durant la
compilation d'un fichier d'entrée. Ainsi, quand une commande du type
@code{\new Staff} apparaît, un nouvel objet du type @code{Staff} est
créé. Cet objet @code{Staff} contient alors toutes les propriétés
associées à cette portée, par exemple son nom et son armure, ainsi que
le détail des graveurs qui ont été désignés pour fonctionner dans ce
contexte de portée. Certains objets peuvent contenir les propriétés de
tous les autres contextes, comme les objets @code{Voice}, les objets
@code{Score}, les objets @code{Lyrics} ; d'autres se rapportent à tous
les éléments de notation, comme les barres de mesure, les liaisons, les
nuances, etc. Chaque objet dispose de son propre échantillon de valeurs
pour le réglage des propriétés.

Certains types d'objet portent des noms spécifiques. Les objets qui se
rapportent à des éléments de notation sur le fichier de sortie, comme
les notes, les hampes, les liaisons de phrasé ou de prolongation, les
doigtés, les clefs, etc. sont appelés « objets de rendu » ; ils sont
aussi connus sous le nom « d'objets graphiques » (en anglais :
@emph{Graphical objects} ou @dfn{grobs} pour faire court). Ce sont bien
des objets au sens générique ci-dessus et, en tant que tels, ils
reçoivent des propriétés qui leur sont associées, comme leur position,
leur taille, leur couleur, etc.

Certains objets de rendu, comme les liaisons de phrasé, les soufflets de
crescendo, les marques d'octaviation et beaucoup d'autres @emph{grobs},
ont pour particularité de ne pas se situer à un seul et unique endroit
-- ils ont un point de départ, un point d'arrivée, et éventuellement
d'autres propriétés relatives à leur forme. Ces objets avec une forme
étendue sont appelés des bandeaux (@dfn{spanners} en anglais).

Les bandeaux ne peuvent être retouchés après leur création. Ceci inclut
les @code{StaffSymbol} et @code{LedgerLineSpanner} qui se déroulent tout
au long de la partition -- à moins qu'ils n'aient été rompus par une
commande @code{\stopStaff} puis créés de nouveau à l'aide de la commande
@code{\startStaff}.

De plus existent certains @emph{grobs} que l'on peut qualifier
« d'abstraits ». Ils n'ont pas pour fonction intrinsèque d'imprimer
quelque chose, mais plutôt de collecter, positionner et gérer d'autres
objets. Citons, parmi les plus courants, @code{DynamicLineSpanner},
@code{BreakAlignment}, @code{NoteColumn}, @code{VerticalAxisGroup} ou
@code{NonMusicalPaperColumn}. Nous verrons plus avant comment les
utiliser.

Il reste à expliquer ce que sont les @dfn{interfaces}. De nombreux
objets, qui peuvent être très différents les uns des autres, ont pour
point commun de devoir être compilés simultanément. Par exemple, tous
les @emph{grobs} ont une couleur, une taille, une position, etc. et
toutes ces propriétés sont compilées simultanément durant
l'interprétation du fichier d'entrée par LilyPond. Pour alléger ces
opérations internes, ces actions et propriétés communes sont regroupées
en un objet appelé @code{grob-interface}. Il existe beaucoup d'autres
regroupements de propriétés communes dans le genre de celui-ci, chacun
portant un nom qui se termine par @code{interface}. En tout, on en
compte plus d'une centaine. Nous verrons plus loin en quoi c'est
intéressant et utile pour l'utilisateur.

Ainsi s'achève le tour des principaux termes relatifs aux objets
que nous serons amenés à utiliser dans ce chapitre.


@node Naming conventions of objects and properties
@subsection Conventions de nommage des objets et propriétés

@cindex conventions de nommage des objets
@cindex conventions de nommage des propriétés
@cindex objets, conventions de nommage
@cindex propriétés, conventions de nommage

Nous avons eu un aperçu, dans @ref{Contexts and engravers}, de la façon
de nommer les objets. Voici maintenant une liste de référence des types
d'objets et de propriétés les plus courants, avec leurs conventions de
nommage et quelques exemples de cas concrets. La lettre @var{A}
représente n'importe quel caractère alphabétique majuscule, et les
lettres @var{aaa} un nombre indéterminé de caractères alphabétiques
minuscules. Les autres caractères sont à prendre tels qu'ils se
présentent.

@indentedblock
@multitable {Layout Object Properties} {@code{Aaaa} or @code{AaaaAaaaAaaa}} {@code{break-aligned-interface}}
@headitem Type d'objet/propriété
  @tab Convention de nommage
  @tab Exemples
@item Contextes
  @tab @code{Aaaa} ou @code{AaaaAaaaAaaa}
  @tab @code{Staff}, @code{GrandStaff}
@item Objets de rendu
  @tab @code{Aaaa} ou @code{AaaaAaaaAaaa}
  @tab @code{Slur}, @code{NoteHead}
@item Graveurs
  @tab @code{Aaaa_aaa_engraver}
  @tab @code{Clef_engraver},@* @code{Note_heads_engraver}
@item Interfaces
  @tab @code{aaa-aaa-interface}
  @tab @code{grob-interface}, @code{break-aligned-interface}
@item Propriétés de contexte
  @tab @code{aaa} ou @code{aaaAaaaAaaa}
  @tab @code{alignAboveContext}, @code{skipBars}
@item Propriétés d'objet de rendu
  @tab @code{aaa} ou @code{aaa-aaa-aaa}
  @tab @code{direction},@* @code{beam-thickness}
@end multitable
@end indentedblock

Comme nous le verrons bientôt, les propriétés des différents types
d'objet sont modifiées par des commandes différentes, si bien qu'il est
bon de savoir reconnaître le type d'un objet ou d'une propriété en
fonction de son nom.

@morerefs
Manuel de notation :
@rnotationnamed{Naming conventions, Conventions de nommage},
@rnotationnamed{Modifying properties, Modification de propriétés}.
@endmorerefs


@need 1500
@node Tweaking methods
@subsection Méthodes de retouche

@cindex retouches, méthodologie
@cindex méthodes de retouche


@node The override command
@unnumberedsubsubsec La commande @code{\override}

@funindex \override

Dans @ref{Modifying context properties} et dans @ref{Adding and removing
engravers}, nous avons déjà rencontré les commandes @code{\set} et
@code{\with}, qui servent à changer les propriétés des
@strong{contextes} et à supprimer ou ajouter des @strong{graveurs}.
Voici maintenant d'autres commandes plus importantes.

La commande pour changer les propriétés des @strong{objets de rendu} est
@code{\override}. Du fait que cette commande modifie en profondeur les
propriétés internes de LilyPond, sa syntaxe n'est pas aussi simple que
pour les commandes vues précédemment. Elle a besoin de savoir avec
précision quelle est la propriété à modifier, pour quel objet et dans
quel contexte, et quelle doit être sa nouvelle valeur. Voyons de quoi il
retourne.

La syntaxe générale de cette commande est :

@example
\override @var{Contexte}.@var{ObjetDeRendu}.@var{propriété-rendu} = @var{valeur}
@end example

@noindent
Elle attribue à la propriété appelée @var{propriété-rendu}, associée à
l'objet @var{ObjetDeRendu}, appartenant lui-même au contexte
@var{Contexte}, une valeur @var{valeur}.

Le contexte @var{Contexte} peut être omis (c'est généralement le cas)
quand il n'y a pas d'ambiguïté et qu'il s'agit d'un contexte de très bas
niveau, comme @code{Voice}, @code{ChordNames} ou @code{Lyrics}. Dans les
exemples qui suivent, le contexte sera très souvent omis. Nous verrons
plus tard dans quelles circonstances il doit impérativement être
indiqué.

Les sections ci-dessous traitent largement des propriétés et de leurs
valeurs -- @pxref{Types of properties} -- mais, pour illustrer la mise
en forme et l'utilisation de ces commandes, nous nous limiterons à
n'employer que quelques propriétés et valeurs simples, facilement
compréhensibles.

LilyPond reconnaît comme expression primaire les éléments musicaux tels
que les notes et durées, ainsi que les chaînes de caractères et
annotations (les @emph{markups}). D'autres expressions spécifiques comme
les symboles et listes sont gérées en « mode Scheme », mode appelé en
faisant précéder une valeur par un @samp{#}. Quant aux nombres, ils
doivent être précédés d'un @samp{#} lorsqu'ils sont utilisés en argument
à une fonction de @emph{markup} -- autrement dit dans un bloc
@code{\markup}.@footnote{Notez cependant que, pour LilyPond, un nombre
@strong{doit commencer} par un chiffre ou un signe moins suivi d'un
chiffre dès qu'on n'est pas en mode Scheme. En d'autre termes,
@samp{0.2} ou @samp{-0.2} sont des nombres valides, alors que @samp{.2}
et @samp{-.2} ne le sont pas. Si cela était vraiment nécessaire, on
pourrait toutefois écrire @samp{#.2} ou @samp{#-.2} -- Scheme prend en
charge bien d'autres représentations des nombres.}

Pour de plus amples informations quant au mode Scheme, consultez
@rextendnamed{LilyPond Scheme syntax, Syntaxe Scheme dans LilyPond}.

La commande @code{\override} est la plus fréquemment utilisée pour faire
des retouches, et pratiquement tout le reste de ce chapitre aura pour
but de montrer, à travers des exemples, comment l'utiliser. L'exemple
ci-dessous change la couleur des têtes de notes :

@cindex couleur, exemple d'utilisation de la propriété
@cindex @code{NoteHead}, exemple de dérogation

@lilypond[quote,ragged-right,verbatim]
\relative {
  c'4 d
  \override NoteHead.color = "red"
  e4 f |
  \override NoteHead.color = "green"
  g4 a b c |
}
@end lilypond


@node The revert command
@unnumberedsubsubsec La commande @code{\revert}

@funindex \revert

Une fois qu'elle a été modifiée, la propriété conserve sa nouvelle
valeur jusqu'à ce qu'elle soit à nouveau modifiée ou qu'elle rencontre
la commande @code{\revert}. La commande @code{\revert} obéit à la
syntaxe ci-dessous et ramène la valeur de la propriété à sa valeur
d'origine. Attention : dans le cas où plusieurs @code{\override} ont été
employés, il ne s'agit pas de la valeur précédente mais bien de la
valeur par défaut.@footnote{Le comportement de @code{\revert} peut être
modifié à l'aide d'un @code{\temporary \override} -- voir
@rextendnamed{Intermediate substitution functions, Fonctions de
substitution intermédiaires}.}

@example
\revert @var{Contexte}.@var{ObjetDeRendu}.@var{propriété-de-rendu}
@end example

Tout comme pour la commande @code{\override}, la mention du
@var{Contexte} est souvent facultative. Elle sera omise dans de nombreux
exemples ci-dessous. Voici un exemple qui ramène la couleur des deux
dernières notes à leur valeur par défaut :

@cindex couleur, exemple d'utilisation de la propriété
@cindex @code{NoteHead}, exemple de dérogation

@lilypond[quote,ragged-right,verbatim]
\relative {
  c'4 d
  \override NoteHead.color = "red"
  e4 f |
  \override NoteHead.color = "green"
  g4 a
  \revert NoteHead.color
  b4 c |
}
@end lilypond


@node The once prefix
@unnumberedsubsubsec Le préfixe @code{\once}

@funindex \once

Les commandes @code{\override}, @code{\revert}, @code{\set} et
@code{\unset} peuvent supporter le préfixe @code{\once}. Celui-ci a pour
fonction de n'appliquer la commande considérée qu'à l'instant musical en
cours, avant que la propriété ne reprenne sa valeur antérieure -- qui
n'est pas forcément la valeur par défaut lorsqu'un autre
@code{\override} ou @code{\set} est toujours effectif. Toujours à partir
du même exemple, il est possible de ne changer la couleur que d'une
seule note :

@cindex couleur, exemple d'utilisation de la propriété
@cindex @code{NoteHead}, exemple de dérogation

@lilypond[quote,ragged-right,verbatim]
\relative {
  c'4 d
  \override NoteHead.color = "red"
  e4 f |
  \once \override NoteHead.color = "green"
  g4 a
  \once \revert NoteHead.color
  b c |
  \revert NoteHead.color
  f2 c |
}
@end lilypond

Le préfixe @code{\once} peut s'utiliser avec de nombreuses commandes
prédéfinies pour en limiter les effets à un seul instant musical :

@lilypond[quote,verbatim]
\relative {
  c'4( d)
  \once \slurDashed
  e4( f) |
  g4( a)
  \once \hideNotes
  b( c) |
}
@end lilypond


@node The tweak and offset commands
@unnumberedsubsubsec Les commandes @code{\tweak} et @code{\offset}

@cindex @emph{tweak}, commande
@cindex @emph{offset}, commande

@funindex \tweak
@funindex \offset

Les dernières commandes disponibles avec LilyPond pour les retouches
sont @code{\tweak} et @code{\offset}. Elles servent à changer les
propriétés d'objets qui surviennent simultanément dans la musique, comme
par exemple les notes d'un accord. La commande @code{\override}
modifierait toutes les notes de l'accord, tandis que @code{\tweak}
permet de ne modifier que l'élément immédiatement suivant dans la chaîne
de saisie.

La commande @code{\offset} peut elle aussi s'utiliser en lieu et place
de @code{\override}. Elle accepte aussi d'autres formes de syntaxe. Voir
@rnotationnamed{The offset command, La commande @code{\offset}} pour
plus de détails.

Voici un exemple. Supposons que nous voulions changer la taille de la
tête de note du milieu (le mi) dans un accord de do majeur. Voyons
d'abord ce que donnerait @code{\once \override} :

@cindex @code{font-size}, exemple d'utilisation de la propriété
@cindex @code{NoteHead}, exemple de dérogation

@lilypond[quote,ragged-right,verbatim]
\relative {
  <c' e g>4
  \once \override NoteHead.font-size = -3
  <c e g>4
  <c e g>4
}
@end lilypond

Nous voyons que @code{\override} modifie @strong{toutes} les têtes de
notes de l'accord, car toutes les notes de l'accord surviennent au même
@strong{instant musical} et que la fonction de @code{\once} est de faire
porter la modification sur tous les objets du type spécifié qui
surviennent au même instant musical, comme le fait la commande
@code{\override} elle-même.

Les commandes @code{\tweak} et @code{\offset} opèrent différemment.
Elles agissent sur l'élément immédiatement suivant dans la chaîne de
saisie. Dans leur forme la plus simple, elles ne fonctionnent que sur
les objets créés directement à partir de l'élément suivant dans la
chaîne de saisie, c'est-à-dire essentiellement des têtes de notes et des
articulations.

Pour reprendre notre exemple, la taille de la note du milieu d'un
accord peut être modifiée de cette manière :

@cindex @code{font-size}, exemple d'utilisation de la propriété
@cindex @code{\tweak}, exemple

@lilypond[quote,ragged-right,verbatim]
\relative {
  <c' e g>4
  <c \tweak font-size -3 e g>4
}
@end lilypond

Essayons maintenant de modifier le positionnement vertical d'un symbole
@code{\breathe}. Par défaut, LilyPond calcule automatiquement un
espacement vertical par rapport à la ligne médiane. Si nous voulions le
remonter de deux unités, par exemple, @code{\offset} est la commande
qu'il convient d'utiliser. Avec un @code{\tweak}, le positionnement
correct ne ne s'obtiendrait qu'en procédant à tâtons.

@cindex @code{\offset}, exemple

@lilypond[quote,ragged-right,verbatim]
\relative c'' {
  c4
  \breathe
  c4
  \offset Y-offset 2 \breathe
  c2
  \tweak Y-offset 4 \breathe
}
@end lilypond

De toute évidence, @code{\offset} n'est effectif que pour traiter des
valeurs de type numérique. Il existe d'autres restrictions à ce qui peut
se modifier, comme mentionné dans @rnotationnamed{The offset command, La
commande @code{\offset}}.

Vous noterez que la syntaxe de @code{\tweak} et @code{\offset} est
différente de celle de la commande @code{\override}. Ni le contexte, ni
l'objet n'ont besoin d'être spécifiés ; au contraire, cela produirait
une erreur si on le faisait. Tous deux sont sous-entendus par l'élément
suivant dans la chaîne de saisie. Il n'est pareillement pas nécessaire
d'insérer un signe égal. La syntaxe générale des commandes @code{\tweak}
et @code{\offset} est donc, tout simplement :

@example
\tweak @var{propriété-de-rendu} @var{valeur}
\offset @var{propriété-de-rendu} @var{valeur}
@end example

@code{\tweak} et @code{\offset} peuvent aussi s'utiliser quand, dans une
série d'articulations, on veut n'en modifier qu'une seule. Ainsi :

@cindex couleur, exemple d'utilisation de la propriété
@cindex @code{\tweak}, exemple

@lilypond[quote,fragment,ragged-right,verbatim]
a'4^"Black"
  -\tweak color "red" ^"Red"
  -\tweak color "green" _"Green"
@end lilypond

@noindent
Attention : les commandes @code{\tweak} et @code{\offset} doivent être
précédées d'une marque d'articulation, comme si elles-mêmes étaient des
articulations. Dans la cas de multiples positionnements forcés --
@samp{^} ou @samp{_} --, celui le plus à gauche aura préséance puisqu'il
sera appliqué en dernier.

@cindex @code{\tweak} et altération
@cindex @code{\tweak} et objet de rendu spécifique

Les objets tels que hampes et altérations seront créés postérieurement à
l'événement qui survient. L'utilisation des commandes @code{\tweak} ou
@code{\offset} sur de tels objets indirectement créés peut se faire en
nommant explicitement l'objet de rendu, si tant est que LilyPond puisse
remonter jusqu'à l'événement originel :

@lilypond[quote,fragment,ragged-right,verbatim]
<\tweak Accidental.color "red"   cis''4
 \tweak Accidental.color "green" es''
 g''>
@end lilypond

Cette forme développée des commandes @code{\tweak} et @code{\offset}
correspond à :

@example
\tweak @var{objet-de-rendu}.@var{propriété-de-rendu} @var{valeur}
\offset @var{objet-de-rendu}.@var{propriété-de-rendu} @var{valeur}
@end example

@cindex n-olets imbriqués
@cindex triolets imbriqués
@cindex crochet de n-olet
@cindex n-olet, crochet
@cindex triolet, crochet
@cindex @code{TupletBracket}

Quand plusieurs n-olets sont imbriqués et commencent au même instant
musical, c'est encore la commande @code{\tweak} qui est utilisée pour
changer l'apparence de l'un d'entre eux. Dans l'exemple suivant, le long
crochet de n-olet et le premier des trois crochets courts commencent au
même instant musical ; une commande @code{\override} s'appliquerait donc
à la fois aux deux. En revanche, @code{\tweak} permet de les dissocier.
La première commande @code{\tweak} indique que le long crochet doit être
placé au-dessus des notes, et la seconde indique que le coefficient de
n-olet doit être imprimé en rouge sur le premier crochet de triolet
court.

@cindex @code{\tweak}, exemple
@cindex @code{direction}, exemple d'utilisation de la propriété
@cindex couleur, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative c'' {
  \tweak direction #up
  \tuplet 3/4 {
    \tweak color "red"
    \tuplet 3/2 { c8[ c c] }
    \tuplet 3/2 { c8[ c c] }
    \tuplet 3/2 { c8[ c c] }
  }
}
@end lilypond

Si les n-olets imbriqués ne commencent pas au même moment, leur
apparence peut alors être modifiée de la façon habituelle, avec la
commande @code{\override} :

@cindex @code{text}, exemple d'utilisation de la propriété
@cindex @code{tuplet-number}, exemple de fonction
@cindex @code{transparent}, exemple d'utilisation de la propriété
@cindex @code{TupletNumber}, exemple de dérogation

@lilypond[quote,ragged-right,verbatim]
\relative {
  \tuplet 3/2 { c'8[ c c] }
  \once \override TupletNumber.text =
    #tuplet-number::calc-fraction-text
  \tuplet 3/2 {
    c8[ c]
    c8[ c]
    \once \override TupletNumber.transparent = ##t
    \tuplet 3/2 { c8[ c c] }
    \tuplet 3/2 { c8[ c c] }
  }
}
@end lilypond

@morerefs
Manuel de notation :
@rnotationnamed{Tweak and single,
Les commandes @code{\tweak} et @code{\single}},
@rnotationnamed{The offset command, La commande @code{\offset}}.
@endmorerefs


@node The single prefix
@unnumberedsubsubsec Le préfixe @code{\single}

@funindex \single

@cindex @emph{tweak} généré par @code{\override}

Supposons que nous voulions mettre en exergue certaines têtes de note --
plus grosses et en rouge -- et, pour nous simplifier la vie, que nous
avons réalisé un fonction à ce effet :

@lilypond[quote,verbatim]
emphNoteHead = {
  \override NoteHead.color = "red"
  \override NoteHead.font-size = 2
}
\relative {
  c''4 a \once \emphNoteHead f d |
}
@end lilypond

Le préfixe @code{\once} fonctionne à merveille dans le cas d'une note
isolée ou de l'intégralité d'un accord, mais ne permet pas de souligner
individuellement l'une des notes d'un accord. Nous avons vu comment un
@code{\tweak} permet d'y arriver -- voir @ref{The tweak and offset
commands}. Un @code{\tweak} ne peut toutefois pas s'utiliser dans une
fonction ; un @code{\single} permet d'appliquer la fonction une seule
fois :

@lilypond[quote,verbatim]
emphNoteHead = {
  \override NoteHead.color = "red"
  \override NoteHead.font-size = 2
}
\relative {
   <c'' a \single \emphNoteHead f d>4
}
@end lilypond

En résumé, l'instruction @code{\single} convertit les instructions
@code{\override} en @code{\tweak} de telle sorte que lorsque plusieurs
objets se trouvent en un même point du temps musical, comme la tête des
notes formant un accord, @code{\single} n'en affectera qu'une seule,
celle générée par l'expression musicale qui vient juste après,
contrairement à un @code{\once} qui en affectera tous les objets.

Cette utilisation de @code{\single} permet d'appliquer individuellement
n'importe quel raccourci de fonction contenant des @code{\override} aux
notes d'un accord. Néanmoins, l'instruction @code{\single} ne permet pas
de convertir des @code{\revert}, @code{\set} ou @code{\unset} en
@code{\tweak}.

@morerefs
Manuel d'initiation :
@ref{The tweak and offset commands},
@ref{Using variables for layout adjustments}.
@endmorerefs


@node The Internals Reference manual
@section Le manuel de référence des propriétés internes

@cindex Références internes

Le manuel des propriétés internes -- @dfn{Internals Reference} abrégé en
IR -- est la réponse ultime à toute la configuration de LilyPond. Généré
automatiquement à partir des sources même du logiciel, aucune
infrastructure de traduction n'est à ce jour disponible en ce qui le
concerne. Pour comprenndre comment l'utiliser, les sections qui suivent
les informations qui vous seront nécessaires.


@node Properties of layout objects
@subsection Propriétés des objets de rendu

@cindex propriétés des objets de rendu
@cindex propriétés des objets graphiques (grobs)
@cindex @emph{grob}, propriétés
@cindex objets de rendu, propriétés
@cindex Manuel des références internes

Imaginons que votre partition contienne une liaison trop fine à votre
goût et que vous vouliez la rendre plus épaisse. Comment vous y
prendre ? Vous êtes convaincu, avec tout ce qui a été dit sur la
souplesse de LilyPond, qu'une telle retouche est réalisable et vous vous
dites qu'elle fera sans doute intervenir la commande @code{\override}.
Mais existe-t-il une propriété épaisseur qui s'applique à une liaison
et, dans l'affirmative, comment faire pour la modifier ? C'est là
qu'intervient la Référence des propriétés internes. Elle contient toutes
les informations dont vous avez besoin pour construire n'importe quelle
commande @code{\override}.

Avant de nous plonger dans la Référence des propriétés internes, un mot
d'avertissement. Il s'agit d'un document de @strong{références}, de
sorte qu'il ne contient pas ou peu d'explications : son but est de
présenter les informations de façon précise et concise. Cela peut
paraître décourageant à première vue. Pas d'inquiétude ! Les conseils et
les explications fournis ici vous permettent de retrouver par vous-même
les informations dans la Référence des propriétés internes. Il suffit
d'un peu de pratique.

@cindex @code{\override}, exemple
@cindex dérogation, exemple
@cindex Références internes, exemple d'utilisation
@cindex @code{\addlyrics}, exemple

Prenons un exemple concret tiré d'un morceau de musique connu :

@c Mozart, Die Zauberflöte Nr.7 Duett

@lilypond[quote,verbatim]
{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8 bes[( g]) g |
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}
@end lilypond

Admettons que nous voulions rendre les traits de liaison plus épais.
Est-ce possible ? Une liaison est assurément un objet de rendu, si bien
que la question est « Existe-t-il une propriété attachée aux liaisons et
qui en contrôle l'épaisseur ? » Pour y répondre, nous consultons la
Référence des propriétés internes (ou RPI pour faire court).

Vous trouverez sur le site de LilyPond @uref{https://lilypond.org} la
RPI correspondant à votre version du programme. Allez sur la page
Documentation et cliquez sur Référence des propriétés internes. Pour
l'apprentissage, mieux vaut utiliser la version HTML standard, et non la
« page unique en anglais » ou le PDF. Durant la lecture des prochains
paragraphes, il vous est conseillé de vous y reporter réellement afin
que les explications prennent tout leur sens.

En dessous du bandeau d'en-tête figurent cinq liens. Cliquez sur le lien
vers le @emph{Backend}, où se trouvent les informations sur les objets
de rendu. En dessous du titre @strong{Backend}, choisissez alors le lien
vers @emph{Tous les objets de rendu}. La page qui s'ouvre énumère, dans
l'ordre alphabétique, tous les objets utilisés dans votre version de
LilyPond. Cliquez sur @code{Slur}, et les propriétés des liaisons
apparaîtront.

Il existe un autre moyen de trouver cette page, à partir du Manuel de
notation. Une des pages qui traitent des liaisons contient un lien vers
la Référence des propriétés internes, qui mène directement à cette page.
Mais lorsque vous connaissez le nom de l'objet à retoucher, le plus
simple est de consulter la RPI.

La page de la RPI sur les liaisons commence par préciser que les objets
« Liaison » sont créés par le graveur @code{Slur_engraver}. Vient
ensuite la liste des réglages standard ; vous y trouverez la propriété
susceptible de contrôler l'épaisseur des traits de liaison.

@example
thickness (number)
    1.2
    [...] For slurs and ties, this is the distance between the two
    arcs of the curve's outline at its thickest point, [...]  This
    property is expressed as a multiple of the current staff-line
    thickness [...]
@end example

@noindent
que l'on pourrait traduire ainsi :

@example
thickness (nombre)
    1.2
    [...] Pour les liaisons de phrasé et de tenue, c'est la distance
    entre les deux arcs extérieurs de la courbe à son point le plus
    épais, [...] Cette propriété s'exprime en multiple de l'épaisseur
    de ligne de portée en cours [...]
@end example

Voilà qui semble approprié pour changer l'épaisseur (@emph{thickness} en
anglais). On apprend que la valeur de @code{thickness} est un simple
nombre (@emph{number}), qu'elle est par défaut définie à 1,2 et que
cette valeur varie en fonction de l'épaisseur des lignes de portée -- on
comprend aisément que des petites portées auront des liaisons plus
fines.

Comme il a été indiqué, on ne trouve que peu, voire pas du tout
d'explication dans la RPI, mais nous en savons assez pour essayer
de changer l'épaisseur de la liaison.  Comme nous l'avons vu, le
nom de l'objet est @code{Slur}, le nom de la propriété à changer
est @code{thickness} et la nouvelle valeur sera un nombre supérieur
à @code{1.2} si l'on veut augmenter l'épaisseur du trait.

Pour construire la commande @code{\override}, il suffit donc de
remplacer les valeurs que nous avons trouvées en guise de noms, en
laissant de côté le contexte.  Commençons par une valeur très élevée
dans un premier temps, pour nous assurer que la commande fonctionne.
Nous obtenons :

@example
\override Slur.thickness = 5.0
@end example

La dernière question est : « Où placer cette commande ? » Tant qu'on
n'est pas sûr de soi, la meilleure réponse est « À l'intérieur de
l'expression musicale, avant la première liaison et proche d'elle. »
Essayons :

@cindex @code{Slur}, exemple de dérogation
@cindex @code{thickness}, exemple d'utilisation de la propriété

@lilypond[quote,verbatim]
{
  \key es \major
  \time 6/8
  \relative {
    % Increase thickness of all following slurs from 1.2 to 5.0
    \override Slur.thickness = 5.0
    r4 bes'8 bes[( g]) g |
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}
@end lilypond

@noindent
et nous constatons que le trait de liaison est beaucoup plus épais.

Telle est la façon normale de construire des commandes @code{\override}.
Comme nous aurons l'occasion de le voir par la suite, le problème est
parfois plus complexe. Dans l'immédiat, nous en savons assez pour
construire nos propres commandes -- mais il faut encore s'exercer. Les
exemples suivants sont là dans cette intention.


@subsubsubheading Détermination du contexte adéquat
@c VO Finding the context

@cindex contexte, détermination du
@cindex contexte, identification correcte du

Tout d'abord, de quoi avions-nous besoin pour préciser le contexte ? À
quoi devait-il ressembler ? Gageons que les liaisons appartiennent au
contexte de voix (@code{Voice}), dans la mesure où elles sont
étroitement liées à une ligne mélodique, mais comment en être sûr ? Pour
répondre à cette question, revenons en haut de la page de la RPI
consacrée aux liaisons ; il est écrit : « Les objets Liaison sont créés
par le graveur @code{Slur_engraver}. » Ainsi les liaisons seront créées
dans n'importe quel contexte où se trouve le @code{Slur_engraver}.
Suivons le lien vers la page @code{Slur_engraver}. Tout en bas, on lit
que le @code{Slur_engraver} est un élément appartenant à huit contextes
Voix, dont le contexte de voix standard, @code{Voice}. Notre hypothèse
était donc juste. Et parce que @code{Voice} est un contexte de très bas
niveau, qu'il est activé sans ambiguïté par le fait que l'on est en
train de saisir des notes, on peut ici ne pas le mentionner.


@subsubsubheading Redéfinition pour une seule occurrence
@c VO Overriding once only

@cindex dérogation pour une seule fois
@cindex usage unique, dérogation à
@cindex @code{\once} @code{\override}

@funindex \once

Dans le dernier exemple ci-dessus, @emph{toutes} les liaisons étaient
plus épaisses. Et si on veut épaissir uniquement la première liaison ?
On recourt alors à la commande @code{\once}. Placée juste avant la
commande @code{\override}, elle lui indique de ne changer que la liaison
commençant avec la note @strong{juste après}. Si la note juste après
n'ouvre pas une liaison, la commande sera sans aucun effet -- elle ne
reste pas en mémoire jusqu'à la prochaine liaison, elle est purement et
simplement ignorée. Il faut donc que la commande introduite par
@code{\once} soit insérée comme suit :

@cindex @code{Slur}, exemple de dérogation
@cindex @code{thickness}, exemple d'utilisation de la propriété
@cindex Liaison, exemple de dérogation
@cindex @'Epaisseur, exemple d'utilisation de la propriété

@lilypond[quote,verbatim]
{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8
    % Increase thickness of immediately following slur only
    \once \override Slur.thickness = 5.0
    bes8[( g]) g |
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}
@end lilypond

@noindent
Alors seule la première liaison est rendue plus épaisse.

La commande @code{\once} peut aussi être utilisée devant la commande
@code{\set}.

Une alternative à @code{\once \override} consiste à utiliser la commande
@code{\tweak} ; on obtiendra le même résultat si l'on remplace

@example
\once \override Slur.thickness = 5.0
bes8[(
@end example

@noindent
dans l'exemple précédent par

@example
bes8[\tweak thickness 5.0 (
@end example


@subsubsubheading Rétablissement
@c VO Reverting

@cindex rétablissement
@cindex retour
@cindex défaut, retour aux propriétés par

@funindex \revert

Et si l'on voulait que les deux premières liaisons soient plus
épaisses ? On pourrait bien sûr utiliser deux commandes, chacune
précédée de @code{\once} et placée juste avant la note par laquelle
débute la liaison :

@cindex liaison, exemple de dérogation
@cindex @code{Slur}, exemple de dérogation
@cindex @code{thickness}, exemple d'utilisation de la propriété
@cindex @'epaisseur, exemple d'utilisation

@lilypond[quote,verbatim]
{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8
    % Increase thickness of immediately following slur only
    \once \override Slur.thickness = 5.0
    bes[( g]) g |
    % Increase thickness of immediately following slur only
    \once \override Slur.thickness = 5.0
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}
@end lilypond

@noindent
mais on peut aussi, au lieu de la commande @code{\once}, utiliser après
la seconde liaison la commande @code{\revert}, qui ramène la propriété
@code{thickness} à sa valeur par défaut :

@cindex @code{Slur}, exemple de dérogation
@cindex @code{thickness}, exemple d'utilisation de la propriété
@cindex liaison, exemple de dérogation
@cindex @'epaisseur, exemple d'utilisation

@lilypond[quote,verbatim]
{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8
    % Increase thickness of all following slurs from 1.2 to 5.0
    \override Slur.thickness = 5.0
    bes[( g]) g |
    g8[( es]) es
    % Revert thickness of all following slurs to default of 1.2
    \revert Slur.thickness
    d8[( f]) as |
    as8 g
  }
  \addlyrics {
    The man who | feels love's sweet e -- | mo -- tion
  }
}
@end lilypond

@noindent
N'importe quelle propriété modifiée par @code{\override} peut ainsi être
ramenée, grâce à la commande @code{\revert}, à sa valeur par défaut.

Ici s'achève notre introduction à la RPI et aux retouches simples. Vous
trouverez d'autres exemples dans les prochaines sections de ce
chapitre ; ils vous permettront, d'une part, d'apprendre à connaître un
peu mieux la RPI et, d'autre part, de vous entraîner un peu plus à y
chercher les informations. Ces exemples seront progressivement
accompagnés d'explications et introduiront des termes nouveaux.


@node Properties found in interfaces
@subsection Propriétés listées par interface

@cindex interface
@cindex interfaces, propriétés des
@cindex propriétés des interfaces

Supposons maintenant que nous voulions imprimer des paroles en italique.
Quelle formulation de la commande @code{\override} allons-nous
utiliser ? Nous consultons en premier lieu, comme précédemment, la page
de la RPI qui contient la liste « Tous les objets de rendu », et
recherchons un objet qui contrôle les paroles. Nous trouvons
@code{LyricText}, qui semble approprié. Nous cliquons dessus et nous
voyons apparaître les différentes propriétés des paroles, parmi
lesquelles @code{font-series} et @code{font-size}. Mais aucune ne
propose l'italique. Car la mise en forme des caractères est une
propriété commune à tous les objets d'écriture, si bien que, au lieu de
figurer dans tous les objets de rendu, elle est regroupée avec d'autres
propriétés semblables et placée dans une @strong{Interface}, la
@code{font-interface}.

Il nous faut donc apprendre à trouver les propriétés des interfaces et
découvrir les objets qui utilisent les propriétés de ces interfaces.

Retournons à la page de la RPI qui traite des paroles
(@code{LyricText}). En bas de la page est dressée sous forme de liens la
liste des interfaces qui concernent LyricText. Cette liste comporte
plusieurs entrées, dont @code{font-interface}. En cliquant dessus, nous
voyons apparaître les différentes propriétés associées à cette
interface, qui sont en même temps les propriétés de tous les objets qui
s'y rapportent, parmi lesquels @code{LyricText}.

Nous avons alors sous les yeux tous les réglages des propriétés qui
contrôlent les polices de caractères, et notamment « @code{font-shape}
(symbol) ». La valeur entre parenthèses indique le type de valeur
attendu pour cette propriété qui, ici, est un symbole Scheme. La
référence de propriétés internes indique aussi les valeurs possibles, à
savoir @code{upright}, @code{italic} ou @code{slanted}.

Vous remarquerez que @code{font-series} et @code{font-size} figurent
aussi dans la liste. La question qui ne manque pas de se poser est :
« Comment se fait-il que les propriétés @code{font-series} et
@code{font-size} se retrouvent à la fois dans @code{LyricText} et dans
l'interface @code{font-interface} alors que ce n'est pas le cas pour
@code{font-shape} ? » La réponse est que lorsqu'un objet
@code{LyricText} est créé, les valeurs globales par défaut de
@code{font-series} et @code{font-size} sont modifiées, mais pas celles
de @code{font-shape}. Les possibilités de modification dans
@code{LyricText} ne concernent donc que les valeurs à appliquer à
@code{LyricText}. Les autres objets qui dépendent de
@code{font-interface} fixeront leurs propriétés différemment lorsqu'ils
seront créés.

Voyons maintenant si nous sommes en mesure de formuler la commande
@code{\override} pour mettre les paroles en italique. L'objet est
@code{LyricText}, la propriété est @code{font-shape} et la valeur est
@code{italic}. Comme auparavant, nous laissons de côté le contexte.

Signalons rapidement -- même si cette remarque est importante -- que
certaines valeurs de propriétés se présentent sous forme de symboles,
comme @code{italics}, et doivent donc être précédées d'une simple
apostrophe, Ces symboles seront alors interprétés comme tels par
LilyPond. À ne pas confondre avec les chaînes de caractères libres qui
se présentent comme @code{"un texte libre"} ; pour plus de détails sur
les symboles et les chaînes de caractères, voir le @rextendnamed{Scheme
tutorial, Tutoriel Scheme}.

Ainsi, la commande @code{\override} pour mettre les paroles en italique
est :

@example
\override LyricText.font-shape = #'italic
@end example

@noindent
et doit être placée juste devant et tout près des paroles à modifier,
comme ceci :

@cindex @code{font-shape}, exemple d'utilisation de la propriété
@cindex @code{italic}, exemple
@cindex @code{LyricText}, exemple de dérogation
@cindex @code{\addlyrics}, exemple

@lilypond[quote,ragged-right,verbatim]
{
  \key es \major
  \time 6/8
  \relative {
    r4 bes'8 bes[( g]) g |
    g8[( es]) es d[( f]) as |
    as8 g
  }
  \addlyrics {
    \override LyricText.font-shape = #'italic
    The man who | feels love's sweet e -- | mo -- tion
  }
}
@end lilypond

@noindent
et voilà les paroles en italiques.

@warning{Dans la saisie des paroles, pensez à toujours laisser une
espace entre la dernière syllabe et l'accolade fermante.}

@morerefs
Manuel d'extension :
@rextendnamed{Scheme tutorial, Tutoriel Scheme}.
@endmorerefs


@node Types of properties
@subsection Types de propriétés

@cindex propriété, types de
@cindex @code{#t} (true)
@cindex @code{#f} (false)
@cindex vrai (@code{#t})
@cindex faux (@code{#f})
@cindex Scheme, expressions (@code{#})
@cindex @code{#}, expressionx Scheme

Nous avons vu jusqu'à maintenant deux types de propriétés : « nombre »
et « symbole ». Pour pouvoir fonctionner, la valeur associée à une
propriété doit correspondre au type attendu et suivre les règles liées à
ce type. Le type de propriété est toujours donné entre parenthèses après
le nom de propriété dans la RPI. Voici une liste des différents types de
propriétés, avec les règles qui les régissent et quelques exemples
d'utilisation. Il faut, bien sûr, toujours ajouter un symbole
@emph{hash} (@code{#}) devant les expressions Scheme lors de la saisie
de la commande @code{\override}, ce même si la valeur comporte déjà
un @code{#} en premier caractère. Les exemples ici présentés ne sont que
de simples illustrations ; l'utilisation de Scheme pour obtenir des
valeurs fait l'objet de la rubrique @rextendnamed{Calculations in
Scheme, Scheme et les calculs}.

@indentedblock
@raggedright
@multitable {@b{Type de propriété}} {either @q{true} or @q{false}, represented} {@code{\markup @{ \italic "cresc." @}},}
@headitem Type de propriété
  @tab Règles
  @tab Exemples de saisie
@item Boolean@* (@emph{Booléen} en français)
  @tab Vrai (@emph{true} en anglais) ou Faux (@emph{false} en anglais),
       sous la forme @code{#t} ou @code{#f}
  @tab @code{##t}, @code{##f}
@item dimension@* (en espaces de portée)
  @tab Un nombre décimal (en unités de lignes de portée)
  @tab @code{2.5}, @code{0.34}
@item direction
  @tab Une direction valide ou son équivalent numérique (@code{0}
       ou @code{CENTER} indiquent une position neutre)
  @tab @code{#LEFT}, @code{#CENTER}, @code{#UP}, @code{1}, @w{@code{-1}}
@item integer@* (@emph{entier} en français)
  @tab Un nombre entier
  @tab @code{3}, @code{-1}
@item Liste
  @tab Une séquence de constantes ou symboles séparés par une
       espace, encadrées par des parenthèses et précédées par une
       apostrophe
  @tab @code{#'(left-edge staff-bar)},@*
       @code{#'(1)}, @code{#'()},@*
       @code{#'(1.0 0.25 0.5)}
@item markup@* (ou étiquette)
  @tab Toute commande @code{\markup} valide
  @tab @code{\markup @{ \italic "cresc." @}},@*
       @code{"bagpipe"}
@item moment@* (@emph{durée} en français)
  @tab Une durée musicale -- ce type est distinct d'une durée de note
  @tab @code{\musicLength 4.},@*
       @code{\musicLength @{2 2.@}}
@item number@* (@emph{nombre} en français)
  @tab Une valeur positive ou négative, qui peut être décimale
  @tab @code{3}, @code{-2.45}
@item paire@* (paire de nombres)
  @tab Deux nombres séparés par « espace point espace », encadrés
       par des parenthèses et précédés par une apostrophe
  @tab @code{#'(2 . 3.5)},@*
       @code{#'(0.1 . -3.2)}
@item symbol@* (un symbole)
  @tab L'un des symboles autorisés pour cette propriété, précédé par une
       apostrophe
  @tab @code{#'italic}, @code{#'inside}
@item unknown@* (@emph{inconnu} en français)
  @tab Un processus, ou @code{#f} pour empêcher toute action
  @tab @code{#bend::print},@*
       @code{#ly:text-interface::print},@*
       @code{##f}
@item vector@* (un vecteur)
  @tab Des constantes encadrés par @code{#(}@dots{}@code{)}
  @tab @code{##(#t #t #f)}
@end multitable
@end raggedright
@end indentedblock

Attention : les arguments numériques aux fonctions de @emph{markup} au
sein d'un bloc @code{\markup} requièrent un signe dièse.

@morerefs
Manuel d'extension :
@rextendnamed{Scheme tutorial, Tutoriel Scheme}.
@endmorerefs


@node Appearance of objects
@section Apparence des objets

Il est temps de mettre en pratique les notions apprises précédemment
pour modifier l'allure de la partition ; les exemples qui suivent
montrent l'utilisation des différentes méthodes de retouche.


@node Visibility and color of objects
@subsection Visibilité et couleur des objets

Dans un but pédagogique, on peut être amené à masquer certains éléments
d'une partition, que les élèves doivent ensuite compléter. Imaginons,
par exemple, un exercice dans lequel il faudrait rétablir les barres de
mesure dans un morceau de musique. En temps normal, les barres de mesure
s'insèrent automatiquement. Comment faire pour les effacer de la
partition ?

Avant de nous y attaquer, souvenons-nous que les propriétés d'objets
sont parfois groupées dans ce qu'on appelle des @dfn{interfaces} --
@pxref{Properties found in interfaces}. Cela permet de rapprocher toutes
les propriétés susceptibles d'être utilisées ensemble pour modifier un
objet graphique -- si l'une d'elles est choisie pour un objet, elle
s'appliquera à tous les autres. Certains objets tirent alors leurs
propriétés de telle ou telle interface, d'autres objets de telle ou
telle autre interface. La liste des interfaces qui contiennent les
propriétés liées à un objet graphique (@emph{grob}) figure dans la RPI,
en bas de la page de description du @emph{grob} ; pour voir ces
propriétés, il faut aller voir ces interfaces.

Nous avons vu, dans @ref{Properties of layout objects}, comment trouver
les informations sur les @emph{grobs}. Nous procédons de la même manière
et consultons la RPI pour connaître l'objet chargé d'imprimer les barres
de mesure. En cliquant sur @emph{Backend} puis sur @emph{Tous les objets
de rendu}, nous trouvons un objet appelé @code{BarLine}. Parmi ses
propriétés, deux d'entre elles déterminent son aspect visuel :
@code{break-visibility} et @code{stencil}. L'objet @code{BarLine} est
également lié à plusieurs interfaces, dont la @code{grob-interface} où
figurent les propriétés @code{transparent} et @code{color}. Toutes
peuvent modifier l'aspect visuel des barres de mesure -- et de beaucoup
d'autres objets, bien sûr. Examinons chacune d'elles tour à tour.


@node The stencil property
@unnumberedsubsubsec La propriété @code{stencil}

@cindex @code{stencil}, propriété

Cette propriété contrôle l'apparence des barres de mesure en précisant
le type de symbole (glyphe) à imprimer. Comme pour de nombreuses autres
propriétés, on peut lui indiquer de ne rien imprimer en lui attribuant
la valeur @code{#f}. Essayons en laissant de côté, une fois encore, le
contexte concerné (@code{Voice} en l'occurrence) :

@cindex @code{BarLine}, exemple de dérogation
@cindex @code{stencil}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \override BarLine.stencil = ##f
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

Les barres de mesure sont encore là ! Pourquoi ? Retournons à la RPI et
regardons de nouveau la page qui traite des propriétés de
@code{BarLine}. En haut de la page, il est précisé que « Les objets
@code{BarLine} sont créés par le graveur @code{Bar_engraver} ». Allons à
la page de @code{Bar_engraver}. Tout en bas se trouve la liste des
contextes dans lesquels fonctionne ce graveur. Tous sont du type
@code{Staff}, de sorte que, si la commande @code{\override} n'a pas
fonctionné comme prévu, c'est parce que @code{BarLine} n'appartient pas
au contexte par défaut, @code{Voice}. Si le contexte spécifié est
erroné, la commande ne fonctionne pas. Cela n'entraîne pas de message
d'erreur, et rien n'apparaît dans le fichier @emph{log}. Essayons de
corriger en mentionnant le bon contexte :

@cindex @code{BarLine}, exemple de dérogation
@cindex @code{stencil}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \override Staff.BarLine.stencil = ##f
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

Cette fois, les barres de mesure ont disparu. Désactiver la propriété
@code{stencil} est une opération tellement fréquente que LilyPond
dispose d'un raccourci -- @code{\omit} (pour « oublier ») -- à cet
effet :

@funindex \omit

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \omit Staff.BarLine
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

Vous remarquerez que l'affectation de la valeur @code{#f} à la propriété
@code{stencil} déclenchera une erreur dès lors que l'objet en question
se doit d'avoir des dimensions pour les nécessités du traitement. Ce
sera le cas, par exemple, si vous effacez le @code{stencil} d'un objet
@code{NoteHead}. Il vaut mieux, en pareil cas, utiliser la fonction
@code{point-stencil} qui, quant à elle, attribue à l'objet une taille à
zéro :

@lilypond[quote,verbatim]
\relative {
  c''4 c
  \once \override NoteHead.stencil = #point-stencil
  c4 c
}
@end lilypond


@node The break-visibility property
@unnumberedsubsubsec La propriété @code{break-visibility}

@cindex @code{break-visibility}, propriété

La RPI mentionne, à la page sur @code{BarLine}, que la propriété
@code{break-visibility} attend comme argument un vecteur de trois
booléens. Ceux-ci indiquent respectivement si les barres de mesure
doivent être imprimées ou non à la fin de la ligne, à l'intérieur de la
ligne et au début de la ligne. Dans notre cas, nous voulons que toutes
les barres soient supprimées, si bien que la valeur dont nous avons
besoin est @code{#(#f #f #f)}. Essayons, sans oublier d'ajouter le
contexte @code{Staff}. Vous remarquerez que, en plus de cette valeur,
nous ajoutons @code{##} devant la parenthèse ouvrante. Un second
@samp{#} est nécessaire car il fait partie intégrante de la valeur
contenant un vecteur, et le premier @samp{#} est là, comme toujours avec
la commande @code{\override}, pour introduire la valeur elle-même.

@cindex @code{BarLine}, exemple de dérogation
@cindex @code{break-visibility}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,ragged-right,verbatim]
\relative {
  \time 12/16
  \override Staff.BarLine.break-visibility = ##(#f #f #f)
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

Comme on peut le constater, cette solution-là aussi supprime les barres
de mesure.


@node The transparent property
@unnumberedsubsubsec La propriété @code{transparent}

@cindex @code{transparent}, propriété
@cindex transparence

La RPI mentionne, à la page sur @code{grob-interface}, que la propriété
@code{transparent} attend comme argument un booléen. Il faudrait donc
mettre @code{#t} pour rendre l'objet transparent. Dans cet exemple,
essayons de rendre transparente la métrique (@emph{time signature} en
anglais) plutôt que les barres de mesure. Pour cela, il nous faut
trouver le nom du @emph{grob} chargé de l'indication de mesure. De
retour sur la page « Tous les objets de rendu » de la RPI, nous
cherchons les propriétés de l'objet @code{TimeSignature}. Celui-ci est
géré par le graveur @code{Time_signature_engraver} qui, comme vous
pouvez le constater, appartient au contexte @code{Staff} et peut se
rattacher à la @code{grob-interface}. Dans ces conditions, la commande
pour rendre la métrique transparente est :

@cindex @code{TimeSignature}, exemple de dérogation
@cindex @code{transparent}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \override Staff.TimeSignature.transparent = ##t
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

L'utilisation de la propriété @code{transparent} étant relativement
fréquente, LilyPond dispose d'un raccourci à cet effet : @code{\hide}
(pour « masquer »).

@funindex \hide

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \hide Staff.TimeSignature
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

@noindent
La métrique a bien disparu dans les deux cas, mais la commande a laissé
un blanc en lieu et place du chiffrage. Ce peut être souhaitable dans le
cadre d'un exercice, afin que les élèves aient la place pour compléter,
mais dans d'autres circonstances, ce peut être gênant. Pour y remédier,
attribuons plutôt au stencil des métriques la valeur @code{#f} :

@cindex @code{TimeSignature}, exemple de dérogation
@cindex @code{stencil}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,ragged-right,verbatim]
\relative {
  \time 12/16
  \omit Staff.TimeSignature
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

@noindent
La différence est flagrante : le fait d'attribuer au stencil la valeur
@code{#f} ou grâce à @code{\omit} supprime totalement l'objet, tandis
que le fait de le rendre @code{transparent} -- ce qui s'obtient aussi
par la commande @code{\hide} -- le laisse en place, mais de façon
invisible.

@xref{Simulating a fermata in MIDI} pour une autre illustration de
la différence entre @code{\omit} et @code{\hide}.


@node The color property
@unnumberedsubsubsec La propriété @code{color}

@cindex @code{color}, propriété

Essayons enfin de rendre les barres de mesure invisibles en les colorant
en blanc. La difficulté est de savoir si les barres blanches vont couper
ou non les lignes de la portée aux endroits où elles se croisent. Vous
verrez dans les exemples ci-dessous que cela peut se produire, sans
qu'on le sache à l'avance. Les explications de ce phénomène et les
solutions pour y remédier sont exposées dans @rnotationnamed{Painting
objects white, Blanchiment des objets}. Pour le moment, acceptons cet
inconvénient et concentrons-nous sur l'apprentissage de la gestion des
couleurs.

La @code{grob-interface} indique que la valeur de la propriété
@code{color} est une liste, sans plus d'explication. En fait, cette
liste est une liste de valeurs en unités internes ; pour éviter d'avoir
à chercher ce qu'il faut y mettre, il existe différents moyens
d'indiquer la couleur. Le premier moyen consiste à utiliser l'une des
couleurs @emph{CSS} de la première @rnotationnamed{List of colors, Liste
des couleurs}. Pour mettre les barres de mesure en blanc, on écrit :

@cindex @code{BarLine}, exemple de dérogation
@cindex @code{color}, exemple d'utilisation de la propriété
@cindex CSS, couleurs
@cindex couleurs CSS

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \override Staff.BarLine.color = "white"
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

@noindent
et nous constatons que les barres de mesure sont une fois de plus
invisibles. Attention : aucune apostrophe ne précède @code{"white"} --
il ne s'agit pas d'un symbole, mais d'une chaîne de caractères mappée
dans une liste prédéfinie de valeurs internes. La syntaxe de LilyPond, à
ce propos, ressemble en tout point au
@uref{https://www.w3.org/Style/CSS/, langage CSS} couramment utilisé
pour les pages internet. En plus des noms prédéfinis, il est possible de
spécifier une couleur par un code hexadécimal :

@cindex @code{BarLine}, exemple de dérogation
@cindex @code{color}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \override Staff.BarLine.color = "#FFFFFF"
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

On pourrait tout aussi bien définir cette couleur sous forme de variable
que l'on utiliserait ensuite en tant que définition d'une propriété.
Dans la mesure où il s'agit à la fois d'une variable LilyPond et d'un
objet Scheme, elle pourra indifféremment se préfixer d'une oblique
inversée ou d'un @emph{hash} :

@lilypond[quote,ragged-right,verbatim]
whiteVar = "#FFFFFF"

\relative {
  \time 12/16
  \override Staff.BarLine.color = \whiteVar
  c''4 b8 c d16 c d8 |
  \override Staff.BarLine.color = #whiteVar
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

@cindex rgb, couleur
@cindex couleurs rgb

@funindex rgb-color

Un autre moyen d'ajouter des couleurs à une partition consiste à
recourir à une fonction. Deux fonctions sont utiles à cet égard : la
fonction @code{x11-colors} que nous verrons plus avant, et la fonction
@code{rgb-colors} qui, quant à elle, illustre la logique interne de
LilyPond. Cette fonction prend trois arguments, donnant respectivement
l'intensité du rouge, du vert et du bleu. Ces arguments prennent des
valeurs comprises entre 0 et 1. Ainsi, pour choisir la couleur rouge, la
valeur serait @code{(rgb-color 1 0 0)} ; pour le blanc, ce serait
@code{(rgb-color 1 1 1)} :

@cindex @code{BarLine}, exemple de dérogation
@cindex @code{color}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \override Staff.BarLine.color = #(rgb-color 1 1 1)
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

@noindent
Notez bien que, dans ce cas, l'intégralité de l'appel à cette fonction
est borné par des parenthèses. Il en va de même pour la fonction
@code{x11-colors} que nous avions laissée de côté.

@cindex couleur X11
@cindex X11, couleurs

@funindex x11-color

La fonction @code{x11-colors}, elle aussi, convertit les noms
symboliques de couleur en une liste de valeurs internes, mais elle offre
plus de choix que les couleurs CSS comme on peut le constater dans la
@rnotationnamed{List of colors, Liste des couleurs}. Par exemple, elle
comporte une échelle de gris qui va du noir (@code{'grey0}) au blanc
(@code{'grey100}), avec un pas de 1. Essayons de l'utiliser en
attribuant à tous les objets de notre exemple différentes nuances de
gris :

@cindex @code{StaffSymbol}, exemple de dérogation
@cindex @code{TimeSignature}, exemple de dérogation
@cindex @code{Clef}, exemple de dérogation
@cindex @code{NoteHead}, exemple de dérogation
@cindex @code{Stem}, exemple de dérogation
@cindex @code{BarLine}, exemple de dérogation
@cindex @code{color}, exemple d'utilisation de la propriété
@cindex @code{x11-color}, exemple d'utilisation

@lilypond[quote,ragged-right,verbatim]
\relative {
  \time 12/16
  \override Staff.StaffSymbol.color = #(x11-color 'grey30)
  \override Staff.TimeSignature.color = #(x11-color 'grey60)
  \override Staff.Clef.color = #(x11-color 'grey60)
  \override Voice.NoteHead.color = #(x11-color 'grey85)
  \override Voice.Stem.color = #(x11-color 'grey85)
  \override Staff.BarLine.color = #(x11-color 'grey10)
  c''4 b8 c d16 c d8 |
  g,8 a16 b8 c d4 e16 |
  e8
}
@end lilypond

@noindent
Vous remarquerez le contexte associé à chacun des objets. Une erreur sur
ce point empêcherait la commande de fonctionner. Souvenez-vous que le
contexte est celui dans lequel est placé le graveur approprié. Pour
chaque graveur, on peut trouver son contexte par défaut en partant de
l'objet lui-même, puis en cherchant le graveur qui le produit ; la page
du graveur dans la RPI nous indique alors le contexte dans lequel le
graveur se trouve normalement.


@node Size of objects
@subsection Taille des objets

@cindex modification de la taille des objets
@cindex taille d'objets
@cindex objets, taille
@cindex objets, modification de taille

Pour commencer, reprenons l'exemple qui se trouvait dans @ref{Nesting
music expressions}, qui montrait comment créer une nouvelle portée
temporaire, du type @rglos{ossia}.

@cindex @code{alignAboveContext}, exemple d'utilisation de la propriété
@cindex @code{\with}, exemple

@lilypond[quote,ragged-right,verbatim]
\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main" }
      { f8 f c }
    >>
    r4 |
  }
}
@end lilypond

Normalement, les ossias ne comportent ni clef ni indication de mesure,
et elles sont imprimées légèrement plus petit que la portée principale.
Nous avons déjà appris à enlever la clef et la métrique -- il suffit de
régler le stencil de chacun sur @code{#f}, comme ceci :

@cindex @code{alignAboveContext}, exemple d'utilisation de la propriété
@cindex @code{\with}, exemple
@cindex @code{Clef}, exemple de dérogation
@cindex @code{TimeSignature}, exemple de dérogation
@funindex \omit

@lilypond[quote,ragged-right,verbatim]
\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
      }
      {
        \omit Staff.Clef
        \omit Staff.TimeSignature
        { f8 f c }
      }
    >>
    r4 |
  }
}
@end lilypond

@noindent
La paire d'accolades ajoutée après la clause @code{\with} est nécessaire
pour être sûr que les retouches (@code{\override}) ainsi que la musique
qui se trouvent à l'intérieur soient bien appliquées à la portée
d'ossia.

Mais alors, quelle différence y a-t-il à modifier le contexte de portée
au moyen de @code{\with} ou à modifier les stencils de la clef et de la
métrique avec @code{\override} ou @code{\omit} comme ici ? La principale
différence est que les changements opérés dans une clause @code{\with}
sont réalisés au moment où le contexte est créé et restent par la suite
les valeurs @strong{par défaut} aussi longtemps que ce contexte existe,
tandis que les commandes @code{\set} ou @code{\override} insérées dans
la musique sont dynamiques -- elles provoquent des changements
synchronisés avec un point particulier de la musique. Si les changements
sont annulés ou désactivés par @code{\unset} ou @code{\revert}, les
réglages reprennent leurs valeurs par défaut, c'est-à-dire celles qui
ont été fixées dans la clause @code{\with}, ou, en l'absence de
celle-ci, les valeurs par défaut normales.

Certaines propriétés de contexte ne peuvent être modifiées que dans une
clause @code{\with}. Il s'agit des propriétés qu'on ne peut évidemment
plus changer après que le contexte a été créé. C'est le cas de
@code{alignAboveContext} et de son pendant, @code{alignBelowContext} --
une fois que la portée a été créée, son alignement est décidé et cela
n'aurait aucun sens de vouloir le modifier par la suite.

Dans une clause @code{\with}, on peut aussi régler les valeurs par
défaut des propriétés d'un objet. Il suffit d'utiliser la commande
@code{\override} normale, sans s'occuper du nom de contexte puisqu'il ne
fait pas de doute qu'il s'agit du contexte en cours de modification par
la clause @code{\with}. Il se produirait même une erreur si le contexte
était précisé.

Remplaçons donc l'exemple ci-dessus par celui-ci :

@cindex @code{alignAboveContext}, exemple d'utilisation de la propriété
@cindex @code{\with}, exemple
@cindex @code{Clef}, exemple de dérogation
@cindex @code{TimeSignature}, exemple de dérogation

@lilypond[quote,ragged-right,verbatim]
\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
        % Don't print clefs in this staff
        \override Clef.stencil = ##f
        % Don't print time signatures in this staff
        \override TimeSignature.stencil = ##f
      }
      { f8 f c }
    >>
    r4 |
  }
}
@end lilypond

Nous pourrions tout aussi bien utiliser les raccourcis @code{\hide} et
@code{\omit} pour activer la propriété @code{transparent} et désactiver
le @code{stencil}, ce qui donnerait :

@lilypond[quote,ragged-right,verbatim]
\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
        % Don't print clefs in this staff
        \omit Clef
        % Don't print time signatures in this staff
        \omit TimeSignature
      }
      { f8 f c }
    >>
    r4 |
  }
}
@end lilypond

Venons-en finalement au changement de taille des objets.

Certains objets sont créés comme des glyphes choisis dans une police de
caractères. C'est le cas des têtes de notes, des altérations, des
@emph{markup}, des clefs, des métriques, des nuances et des paroles.
Pour changer leur taille, on modifie la propriété @code{font-size},
comme nous le verrons rapidement. D'autres objets, comme les liaisons de
phrasé ou de prolongation -- en général les objets étendus -- sont
dessinés à la demande, si bien qu'aucune @code{font-size} ne leur est
associée. Ces objets tirent généralement leur dimension des objets
auxquels ils sont rattachés, de sorte qu'on ne doit pas avoir à les
redimensionner à la main. D'autres propriétés, comme la hauteur des
hampes et des barres de mesure, l'épaisseur des ligatures et d'autres
lignes, et l'écartement des lignes de portée, doivent encore être
modifiées de façon particulière.

Si l'on revient à l'exemple d'ossia, commençons par changer la taille de
police. Nous pouvons employer deux méthodes. Soit nous changeons la
taille de police de chaque type d'objet avec des commandes comme
celle-ci pour les têtes de notes (@code{NoteHead}) :

@example
\override NoteHead.font-size = -2
@end example

soit nous changeons la taille de toutes les polices à la fois grâce à la
propriété @code{fontSize}, en utilisant @code{\set} ou en l'insérant
dans une clause @code{\with} (mais alors sans le @code{\set}).

@example
\set fontSize = -2
@end example

Chacune de ces méthodes réduira la taille de police de deux points par
rapport à sa valeur précédente, sachant que chaque point réduit ou
augmente la taille d'environ 12 %.

Essayons sur l'exemple d'ossia :

@cindex @code{alignAboveContext}, exemple d'utilisation de la propriété
@cindex @code{\with}, exemple
@cindex @code{Clef}, exemple de dérogation
@cindex @code{TimeSignature}, exemple de dérogation
@cindex @code{fontSize}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
        \omit Clef
        \omit TimeSignature
        % Reduce all font sizes by ~24%
        fontSize = -2
      }
      { f8 f c }
    >>
    r4 |
  }
}
@end lilypond

Ce n'est pas encore parfait. Les têtes de notes et les crochets sont
plus petits mais, proportionnellement, les hampes sont trop longues et
les lignes de la portée trop espacées. Il faut donc les réduire dans les
mêmes proportions que les polices de caractères. La prochaine
sous-section montrera comment faire.


@node Length and thickness of objects
@subsection Longueur et épaisseur des objets

@cindex distance entre objets
@cindex @'epaisseur des objets
@cindex longueur des objets
@cindex taille, modification
@cindex hampe, modification de longueur
@cindex @'ecartement des lignes, modification
@cindex intervalle de ligne, unité
@cindex espace de portée

Dans LilyPond, les écartements et longueurs sont généralement mesurés en
« intervalles de lignes » (@emph{staff spaces} en anglais), c'est-à-dire
l'écartement qui sépare deux lignes adjacentes dans la portée. Plus
rarement, il est question de demi-intervalles de lignes. Les propriétés
d'épaisseur (@code{thickness}), quant à elles, sont généralement
mesurées en unités d'une propriété interne appelée « épaisseur de
ligne » (propriété @code{thickness} de l'objet graphique
@code{StaffSymbol}). Par exemple, les lignes de (de)crescendo présentent
par défaut une épaisseur d'une unité d'épaisseur de ligne de portée,
alors que l'épaisseur d'une hampe est de 1,3. Toutefois, certaines
propriétés d'épaisseur sont différentes : par exemple, l'épaisseur des
ligature -- @code{beam-thickness} -- se mesure en espaces de portée.

Dans ces conditions, comment ajuster les longueurs à la taille des
polices de caractères ? La solution consiste à utiliser une fonction
spéciale appelée @code{magstep} -- pseudo facteur de zoom --, créée
précisément dans ce but. Elle comporte un argument, le changement de
taille de police (la valeur -2 dans l'exemple précédent), à partir
duquel elle applique un facteur de mise à l'échelle qui réduit, ou
augmente, les objets en question. La gageure consiste donc à ne pas
modifier la taille des hampes et autres objets, mais de plutôt jouer
sur la l'unité de base de ces tailles -- en l'occurrence la propriété
@code{staff-space} de l'objet graphique @code{StaffSymmbol}.

@cindex @code{alignAboveContext}, exemple d'utilisation de la propriété
@cindex @code{\with}, exemple
@cindex @code{Clef}, exemple de dérogation
@cindex @code{TimeSignature}, exemple de dérogation
@cindex @code{fontSize}, exemple d'utilisation de la propriété
@cindex @code{StaffSymbol}, exemple de dérogation
@cindex @code{magstep}, exemple d'utilisation de la fonction
@cindex @code{staff-space}, exemple d'utilisation de la propriété
@cindex @code{stencil}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\new Staff ="main" {
  \relative {
    r4 g'8 g c4 c8 d |
    e4 r8
    <<
      { f8 c c }
      \new Staff \with {
        alignAboveContext = "main"
        \omit Clef
        \omit TimeSignature
        fontSize = -2
        % Reduce stem length and line spacing to match
        \override StaffSymbol.staff-space = #(magstep -2)
      }
      { f8 f c }
    >>
    r4 |
  }
}
@end lilypond

Bien que la modification de @code{staff-space} affecte la taille de
l'ossia, cela ne change en rien l'espacement horizontal -- la dimension
horizontale étant déterminée par les objets de la portée principale de
façon à rester synchronisée vis-à-vis d'elle, elle n'est pas affectée
par tous ces changements de taille. Bien sûr, si l'échelle de toute la
portée principale était modifiée, tout le placement horizontal s'en
trouverait affecté. Il en sera question plus bas dans cette section.

Voilà qui complète la création d'une ossia. Les taille et longueur de
tous les objets peuvent être modifiées de manière analogue.

Pour de petits changements d'échelle, comme dans l'exemple ci-dessus, il
n'est généralement pas utile d'ajuster l'épaisseur des différentes
lignes telles que les barres de mesure, les ligatures, les soufflets de
crescendo ou decrescendo, les liaisons, etc. Si l'épaisseur d'un objet
en particulier doit être ajustée, le mieux est de modifier sa propriété
@code{thickness}. Nous avons vu plus haut, dans @ref{Properties of
layout objects}, un exemple de modification de l'épaisseur des liaisons.
L'épaisseur de tous les objets tracés (c'est-à-dire ceux qui ne
proviennent pas d'une police de caractère) peut être changée de la même
manière.


@node Offsets and alignments
@section Décalages et alignements

LilyPond a besoin de connaître où chacun des objets graphiques devrait
se placer. Cette information quant au positionnement est enregistrée
sous forme de coordonnées relatives : le positionnement d'un objet se
définit relativement au positionnement de son parent. Si l'on
travaillait en coordonnées absolues -- autrement dit à partir des coins
de la page --, préserver la relation spatiale entre les différents objets
relèverait du cauchemar.

Chaque objet graphique sait quel est son parent dans l'axe respectif.
Par exemple, un objet @code{Flag} (crochet) sait que son parent sur
l'axe des abscisses est un objet @code{Stem} (hampe) particulier.

@cindex @code{X-offset}, propriété
@cindex @code{Y-offset}, propriété

Les coordonnées relatives qui décrivent le positionnement d'un objet
sont enregistrées dans les propriétés d'objet appelées @code{X-offset}
et @code{Y-offset}. Elles sont exprimées en espace de portée.
@code{X-offset} est le décalage horizontal entre le @dfn{point de
référence} d'un objet et le point de référence d'un objet parent sur
l'axe des X (il en va de même pour @code{Y-offset}).

Mais qu'est-ce qu'un point de référence ? Il s'agit d'un point
spécifique qui définit le positionnement de l'objet. Faisons un peu de
géométrie : si l'on doit placer des formes sur un plan, on pourrait bien
dire « le coin inférieur gauche de ce carré a pour coordonnées (0, 2) »
ou « le centre de ce cercle est en (@minus{}1, 3) ». « Coin inférieur
gauche » et « centre » seront respectivement les points de référence du
carré et du cercle.

L'illustration ci-dessous montre où se place le point de référence
de quelques objets particuliers, indiqué par un point rouge -- par
exemple, la ligne médiane pour les barres de mesure, l'intersection
entre la ligne de base et le bord gauche d'une boîte de texte, ou bien
encore le centre vertical sur la gauche d'une tête de note.

@example
@{
  \override NoteHead.style = #'altdefault     % for breve

  \time 4/2 g'2-> c''\fermata as'1^"Yogi" |
  b'\breve _"Larry" |
  \mark "Twinkle" e''8 s4.. \bar "|."
@}
@end example

@lilypond[quote,staffsize=26]
\include "reference-points.ly"

\new Staff \with {
  \printRefpoint ##f #'all-grobs
} {
  \override NoteHead.style = #'altdefault     % for breve

  \time 4/2 g'2-> c''\fermata as'1^"Yogi" |
  b'\breve _"Larry" |
  \mark "Twinkle" e''8 s4.. \bar "|."
}

\layout {
  \context {
    \Score
    \remove "Mark_engraver"
  }
  \context {
    \Staff
    \consists "Mark_engraver"
  }
}
@end lilypond

Une dérogation aux valeurs de @code{X-offset} ou @code{Y-offset} peut
faire se déplacer des objets relativement à leurs parents :

@cindex @code{X-offset}, exemple d'utilisation
@cindex @code{Y-offset}, exemple d'utilisation

@example
@{
  \override Script.X-offset = 3               % fermata, accent
  \override TextScript.X-offset = 2           % "Yogi", "Larry"
  \override Stem.X-offset = -2
  \override Score.RehearsalMark.Y-offset = 5  % "Twinkle"

  \override NoteHead.style = #'altdefault     % for breve

  \time 4/2 g'2-> c''\fermata as'1^"Yogi" |
  b'\breve _"Larry" |
  \mark "Twinkle" e''8 s4.. \bar "|."
@}
@end example

@lilypond[quote,staffsize=26]
\include "reference-points.ly"

\new Staff \with {
  \printRefpoint ##f #'all-grobs
} {
  \override Script.X-offset = 3               % fermata, accent
  \override TextScript.X-offset = 2           % "Yogi", "Larry"
  \override Stem.X-offset = -2
  \override Score.RehearsalMark.Y-offset = 5  % "Twinkle"

  \override NoteHead.style = #'altdefault     % for breve

  \time 4/2 g'2-> c''\fermata as'1^"Yogi" |
  b'\breve _"Larry" |
  \mark "Twinkle" e''8 s4.. \bar "|."
}

\layout {
  \context {
    \Score
    \remove "Mark_engraver"
  }
  \context {
    \Staff
    \consists "Mark_engraver"
  }
}
@end lilypond

@noindent
Vous n'aurez pas manqué de constater que l'objet @code{Flag} s'est
déplacé comme son parent @code{Stem}.

@warning{Modifier @code{X-offset} ou @code{Y-offset} ne produit pas
toujours les effets escomptés, voir @rnotationnamed{Aligning objects,
Alignement des objets}.}

@cindex @code{X-extent}, propriété
@cindex @code{Y-extent}, propriété

Venons-en maintenant à une autre paire de propriétés : @code{X-extent}
et @code{Y-extent}. Toutes deux sont constituées d'une paire de nombres,
que LilyPond appelle en interne un @dfn{intervalle}, et enregistrent la
taille relative d'un objet par rapport à son point de référence. Par
exemple, un @code{X-extent} égal à (@w{-1} . 4) signifie que le bord
gauche du @emph{grob} est à 1 espace de portée sur la gauche de son point
de référence, et son bord droit à 4 espaces de portée sur la droite du
point de référence, pour une largeur totale de 4 - @w{(-1)} = 4 + 1 =
5 espaces de portée. Les deux nombres d'une étendue peuvent être
positifs ; par exemple, (2 . 3) est une étendue tout à fait valide :
cela signifie que l'intégralité du @emph{grob} est à droite de son point
de référence, et que la largeur de ce @emph{grob} est de 3 - 2 =
1 espace de portée. De la même manière, les deux nombres pourraient être
négatifs ; bien que peu probable, cette situation ne perturberait pas
LilyPond. Dans la plupart des cas, du moins pour @code{X-extent}, le
premier nombre est 0, ce qui signifie que le point de référence est sur
le bord gauche de l'objet graphique.

L'exemple précédent illustre ceci tout à fait : le bord gauche aussi bien de
l'accent que du point d'orgue est à gauche du point de référence ; il en
va de même pour la tête de la brève (nous avons préféré le style de tête
@code{'altdefault} pour plus de visibilité).

Supposons maintenant que nous voulions positionner un objet
@code{RehearsalMark} de telle sorte que son bord droit s'aligne sur une
barre de mesure (par défaut, LilyPond centre horizontalement la marque
de repère). Avec un @code{X-offset} égal à zéro, c'est à dire que son
point de référence s'aligne sur le point de référence de son parent, à
savoir la barre de mesure dans le cas présent, le @emph{grob}
@code{RehearsalMark} se place comme ceci :

@lilypond[quote,verbatim]
{
  \override Score.RehearsalMark.X-offset = 0
  b4 b b b \mark "Twinkle" b b b b
}
@end lilypond

@noindent
Il nous faut donc le décaler. N'oublions pas la signification du second
nombre de @code{X-extent} : il s'agit de la position du bord droit de
l'objet relativement à son point de référence. Si nous soustrayons cette
valeur à zéro, nous devrions obtenir le décalage horizontal voulu :

@lilypond[quote,verbatim]
{
  % value -10.4 found by trial and error
  \override Score.RehearsalMark.X-offset = -10.4
  b4 b b b \mark "Twinkle" b b b b
}
@end lilypond

Et si nous voulions centrer un objet sur le point de référence de son
parent ? Rien de plus simple : calculons le déplacement entre le point
de référence de cet objet et le @emph{centre} de son étendue. Quelques
exemples :

@itemize
@item @code{X-extent} = (-2 . 2)@*
      @result{} @code{X-offset} = 0 - 0 = 0
@item @code{X-extent} = (0 . 4)@*
      @result{} @code{X-offset} = 0 - (0 + 0.5 *@tie{}4) = @w{-2}
@item @code{X-extent} = (-2 . 4)@*
      @result{} @code{X-offset} = 0 - ((0.5 * @w{-2}) + (0.5 * 4))
                                = 0 - (@w{-1} +@tie{}2) = @w{-1}
@end itemize

Une fonction avec un nom à rallonges est déjà disponible et capable de
réaliser ces calculs pour nous :

@example
\override @var{NomGrob}.X-offset =
  #ly:self-alignment-interface::x-aligned-on-self
@end example

@noindent
à laquelle il suffit d'indiquer l'alignement désiré :

@example
\override @var{NomGrob}.self-alignment-X = #RIGHT
@end example

Ce code demande à la procédure de trouver la distance entre le point de
référence de l'objet et son bord droit, puis de l'utiliser comme
décalage horizontal, ce qui aura pour résultat que l'objet sera aligné
par sa droite.

Si donc on change l'étendue d'un objet, on affecte la manière dont il
sera aligné -- parce que LilyPond pensera que les dimensions de l'objet
sont différentes :

@lilypond[quote,verbatim]
{
  \override Score.RehearsalMark.X-extent = #'(0 . 8)
  \override Score.RehearsalMark.self-alignment-X = #RIGHT
  b4 b b b \mark "Twinkle" b b b b
}
@end lilypond

Bien sûr, si l'étendue d'un objet est vide (sa paire ne forme pas
un intervalle), les procédures telles que @code{x-aligned-on-self}
n'auront aucune information quant aux dimensions de cet objet et ne
pourront donc pas calculer de décalage (elles retourneront simplement la
valeur 0). Autrement dit, un @emph{grob} dont l'étendue est vide ne peut
« s'aligner » que sur son point de référence puisqu'aucune autre
information n'est disponible pour l'alignement :

@lilypond[quote,verbatim]
{
  \override Score.RehearsalMark.X-extent = ##f
  b4 b b b \mark "Twinkle" b b b b
}
@end lilypond

Notez bien qu'une étendue vide et une étendue égale à zéro résultent en
un même positionnement :

@lilypond[quote,verbatim]
{
  \override Score.RehearsalMark.X-extent = #'(0 . 0)
  b4 b b b \mark "Twinkle" b b b b
}
@end lilypond

Néanmoins, une étendue vide (ou nulle, ou autre) ne nous empêche pas de
placer l'objet à l'endroit où nous le souhaitons -- on doit juste se
passer des procédures d'alignement. On peut toujours spécifier le
décalage désiré, et tout fonctionne comme à l'accoutumée :

@lilypond[quote,verbatim]
{
  \override Score.RehearsalMark.X-extent = ##f
  \override Score.RehearsalMark.X-offset = -10.4
  b4 b b b \mark "Twinkle" b b b b
}
@end lilypond

Il y a encore quelque chose à garder à l'esprit : le parent d'un
@emph{grob} a, lui aussi, ses propres dimensions, et nous devons en
tenir compte. Par exemple, si nous disons

@lilypond[quote,verbatim]
{ a'1 }
\addlyrics {
  \override LyricText.X-offset =
    #ly:self-alignment-interface::x-aligned-on-self
  \override LyricText.self-alignment-X = #CENTER
  nn
}
@end lilypond

@noindent
l'objet @code{LyricText} sera centré, mais @emph{sur le point de
référence de son parent} -- c'est à dire que le centre de la syllabe
s'alignera sur le point de référence de la tête de note. Si nous voulons
que le centre de l'objet @code{LyricText} s'aligne avec le centre de son
objet parent @code{NoteHead}, il nous faut recourir à une autre
procédure : @code{aligned-on-x-parent}. Son comportement est similaire à
@code{x-aligned-on-self} mais, en plus de calculer un décalage sur la
base de l'étendue d'un objet, elle utilise aussi l'étendue de l'objet
parent pour déterminer les positions relatives au centre de l'étendue :

@lilypond[quote,verbatim]
{ a'1 }
\addlyrics {
  \override LyricText.X-offset =
    #ly:self-alignment-interface::aligned-on-x-parent
  \override LyricText.self-alignment-X = #CENTER
  nn
}
@end lilypond


@need 1500
@node Placement of objects
@section Positionnement des objets


@node Automatic behavior
@subsection Comportement automatique

@cindex objets de la portée
@cindex objets extérieurs à la portée
@cindex portée, objets de la
@cindex portée, objets extérieurs à la

@cindex @code{outside-staff-priority}, propriété

Dans la notation musicale, il y a des objets qui appartiennent à la
portée et d'autres qui sont placés à l'extérieur de la portée. On les
appelle respectivement les « objets de la portée » (@emph{within-staff
objects} en anglais) et les « objets extérieurs à la portée »
(@emph{outside-staff objects} en anglais).

Les objets de la portée sont ceux qui sont placés sur la portée -- les
têtes de notes et les hampes, les altérations, etc. Leur position est
généralement déterminée par la musique elle-même -- ils sont placés
verticalement sur des lignes spécifiques ou sont liés à d'autres objets
placés de cette manière. Normalement, les collisions entre les têtes et
queues de notes et les altérations dans des accords proches sont évitées
automatiquement. Comme nous le verrons rapidement, il existe des
commandes et des possibilités de retouche qui permettent de modifier ce
comportement automatique.

Parmi les objets extérieurs à la portée, on compte des éléments comme
les marques de reprise, les indications de texte ou de nuance. Dans
LilyPond, la règle est de placer verticalement ces objets extérieurs à
la portée le plus près possible de la portée, tout en évitant la
collision avec d'autres objets. LilyPond utilise la propriété
@code{outside-staff-priority} pour déterminer l'ordre selon lequel
placer ces objets, de la manière suivante :

D'abord, LilyPond dresse la liste de tous les objets extérieurs à la
portée. Puis ceux-ci sont classés suivant leur
@code{outside-staff-priority}. Enfin, ils sont pris un par un, en
commençant par les objets avec la @code{outside-staff-priority} la plus
basse, et placés de façon à ne pas entrer en collision avec d'autres
objets déjà positionnés. Cela signifie que, si deux @emph{grobs}
extérieurs à la portée doivent occuper la même place, c'est celui qui a
la @code{outside-staff-priority} la plus basse qui est placé le plus
près de la portée. Et si deux objets ont la même
@code{outside-staff-priority}, le premier rencontré sera placé au plus
près de la portée.

Dans l'exemple suivant, tous les @emph{markup} ont la même priorité,
dans la mesure où rien n'est indiqué explicitement. Vous remarquerez que
@code{Text3} est également positionné près de la portée, juste
au-dessous de @code{Text2}.

@cindex @emph{markup}, exemple

@lilypond[quote,fragment,ragged-right,verbatim]
c''2^"Text1"
c''2^"Text2" |
c''2^"Text3"
c''2^"Text4" |
@end lilypond

Les portées aussi sont positionnées, par défaut, le plus près possible
les unes des autres, en ménageant tout de même une certaine séparation.
Si des notes se rapprochent nettement d'une portée adjacente, elles ne
forceront les portées à s'écarter que s'il y a un risque de
chevauchement.

@lilypond[quote,ragged-right,verbatim]
<<
  \new Staff {
    \relative { c'4 a, }
  }
  \new Staff {
    \relative { c''''4 a, }
  }
>>
@end lilypond


@node Within-staff objects
@subsection Objets inclus dans la portée

Nous avons vu que les commandes @code{\voice@var{XXX}} jouent sur la
direction des liaisons, des doigtés et sur tout autre élément lié à
l'orientation des hampes -- @pxref{Explicitly instantiating voices}. Ces
commandes sont essentielles dans la musique polyphonique pour distinguer
des lignes mélodiques entremêlées. Mais il arrive qu'on ait besoin de
modifier ce comportement automatique. On peut le faire pour toutes les
parties de la musique ou juste pour une note. La propriété qui contrôle
ce comportement est la propriété @code{direction} de chaque objet.
Expliquons d'abord ce qu'elle fait, puis nous présenterons un certain
nombre de commandes déjà prêtes qui évitent, pour les modifications les
plus courantes, d'avoir à encoder les retouches.

Certains objets comme les traits des liaisons se recourbent tantôt vers
le haut, tantôt vers le bas ; d'autres encore, comme les hampes et les
crochets, peuvent se décaler vers la gauche ou vers la droite selon
qu'ils pointent vers le haut ou vers le bas. Ce comportement est géré
automatiquement dès lors que @code{direction} est activé.


@node The direction property
@unnumberedsubsubsec La propriété @code{direction}

@cindex @code{DOWN}
@cindex @code{UP}
@cindex @code{CENTER}

L'exemple ci-dessous montre dans la première mesure le positionnement
par défaut des liaisons -- celles des notes les plus hautes en surplomb
des têtes et celles des notes les plus basses au-dessous ; viennent
ensuite une mesure avec les liaisons forcées vers le bas, puis une
mesure avec les liaisons forcées vers le haut, et pour finir une mesure
où elles adoptent de nouveau le comportement par défaut.

@cindex @code{Slur}, exemple de dérogation
@cindex @code{direction}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,verbatim]
a'4( g') c''( a') |
\override Slur.direction = #DOWN
a'4( g') c''( a') |
\override Slur.direction = #UP
a'4( g') c''( a') |
\revert Slur.direction
a'4( g') c''( a') |
@end lilypond

Nous utilisons ici les directions @code{DOWN} et @code{UP}. Elles
correspondent respectivement aux valeurs @code{-1} et @code{+1}, que
l'on peut utiliser à la place. La valeur @code{0} peut aussi être
utilisée dans certains cas. Elle est interprétée comme un @code{UP} pour
les liaisons, et comme un « centré » pour d'autres objets. Il existe une
direction, @code{CENTER}, qui correspond à la valeur @code{0}.

Quoi qu'il en soit, ces retouches manuelles sont rarement utilisées car
il existe des équivalents sous forme de commandes prédéfinies. Voici un
tableau des plus courantes. Lorsque ce n'est pas évident, leur
signification est précisée.

@smallindentedblock
@raggedright
@multitable {@code{\phrasingSlurDown}} {@code{\phrasingSlurUp}}{@code{\phrasingSlurNeutral}} {Text entered as spanner is}
@headitem Bas
  @tab Haut
  @tab Annulation
  @tab Effet
@item @code{\dotsDown}
  @tab @code{\dotsUp}
  @tab @code{\dotsNeutral}
  @tab Déplacement des points pour éviter les lignes de portée
@item @code{\dynamicDown}
  @tab @code{\dynamicUp}
  @tab @code{\dynamicNeutral}
  @tab
@item @code{\phrasingSlurDown}
  @tab @code{\phrasingSlurUp}
  @tab @code{\phrasingSlurNeutral}
  @tab Attention : à distinguer des commandes de liaison ci-dessous
@item @code{\slurDown}
  @tab @code{\slurUp}
  @tab @code{\slurNeutral}
  @tab
@item @code{\stemDown}
  @tab @code{\stemUp}
  @tab @code{\stemNeutral}
  @tab
@item @code{\textSpannerDown}
  @tab @code{\textSpannerUp}
  @tab @code{\textSpannerNeutral}
  @tab Le texte saisi en tant qu'extension est au-dessous/au-dessus de
  la portée
@item @code{\tieDown}
  @tab @code{\tieUp}
  @tab @code{\tieNeutral}
  @tab
@item @code{\tupletDown}
  @tab @code{\tupletUp}
  @tab @code{\tupletNeutral}
  @tab Les n-olets sont au-dessous/au-dessus des notes
@end multitable
@end raggedright
@end smallindentedblock

Les variantes @code{\@var{xxx}Neutral} de ces commandes sont
implémentées à l'aide de @code{\revert} ; elles @strong{ne doivent pas}
être précédées de @code{\once}. Pour limiter les effets des autres
commandes prédéfinies (fonctionnant à base de @code{\override}) à une
seule note, il faut les faire précéder d'un @code{\once}, comme pour
toute dérogation.

Dans le cas où un seul objet de rendu doit déroger à la règle, LilyPond
dispose des indicateurs de positionnement @samp{^} et @samp{_} :

@lilypond[quote,fragment,verbatim]
a'4( g') c''( a') |
a'4^( g') c''_( a') |
@end lilypond


@node Fingering
@unnumberedsubsubsec Doigtés

@cindex doigtés, positionnement
@cindex doigtés, accords

Le placement des doigtés sur des notes simples peut aussi être contrôlé
par la propriété @code{direction}, mais le changement de
@code{direction} n'a pas d'effet sur les accords. Comme nous le verrons,
il existe des commandes qui permettent de contrôler le doigté sur chaque
note d'un accord, en plaçant l'indication de doigté au-dessus, en
dessous, à gauche ou à droite de chaque note.

Tout d'abord, voici l'effet de @code{direction} sur le doigté lié à une
note simple. La première mesure montre le comportement par défaut, et
les deux suivantes montrent l'effet lorsqu'on indique @code{DOWN} et
@code{UP} :

@cindex doigtés, exemple de dérogation
@cindex @code{Fingering}, exemple de dérogation
@cindex @code{direction}, exemple d'utilisation de la propriété

@lilypond[quote,verbatim]
\relative {
  c''4-5 a-3 f-1 c'-5 |
  \override Fingering.direction = #DOWN
  c4-5 a-3 f-1 c'-5 |
  \override Fingering.direction = #UP
  c4-5 a-3 f-1 c'-5 |
}
@end lilypond

@funindex -
@funindex ^
@funindex _

Le fait d'intervenir sur la propriété @code{direction} n'est sûrement
pas la façon la plus simple de placer manuellement les doigtés au-dessus
ou en dessous des notes ; mieux vaut utiliser @code{_} ou @code{^}
devant le chiffre de doigté plutôt que @code{-}. Voici ce que donne
l'exemple précédent avec cette méthode :

@cindex doigtés, exemple

@lilypond[quote,verbatim]
\relative {
  c''4-5 a-3 f-1 c'-5 |
  c4_5 a_3 f_1 c'_5 |
  c4^5 a^3 f^1 c'^5 |
}
@end lilypond

La propriété @code{direction} ne fonctionne pas pour les accords alors
que les préfixes de direction, @samp{_} et @samp{^}, fonctionnent. Par
défaut, le doigté est placé automatiquement à la fois au-dessus et
au-dessous des notes d'un accord, comme ceci :

@cindex doigtés, exemple

@lilypond[quote,verbatim]
\relative {
  <c''-5 g-3>4
  <c-5 g-3 e-2>4
  <c-5 g-3 e-2 c-1>4
}
@end lilypond

@noindent
mais il est possible de forcer manuellement vers le haut ou vers le bas
le placement de tous ou certains chiffres de doigté, comme ceci :

@cindex doigtés, exemple

@lilypond[quote,verbatim]
\relative {
  <c''-5 g-3 e-2 c-1>4
  <c^5 g_3 e_2 c_1>4
  <c^5 g^3 e^2 c_1>4
}
@end lilypond

@cindex @code{fingeringOrientations}, propriété

On peut aller encore plus loin dans le positionnement des doigtés pour
chacune des notes d'un accord grâce à la commande
@code{\set fingeringOrientations}. La syntaxe de cette commande est :

@example
\set fingeringOrientations = #'([up] [left/right] [down])
@end example

@noindent
On utilise @code{\set} car @code{fingeringOrientations} est une
propriété du contexte @code{Voice}, créée et utilisée par le graveur
@code{New_fingering_engraver}.

On peut attribuer à cette propriété une liste composée de une à trois
valeurs.  Celles-ci déterminent si l'indication de doigté doit être
placée au-dessus (lorsque @code{up} apparaît dans la liste), au-dessous
(lorsque @code{down} apparaît), à gauche (lorsque @code{left} apparaît)
ou à droite (lorsque @code{right} apparaît).  En revanche, si une valeur
n'est pas dans la liste, aucun doigté n'ira à cet emplacement.  LilyPond
garde ces contraintes en mémoire et recherche le meilleur emplacement
pour le doigté des notes des accords suivants.  Vous remarquerez que
@code{left} et @code{right} s'excluent l'un l'autre -- l'indication de
doigté ne peut être placée que d'un côté ou de l'autre, pas des deux.

@warning{Pour contrôler à l'aide de cette commande le placement du
doigté sur une note simple, il faut la saisir comme un accord composé
d'une note unique, en l'encadrant de chevrons.}

Voici quelques exemples :

@cindex doigtés, exemple
@cindex @code{\set}, exemple d'utilisation
@cindex @code{fingeringOrientations}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative {
  \set fingeringOrientations = #'(left)
  <f'-2>4
  <c-1 e-2 g-3 b-5>4
  \set fingeringOrientations = #'(left)
  <f-2>4
  <c-1 e-2 g-3 b-5>4 |
  \set fingeringOrientations = #'(up left down)
  <f-2>4
  <c-1 e-2 g-3 b-5>4
  \set fingeringOrientations = #'(up left)
  <f-2>4
  <c-1 e-2 g-3 b-5>4 |
  \set fingeringOrientations = #'(right)
  <f-2>4
  <c-1 e-2 g-3 b-5>4
}
@end lilypond

@noindent
Si les indications de doigtés paraissent un peu serrées, on peut
toujours réduire la taille de police (@code{font-size}). La valeur par
défaut donnée dans la RPI à la page de l'objet @code{Fingering} étant
@code{-5}, essayons @w{@code{-7}} :

@lilypond[quote,ragged-right,verbatim]
\relative {
  \override Fingering.font-size = -7
  \set fingeringOrientations = #'(left)
  <f'-2>4
  <c-1 e-2 g-3 b-5>4
  \set fingeringOrientations = #'(left)
  <f-2>4
  <c-1 e-2 g-3 b-5>4 |
  \set fingeringOrientations = #'(up left down)
  <f-2>4
  <c-1 e-2 g-3 b-5>4
  \set fingeringOrientations = #'(up left)
  <f-2>4
  <c-1 e-2 g-3 b-5>4 |
  \set fingeringOrientations = #'(right)
  <f-2>4
  <c-1 e-2 g-3 b-5>4
}
@end lilypond


@node Outside-staff objects
@subsection Objets hors de la portée

Les objets extérieurs à la portée sont placés automatiquement de façon à
éviter les collisions. Il est toutefois possible, grâce à différentes
méthodes, de rectifier un positionnement automatique qui se révélerait
ne pas être optimal.


@node The outside-staff-priority property
@unnumberedsubsubsec La propriété @code{outside-staff-priority}

Les objets avec la plus petite valeur de la propriété
@code{outside-staff-priority} sont placés au plus près de la portée,
tandis que les autres sont écartés autant qu'il faut pour éviter les
collisions. La @code{outside-staff-priority} est définie dans la
@code{grob-interface} ; elle est donc une propriété commune à tous les
objets de rendu. Par défaut, elle est réglée sur @code{#f} pour tous les
objets de la portée, et porte une valeur numérique appropriée à chacun
des objets extérieurs à la portée, à mesure qu'ils sont créés. Une
@rnotationnamed{Default values for outside-staff-priority, annexe
spécifique} recense les différents objets concernés, avec leur valeur
par défaut.

@cindex @emph{spanner}
@cindex bandeaux
@cindex extenseurs

Vous noterez au passage certaines particularités quant au nom des
objets. En effet, des objets à extension sont automatiquement créés dans
le but de pouvoir contrôler le positionnement vertical des extrémités
d'un @emph{grob} qui commencerait et se terminerait à des instants
musicaux différents. C'est la raison pour laquelle modifier le
@code{outside-staff-priority} du @emph{grob} sous-jacent n'aura aucun
effet. C'est par exemple le cas lorsque vous modifiez l'alignement d'un
objet @code{Hairpin} à l'aide de @code{outside-staff-priority} ; puisque
le soufflet est associé à un objet @code{DynamicLineSpanner}, c'est sur
celui-ci que doit porter l'effet de @code{outside-staff-priority}.
L'instruction dérogatoire se place au début du bandeau qui constitue une
ligne de base susceptible de contenir plusieurs soufflets ou indications
de nuance.

Voici un exemple qui montre le placement par défaut de certains
d'entre eux.

@cindex extension de texte
@cindex indication d'octaviation

@funindex \startTextSpan
@funindex \stopTextSpan

@cindex @code{TextSpanner}, exemple de dérogation
@cindex @code{bound-details}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,ragged-right,verbatim]
% set details for later TextSpanner
\override TextSpanner.bound-details.left.text =
  \markup { \small \bold Slower }
% place dynamics above staff
\dynamicUp
% start ottava bracket
\ottava 1
c''4 \startTextSpan
% add dynamic text and hairpin
c''4\pp\<
c''4
% add text script
c''4^Text |
c''4 c''
% add dynamic text and terminate hairpin
c''4\ff c'' \stopTextSpan |
% stop ottava bracket
\ottava 0
c'4 c' c' c' |
@end lilypond

Cet exemple montre comment créer des extensions de texte (@emph{text
spanners} en anglais) -- texte avec des longues lignes au-dessus d'un
passage musical. L'extension s'étend depuis la commande
@code{\startTextSpan} jusqu'à la commande @code{\stopTextSpan} et le
format de texte est défini par la commande @code{\override TextSpanner}.
Pour de plus amples détails, voir @rnotationnamed{Text spanners,
Indication textuelle avec extension}.

Il montre aussi comment créer des marques d'octaviation.

@cindex modification du positionnement des numéros de mesure
@cindex numéro de mesure, modification du positionnement
@cindex modification du positionnement des indications métronomiques
@cindex indication métronomique, modification du positionnement
@cindex modification du positionnement des marques de repère
@cindex marque de repère, modification du positionnement

Si les valeurs de @code{outside-staff-priority} par défaut ne donnent
pas les résultats escomptés, il suffit de modifier la priorité de l'un
de ces objets. Supposons que vous vouliez placer l'indication
d'octaviation sous le bandeau de texte, dans l'exemple précédent. Tout
ce que nous devons faire, c'est regarder la priorité de
@code{OttavaBracket} dans la Référence des propriétés internes ou dans
@rnotationnamed{Default values for outside-staff-priority, Valeurs par
défaut de @code{outside-staff-priority}}, et la ramener à une valeur
plus basse que celle de @code{TextSpanner}, en gardant à l'esprit que
@code{OttavaBracket} est créé dans le contexte @code{Staff} :

@cindex @code{TextSpanner}, exemple de dérogation
@cindex @code{bound-details}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,ragged-right,verbatim]
% set details for later text spanner
\override TextSpanner.bound-details.left.text =
  \markup { \small \bold Slower }
% place dynamics above staff
\dynamicUp
% place following ottava bracket below text spanners
\once \override Staff.OttavaBracket.outside-staff-priority = 340
% start ottava bracket
\ottava 1
c''4 \startTextSpan
% add dynamic text
c''4\pp
% add dynamic line spanner
c''4\<
% add text script
c''4^Text |
c''4 c''
% add dynamic text
c''4\ff c'' \stopTextSpan |
% stop ottava bracket
\ottava 0
c'4 c' c' c' |
@end lilypond

N'oublions pas que certains objets, tels les numéros de mesure,
indications métronomiques et marques-repères, sont par défaut attachés
au contexte @code{Score}.

@cindex liaison et @code{outside-staff-priority}
@cindex liaison et articulations
@cindex articulation et liaisons

@cindex @code{avoid-slur}, propriété

Les liaisons sont intrinsèquement des objets membres de la portée
(@emph{within-staff objects}) bien qu'elles la surplombent lorsque les
notes auxquelles elles se rattachent sont relativement hautes. Ceci peut
avoir pour conséquence de remonter d'autant les objets externes
(@emph{outside-staff objects}) tels les articulations. La propriété
@code{avoid-slur} de l'articulation en question peut se voir déterminée
à @code{'inside} dans le but de « ramener » cette articulation à
l'intérieur de la liaison. Cette propriété @code{avoid-slur} ne sera
toutefois effective que dans la mesure où la
@code{outside-staff-priority} est désactivée (valeur @code{#f}). Dans le
même esprit, il est possible d'affecter une valeur numérique
particulière à la propriété @code{outside-staff-priority} d'une liaison
dans le but de regrouper la liaison avec les objets externes. L'exemple
suivant illustre ces deux différentes méthodes.

@lilypond[quote,verbatim]
\relative c'' {
  c4( c^\markup { \tiny \sharp } d4.) c8 |
  c4(
    \once \override TextScript.avoid-slur = #'inside
    \once \override TextScript.outside-staff-priority = ##f
    c4^\markup { \tiny \sharp } d4.) c8 |
  \once \override Slur.outside-staff-priority = 500
    c4( c^\markup { \tiny \sharp } d4.) c8 |
}
@end lilypond

Le fait de changer la @code{outside-staff-priority} peut aussi servir à
contrôler le positionnement vertical des objets individuels, quoique le
résultat ne soit pas toujours formidable. Imaginons que nous voulions
placer « Text3 » au-dessus de « Text4 » dans l'exemple de la section
@ref{Automatic behavior}, plus haut. Il nous suffit pour cela de
regarder dans la Référence des propriétés internes ou dans le tableau
plus haut la priorité de @code{TextScript}, et d'augmenter la priorité
de « Text3 » jusqu'à une valeur très haute :

@cindex @code{TextScript}, exemple de dérogation
@cindex @code{outside-staff-priority}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,ragged-right,verbatim]
c''2^"Text1"
c''2^"Text2" |
\once \override TextScript.outside-staff-priority = 500
c''2^"Text3"
c''2^"Text4" |
@end lilypond

S'il est vrai que cela place « Text3 » au-dessus de « Text4 », ça le
place aussi plus haut que « Text2 » tandis que « Text4 » dégringole. Ce
n'est peut-être pas si bien que ça. En fait, ce que nous aimerions
faire, c'est placer toutes les annotations à égale distance de la
portée. Pour cela, nous avons besoin d'espacer horizontalement les notes
pour laisser plus de place au texte. C'est possible grâce à la commande
@code{\textLengthOn}.


@node The textLengthOn command
@unnumberedsubsubsec La commande @code{\textLengthOn}

@cindex notes, répartition selon le texte

@funindex \textLengthOn
@funindex \textLengthOff

Par défaut, l'espacement horizontal d'un texte produit sous forme de
@emph{markup} (ou d'étiquette) n'est pas pris en compte, dans la mesure
où ce qui est concerné n'entre pas dans la musique. La commande
@code{\textLengthOn} modifie ce comportement, faisant en sorte que les
notes soient espacées autant qu'il le faut pour s'adapter au texte :

@lilypond[quote,fragment,ragged-right,verbatim]
\textLengthOn  % Cause notes to space out to accommodate text
c''2^"Text1"
c''2^"Text2" |
c''2^"Text3"
c''2^"Text4" |
@end lilypond

@funindex \markLengthOn
@funindex \markLengthOff

La commande qui permet de revenir au comportement par défaut est
@code{\textLengthOff}. Alternativement, lorsque l'instruction
@code{\textLengthOn} se limite à un seul instant musical, vous pouvez la
préfixer d'un @code{\once}.@*
LilyPond dispose de commandes équivalentes
et dévolues au traitement des repères et indications de tempo :
@code{\markLengthOn} et @code{\markLengthOff}.

@cindex @'etiquette de texte et collision
@cindex @emph{markup} et collision

Les textes des @emph{markup} éviteront également les notes qui
s'échappent au-dessus de la portée. Si ce n'est pas notre souhait, il
est possible de supprimer ce déplacement automatique vers le haut en
attribuant à la priorité la valeur @code{#f}. Voici un exemple qui
montre comment les textes des @emph{markup} interagissent avec ces types
de note.

@cindex @code{TextScript}, exemple de dérogation
@cindex @code{outside-staff-priority}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative {
  % This markup is short enough to fit without collision
  c''2^"Tex" c'' |
  R1 |

  % This is too long to fit, so it is displaced upwards
  c,,2^"Text" c'' |
  R1 |

  % Turn off collision avoidance
  \once \override TextScript.outside-staff-priority = ##f
  c,,2^"Long Text   " c'' |
  R1 |

  % Turn off collision avoidance
  \once \override TextScript.outside-staff-priority = ##f
  \textLengthOn        % and turn on textLengthOn
  c,,2^"Long Text   "  % Spaces at end are honored
  c''2 |
}
@end lilypond


@node Dynamics placement
@unnumberedsubsubsec Positionnement des nuances

@cindex modification du positionnement des nuances
@cindex nuances, modification du positionnement

Les indications de nuance se placent normalement sous la portée, mais on
peut les placer au-dessus avec la commande @code{\dynamicUp}. Elles se
positionnent verticalement par rapport à la note à laquelle elles sont
liées et se décalent vers le bas (ou le haut) en fonction des objets de
la portée comme les liaisons de phrasé ou les numéros de mesure. Cela
peut donner d'assez bons résultats, comme le montre cet exemple :

@lilypond[quote,ragged-right,verbatim]
\relative {
  \clef "bass"
  \key aes \major
  \time 9/8
  \dynamicUp
  bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
  ees,2.~\)\mf ees4 r8 |
}
@end lilypond

De toute façon, si les notes et les nuances qui leur sont liées sont
trop proches, le positionnement automatique évitera les collisions en
déplaçant davantage les nuances suivantes, mais le résultat peut ne pas
être très satisfaisant, comme le montre cet exemple artificiel :

@lilypond[quote,ragged-right,verbatim,fragment]
\dynamicUp
\relative { a'4\f b\mf a\mp b\p }
@end lilypond

@noindent
Si une telle situation devait survenir dans de la musique « réelle », il
serait préférable d'espacer un peu plus les notes, de façon que les
indications de nuance puissent toutes se situer à la même distance de la
portée. S'il est possible de faire cela pour les textes de @emph{markup}
grâce à la commande @code{\textLengthOn}, il n'existe pas d'équivalent
pour les indications de nuance. Il nous faut donc chercher à faire cela
avec la commande @code{\override}.


@node Grob sizing
@unnumberedsubsubsec Dimensionnement des objets graphiques

@cindex @emph{grob}, dimensionnement
@cindex dimensionnement des @emph{grobs}

En règle générale, tous les objets graphiques disposent de la
@code{grob-interface} qui contient, entre autres, les propriétés
@code{X-offset}, @code{Y-offset}, @code{X-extent} et @code{Y-extent}
-- @pxref{Offsets and alignments} pour une introduction minutieuse.

@cindex @code{extra-spacing-width}, propriété

Par défaut, la largeur des objets extérieurs à la portée est donnée
comme étant nulle, si bien qu'ils peuvent se chevaucher horizontalement.
Pour remédier à cela, on a ajouté l'infini à l'extension gauche et moins
l'infini à l'extension droite, en attribuant à
@code{extra-spacing-width} la valeur @code{'(+inf.0 . -inf.0)}. Pour
être sûr que les objets ne se chevaucheront pas horizontalement, nous
devons donc corriger cette valeur de @code{extra-spacing-width} pour
leur attribuer un peu d'espace supplémentaire. L'unité de base est ici
la largeur séparant deux lignes de portée ; décaler le bord gauche d'une
demie unité vers la gauche et le bord droit d'une demie unité vers la
droite devrait suffire :

@example
\override DynamicText.extra-spacing-width = #'(-0.5 . 0.5)
@end example

@noindent
Voyons si ça marche sur notre exemple précédent :

@cindex @code{DynamicText}, exemple de dérogation
@cindex @code{extra-spacing-width}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim,fragment]
\dynamicUp
% Extend width by 1 staff space
\override DynamicText.extra-spacing-width = #'(-0.5 . 0.5)
\relative { a'4\f b\mf a\mp b\p }
@end lilypond

@noindent
C'est mieux mais nous voulons peut-être aligner les indications de
nuance sur une même ligne plutôt que de les voir monter et descendre
avec les notes. La propriété qui gère cela est @code{staff-padding} --
voir @ref{Collisions of objects}.


@node Vertical spacing
@section Espacement vertical

En règle générale, LilyPond est plutôt performant en matière
d'espacement vertical des objets musicaux. Examinons ce qui se passe
avec un chant simple à deux voix accompagnées au piano :

@lilypond[quote,fragment,ragged-right]
<<
  \new ChoirStaff
  <<
    \new Staff {
      \new Voice = "music" {
        b'2 c' c' c'
      }
    }
    \new Lyrics
    \lyricsto "music" {
      Here are some lyrics
    }
    \new Staff {
      \clef bass e'2 f e c
    }
  >>
  \new PianoStaff
  <<
    \new Staff {
      g''2 c'' c'' a''
    }
    \new Staff {
      \clef bass e2 f c e
    }
  >>
>>
@end lilypond

Il n'y a rien à redire quant à l'espacement vertical. Toutefois, partons
du principe que nous travaillons avec un éditeur dont les exigences en
matière d'espacement vertical sont les suivantes : les paroles doivent
être clairement détachées des notes, l'accompagnement de piano séparé du
chant et les portées de piano rapprochées l'une de l'autre. Commençons
par les paroles.

Les paroles résident dans un système ; les commandes dévolues à leur
espacement sont donc mentionnées à la section @rnotationnamed{Flexible
vertical spacing within systems, Espacement vertical au sein d'un
système}. Nous y constatons que les paroles sont des lignes de
non-portée (@emph{non-staff lines}) ; les commandes qui gèrent leur
espacement font donc référence à des propriétés dont le nom contient
@code{nonstaff}. Les décaler de la portée à laquelle elles sont
attachées (celle du haut) jouera sur le vocable @code{relatedstaff}, les
décaler de la ligne inférieure sur le vocable @code{unrelatedstaff}. Les
parties vocales sont membre d'un @code{VerticalAxisGroup} ; ce sont donc
les propriétés de ce groupe qui doivent être ajustées. Faisons un
premier essai pour voir :

@cindex @code{VerticalAxisGroup}
@cindex @code{padding}, sous-propriété
@cindex @code{nonstaff-relatedstaff-spacing}, propriété
@cindex @code{nonstaff-unrelatedstaff-spacing}, propriété

@lilypond[quote,fragment,ragged-right,verbatim]
<<
  \new ChoirStaff
  <<
    \new Staff {
      \new Voice = "music" {
        b'2 c' c' c'
      }
    }
    \new Lyrics \with {
      \override VerticalAxisGroup
                .nonstaff-relatedstaff-spacing.padding = 5
      \override VerticalAxisGroup
                .nonstaff-unrelatedstaff-spacing.padding = 5
    }
    \lyricsto "music" {
      Here are some lyrics
    }
    \new Staff {
      \clef bass e'2 f e c
    }
  >>
  \new PianoStaff
  <<
    \new Staff {
      g''2 c'' c'' a''
    }
    \new Staff {
      \clef bass e2 f c e
    }
  >>
>>
@end lilypond

L'espacement est maintenant quelque peu exagéré. Lorsque nous
affectons 5 à la variable @code{padding}, LilyPond ajoute cinq espaces
de portée à la distance séparant deux objets, ce qui est plus que
généreux. Nous nous limiterons à 2.

@cindex @code{StaffGrouper}
@cindex @code{ChoirStaff}, contexte
@cindex @code{basic-distance},sous-propriété
@cindex @code{staffgroup-staff-spacing}, propriété

Occupons-nous à présent de séparer l'accompagnement du chant. La musique
vocale fait l'objet d'un contexte @code{ChoirStaff} ; il nous faut donc
augmenter l'espace entre ce groupe et la portée de piano qui le suit.
Nous y parviendrons en modifiant la sous-propriété @code{basic-distance}
de la @code{staffgroup-staff-spacing} du @emph{grob} @code{StaffGrouper}.

@lilypond[quote,fragment,ragged-right,verbatim]
<<
  \new ChoirStaff \with {
    \override StaffGrouper
              .staffgroup-staff-spacing.basic-distance = 15
  }
  <<
    \new Staff {
      \new Voice = "music" {
        b'2 c' c' c'
      }
    }
    \new Lyrics \with {
      \override VerticalAxisGroup
                .nonstaff-relatedstaff-spacing.padding = 2
      \override VerticalAxisGroup
                .nonstaff-unrelatedstaff-spacing.padding = 2
    }
    \lyricsto "music" {
      Here are some lyrics
    }
    \new Staff {
      \clef bass e'2 f e c
    }
  >>
  \new PianoStaff
  <<
    \new Staff {
      g''2 c'' c'' a''
    }
    \new Staff {
      \clef bass e2 f c e
    }
  >>
>>
@end lilypond

Excellent. Ne reste plus qu'à répondre à la dernière exigence :
resserrer les portées du piano. Pour y parvenir, nous ajusterons à
nouveau les propriétés du @emph{grob} @code{StaffGrouper}, ici en jouant
à la fois sur la distance de base (@code{basic-distance}) et le décalage
(@code{padding}) comme ci-dessous :

@lilypond[quote,fragment,ragged-right,verbatim]
<<
  \new ChoirStaff \with {
    \override StaffGrouper
              .staffgroup-staff-spacing.basic-distance = 15
  }
  <<
    \new Staff {
      \new Voice = "music" {
        b'2 c' c' c'
      }
    }
    \new Lyrics \with {
      \override VerticalAxisGroup
                .nonstaff-relatedstaff-spacing.padding = 2
      \override VerticalAxisGroup
                .nonstaff-unrelatedstaff-spacing.padding = 2
    }
    \lyricsto "music" {
      Here are some lyrics
    }
    \new Staff {
      \clef bass e'2 f e c
    }
  >>
  \new PianoStaff \with {
    \override StaffGrouper.staff-staff-spacing =
                #'((basic-distance . 0)
                   (padding . 0))
  }
  <<
    \new Staff {
      g''2 c'' c'' a''
    }
    \new Staff {
      \clef bass e2 f c e
    }
  >>
>>
@end lilypond

Les portées sont vraiment rapprochées, mais c'est ce que veut l'éditeur.
On pourra toujours les écarter au besoin en jouant sur les éléments
@code{padding} ou @code{basic-distance}.

Il existe bien des manières de modifier l'espacement vertical. Le point
crucial à ne pas oublier est que l'espacement des objets au sein d'un
regroupement -- un @code{StaffGroup}, tels @code{GrandStaff} ou
@code{PianoStaff} -- dépend des variables d'espacement d'un
@code{StaffGrouper} ; l'espacement de portées non regroupées (comme
@code{Lyrics} et @code{Staff}) dépend des variables d'un
@code{VerticalAxisGroup}. Voir @rnotationnamed{Flexible vertical spacing
paper variables, Variables d'espacement vertical fluctuant} et
@rnotationnamed{Flexible vertical spacing within systems, Espacement
vertical au sein d'un système} pour de plus amples détails.


@node Collisions of objects
@section Collisions d'objets

Les trucs et astuces présentés dans cette section sont l'application et
l'extension d'aspects vus précédemment dans ce manuel. Vous devriez vous
sentir à l'aise avec les concepts d'@dfn{extent}, @dfn{offset} et
@dfn{alignment}, @pxref{Offsets and alignments}.


@node Moving objects
@subsection Déplacement d'objets

@cindex déplacement d'objets se chevauchant
@cindex déplacement d'objets en collision
@cindex déplacement de @emph{grobs} en collision
@cindex objets, évitement des collisions
@cindex @emph{grobs}, évitement des collisions

Aussi surprenant que cela puisse paraître, LilyPond n'est pas parfait.
Certains éléments sur la partition peuvent se chevaucher, ce qui est
regrettable mais, le plus souvent, facile à corriger. En général, quand
on déplace des objets, c'est pour des raisons de lisibilité ou
d'esthétique -- ils rendraient mieux avec un peu plus ou un peu moins
d'espace autour d'eux.

Il y a trois façons de résoudre les problèmes de chevauchement. Il est
préférable de les aborder dans l'ordre suivant :

@enumerate
@item
L'@strong{orientation} d'un objet qui en chevauche un autre peut être
changée grâce aux commandes prédéfinies dont la liste a été donnée plus
haut à propos des objets de portée ( @pxref{Within-staff objects}). Les
queues de note, les liaisons de phrasé et de prolongation, les crochets,
les nuances et les n-olets peuvent facilement être repositionnés de
cette manière. En contrepartie, vous n'avez le choix qu'entre deux
positions, sans personnalisation possible.

@item
Les @strong{propriétés d'objet}, auxquelles LilyPond a recours pour
positionner les objets, sont modifiables avec @code{\override}. Il y a
deux avantages à changer ces propriétés : (a) d'autres objets pourront
être déplacés automatiquement si nécessaire pour faire de la place et
(b) la même retouche peut s'appliquer à toutes les occurrences du même
type d'objet. Ces propriétés sont :

@itemize

@item
@code{direction}

Ce point a déjà été traité en détails -- @pxref{Within-staff objects}.


@item
@code{padding}, @code{right-padding}, @code{staff-padding}

@cindex décalage (padding)
@cindex @code{padding}, propriété
@cindex @code{right-padding}, propriété
@cindex @code{staff-padding}, propriété

Au moment de positionner un objet, la valeur de sa propriété
@code{padding} détermine l'espace à laisser libre entre celui-ci et le
coin le plus proche de l'objet à côté duquel il est placé. Vous
remarquerez que c'est la valeur @code{padding} de l'objet @strong{à
placer} qui compte ; la valeur @code{padding} de l'objet déjà placé est
ignorée. Les espaces libres déterminés par @code{padding} s'appliquent à
tous les objets associés à la @code{side-position-interface}.

Le positionnement de groupes d'altérations est contrôlé par
@code{right-padding}, et non plus @code{padding}. Cette propriété
appartient à l'objet @code{AccidentalPlacement} qui, vous le
remarquerez, prend place dans le contexte @strong{Staff}. Dans le
processus de composition, les têtes de notes sont disposées en premier,
puis les altérations, s'il y en a, sont ajoutées à gauche des têtes de
note suivant la propriété @code{right-padding} qui détermine
l'espacement par rapport aux têtes de note. C'est pourquoi seule la
propriété @code{right-padding} de l'objet @code{AccidentalPlacement}
joue sur le positionnement des altérations.

La propriété @code{staff-padding} est très proche de la propriété
@code{padding} : @code{padding} contrôle l'espace minimum entre un objet
qui accepte la @code{side-position-interface} et l'objet le plus proche
(généralement une note ou une ligne de portée) ; @code{staff-padding} ne
s'applique qu'aux objets qui sont toujours placés au-dehors de la portée
-- il contrôle l'espace minimum à insérer entre la portée et l'objet
extérieur. Attention : @code{staff-padding} concerne les objets
positionnés par rapport à la portée et n'a aucun effet sur les objets
qui sont positionnés par rapport à une note ; tout aménagement qui lui
serait apporté ne provoquera pas d'erreur, mais sera ignoré.

Pour trouver quelle propriété @code{padding} employer pour l'objet que
vous cherchez à repositionner, il vous faut consulter les propriétés de
l'objet dans la Référence des propriétés internes. Prenez garde que les
propriétés @code{padding} ne sont pas forcément traitées dans l'objet en
question ; il faut alors regarder les objets qui semblent s'en
rapprocher.

Toutes les valeurs @code{padding} sont exprimées en espace de portée.
Pour la plupart des objets, la valeur par défaut est aux alentours de
1,0 et parfois moins (cela dépend de chaque objet). Il est possible de
la modifier lorsqu'on a besoin d'un espace vide plus grand (ou plus
petit).


@item
@code{self-alignment-X}

@cindex @code{self-alignment-X},  propriété

Cette propriété sert à aligner les objets sur la gauche, sur la droite
ou à les centrer par rapport au point de référence des objets parents.
Elle peut être utilisée avec tous les objets qui acceptent la
@code{self-alignment-interface}. Il s'agit, en général, des objets qui
contiennent du texte. Les valeurs admises sont @code{LEFT}, @code{RIGHT}
et @code{CENTER}. On peut aussi attribuer à la place une valeur
numérique entre @code{-1} et @code{+1}, où @code{-1} signifie alignement
sur la gauche, @code{+1} alignement sur la droite, et les nombres
intermédiaires déplacent progressivement le texte de la gauche vers la
droite. Des valeurs numériques supérieures à @code{1} sont également
admises pour déplacer le texte encore plus loin vers la gauche, ou des
valeurs inférieures à @code{-1} pour déplacer le texte encore plus loin
vers la droite. Un écart de @code{1} en valeur correspond à un
déplacement de la moitié de la longueur du texte.


@item
@code{extra-spacing-width}

@cindex @code{extra-spacing-width}, propriété

Cette propriété est utilisée pour tous les objets qui acceptent la
@code{item-interface}. Elle reçoit deux nombres, le premier étant ajouté
au bord gauche et le second au bord droit. Des nombres négatifs
déplacent le coin vers la gauche, des nombres positifs vers la droite,
si bien que pour élargir un objet, le premier nombre doit être négatif
et le second positif. Attention : tous les objets n'acceptent pas
forcément les deux nombres. Par exemple, l'objet @code{Accidental} ne
retient que le premier nombre (coin gauche).


@item
@code{staff-position}

@cindex @code{staff-position}, propriété

Cette propriété est attachée à la
@code{staff-symbol-referencer-interface}, qui s'applique aux objets
positionnés par rapport à la portée. Elle indique, en demi-espace de
portée, la position verticale des objets par rapport à la ligne médiane
de la portée. C'est bien pratique pour résoudre des problèmes de
collision entre des objets comme les silences valant mesure entière, les
liaisons et les notes de différentes voix.


@item
@code{horizontal-shift}

@cindex @code{horizontal-shift}, propriété
@cindex notes, empilement
@cindex empilement de notes
@cindex notes, collisions
@cindex collisions de notes
@cindex @emph{shift}, commandes
@funindex \shiftOff
@funindex \shiftOn
@funindex \shiftOnn
@funindex \shiftOnnn

Au sein d'une même voix, toutes les notes intervenant au même instant
musical sont regroupées dans un @dfn{empilement} (une colonne) et est
créé un objet @code{NoteColumn} afin de contrôler le positionnement
horizontal de ce groupe de notes -- voir « Empilement de notes » dans
@ref{Explicitly instantiating voices}. Si, et seulement si deux ou
plusieurs empilements au sein d'un même contexte de portée ont une
orientation de hampe identique et se produisent au même instant musical,
les valeurs de leurs propriétés @code{horizontal-shift} permettront de
les ordonner, les empilements de rang supérieur étant progressivement
décalés pour éviter les chevauchements des têtes. Cette propriété est
déterminée par les commandes @code{\voice@var{XXX}} et peut se voir
aménagée par une commande @code{\override} ou, plus habituellement, par
les commandes @code{\shiftOn}. Notez bien que cette propriété ne fait
qu'affecter un rang aux empilements pour leur décalage ; elle ne
détermine en rien la magnitude du décalage, qui sera augmentera
progressivement et selon un pas proportionnel à la largeur des têtes de
chaque rang. Le pas, généralement de la moitié de la largeur d'une tête,
peut aller jusqu'à la pleine largeur de tête en cas de groupes
resserrés.

@item
@code{force-hshift}

@cindex @code{force-hshift}, propriété

La propriété @code{force-hshift} appartient aux @emph{grobs}
@code{NoteColumn} (en réalité à la @code{note-column-interface}). Le
fait de la modifier permet de déplacer un empilement dans le cas de
chevauchement d'empilements. Notez bien qu'elle sera sans effet en
l'absence de chevauchement. Elle s'exprime en unité appropriée aux
colonnes de notes, à savoir la largeur des têtes de note de la première
voix. Son utilisation est réservée à des situations complexes dans
lesquelles les commandes habituelles @code{\shiftOn} (@pxref{Explicitly
instantiating voices}) ne suffisent plus à résoudre les conflits. Elle
est alors préférable à l'utilisation de la propriété
@code{extra-offset}, dans la mesure où on n'a pas besoin d'exprimer la
distance en espace de portée et où le fait de déplacer les notes à
l'intérieur ou à l'extérieur d'une @code{NoteColumn} affecte d'autres
actions comme les fusions de notes.

@end itemize


@item
Pour terminer, quand toutes les autres méthodes ont échoué, il est
possible de repositionner verticalement les objets à la main par rapport
à la ligne médiane de la portée, ou en les déplaçant à une distance
donnée vers une nouvelle position. Les inconvénients sont qu'il faut
individuellement, pour chaque objet, trouver les valeurs correctes de
repositionnement souvent par tâtonnement et que, puisque le mouvement
est opéré après que LilyPond a placé tous les autres objets, c'est à
l'utilisateur de résoudre tous les problèmes de collision qui pourraient
survenir. Et le pire avec cette méthode est que, le jour où la musique
est modifiée, il faut de nouveau rechercher les valeurs de
repositionnement. Les propriétés à utiliser pour ce type de
repositionnement manuel sont :


@itemize
@item
@code{extra-offset}

@cindex @code{extra-offset}, propriété

Cette propriété s'applique à tout objet acceptant la
@code{grob-interface}. Elle reçoit une paire de nombres qui indiquent le
déplacement supplémentaire dans le sens horizontal et vertical. Des
nombres négatifs déplacent l'objet vers la gauche ou vers le bas.
L'unité utilisée est l'espace de portée. Le déplacement supplémentaire
intervient une fois que la composition des objets est achevée, si bien
qu'un objet peut être repositionné à n'importe quel endroit sans
perturber quoi que ce soit.

@item
@code{positions}

@cindex @code{positions}, propriété

Cette propriété est très utile pour ajuster manuellement l'inclinaison
et la hauteur des barres de ligature, des liaisons et des n-olets. Elle
est suivie de deux nombres qui donnent la position des extrémités gauche
et droite des barres, liaisons, etc. par rapport à la ligne médiane de
la portée. L'unité de référence est l'intervalle de lignes de portée.
Attention toutefois au fait que les liaisons et phrasés ne peuvent pas
être repositionnés n'importe où. LilyPond commence par dresser la liste
des emplacements possibles pour les liaisons et choisit par défaut la
liaison qui « semble la meilleure ». Si la propriété @code{positions} a
été retouchée, la liaison la plus proche de la position demandée sera
retenue dans la liste.
@end itemize

@end enumerate

Il est possible qu'un objet ne dispose pas de toutes ces propriétés. Il
est donc nécessaire de consulter la RPI pour vérifier quelles sont les
propriétés disponibles pour l'objet en question.

Voici une liste d'objets les plus couramment impliqués dans les
collisions, avec le nom de l'objet à consulter dans la RPI afin de
trouver les propriétés à retoucher pour obtenir un déplacement.


@indentedblock
@multitable {Dynamics (horizontally)} {@code{DynamicLineSpanner}}
@headitem Type d'objet
  @tab Nom d'objet
@item Articulations, par ex. @samp{->}
  @tab @code{Script}
@item Barre de ligature
  @tab @code{Beam}
@item Doigté
  @tab @code{Fingering}
@item Liaison de phrasé
  @tab @code{Slur}
@item Liaison de prolongation
  @tab @code{Tie}
@item N-olet
  @tab @code{TupletBracket}
@item Nuance (verticalement)
  @tab @code{DynamicLineSpanner}
@item Nuance (horizontalement)
  @tab @code{DynamicText}
@item Reprise / marque de texte
  @tab @code{RehearsalMark}
@item Texte, par ex. @samp{^"texte"}
  @tab @code{TextScript}
@end multitable
@end indentedblock


@node Fixing overlapping notation
@subsection Correction des collisions d'objets

Voyons maintenant comment les propriétés décrites dans la section
précédente peuvent nous aider à résoudre les collisions.


@node The padding property
@unnumberedsubsubsec La propriété @code{padding}

@cindex décalage (padding)
@cindex résolution des chevauchements de notation
@cindex chevauchement de notation

En jouant sur la propriété @code{padding} (littéralement
« rembourrage »), on augmente (ou on diminue) la distance entre des
symboles qui sont imprimés au-dessus ou en dessous des notes.

@cindex @code{Script}, exemple de dérogation
@cindex @code{padding}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,verbatim]
c'2\fermata
\override Script.padding = 3
b2\fermata
@end lilypond

@cindex @code{MetronomeMark}, exemple de dérogation
@cindex @code{padding}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,verbatim]
% This will not work, see below:
\override MetronomeMark.padding = 3
\tempo 4=120
c'1 |
% This works:
\override Score.MetronomeMark.padding = 3
\tempo 4=80
d'1 |
@end lilypond

Vous remarquerez dans le second exemple à quel point il est important de
préciser le nom du contexte qui contient l'objet. Puisque l'objet
@code{MetronomeMark} appartient au contexte @code{Score}, le fait de
modifier la propriété dans le contexte @code{Voice} passera inaperçu.
Pour plus de détails, voir @rnotationnamed{Modifying properties,
Modification de propriétés}.

Si on augmente la propriété @code{padding} d'un objet alors que celui-ci
fait partie d'un ensemble d'objets positionnés en fonction de leur
@code{outside-staff-priority}, cet objet sera déplacé, ainsi que tous
les autres objets du groupe.


@node The right-padding property
@unnumberedsubsubsec La propriété @code{right-padding}

@cindex @code{right-padding}, propriété

La propriété @code{right-padding} joue sur l'espacement entre une
altération et la note sur laquelle elle porte.@footnote{L'objet
@code{DynamicText} dispose aussi de la propriété @code{right-padding},
mais avec un fonctionnement radicalement différent : elle contrôle
l'espacement horizontal entre une nuance absolue et une nuance textuelle
avec extenseur démarrant au même moment.} On ne l'utilise pas souvent,
mais l'espacement par défaut peut se révéler inadéquat avec certaines
altérations ou certains glyphes utilisés en musique micro-tonale.

@cindex @code{AccidentalPlacement}, exemple de dérogation
@cindex @code{right-padding}, exemple d'utilisation de la propriété

@lilypond[quote,ragged-right,verbatim]
\relative c' {
  cis8[ dis eis fis gis ais bis cis]
}

\relative c' {
  % move accents nearer to note heads
  \override Score.AccidentalPlacement.right-padding = -0.1
  cis8[ dis eis fis gis ais bis cis]
}
@end lilypond


@node The staff-padding property
@unnumberedsubsubsec La propriété @code{staff-padding}

@cindex alignement d'objets sur une ligne de base
@cindex objets, alignement sur une ligne de base

@code{staff-padding} sert à aligner des objets tels que des nuances sur
une ligne fictive à une distance donnée par rapport à la portée en
l'absence d'autre élément de notation qui les repousserait. Ce n'est pas
une propriété de @code{DynamicText} mais de @code{DynamicLineSpanner},
car la ligne fictive est destinée à s'appliquer autant à @strong{toutes}
les nuances, notamment celles qui sont créées comme des bandeaux en
longueur (en anglais @emph{Spanners}). Tel est donc le moyen d'aligner
les indications de nuance, comme dans cet exemple repris de la section
précédente :

@cindex @code{DynamicText}, exemple de dérogation
@cindex @code{extra-spacing-width}, exemple d'utilisation de la propriété
@cindex @code{DynamicLineSpanner}, exemple de dérogation
@cindex @code{staff-padding}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,ragged-right,verbatim]
\override DynamicLineSpanner.staff-padding = 3
\relative { a'4\f b\mf a\p b\mp }
@end lilypond


@node The self-alignment-X property
@unnumberedsubsubsec La propriété @code{self-alignment-X}

L'exemple suivant montre comment ajuster le positionnement d'une
indication de corde relativement à une hampe, en alignant le coin droit
sur le point de référence de la note parente :

@cindex @code{StringNumber}, exemple de dérogation
@cindex @code{self-alignment-X}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,ragged-right,verbatim]
\voiceOne
<a''\2>
\once \override StringNumber.self-alignment-X = #RIGHT
<a''\2>
@end lilypond


@node The staff-position property
@unnumberedsubsubsec La propriété @code{staff-position}

@cindex collision d'objets à l'intérieur d'une portée

Dans une voix, un silence valant une mesure entière peut chevaucher les
notes d'une autre voix. Vu que ces silences sont centrés entre les deux
barres de mesure, il serait très compliqué de programmer LilyPond pour
repérer ces risques de collision dans la mesure où, normalement, toutes
les collisions entre notes ou entre notes et silences se produisent sur
des notes et silences simultanés. Voici un exemple de collision de ce
type :

@lilypond[quote,verbatim,ragged-right]
<< \relative { c'4 c c c } \\ { R1 } >>
@end lilypond

Ici, la meilleure solution consiste à déplacer le symbole de pause vers
le bas -- puisque cette pause appartient à une voix inférieure. Par
défaut, dans la @code{\voiceTwo} (c'est-à-dire dans la seconde voix
d'une construction @code{<<@{ @dots{} @} \\ @{ @dots{} @}>>}), la
propriété @code{staff-position} est réglée sur @code{-6} pour les
@code{MultiMeasureRest} ; nous avons donc besoin de la déplacer, disons,
de quatre demi-intervalles vers le bas, ce qui donne @code{-10}.

@cindex @code{MultiMeasureRest}, exemple de dérogation
@cindex @code{staff-position}, exemple d'utilisation de la propriété

@lilypond[quote,verbatim,ragged-right]
<<
  \relative { c'4 c c c }
  \\
  \override MultiMeasureRest.staff-position = -10
  { R1 }
>>
@end lilypond

C'est mieux que d'utiliser, par exemple, @code{extra-offset}, car la
ligne supplémentaire au-dessus du silence est insérée automatiquement.

Il faut noter une particularité à propos de cette propriété lorsqu'on
l'applique à un objet @code{Tie} : LilyPond fait une distinction entre
des nombres @dfn{exacts} (entiers ou fractions) et @dfn{inexacts}
(nombres à virgule). Voir le morceau choisi « Dessin à main levée de
liaisons de tenue » dans la section @rnotationnamed{Ties, Liaisons de
prolongation} pour ce qui différencie des valeurs exactes des valeurs
inexactes.


@node The extra-offset property
@unnumberedsubsubsec La propriété @code{extra-offset}

@cindex positionnement des objets
@cindex positionnement des grobs
@cindex objets, positionnement
@cindex @emph{grobs}, positionnement

La propriété @code{extra-offset} offre la possibilité de contrôler
entièrement le placement d'un objet, aussi bien horizontalement que
verticalement.

Dans l'exemple suivant, la seconde indication de doigté est déplacée
légèrement vers la gauche et de 1,8 intervalle de lignes vers le bas :

@cindex @code{Fingering}, exemple de dérogation
@cindex @code{extra-offset}, exemple d'utilisation de la propriété

@lilypond[quote,fragment,verbatim]
f'4-5
\once \override Fingering.extra-offset = #'(-0.3 . -1.8)
f'4-5
@end lilypond


@node The positions property
@unnumberedsubsubsec La propriété @code{positions}

@cindex contrôle des n-olets, liaisons, phrasés et ligatures
@cindex gestion manuelle des n-olets, liaisons, phrasés et ligatures
@cindex ligatures de n-olet, gestion manuelle
@cindex liaisons, gestion manuelle
@cindex phrasés, gestion manuelle
@cindex ligatures, gestion manuelle

La propriété @code{positions} permet de contrôler manuellement la
position et l'inclinaison des n-olets, coulés, liaisons de phrasé et
barres de ligature.

Voici un exemple où la liaison de phrasé recouvre la liaison
d'articulation :

@lilypond[quote,verbatim,ragged-right]
\relative { a'8 \( ( a'16 ) a \) }
@end lilypond

@cindex @code{PhrasingSlur}, exemple de dérogation
@cindex @code{positions}, exemple d'utilisation de la propriété

@noindent
Nous pourrions envisager de remonter quelque peu les extrémités de la
liaison de phrasé. Commençons par repositionner l'extrémité gauche à
2,5 espaces de portée au-dessus de la ligne médiane, et la droite
à 4,5 ; LilyPond choisira la courbe dont les extrémités seront les plus
approchantes de celle déterminées :

@lilypond[quote,verbatim,fragment,ragged-right]
\once \override PhrasingSlur.positions = #'(2.5 . 4.5)
a'8 \( ( a''16 ) a'' \)
@end lilypond

C'est déjà mieux, mais ne pourrait-on pas maintenant abaisser un peu
l'extrémité droite de la liaison d'articulation ? Vous constaterez qu'il
n'est pas possible d'y arriver, tout simplement parce qu'il n'y a pas de
meilleur candidat ; la propriété @code{positions} n'est alors d'aucune
utilité. Les liaisons, aussi bien de tenue que d'articulation ou de
phrasé, peuvent se positionner et se dessiner tout en finesse lorsque
nécessaire -- voir à ce sujet @rnotationnamed{Modifying ties and slurs,
Modification des liaisons}.

Voici un autre exemple. Comme nous pouvons le constater, les barres de
ligature chevauchent les liaisons de tenue :

@lilypond[quote,verbatim,ragged-right]
{
  \time 4/2
  <<
    \relative { c'1~ 2. e8 f }
    \\
    \relative {
      e''8 e e e
      e e e e
      f2 g
    }
  >>
  <<
    \relative { c'1~ 2. e8 f }
    \\
    \relative {
      e''8 e e e
      e e e e
      f2 g
    }
  >>
}
@end lilypond

@noindent
On peut y remédier en déplaçant manuellement vers le haut les deux
extrémités des ligatures de croches, non plus à 1,81 intervalle
au-dessous de la ligne médiane mais, disons, à 1 :

@cindex @code{Beam}, exemple de dérogation
@cindex @code{positions}, exemple d'utilisation de la propriété

@lilypond[quote,verbatim,fragment,ragged-right]
{
  \time 4/2
  <<
    \relative { c'1~ 2. e8 f }
    \\
    \relative {
      \override Beam.positions = #'(-1 . -1)
      e''8 e e e
      e e e e
      f2 g
    }
  >>
  <<
    \relative { c'1~ 2. e8 f }
    \\
    \relative {
      e''8 e e e
      e e e e
      f2 g
      \revert Beam.positions
    }
  >>
}
@end lilypond

@noindent
Vous remarquerez que la retouche continue de s'appliquer au second bloc
de croches de la deuxième voix mais qu'il ne s'applique à aucune des
ligatures de la première voix, même dans la seconde mesure. Dès que la
dérogation ne doit plus s'appliquer, il suffit de l'annuler comme
indiqué ici.


@node The force-hshift property
@unnumberedsubsubsec La propriété @code{force-hshift}

Maintenant, nous sommes prêts à appliquer les dernières corrections à
l'exemple de Chopin présenté à la fin de @ref{I'm hearing voices}, que
nous avions laissé dans cet état :

@lilypond[quote,verbatim,fragment,ragged-right]
\new Staff \relative {
  \key aes \major
  <<
    { c''2 aes4. bes8 }
    \\
    { <ees, c>2 des }
    \\
    \\
    { aes'2 f4 fes }
  >> |
  <c ees aes c>1 |
}
@end lilypond

@noindent
La note intermédiaire du premier accord, le la bémol à la quatrième
voix, doit rester dans le même empilement que la note haute, ce pourquoi
nous utilisons un @code{\shiftOff}

Quant au second accord, il serait préférable que le fa s'aligne avec le
la et que la note la plus basse se positionne un peu plus sur la droite
pour éviter que les hampes se chevauchent. Pour cela, nous réglons le
@code{force-hshift} au niveau du @code{NoteColumn} du ré bémol de telle
sorte qu'il se déplace de la moitié d'un espace de portée vers la droite
et le @code{force-hshift} du fa sur zéro. Vous noterez la présence du
@code{\once} qui évite la propagation de ces réglages au-delà de cet
instant musical particulier -- bien que la présence du @code{\once} et
du second @code{\override} de la quatrième voix ne soient pas
indispensables dans ce court extrait, ce ne serait pas montrer l'exemple
que de les omettre.

Et voici le résultat final :

@cindex @code{NoteColumn}, exemple de dérogation
@cindex @code{force-hshift}, exemple d'utilisation de la propriété

@lilypond[quote,verbatim,fragment,ragged-right]
\new Staff \relative {
  \key aes \major
  <<
    { c''2 aes4. bes8 }
    \\
    { <ees, c>2 \once \override NoteColumn.force-hshift = #0.5 des }
    \\
    \\
    { \once \shiftOff aes'2 \once \shiftOff f4 fes }
  >> |
  <c ees aes c>1 |
}
@end lilypond


@node Real music example
@subsection Exemple concret

Pour terminer ce chapitre consacré aux retouches, voici, étape par
étape, la mise en forme d'un exemple concret nécessitant un certain
nombre de retouches jusqu'à l'obtention du résultat attendu. Cet exemple
a été choisi en raison des problèmes inhabituels de notation qu'il
soulevait et pour vous apprendre à les résoudre grâce au Manuel de
notation. Il n'est pas représentatif d'une opération normale de
gravure ; que ces difficultés ne vous découragent donc pas ! Des
difficultés comme celles-ci ne sont, heureusement, pas courantes.

Cet exemple est tiré de la @emph{Première Ballade} de Chopin, Op. 23,
mesures 6 à 9 ; cela correspond à la transition entre le @emph{Lento}
d'ouverture et le @emph{Moderato}.@footnote{Ceci est extrait d'une
partition plus ancienne et différente de la version Urtext disponible
chez Henle, par exemple.} Voici, pour commencer, ce à quoi nous voulons
que la partition ressemble ; pour limiter les complications, nous
n'avons pas fait apparaître les indications de nuance, de doigté ni de
pédale, et n'avons pas poussé les affinages autant qu'il aurait été
possible.


@c The following should appear as music without code
@c This example should not be indexed
@c line-width ensures no break
@lilypond[quote,ragged-right,line-width=6\in]
rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    \once \override Tie.staff-position = 3.5
    bes1~ |
    \bar "||"
    \time 6/4
    \mergeDifferentlyHeadedOn
    \mergeDifferentlyDottedOn
    bes2.\tempo "Moderato" r8
    <<
      { c,8 d fis bes a }
      \new Voice {
        \voiceTwo
        c,8~
        % Reposition the c2 to the right of the merged note
        \once \override NoteColumn.force-hshift = 1.0
        % Move the c2 out of the main note column
        % so the merge will work
        \shiftOnn
        c2
      }
      \new Voice {
        \voiceThree
        s8
        % Stem on the d2 must be down to permit merging
        \stemDown
        % Stem on the d2 should be invisible
        \tweak Flag.transparent ##t
        d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    \mergeDifferentlyHeadedOff
    \mergeDifferentlyDottedOff
    g2.\)
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1)\arpeggio |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}
@end lilypond

Nous constatons tout d'abord que, dans la troisième mesure, la main
droite compte quatre voix. Ce sont les cinq croches avec une barre, le
do avec liaison, le ré blanche qui se fond avec le ré croche, et le fa
dièse noire pointée qui se fond lui aussi avec la croche de même
hauteur. Tout le reste se réduit à une seule voix. Le plus simple est
donc de créer temporairement ces trois voix supplémentaires au moment
opportun. Si vous avez oublié comment faire, reportez-vous à @ref{I'm
hearing voices} et @ref{Explicitly instantiating voices}. Nous opterons
ici pour une déclaration explicite des voix du passage polyphonique,
puisque LilyPond est alors plus performant en matière d'évitement des
collisions.

Commençons par saisir les notes comme appartenant à deux variables,
mettons en place l'ossature des portées dans un bloc @code{\Score} et
voyons ce que LilyPond propose par défaut :

@c line-width ensures no break
@lilypond[quote,verbatim,ragged-right,line-width=6\in]
rhMusic = \relative {
  \new Voice {
    r2 c''4. g8 |
    bes1~ |
    \time 6/4
    bes2. r8
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~ 2
      }
      \new Voice {
        \voiceThree
        s8 d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    g2.  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2 |
  <d g, d>1 |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}
@end lilypond

Toutes les notes sont correctes mais l'allure générale est loin d'être
satisfaisante. La liaison se heurte à l'indication de mesure lors du
changement de métrique, la ligature des croches n'est pas bonne dans la
troisième mesure, les notes ne sont pas fusionnées et il manque
plusieurs éléments de notation. Commençons par le plus simple. Nous
pouvons corriger la ligature des croches en la créant manuellement et
nous pouvons facilement ajouter les limites droite et gauche de la
liaison de phrasé, puisque tout cela a déjà été traité dans le tutoriel.
Voici le résultat :

@c line-width ensures no break
@lilypond[quote,verbatim,ragged-right,line-width=6\in]
rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    bes1~ |
    \time 6/4
    bes2. r8
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~ 2
      }
      \new Voice {
        \voiceThree
        s8 d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1) |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}
@end lilypond

La première mesure est maintenant correcte. La seconde contient un
arpège et doit se terminer par une double barre. Comment faire, puisque
cela n'a pas été traité dans le Manuel d'initiation ? C'est alors qu'il
faut nous reporter au Manuel de notation. Quand on cherche « arpège » et
« barre de mesure » dans l'index, on voit aisément qu'il faut ajouter
@code{\arpeggio} à un accord pour produire un arpège et qu'une double
barre est le résultat de la commande @code{\bar "||"}. Rien de plus
facile ! Nous devons ensuite corriger la collision entre la liaison et
l'indication de mesure. Le mieux est de déplacer la liaison vers le
haut.@footnote{Une alternative consisterait à ajuster
@code{Tie.details.height-limit} pour rendre la liaison plus concave.} La
méthode pour déplacer les objets a déjà été présentée dans @ref{Moving
objects}, et l'on sait que, pour des objets positionnés par rapport à la
portée, il nous faut modifier leur propriété @code{staff-position},
exprimée en demi-intervalles de lignes par rapport à la ligne médiane de
la portée. Voici donc la retouche à insérer juste devant la première
note liée ; elle est censée déplacer la liaison vers le haut de 3,5
demi-intervalles de lignes au-dessus de la ligne médiane :

@code{\once \override Tie.staff-position = 3.5}

Cela s'adjoint à la deuxième mesure, pour donner :

@c line-width ensures no break
@lilypond[quote,verbatim,ragged-right,line-width=6\in]
rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    \once \override Tie.staff-position = 3.5
    bes1~ |
    \bar "||"
    \time 6/4
    bes2. r8
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~ 2
      }
      \new Voice {
        \voiceThree
        s8 d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1)\arpeggio |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}
@end lilypond

Venons-en à la troisième mesure et au début de la section Moderato. Dans
le Tutoriel, il est indiqué comment insérer une indication de tempo à
l'aide de la commande @code{\tempo} ; pas de problème, du coup, pour
ajouter « Moderato ». Mais comment faire pour fusionner les notes de
différentes voix ? C'est là que le Manuel de notation peut nous venir en
aide. Une recherche sur « fusionnement de notes » dans l'index nous
renvoie au chapitre @rnotationnamed{Collision resolution, Résolution des
collisions}, et plus précisément aux commandes permettant de fusionner
des notes en fonction de leur type et selon qu'elles sont pointées ou
non. Dans notre exemple, pour la durée de la polyphonie de la troisième
mesure, nous avons besoin de fusionner deux types de notes ; grâce aux
informations trouvées dans le Manuel de notation, nous ajoutons

@example
\mergeDifferentlyHeadedOn
\mergeDifferentlyDottedOn
@end example

@noindent
au début de cette section et

@example
\mergeDifferentlyHeadedOff
\mergeDifferentlyDottedOff
@end example

@noindent
à la fin, ce qui donne :

@c line-width ensures no break
@lilypond[quote,verbatim,ragged-right,line-width=6\in]
rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    \once \override Tie.staff-position = 3.5
    bes1~ |
    \bar "||"
    \time 6/4
    bes2.\tempo "Moderato" r8
    \mergeDifferentlyHeadedOn
    \mergeDifferentlyDottedOn
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~ 2
      }
      \new Voice {
        \voiceThree
        s8 d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    \mergeDifferentlyHeadedOff
    \mergeDifferentlyDottedOff
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1)\arpeggio |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}
@end lilypond

Ces retouches ont permis de fusionner les deux fa dièse mais pas les
deux ré. Pourquoi ? La réponse se trouve dans la même section du Manuel
de notation : les notes à fusionner doivent avoir des hampes dans des
directions opposées et deux notes ne peuvent pas être fusionnées s'il y
a une troisième note dans la même colonne. Ici, les deux ré ont leur
hampe orientée vers le haut et il y a une troisième note, do. Nous
savons changer l'orientation de la hampe avec @code{\stemDown} et le
Manuel de notation nous indique également comment déplacer le do -- en
produisant un décalage grâce à l'une des commandes @code{\shift}. Mais
laquelle ? Le do appartient à la deuxième voix et n'est pas décalé ; les
deux ré appartiennent respectivement à la première et à la troisième
voix, et l'un n'est pas décalé tandis que l'autre l'est. Il nous faut
donc décaler largement le do avec la commande @code{\shiftOnn} pour
éviter une interférence avec les deux ré. Voici ce que donnent ces
modifications :

@cindex @code{Tie}, exemple de dérogation
@cindex @code{staff-position}, exemple d'utilisation de la propriété

@c line-width ensures no break
@lilypond[quote,verbatim,ragged-right,line-width=6\in]
rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    \once \override Tie.staff-position = 3.5
    bes1~ |
    \bar "||"
    \time 6/4
    bes2.\tempo "Moderato" r8
    \mergeDifferentlyHeadedOn
    \mergeDifferentlyDottedOn
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        % Move the c2 out of the main note column
        % so the merge will work
        c,8~ \shiftOnn c2
      }
      \new Voice {
        \voiceThree
        % Stem on the d2 must be down to permit merging
        s8 \stemDown d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    \mergeDifferentlyHeadedOff
    \mergeDifferentlyDottedOff
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1)\arpeggio |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}
@end lilypond

Pas loin ! Il ne reste plus que deux problèmes : les ré une fois
fusionnés ne devraient plus avoir de hampe vers le bas, et le do serait
mieux à la droite des ré. Nous savons remédier à ces deux problèmes
grâce aux retouches précédentes : nous allons rendre la hampe
transparente et déplacer le do avec la propriété @code{force-hshift}. Et
voici le résultat final :

@cindex @code{NoteColumn}, exemple de dérogation
@cindex @code{force-hshift}, exemple d'utilisation de la propriété
@cindex @code{Stem}, exemple de dérogation
@cindex @code{transparent}, exemple d'utilisation de la propriété

@c line-width ensures no break
@lilypond[quote,verbatim,ragged-right,line-width=6\in]
rhMusic = \relative {
  \new Voice {
    r2 c''4.\( g8 |
    \once \override Tie.staff-position = 3.5
    bes1~ |
    \bar "||"
    \time 6/4
    bes2.\tempo "Moderato" r8
    \mergeDifferentlyHeadedOn
    \mergeDifferentlyDottedOn
    % Start polyphonic section of four voices
    <<
      { c,8 d fis bes a }  % continuation of main voice
      \new Voice {
        \voiceTwo
        c,8~
        % Reposition the c2 to the right of the merged note
        \once \override NoteColumn.force-hshift = 1.0
        % Move the c2 out of the main note column
        % so the merge will work
        \shiftOnn
        c2
      }
      \new Voice {
        \voiceThree
        s8
        % Stem on the d2 must be down to permit merging
        \stemDown
        % Stem on the d2 should be invisible
        \tweak Flag.transparent ##t
        d2
      }
      \new Voice {
        \voiceFour
        s4 fis4.
      }
    >> |
    \mergeDifferentlyHeadedOff
    \mergeDifferentlyDottedOff
    g2.\)  % continuation of main voice
  }
}

lhMusic = \relative {
  r2 <c' g ees>2( |
  <d g, d>1)\arpeggio |
  r2. d,,4 r4 r |
  r4
}

\score {
  \new PianoStaff <<
    \new Staff = "RH"  <<
      \key g \minor
      \rhMusic
    >>
    \new Staff = "LH" <<
      \key g \minor
      \clef "bass"
      \lhMusic
    >>
  >>
}
@end lilypond


@node Further tweaking
@section Autres retouches

Nous avons pratiquement fait le tour de cette introduction aux
retouches. Quelques aspects méritent un peu d'attention.


@node Other uses for tweaks
@subsection Autres utilisations des retouches

Nous allons ici aborder des situations qui se produisent régulièrement
dans les partitions courantes.

@cindex suppression d'objets
@cindex objets, suppression d'


@node Tying notes across voices
@unnumberedsubsubsec Liaison entre plusieurs voix

Voici un exemple qui montre comment créer une liaison de prolongation
entre des notes appartenant à des voix différentes. En temps normal,
seules deux notes appartenant à une même voix peuvent être ainsi liées.
La solution consiste à utiliser deux voix, dont l'une avec les notes
liées,

@lilypond[quote]
<< { b'8~ 8\noBeam } \\ { b'8[ g'] } >>
@end lilypond

@noindent
et à supprimer la première hampe ascendante et le crochet dans cette
voix ; on a alors l'impression que la liaison couvre les deux voix.

@cindex @code{Stem}, exemple de suppression
@cindex @code{Flag}, exemple de suppression
@cindex @code{\omit}, exemple d'utilisation

@funindex \omit

@lilypond[quote,fragment,verbatim]
<<
  {
    \once \omit Stem
    \once \omit Flag
    b'8~ 8\noBeam
  }
\\
  { b'[ g8] }
>>
@end lilypond

@morerefs
Manuel d'initiation :
@ref{The once prefix},
@ref{The stencil property}.
@endmorerefs


@node Simulating a fermata in MIDI
@unnumberedsubsubsec Rendu MIDI d'un point d'orgue

@cindex point d'orgue, rendu en MIDI

En ce qui concerne les objets extérieurs à la portée, quand on veut les
faire disparaître de la partition imprimée, il est généralement
préférable de modifier leur propriété @code{stencil} plutôt que leur
propriété @code{transparent}. Le fait d'attribuer à la propriété
@code{stencil} d'un objet la valeur @code{#f} supprimera entièrement
celui-ci de la partition. Il ne risquera donc pas de gêner le placement
d'autres objets.

Par exemple, si nous voulons changer le réglage de métronome pour
simuler un point d'orgue dans le fichier MIDI, nous ne voulons surtout
pas que cette indication métronomique apparaisse sur la partition ni
qu'elle influence l'espacement entre les deux systèmes ou la position
des annotations voisines sur la portée. Le fait d'attribuer à la
propriété @code{stencil} la valeur @code{#f} est donc la bonne solution.
Nous montrons ci-dessous le résultat des deux méthodes :

@cindex @code{MetronomeMark}, exemple de dérogation
@cindex @code{transparent}, exemple d'utilisation de la propriété

@lilypond[quote,verbatim,ragged-right]
\score {
  \relative {
    % Visible tempo marking
    \tempo 4=120
    a'4 a a
    \once \hide Score.MetronomeMark
    % Invisible tempo marking to lengthen fermata in MIDI
    \tempo 4=80
    a4\fermata |
    % New tempo for next section
    \tempo 4=100
    a4 a a a |
  }
  \layout { }
  \midi { }
}
@end lilypond

@cindex @code{MetronomeMark}, exemple de dérogation
@cindex @code{stencil}, exemple d'utilisation de la propriété

@lilypond[quote,verbatim,ragged-right]
\score {
  \relative {
    % Visible tempo marking
    \tempo 4=120
    a'4 a a
    \once \omit Score.MetronomeMark
    % Invisible tempo marking to lengthen fermata in MIDI
    \tempo 4=80
    a4\fermata |
    % New tempo for next section
    \tempo 4=100
    a4 a a a |
  }
  \layout { }
  \midi { }
}
@end lilypond

@noindent
Les deux méthodes permettent d'enlever l'indication métronomique qui
allonge le point d'orgue de la partition, et toutes deux modifient le
rythme MIDI comme souhaité mais, dans la première, l'indication
métronomique transparente repousse vers le haut l'indication de tempo,
contrairement à la seconde (avec le stencil désactivé) qui la laisse à
sa place.

@morerefs
Glossaire musicologique :
@rglosnamed{system,système}.
@endmorerefs


@node Using variables for layout adjustments
@subsection Utilisation de variables dans les retouches

@cindex variables, utilisation dans les retouches
@cindex utilisation de variables dans les retouches
@cindex retouches et utilisation de variables

Les commandes de retouche sont souvent longues et pénibles à taper, et
ne tolèrent pas la moindre erreur. Lorsqu'on a besoin de faire plusieurs
fois les mêmes retouches, il est préférable de définir des variables qui
les contiennent.

Imaginons que nous voulions accentuer certains mots dans des paroles en
les mettant en italique. Au lieu des commandes @code{\italic} et
@code{\bold}, qui ne fonctionnent dans les paroles que si elles sont
enchâssées dans un @code{\markup} -- ce qui les rend pénibles à saisir
-- pouvons-nous employer les commandes @code{\override} et
@code{\revert} ?

@example
\override Lyrics.LyricText.font-shape = #'italic
\override Lyrics.LyricText.font-series = #'bold

\revert Lyrics.LyricText.font-shape
\revert Lyrics.LyricText.font-series
@end example

Là encore, ce serait extrêmement pénible à saisir, surtout s'il y avait
beaucoup de mots à retoucher de cette façon. Plutôt que cette solution,
nous déclarons ces commandes comme étant deux variables, et les
utilisons comme ci-après -- quoique on choisirait sans doute pour les
variables des noms plus courts pour simplifier la frappe. Par ailleurs,
le fait de recourir à une variable ne nous expose plus à l'oubli des
espaces entourant les points lorsqu'explicités au beau milieu d'un bloc
@code{\lyricmode} !

@cindex @code{LyricText}, exemple de dérogation
@cindex @code{font-shape}, exemple d'utilisation de la propriété
@cindex @code{font-series}, exemple d'utilisation de la propriété

@lilypond[quote,verbatim]
emphasize = {
  \override Lyrics.LyricText.font-shape = #'italic
  \override Lyrics.LyricText.font-series = #'bold
}

normal = {
  \revert Lyrics.LyricText.font-shape
  \revert Lyrics.LyricText.font-series
}

global = { \key c \major \time 4/4 \partial 4 }

SopranoMusic = \relative { c'4 | e4. e8 g4 g    | a4   a   g  }
AltoMusic    = \relative { c'4 | c4. c8 e4 e    | f4   f   e  }
TenorMusic   = \relative  { e4 | g4. g8 c4.  b8 | a8 b c d e4 }
BassMusic    = \relative  { c4 | c4. c8 c4 c    | f8 g a b c4 }

VerseOne = \lyricmode {
  E -- | ter -- nal \emphasize Fa -- ther, | \normal strong to save,
}

VerseTwo = \lyricmode {
  O | \emphasize Christ, \normal whose voice the | wa -- ters heard,
}

VerseThree = \lyricmode {
  O | \emphasize Ho -- ly Spi -- rit, | \normal who didst brood
}

VerseFour = \lyricmode {
  O | \emphasize Tri -- ni -- ty \normal of | love and pow'r
}

\score {
  \new ChoirStaff <<
    \new Staff <<
      \clef "treble"
      \new Voice = "Soprano"  { \voiceOne \global \SopranoMusic }
      \new Voice = "Alto" { \voiceTwo \AltoMusic }
      \new Lyrics \lyricsto "Soprano" { \VerseOne }
      \new Lyrics \lyricsto "Soprano" { \VerseTwo }
      \new Lyrics \lyricsto "Soprano" { \VerseThree }
      \new Lyrics \lyricsto "Soprano" { \VerseFour }
    >>
    \new Staff <<
      \clef "bass"
      \new Voice = "Tenor" { \voiceOne \TenorMusic }
      \new Voice = "Bass"  { \voiceTwo \BassMusic }
    >>
  >>
}
@end lilypond


@node Style sheets
@subsection Feuilles de style

La sortie que produit LilyPond peut être largement modifiée --
@pxref{Tweaking output} pour plus de détails. Mais que faire si vous
avez beaucoup de fichiers auxquels vous souhaitez appliquer vos
retouches ? Ou si vous souhaitez simplement séparer les retouches de la
musique elle-même ? Rien de plus facile.

Prenons un exemple. Ne vous inquiétez pas si vous ne comprenez pas les
parties avec tous les @code{#(@dots{})}. Celles-ci sont expliquées dans
@ref{Advanced tweaks with Scheme}.

@lilypond[quote,verbatim,ragged-right]
mpdolce =
  \tweak self-alignment-X -0.6
  #(make-dynamic-script
    #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})

inst =
#(define-music-function
     (string)
     (string?)
   #{ <>^\markup \bold \box #string #})

\relative {
  \tempo 4=50
  a'4.\mpdolce d8 cis4--\glissando a |
  b4 bes a2 |
  \inst "Clarinet"
  cis4.\< d8 e4 fis |
  g8(\! fis)-. e( d)-. cis2 |
}
@end lilypond

On peut faire quelque chose pour les définitions de @code{mpdolce} et
@code{inst}. Elles produisent le résultat que nous désirons, mais nous
pourrions aussi vouloir les utiliser dans une autre pièce. Il suffirait
de les copier et coller au début de chaque fichier, mais c'est
fastidieux. De plus, cela laisse les définitions dans nos fichiers de
musique, et je trouve personnellement tous ces @code{#()} assez laids.
Stockons-les dans un autre fichier :

@example
%%% enregistrez ceci dans un fichier nommé "definitions.ily"
mpdolce =
  \tweak self-alignment-X -0.6
  #(make-dynamic-script
    #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})

inst =
#(define-music-function
     (string)
     (string?)
   #@{ <>^\markup \bold \box #string #@})
@end example

Nous rappellerons ce fichier par une simple commande @code{\include} au
début de notre fichier de musique. Lui attribuer l'extension @code{.ily}
nous permet de distinguer aisément qu'il s'agit d'un fichier voué à être
inclus dans un fichier maître ; il n'est pas destiné à être compilé
isolément.@*
Maintenant, modifions notre musique (enregistrez ce fichier sous
@file{musique.ly}).

@c  We have to do this awkward example/lilypond-non-verbatim
@c  because we can't do the \include stuff in the manual.

@example
\include "definitions.ily"

\relative @{
  \tempo 4=50
  a'4.\mpdolce d8 cis4--\glissando a |
  b4 bes a2 |
  \inst "Clarinet"
  cis4.\< d8 e4 fis |
  g8(\! fis)-. e( d)-. cis2 |
@}
@end example

@lilypond[quote,ragged-right]
mpdolce =
  \tweak self-alignment-X -0.6
  #(make-dynamic-script
    #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})

inst =
#(define-music-function
     (string)
     (string?)
   #{ <>^\markup \bold \box #string #})

\relative {
  \tempo 4=50
  a'4.\mpdolce d8 cis4--\glissando a |
  b4 bes a2 |
  \inst "Clarinet"
  cis4.\< d8 e4 fis |
  g8(\! fis)-. e( d)-. cis2 |
}
@end lilypond

C'est mieux, mais effectuons encore quelques retouches. Le glissando est
peu visible, c'est pourquoi nous allons l'épaissir et le rapprocher des
têtes de note. Déplaçons l'indication métronomique au-dessus de la clef,
au lieu de la laisser au-dessus de la première note. Et pour finir, mon
professeur de composition déteste les chiffrages de mesure en « C »,
nous allons donc le transformer en « 4/4 ».

Cependant, ne changez pas le fichier @file{musique.ly}.  Remplacez le
fichier @file{definitions.ily} par ceci :

@example
%%%  definitions.ily
mpdolce =
  \tweak self-alignment-X -0.6
  #(make-dynamic-script
    #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})

inst =
#(define-music-function
     (string)
     (string?)
   #@{ <>^\markup \bold \box #string #@})

\layout@{
  \context @{
    \Score
    \override MetronomeMark.extra-offset = #'(-5 . 0)
    \override MetronomeMark.padding = 3
  @}
  \context @{
    \Staff
    \numericTimeSignature
  @}
  \context @{
    \Voice
    \override Glissando.thickness = 3
    \override Glissando.gap = 0.1
  @}
@}
@end example

@lilypond[quote,ragged-right]
mpdolce =
  \tweak self-alignment-X -0.6
  #(make-dynamic-script
    #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})

inst =
#(define-music-function
     (string)
     (string?)
   #{ <>^\markup \bold \box #string #})

\layout{
  \context {
    \Score
    \override MetronomeMark.extra-offset = #'(-5 . 0)
    \override MetronomeMark.padding = 3
  }
  \context {
    \Staff
    \numericTimeSignature
  }
  \context {
    \Voice
    \override Glissando.thickness = 3
    \override Glissando.gap = 0.1
  }
}

\relative {
  \tempo 4=50
  a'4.\mpdolce d8 cis4--\glissando a |
  b4 bes a2 |
  \inst "Clarinet"
  cis4.\< d8 e4 fis |
  g8(\! fis)-. e( d)-. cis2 |
}
@end lilypond

C'est encore mieux ! Mais supposons maintenant que je veuille publier
cette pièce. Mon professeur de composition n'aime pas les chiffrages de
mesure en « C », mais moi je les aime bien. Copions l'actuel
@file{definitions.ily} dans le fichier @file{publication-web.ily}, et
modifions ce dernier. Puisque la musique est destinée à produire un
fichier PDF affiché sur écran, nous allons aussi augmenter la taille
globale de police.

@example
%%%  web-publish.ily
mpdolce =
  \tweak self-alignment-X -0.6
  #(make-dynamic-script
    #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})

inst =
#(define-music-function
     (string)
     (string?)
   #@{ <>^\markup \bold \box #string #@})

#(set-global-staff-size 23)

\layout@{
  \context @{
    \Score
    \override MetronomeMark.extra-offset = #'(-5 . 0)
    \override MetronomeMark.padding = 3
  @}
  \context @{
    \Staff
  @}
  \context @{
    \Voice
    \override Glissando.thickness = 3
    \override Glissando.gap = 0.1
  @}
@}
@end example

@lilypond[quote,ragged-right]
mpdolce =
  \tweak self-alignment-X -0.6
  #(make-dynamic-script
    #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})

inst =
#(define-music-function
     (string)
     (string?)
   #{ <>^\markup \bold \box #string #})

#(set-global-staff-size 23)

\layout{
  \context { \Score
    \override MetronomeMark.extra-offset = #'(-5 . 0)
    \override MetronomeMark.padding = 3
  }
  \context { \Voice
    \override Glissando.thickness = 3
    \override Glissando.gap = 0.1
  }
}

\relative {
  \tempo 4=50
  a'4.\mpdolce d8 cis4--\glissando a |
  b4 bes a2 |
  \inst "Clarinet"
  cis4.\< d8 e4 fis |
  g8(\! fis)-. e( d)-. cis2 |
}
@end lilypond

Il ne nous reste plus qu'à remplacer @code{\include "definitions.ily"}
par @code{\include "publication-web.ily"} dans notre fichier de musique.

Il est possible, bien sûr, de rendre cela encore plus pratique. Nous
pourrions créer un fichier @file{definitions.ily} qui ne contiendrait
que les définitions de @code{\mpdolce} et de @code{\inst}, un fichier
@file{publication-web.ily} qui ne contiendrait que la section
@code{\layout} décrite ci-dessus et un fichier @file{universite.ily} qui
ne contiendrait que les retouches pour produire le résultat que mon
professeur préfère. Le début du fichier @file{musique.ly} ressemblerait
alors à

@example
\include "definitions.ily"

%%%  Décommentez seulement une de ces deux lignes !
\include "publication-web.ily"
%\include "universite.ily"
@end example

Cette approche peut être utile même si vous ne produisez qu'un seul jeu
de partitions. J'utilise personnellement une demi-douzaine de fichiers
de « feuille de style » pour mes projets. Je commence chaque fichier de
musique par @code{\include "../global.ily"} qui contient :

@example
%%%   global.ily
\version "@version{}"

#(ly:set-option 'point-and-click #f)

\include "../init/init-defs.ly"
\include "../init/init-mise-en-page.ly"
\include "../init/init-en-tetes.ly"
\include "../init/init-papier.ly"
@end example


@node Other sources of information
@subsection Autres sources de documentation

La référence des propriétés internes contient beaucoup d'informations
sur LilyPond. Cependant vous pouvez en découvrir encore plus en
consultant les fichiers internes de LilyPond. Pour cela, il vous faut
d'abord connaître le répertoire @emph{ad hoc} sur votre système. Si vous
tapez

@example
lilypond --help
@end example

@noindent
sur la ligne de commande, le dossier racine de l'aborescence des données
de LilyPond s'affiche vers la fin de la fenêtre d'aide ; quelque chose
comme

@example
Répertoire racine des données de LilyPond :
  '/usr/local/share/lilypond/@version{}'
@end example

Dans ce répertoire, deux sous-répertoires sont particulièrement
intéressants :

@indentedblock
@table @file
@item ly/
contient les fichiers en format LilyPond
@item scm/
contient les fichiers en format Scheme
@end table
@end indentedblock

Commençons par examiner quelques fichiers contenus dans @file{ly/}. Nous
ouvrons @file{ly/property-init.ly} dans un éditeur de texte -- celui que
vous avez l'habitude d'utiliser pour les fichiers @file{.ly} fera très
bien l'affaire. Ce fichier contient les définitions de toutes les
commandes standard prédéfinies de LilyPond, comme @code{\tieUp} et
@code{\slurDotted}. Vous pouvez constater que ce n'est rien d'autre que
des définitions de variables composées d'un ou plusieurs groupes de
commandes @code{\override}. Par exemple, @code{\textLengthOn} est défini
comme :

@example
textLengthOn = @{
  % 0.4 staff-space between adjacent texts
  \override TextScript.extra-spacing-width = #'(-0.0 . 0.4)
  \override TextScript.extra-spacing-height = #'(-inf.0 . +inf.0)
@}
@end example

Si vous n'aimez pas les valeurs par défaut, les commandes prédéfinies
peuvent être facilement redéfinies, comme n'importe quelle autre
variable, en tête de votre fichier d'entrée.

Voici les fichiers les plus utiles dans le répertoire @file{ly/} :

@indentedblock
@raggedright
@multitable @columnfractions .42 .53
@headitem Nom de fichier
  @tab Contenu
@item @file{ly/engraver-init.ly}
  @tab Définition des contextes de graveur
@item @file{ly/paper-defaults-init.ly}
  @tab Réglages papier par défaut
@item @file{ly/performer-init.ly}
  @tab Définition des contextes d'interprétation
@item @file{ly/property-init.ly}
  @tab Définition de toutes les commandes prédéfinies courantes
@item @file{ly/spanner-init.ly}
  @tab Définition des commandes prédéfinies pour les bandeaux
@end multitable
@end raggedright
@end indentedblock

Les autres réglages (comme les définitions de commandes @emph{markup})
sont conservés comme fichiers @file{.scm} (Scheme). Le langage de
programmation Scheme offre une interface programmable dans le processus
interne de LilyPond. De plus amples explications sur ces fichiers
dépasseraient le cadre de ce manuel dans la mesure où elles requièrent
la connaissance du langage Scheme. Les utilisateurs qui souhaiteraient
comprendre le fonctionnement de ces fichiers de configuration doivent
être avertis que des connaissances techniques substantielles et beaucoup
de temps sont nécessaires (voir le @rextendnamed{Scheme tutorial,
Tutoriel Scheme}).

Si c'est votre cas, les fichiers Scheme les plus utiles à connaître
sont :

@indentedblock
@raggedright
@multitable @columnfractions .42 .53
@headitem Nom de fichier
  @tab Contenu
@item @file{scm/auto-beam.scm}
  @tab Règles par défaut des ligatures subalternes
@item @file{scm/define-grobs.scm}
  @tab Réglages par défaut des propriétés de @emph{grobs}
@item @file{scm/define-markup-commands.scm}
  @tab Spécification de toutes les commandes de @emph{markup}
@item @file{scm/midi.scm}
  @tab Réglages par défaut pour les sorties MIDI
@item @file{scm/output-lib.scm}
  @tab Réglages affectant l'apparence des frets, couleurs, altérations,
       barres de mesure, etc.
@item @file{scm/parser-clef.scm}
  @tab Définition des clefs prises en charge
@item @file{scm/script.scm}
  @tab Réglages par défaut des articulations
@end multitable
@end raggedright
@end indentedblock


@node Advanced tweaks with Scheme
@subsection Retouches avancées avec Scheme

Nous avons vu à quel point le résultat obtenu avec LilyPond peut être
largement personnalisé à l'aide de commandes comme @code{\override} et
@code{\tweak}. Et pourtant l'utilisation de Scheme ouvre des
possibilités encore plus grandes. Le code écrit dans le langage de
programmation Scheme peut être intégré directement dans le processus
interne de LilyPond. Bien sûr, il faut pour cela connaître un minimum de
programmation en langage Scheme. Pour des explications complètes
là-dessus, consultez le @rextendnamed{Scheme tutorial, Tutoriel Scheme}.

En guise d'illustration -- et ce n'est qu'une possibilité parmi tant
d'autres -- nous allons attribuer à une propriété non pas une valeur
préétablie mais une procédure Scheme qui sera lancée à chaque
utilisation de la propriété par LilyPond. De cette façon, nous obtenons
un réglage dynamique de la propriété par le simple fait d'invoquer la
procédure. Dans cet exemple, nous colorons les têtes de notes en
fonction de leur position sur la portée.

@cindex @code{x11-color}, exemple d'utilisation de la fonction
@cindex @code{NoteHead}, exemple de dérogation
@cindex @code{color}, détermination de la propriété par une procédure Scheme

@lilypond[quote,verbatim,ragged-right]
#(define (color-notehead grob)
   "Color the notehead according to its position on the staff."
   (let ((mod-position (modulo (ly:grob-property grob 'staff-position)
                               7)))
     (case mod-position
       ;;   Return rainbow colors
       ((1) (x11-color 'red    ))  ; for C
       ((2) (x11-color 'orange ))  ; for D
       ((3) (x11-color 'yellow ))  ; for E
       ((4) (x11-color 'green  ))  ; for F
       ((5) (x11-color 'blue   ))  ; for G
       ((6) (x11-color 'purple ))  ; for A
       ((0) (x11-color 'violet ))  ; for B
       )))

\relative {
  % Arrange to obtain color from color-notehead procedure
  \override NoteHead.color = #color-notehead
  a2 b | c2 d | e2 f | g2 a |
}
@end lilypond

Vous trouverez dans @rextendnamed{Callback functions, Fonctions de
rappel} d'autres exemples d'utilisation de ces interfaces programmables.
