@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
@ignore
- Translation of GIT committish: 8c1840ca28a05b3dad8d595e04d03779ba0a286a
+ Translation of GIT committish: c377d85f06e524599d20e9edf102ae186ede5e77
When revising a translation, copy the HEAD committish of the
version that you are working on. For details, see the Contributors'
@}
@end example
+De la même manière, si la musique est saisie à la suite d'une commande
+abrégée, telle que @code{\chords} au lieu de @code{\chordmode},
+l'instruction @code{\with} viendra se placer juste après la commande
+spécifiant le mode :
+
+@example
+\chords \with @{ [réglages pour ce contexte (implicite) pris individuellement] @}
+@{
+ @dots{}
+@}
+@end example
+
+@noindent
+puisque c'est le contexte implicite alors créé qui devra être modifié.
+Cette manière de procéder s'applique à toutes les autres formes abrégées
+de spécification du mode de saisie (@code{\drums}, @code{\figures}) --
+voir @ref{Modes de saisie}.
+
Dans la mesure où une telle « modification de contexte » est spécifiée
au sein même de la musique, ses effets toucheront @b{toutes} les sorties
(imprimable @b{et} Midi), contrairement à ce qui se passe lorsque les
@end itemize
+@seealso
+Manuel de notation :
+@ref{Modes de saisie}.
+
@node Ordre de préséance
@unnumberedsubsubsec Ordre de préséance
* La commande de dérogation (override)::
* La commande d'affinage (tweak)::
* set ou override::
+* La commande de décalage (offset)::
* Modification de listes associatives::
@end menu
Les instructions spéciales @code{\tweak} et @code{\overrideProperty}
modifient les propriétés de @emph{grob} en court-circuitant totalement
les propriétés de contexte. En fait, elles capturent les @emph{grobs}
-au moment de leur création pour y injecter directement des propriétés soit
-émanant d'un événement musical retouché par un @code{\tweak}, soit
+au moment de leur création pour y injecter directement des propriétés
+soit émanant d'un événement musical retouché par un @code{\tweak}, soit
lorsqu'ils sont d'une qualité particulière (un @code{\overrideProperty}).
+@node La commande de décalage (offset)
+@subsection La commande de décalage @code{\offset}
+@translationof The offset command
+
+@funindex \offset
+@cindex décalage
+@cindex offset (décalage)
+
+Bien qu'il soit possible d'affecter de nouvelles valeurs aux propriétés
+d'un objet graphique à l'aide des commandes @code{\override},
+@code{\tweak} ou @code{\overrideProperty}, il est souvent plus pratique
+de modifier de telles propriétés par rapport à une valeur par défaut.
+Ceci est la raison d'être de la commande @code{\offset}.
+
+La commande @code{\offset} répond à la syntaxe suivante :
+
+@example
+[-]\offset @var{propriété} @var{décalages} @var{élément}
+@end example
+
+La commande @code{\offset} agit par addition du contenu de
+@var{décalage} au réglage par défaut de la propriété @var{propriété} de
+l'objet graphique indiqué par @var{élément}.
+
+Selon la manière dont la commande est formulée, @code{\offset} agira
+tantôt comme un @code{\tweak}, tantôt comme un @code{\override}. Les
+différences entre ces utilisations seront abordées après avoir recensé
+les propriétés qui peuvent être soumises à un @code{\offset}.
+
+@subsubsubheading Propriétés acceptant des décalages
+@c VO Properties which may be offset
+
+Bon nombre de propriétés d'objet graphique, mais pas toutes, peuvent
+faire l'objet d'un décalage. Si d'aventure @var{propriété} ne peut être
+affectée, l'objet restera inchangé et sera émis un message
+d'avertissement. En pareil cas, l'objet doit être modifié par un
+@code{\override} ou un @code{\tweak}.
+
+Il est toujours possible de procéder à tâtons et laisser les
+avertissement indiquer si tel objet peut ou ne peut pas être soumis à
+@code{\offset}. Néanmoins, une approche plus systématique est possible.
+
+Les critères énoncés ci-après déterminent l'égibilité d'une propriété à
+être modifiée par la commande @code{\offset}.
+
+@itemize
+
+@item
+La propriété possède un « réglage par défaut » au niveau de la
+définition de l'objet graphique. Les propriétés en question sont
+listées, pour chacun des @emph{grobs}, dans
+@rinternalsnamed{All layout objects, Tous les objets de rendu} -- on les
+trouvera aussi dans le fichier @file{scm/define-grobs.scm}.
+
+@item
+La propriété prend une valeur numérique. Les valeurs numériques
+comprennent @code{number}, liste de @code{number}s, @code{number-pair}
+et @code{number-pair-list}. Les pages de
+@rinternalsnamed{All layout objects, Tous les objets de rendu}
+répertorient le type de donnée propre à chaque propriété. Peu importe
+que le réglage par défaut soit une fonction.
+
+@item
+La propriété ne saurait constituer une « sous-propriété » -- une
+propriété résidant au sein d'une autre propriété.
+
+@item
+Les propriétés réglées sur des valeurs infinies ne peuvent faire l'objet
+d'un décalage. Il n'y a aucun moyen d'influencer l'infini, qu'il soit
+positif ou négatif.
+@end itemize
+
+Les exemples qui suivent s'arrêtent sur plusieurs propriétés d'objet
+graphique au regard des critères énoncés ci-dessus.
+
+@itemize
+
+@item Propriétés qui peuvent être décalées
+
+@table @asis
+
+@item @code{Hairpin.height}
+Cette propriété n'est pas une sous-propriété, et est référencée à
+@rinternalsnamed{Hairpin, Soufflet}. En tant que valeur, elle prend une
+« dimension, exprimée en espace de portée » réglée à @code{0.6666} --
+clairement une valeur @code{number} non infini.
+
+@item @code{Arpeggio.positions}
+La page @rinternalsnamed{Arpeggio, Arpeggio} référence une propriété
+@code{positions} qui accepte une « paire de nombres ». Sa valeur par
+défaut est @code{ly:arpeggio::positions} -- une fonction de rappel qui
+sera évaluée au cours de la phase de typographie pour donner une paire
+de nombres pour tout objet @code{Arpeggio}.
+
+@end table
+
+@item Propriétés qui ne peuvent être décalées
+
+@table @asis
+
+@item @code{Hairpin.color}
+Aucune référence à @code{color} n'est mentionnée dans
+@rinternalsnamed{Hairpin, Soufflet}.
+
+@item @code{Hairpin.circled-tip}
+La référence à @code{Hairpin.circled-tip} dans
+@rinternalsnamed{Hairpin, Soufflet} indique que cette propriété prend une
+valeur @code{boolean}. Les boléens ne sont pas des nombres.
+
+@item @code{Stem.details.lengths}
+Bien que mentionnée dans @rinternalsnamed{Stem, Hampe} et ayant par
+défaut une liste de @code{number}s, il s'agit d'une « sous-propriété ».
+Il n'existe à ce jour aucune prise en charge des « propriétés
+imbriquées ».
+
+@end table
+
+@end itemize
+
+
+@subsubsubheading @code{\offset} en tant que dérogation
+@c VO \offset as an override
+
+Lorsque @var{élément} est un nom d'objet graphique comme @code{Arpeggio}
+ou @code{Staff.OttavaBracket}, le comportement de la commande
+@code{\offset} est assimilable à un @code{\override} sur le type d'objet
+spécifié.
+
+@example
+\offset @var{propriété} @var{décalages} [@var{contexte}.]@var{NomGrob}
+@end example
+
+Notez bien qu'il n'y a jamais de tiret avant un comportement
+« dérogatoire », tout comme il n'y en a jamais avec la commande
+@code{\override} elle-même.
+
+L'exemple suivant utilise la forme « dérogation » pour allonger les
+arpeggios affichés dans la première mesure, jusqu'à couvrir l'accord
+dans son intégralité. Les arpeggios sont étirés d'un demi espace de
+portée à leur sommet ainsi qu'à leur base. Est aussi indiquée la même
+opération sur le premier accord à l'aide d'une simple dérogation
+appliquée à la propriété @code{positions}. Cette méthode n'est pas la
+plus illustrative pour « étirer d'un demi espace de portée » dans la
+mesure où les extrémités doivent être spécifiées en coordonnées absolues
+plutôt que relatives. De plus, des dérogations individuelles seraient
+nécessaires pour les autres accords en raison de leurs différentes
+amplitude et position.
+
+@lilypond[quote,verbatim]
+arpeggioMusic = {
+ <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
+ <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
+}
+
+{
+ \arpeggioMusic
+ \bar "||"
+ \offset positions #'(-0.5 . 0.5) Arpeggio
+ \arpeggioMusic
+ \bar "||"
+ \once \override Arpeggio.positions = #'(-3.5 . -0.5)
+ <c' e' g'>1\arpeggio
+ \bar "||"
+}
+@end lilypond
+
+Dans cette utilisation d'@emph{override}, @code{\offset} peut se
+préfixer de @code{\once} ou @code{\temporary} et être annulé à l'aide
+d'un @code{\revert} suivi de @var{propriété}. Ceci tient au fait que
+@code{\offset} crée effectivement un @code{\override} de
+@var{propriété}.
+
+@lilypond[quote,verbatim]
+music = { c'8\< d' e' f'\! }
+
+{
+ \music
+ \offset height 1 Hairpin
+ \music
+ \music
+ \revert Hairpin.height
+ \music
+ \bar "||"
+ \once \offset height 1 Hairpin
+ \music \music
+ \bar "||"
+ \override Hairpin.height = 0.2
+ \music
+ \temporary \offset height 2 Hairpin
+ \music
+ \music
+ \revert Hairpin.height
+ \music
+ \bar "||"
+}
+@end lilypond
+
+Tout comme @code{\override}, la forme « dérogation » de @code{\offset}
+peut s'utiliser avec @code{\undo} et @code{\single}.
+
+@lilypond[quote,verbatim]
+longStem = \offset length 6 Stem
+
+{
+ \longStem c'4 c''' c' c''
+ \bar "||"
+ \undo \longStem c'4 c''' c' c''
+ \bar "||"
+ \single \longStem c'4 c''' c' c''
+ \bar "||"
+}
+@end lilypond
+
+@subsubsubheading @code{\offset} en tant qu'affinage
+@c VO offset as a tweak
+
+Lorsque @var{élément} est une expression musicale, comme @code{(} ou
+@code{\arpeggio}, le résultat sera la même expression musicale à
+laquelle aura été appliqué un affinage.
+@c closing )
+
+@example
+[-]\offset [@var{NomGrob}.]@var{propriété} @var{décalages} @var{expression-musicale}
+@end example
+
+La syntaxe de @code{\offset} dans sa forme « affinage » est en tout
+point analogue à la commande @code{\tweak}, autant dans l'ordre des
+arguments que dans la présence ou non du tiret l'introduisant.
+
+L'exemple suivant utilise la forme « affinage » pour ajuster le
+positionnement vertical de l'objet @code{BreathingSign}. Les effets de
+la simple commande @code{\tweak} sont présent à titre de comparaison.
+Leur syntaxe est équivalente. Néanmoins, le résultat de @code{\tweak}
+est moins intuitif dans la mesure où @code{BreathingSign.Y-offset} est
+calculé en référence à la ligne médiane. Il n'est pas nécessaire de
+savoir comment se calcule @code{Y-offset} dans le cas d'un
+@code{\offset}.
+
+@lilypond[quote,verbatim]
+{
+ c''4
+ \breathe
+ c''4
+ \offset Y-offset 2 \breathe
+ c''2
+ \tweak Y-offset 3 \breathe
+}
+@end lilypond
+
+Dans cet exemple, les objets affinés étaient créés directement à partir
+du code saisi : la commande @code{\breathe} était une instruction
+explicite pour renvoyer un objet @code{BreathingSign}. Puisque la cible
+de la commande était sans ambiguïté, point n'était besoin de spécifier
+le nom de l'objet. Cependant, lorsqu'un objet est créé
+@emph{indirectement}, mention du nom de l'objet devient requise. Il en
+va de même pour la commende @code{\tweak}.
+
+Dans l'exemple qui suit, l'objet @code{Beam} est abaissé de deux espaces
+de portée par application de @code{\offset} à la propriété
+@code{positions}.
+
+La première application de @code{\offset} requiert mention du nom de
+l'objet puisque rien dans le code ne crée explicitement de ligature.
+Dans la seconde application, la ligature est explicitement créée par
+l'expression musicale @code{[}, ce qui dispense de mentionner le nom de
+l'objet. Cette deuxième application comporte par ailleurs un
+raccourci : un unique @code{number} s'appliquera aux deux membres d'un
+@code{number-pair}.
+@c close ]
+
+@lilypond[quote,verbatim]
+{
+ c''8 g'' e'' d''
+ \offset Beam.positions #'(-2 . -2)
+ c''8 g'' e'' d''
+ c''8 g'' e'' d''
+ c''8-\offset positions #-2 [ g'' e'' d'']
+}
+@end lilypond
+
+@subsubsubheading @code{\offset} et les bandeaux avec rupture
+@c VO offset with broken spanners
+
+Il est aussi possible de modifier indépendamment les segments d'un objet
+étendu rencontrant des sauts de ligne. Dans ce cas, @var{décalages} est
+consitué d'une liste de valeurs pour le type de donnée requis par la
+propriété.
+
+Utilisée de telle manière, la commande @code{\offset} est similaire à la
+commande @code{\alterBroken} -- voir
+@ref{Modification de bandeaux avec rupture}. Cependant, et
+contrairement à la commande @code{\alterBroken}, les valeurs fournies à
+@code{\offset} sont relatives.
+
+Dans l'exemple suivant est déplacé l'objet « segmenté »
+@code{OttavaBracket} au travers de sa propriété @code{staff-padding}.
+Puisque cette propriété est affectée d'un @code{number}, @var{décalages}
+est alimenté d'une liste de @code{number}s afin de prendre en compte les
+deux segments créés par le saut de ligne. La portion de crochet de la
+première ligne n'est en fait pas touchée puisque @code{0} est ajouté à
+la valeur par défaut de @code{staff-padding}. Le segment de la deuxième
+ligne est haussé de trois espaces de portée par rapport à sa hauteur par
+défaut. La hauteur par défaut est de @code{2}, bien qu'il ne soit pas
+nécessaire de le savoir.
+
+@lilypond[quote,verbatim]
+{
+ \offset staff-padding #'(0 3) Staff.OttavaBracket
+ \ottava #1
+ c'''2 c'''
+ \break
+ c'''2 c'''
+}
+@end lilypond
+
+L'exemple ci-dessous reproduit les effets de la commande @code{\shape}
+en décalant la propriété @code{control-points} de l'objet @code{Slur}.
+Ici, @var{décalages} est constitué d'une liste de
+@code{number-pair-list}s, une pour chaque segment de la liaison. Cet
+exemple produit un résultat identique à ce qui est illustré dans
+@ref{Modification de l'allure des éléments}.
+
+@lilypond[quote,verbatim]
+{
+ c'4-\offset control-points #'(
+ ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
+ ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
+ ) ( f'4 g' c''
+ \break
+ d'4 c'' f' c')
+}
+@end lilypond
+
+
@node Modification de listes associatives
@subsection Modification de listes associatives
@translationof Modifying alists
@translationof Input modes
La manière dont sera interprétée la notation contenue dans un fichier
-source dépend du mode affecté à la saisie.
+source dépend du mode affecté à la saisie. Il existe, en règle
+générale, deux façons de spécifier le mode : une forme développée -- par
+exemple @code{\chordmode} -- et une forme abrégée -- par exemple
+@code{\chords}. La forme développée s'utilise particulièrement lorsque
+la saisie fait l'objet d'une variable ou se trouve dans un contexte
+explicitement créé. La forme abrégée crée implicitement un contexte du
+type adéquate à la saisie et la lui transmet directement. Cette forme
+abrégée est tout à fait indiquée aux situations simples pour lesquelles
+nul n'est besoin de créer explicitement le contexte qui prendra en
+charge la saisie.
+
@subsubsubheading Mode accords
@c VO Chord mode
Ce mode, activé par la commande @code{\chordmode}, permet d'interpréter
les saisies comme étant des accords, qui seront imprimés sous forme de
-notes sur une portée -- voir @ref{Notation des accords}.
+notes sur une portée -- voir @ref{Notation des accords}. La musique
+entrée en mode accords est rendue soit sous forme d'accords sur une
+portée pour un contexte @code{Staff}, soit sous forme de noms d'accord
+pour un contexte @code{ChordNames} ou sous forme de diagrammes pour un
+contexte @code{FretBoards}.
Le mode accords s'active aussi par la commande @code{\chords}, qui
-créera un contexte @code{ChordNames}. Les saisies, interprétées comme
-étant des accords, seront alors rendues sous forme nominale dans ce
+créera implicitement un nouveau contexte @code{ChordNames}. Le code
+saisi selon la syntaxe dévolue aux accords, sera interprété comme étant
+des accords nommés et sera alors rendu sous forme nominale dans ce
contexte @code{ChordNames} -- voir @ref{Impression des noms d'accord}.
+
@subsubsubheading Mode percussions
@c VO Drum mode
Ce mode, activé par la commande @code{\drummode}, permet d'interpréter
les saisies comme étant de la notation pour percussions -- voir
-@ref{Notation de base pour percussions}.
+-@ref{Notation de base pour percussions}. Lorsqu'elle est entrée en
+mode percussions, la musique est rendue dans un contexte
+@code{DrumStaff}.
Le mode percussions s'active aussi par la commande @code{\drums}, qui
-créera un contexte @code{DrumStaff}. Les saisies, interprétées comme
-étant de la notation pour percussions, seront alors rendues sous forme
+créera implicitement un nouveau contexte @code{DrumStaff}. Le code
+saisi selon la syntaxe dévolue aux percussions, sera interprété comme
+étant de la notation pour percussions et alors rendu sous forme
symbolique sur une portée de percussions -- voir
@ref{Notation de base pour percussions}.
+
@subsubsubheading Mode figures
@c VO Figure mode
Ce mode, activé par la commande @code{\figuremode}, permet d'interpréter
les saisies comme étant de la basse chiffrée (ou figurée) -- voir
-@ref{Saisie de la basse chiffrée}.
+@ref{Saisie de la basse chiffrée}. Lorsqu'elle est entrée en mode
+figures, la musique est rendue sous forme de basse figurée dans un
+contexte @code{FiguredBass} ou dans un contexte @code{Staff}.
Le mode figures s'active aussi par la commande @code{\figures}, qui
-créera un contexte @code{FiguredBass}. Les saisies interprétées comme
-étant de la basse chiffrée, seront alors rendues sous forme symbolique
-dans le contexte @code{FiguredBass} -- voir
+créera implicitement un nouveau contexte @code{FiguredBass}. Le code,
+saisi selon la syntaxe dévolue à la basse chiffrée, sera interprété
+comme étant des indication de basse chiffrée et sera alors rendu sous
+forme symbolique dans le contexte @code{FiguredBass} -- voir
@ref{Introduction à la basse chiffrée}.
+
@subsubsubheading Mode frets et tablatures
@c VO Fret and tab modes
@code{TabStaff} seront rendus sous forme de diagramme de tablature --
voir @ref{Tablatures par défaut}.
-Deux options différentes permettent d'obtenir des diagrammes de fret en
-surplomb d'une portée : directement à l'aide d'un contexte
-@code{FretBoards} -- voir @ref{Tablatures automatiques} -- ou en
-attachant aux notes des @emph{markups} créés par la commande
-@code{\fret-diagram} -- voir @ref{Tablatures sous forme d'étiquette}.
+Des diagrammes de fret viendront se positionner en surplomb d'une portée
+dès lors que les notes ou accords auront été saisis en mode note ou
+accord puis rendus dans un contexte @code{FretBoards} -- voir
+@ref{Tablatures automatiques}. Ils peuvent aussi se gérer sous forme de
+@emph{markups} créés par la commande @code{\fret-diagram} -- voir
+@ref{Tablatures sous forme d'étiquette}.
+
@subsubsubheading Mode paroles
@c VO Lyrics mode
Ce mode, activé par la commande @code{\lyricmode}, permet d'interpréter
les saisies comme étant des syllabes, ayant éventuellement une durée, et
des indications habituelles aux paroles -- voir @ref{Musique vocale}.
+Lorsqu'il est entré en mode paroles, le texte est rendu sous forme de
+syllabes dans un contexte @code{Lyrics}.
+
+Le mode paroles s'active aussi par la commande @code{\lyrics}, qui
+créera implicitement un nouveau contexte @code{Lyrics}. Le code saisi
+sera interprété comme étant des paroles et sera alors rendu sous forme
+de syllabes dans le contexte @code{Lyrics}.
Le mode paroles s'active aussi par la commande @code{\addlyrics}, qui
créera un contexte @code{Lyrics} et ajoutera implicitement une commande
@code{\lyricsto} afin d'associer les paroles qui suivent à la musique
-précédemment saisie.
+précédemment saisie -- voir @ref{Durée automatique des syllabes}.
+
@subsubsubheading Mode @emph{markup}
@c VO Markup mode
}
@end lilypond
-Tous les glyphes de la fonte Feta sont accessibles à l'aide de la
-commande de @emph{markup} @code{\musicglyph} -- voir
-@ref{La fonte Feta}.
+Tous les glyphes @code{Feta} de la fonte Emmentaler sont
+accessibles à l'aide de la commande de @emph{markup} @code{\musicglyph}
+-- voir @ref{La fonte Emmentaler}.
L'insertion de fichier @file{EPS} ou d'instructions Postscript sont
accessibles par les commandes de @emph{markup} @code{\epsfile} et
@ref{Commandes pour markup},
@ref{Éléments graphiques dans du texte formaté},
@rusernamed{Graphic, Graphisme},
-@ref{La fonte Feta},
+@ref{La fonte Emmentaler},
@ref{Mise en forme du texte}.
projects / lilypond.git / blobdiff