@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
@c This file is part of lilypond.tely
@ignore
    Translation of GIT committish: 964d024dd4f022ba7cd66adc13c0169035d4c4e5

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.11.61"

@c Translators: Valentin Villenave, Nicolas Klutchnikoff
@c Translation checkers: Jean-Charles Malahieude, John Mandereau

@node Tweaking output
@chapter Tweaking output

Ce chapitre indique comment modifier le résultat que vous obtiendrez.
LilyPond offre de nombreuses possibilités de réglages, permettant de modifier
quasiment chaque élément de votre partition.

@menu
* Tweaking basics::             
* The Internals Reference manual::  
* Appearance of objects::       
* Placement of objects::        
* Collisions of objects::       
* Common tweaks::               
* Further tweaking::            
@end menu

@node Tweaking basics
@section Tweaking basics

@untranslated

@menu
* Introduction to tweaks::      
* Objects and interfaces::      
* Naming conventions of objects and properties::  
* Tweaking methods::            
@end menu

@node Introduction to tweaks
@subsection Introduction to tweaks

@untranslated

@node Objects and interfaces
@subsection Objects and interfaces

@untranslated

@node Naming conventions of objects and properties
@subsection Naming conventions of objects and properties

@untranslated

@node Tweaking methods
@subsection Tweaking methods

@untranslated

@node The Internals Reference manual
@section The Internals Reference manual

@untranslated

@menu
* Properties of layout objects::  
* Properties found in interfaces::  
* Types of properties::         
@end menu

@node Properties of layout objects
@subsection Properties of layout objects

@untranslated

@node Properties found in interfaces
@subsection Properties found in interfaces

@untranslated

@node Types of properties
@subsection Types of properties

@untranslated

@node Appearance of objects
@section Appearance of objects

@untranslated

@menu
* Visibility and color of objects::  
* Size of objects::             
* Length and thickness of objects::  
@end menu

@node Visibility and color of objects
@subsection Visibility and color of objects

@untranslated

@node Size of objects
@subsection Size of objects

@untranslated

@node Length and thickness of objects
@subsection Length and thickness of objects

@untranslated

@node Placement of objects
@section Placement of objects

@untranslated

@menu
* Automatic behavior::          
* Within-staff objects::        
* Outside staff objects::       
@end menu

@node Automatic behavior
@subsection Automatic behavior

@untranslated

@node Within-staff objects
@subsection Within-staff objects

@untranslated

@node Outside staff objects
@subsection Outside staff objects

@untranslated


@node Collisions of objects
@section Collisions of objects


@menu
* Moving objects::              
* Fixing overlapping notation::  
* Real music example::          
@end menu

@node Moving objects
@subsection Moving objects

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.

@c  FIXME: find a better example for 5.1 Moving Objects.  -gp
@c  yes, I want this TODO to be visible to end-users.  It's better
@c  than having nothing at all.
À FAIRE : les modifications de la gestion des espacements de la version 2.12
feront perdre leur pertinence aux exemples suivants.  Ils démontrent cependant 
la puissance de LilyPond, et justifient à ce titre leur présence dans
ces lignes, tant que d'autres exemples n'auront pas été proposés.

@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  % temporary code to break this example:
  \override TextScript #'outside-staff-priority = ##f
e4^\markup{ \italic ritenuto } g b e
@end lilypond

@cindex padding

Le plus simple est ici d'augmenter la distance entre l'objet (du
texte comme ici, ou bien des nuances ou des doigtés) et la note.
Dans LilyPond, il s'agit de la propriété @code{padding}, qui
se mesure en espaces relatifs à la taille de la portée. Pour la plupart
des objets (chacun ayant sa propre valeur), elle est définie à 1.0, ou
un peu moins.  Nous voulons ici l'augmenter : essayons 1.5.

@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  % temporary code to break this example:
  \override TextScript #'outside-staff-priority = ##f
\once \override TextScript #'padding = #1.5
e4^\markup{ \italic ritenuto } g b e
@end lilypond


C'est déjà mieux ! Mais on peut certainement encore améliorer le résultat. 
Il nous semble, après plusieurs essais, que la meilleure valeur
dans ce cas soit 2.3. Toutefois, ce constat est le fruit 
d'expérimentations et de goût personnel en matière de notation.
Essayez le même exemple avec 2.3... mais également avec 
des valeurs plus grandes (ou plus petites).
À votre avis, quelle est la meilleure version ?


La propriété @code{staff-padding} est de nature similaire.
@code{padding} détermine l'espace minimum entre un objet et l'objet
le plus proche (le plus souvent une note ou les lignes de la portée) ;
@code{staff-padding} détermine pour sa part l'espace minimum entre
un objet et la portée. La différence est subtile, mais vous apparaîtra 
clairement ici :

@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  % temporary code to break this example:
  \override TextScript #'outside-staff-priority = ##f
c4^"piu mosso" b a b
\once \override TextScript #'padding = #4.6
c4^"piu mosso" d e f
\once \override TextScript #'staff-padding = #4.6
c4^"piu mosso" fis a g
\break
c'4^"piu mosso" b a b
\once \override TextScript #'padding = #4.6
c4^"piu mosso" d e f
\once \override TextScript #'staff-padding = #4.6
c4^"piu mosso" fis a g
@end lilypond

@cindex extra-offset

Une autre démarche permet de contrôler totalement la position d'un
objet --- on peut le déplacer horizontalement ou verticalement.  Il
suffit d'avoir recours à la propriété @code{extra-offset}.  En fait
c'est une méthode plus complexe, qui peut en outre poser des
problèmes.  Quand on déplace un objet à l'aide de @code{extra-offset},
le déplacement est effectué après que LilyPond a placé tous les autres
objets.  Par conséquent, l'objet ainsi déplacé peut venir
recouvrir d'autres objets déjà placés.


@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  % temporary code to break this example:
  \override TextScript #'outside-staff-priority = ##f
\once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
e4^\markup{ \italic ritenuto } g b e
@end lilypond

Lorsqu'on utilise @code{extra-offset}, le premier nombre décrit le
déplacement horizontal (négatif pour un déplacement vers la gauche) 
tandis que le deuxième décrit un déplacement vertical (positif 
pour le haut).  Après quelques essais, on peut choisir les valeurs suivantes
qui semblent donner un résultat satisfaisant.

@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  % temporary code to break this example:
  \override TextScript #'outside-staff-priority = ##f
\once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
e4^\markup{ \italic ritenuto } g b e
@end lilypond

@noindent

Une fois encore, c'est après quelques tâtonnements que l'on a abouti à
ces nombres, au regard du résultat final.  Si vous souhaitez que 
le texte soit plus haut, plus à gauche, etc. essayez vous-même et choisissez
aprés avoir regardé le résultat.

Une dernière mise en garde : dans cette section, nous avons eu recours à

@example
\once \override TextScript @dots{}
@end example

ce qui permet de régler le placement du texte pour la note suivante. 
Mais si cette note n'a pas de texte, le réglage ne s'appliquera pas
et n'attendra @strong{pas} le prochain texte.  Pour que ce comportement 
persiste après la commande, ne mettez pas @code{\once}.  Votre réglage
s'appliquera alors partout, jusqu'à ce que vous l'annuliez au moyen de
la commande @code{\revert}.  Ceci est expliqué en détail dans 
@ruser{The \override command}.

@lilypond[quote,fragment,ragged-right,verbatim,relative=3]
  % temporary code to break this example:
  \override TextScript #'outside-staff-priority = ##f
c4^"piu mosso" b
\once \override TextScript #'padding = #4.6
  a4 b
c4^"piu mosso" d e f
\once \override TextScript #'padding = #4.6
c4^"piu mosso" d e f
c4^"piu mosso" d e f
\break
\override TextScript #'padding = #4.6
c4^"piu mosso" d e f
c4^"piu mosso" d e f
\revert TextScript #'padding
c4^"piu mosso" d e f
@end lilypond


@seealso
Dans ce même manuel : @ruser{The \override command}, @ref{Common tweaks}.


@node Fixing overlapping notation
@subsection Fixing overlapping notation

Dans la section @ref{Moving objects}, nous avons vu comment
déplacer un objet @code{TextScript}.  Ce même procédé peut être
appliqué à d'autres types d'objet : il vous suffira de remplacer
@code{TextScript} par le nom de l'objet en question.

Pour trouver cette dénomination, regardez les liens @q{@strong{Voir aussi}}
en bas des pages de la documentation.  Par exemple, en bas de la page
@ruser{Dynamics}, nous trouvons 


@seealso
Référence du programme : @rinternals{DynamicText}, @rinternals{Hairpin}.
Le placement vertical de ces symboles est contrôlé par
@rinternals{DynamicLineSpanner}.

@noindent
Ce qui implique que, pour modifier la hauteur d'une nuance, nous utiliserons

@example
\override DynamicLineSpanner #'padding = #2.0
@end example

Nous ne listerons pas ici tous les types d'objets, mais seulement
les plus communs :

@multitable @columnfractions .33 .66
@headitem Type d'objet            @tab Nom de l'objet
@item Nuances (verticalement)     @tab @code{DynamicLineSpanner}
@item Nuances (horizontalement)   @tab @code{DynamicText}
@item Laisons de tenue            @tab @code{Tie}
@item Liaisons                    @tab @code{Slur}
@item Indications d'articulation  @tab @code{Script}
@item Doigtés                     @tab @code{Fingering}
@item Textes (@code{^"texte"})    @tab @code{TextScript}
@item Repères                     @tab @code{RehearsalMark}
@end multitable


@node Real music example
@subsection Real music example

@untranslated


@c DEPRECATED SECTION
@node Common tweaks
@section Common tweaks

Certains réglages sont si courants que des raccourcis sont fournis
sous forme de commandes telles que @code{\slurUp} ou @code{\stemDown}.  
Toutes ces commandes sont décrites dans les différentes sections
de la Référence de notation.

La liste complète des modifications possibles pour chaque type d'objet
(tel que liaison ou ligature) se trouve dans la Référence du
programme.  Cependant, certaines propriétés sont communes à de nombreux
objets, et on peut de ce fait définir quelques réglages génériques.


@itemize @bullet

@cindex padding

@item
La propriété @code{padding} peut être définie de manière à
accroître (ou décroître) la distance entre les symboles qui se
placent au-dessus ou au-dessous des notes.  Ce qui s'applique à
tous les objets régis par @code{side-position-interface}.

@lilypond[quote,fragment,relative=1,verbatim]
c2\fermata
\override Script #'padding = #3
b2\fermata
@end lilypond

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

Notez, dans le second exemple, l'importance de savoir à quel contexte
correspond l'objet.  Dans la mesure où l'objet @code{MetronomeMark}
appartient au contexte @code{Score}, ses modifications affectées au
contexte @code{Voice} ne l'affecteront pas.  Pour plus de détails, voir 
@ruser{Constructing a tweak}.

@cindex extra-offset

@item
La propriété @code{extra-offset} permet de déplacer latéralement et
verticalement ; c'est pourquoi elle requiert deux nombres.  Le premier
affecte le placement horizontal (un nombre positif déplace l'objet
vers la droite) ; le second le placement vertical (un nombre positif
déplace l'objet vers le haut).  Cette propriété est de bas niveau : le
moteur de formatage ne tient aucun compte des placements qu'elle induit.

Dans l'exemple suivant, le second doigté est déplacé un peu vers la gauche, et
plus bas de 1.8 espaces :

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

@item
La propriété @code{transparent} imprime les objets avec de 
l'@q{encre invisible} : l'objet n'est pas visible, mais tous
les comportement le concernant s'appliquent quand même.  Il occupe
une certaine place, intervient dans la gestion des collisions, et on
peut lui attacher des liaisons ou des ligatures.

@cindex transparents, objets
@cindex suppression d'objets
@cindex masquage d'objets
@cindex invisibles, objets

L'exemple suivant montre comment tenir des notes entre différentes voix,
au moyen de liaisons.  Ces liaisons de tenue, en principe, ne peuvent relier
que deux notes d'une même voix.  On introduit donc la liaison dans une
autre voix :

@lilypond[quote,fragment,relative=2]
<< {
  b8~ b8\noBeam
} \\ {
  b[ g8]
} >>
@end lilypond

@noindent
et on efface la première croche (hampe vers le haut) de ladite voix ; 
maintenant la liaison semble passer d'une voix à l'autre :


@lilypond[quote,fragment,relative=2,verbatim]
<< {
  \once \override Stem #'transparent = ##t
  b8~ b8\noBeam
} \\ {
  b[ g8]
} >>
@end lilypond

Pour s'assurer que le crochet de la hampe que nous avons effacée ne 
raccourcira pas la liaison, nous allons également rallonger cette hampe,
en attribuant à la propriété @code{length} la valeur @code{8} :

@lilypond[quote,fragment,relative=2,verbatim]
<< {
  \once \override Stem #'transparent = ##t
  \once \override Stem #'length = #8
  b8~ b8\noBeam
} \\ {
  b[ g8]
} >>
@end lilypond

@end itemize

@cindex retouches, distances
@cindex distances

Les distances dans LilyPond sont mesurées dans l'unité staff-space
(espace de portée) tandis que la plupart des propriétés relatives aux
épaisseurs sont mesurées à l'aide de l'unité line-thickness (épaiseur
de ligne). Toutefois, certaines d'entre-elles échappent à cette règle
: par exemple l'épaisseur des liens de croches est mesurée à l'aide de
l'unité staff-space.  Pour de plus amples informations, 
consultez les sections correspondantes de la Référence du programme.


@node Further tweaking
@section Further tweaking

@menu
* Other uses for tweaks::       
* Using variables for tweaks::  
* Other sources of information::  
* Avoiding tweaks with slower processing::  
* Advanced tweaks with Scheme::  
@end menu

@node Other uses for tweaks
@subsection Other uses for tweaks

@untranslated

@node Using variables for tweaks
@subsection Using variables for tweaks

@untranslated

@node Other sources of information
@subsection Other sources of information

La Référence du programme contient
beaucoup d'informations sur LilyPond. Cependant vous pouvez en découvrir 
encore plus en consultant les fichiers internes de LilyPond.

Des réglages par défaut (tels que les définitions des blocs
@code{\header@{@}}) sont contenus dans des fichiers @code{.ly}. D'autres 
(comme les définitions des commandes @qq{markup} ) sont contenus dans
des fichiers @code{.scm} (Scheme).  Malheureusement, des explications
plus complètes dépassent le cadre de ce manuel.
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.

@itemize @bullet

@item Linux : @file{@var{dossierduprogramme}/lilypond/usr/share/lilypond/current/}

@item Mac OS X :
@file{@var{dossierduprogramme}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
Pour accéder à ce dossier, deux possibilités : soit, dans un Terminal,
taper @code{cd} suivi du chemin complet ci-dessus ; soit
Control-cliquer (ou clic droit) sur l'application LilyPond
et sélectionner @q{Afficher le contenu du paquet}.


@item Windows : @file{@var{dossierduprogramme}/LilyPond/usr/share/lilypond/current/}

@end itemize

Les répertoires @file{ly/} et @file{scm/} sont tout particulièrement
intéressants.  En effet les fichiers du type
@file{ly/property-init.ly} ou encore @file{ly/declarations-init.ly}
déterminent toutes les définitions avancées communes.

@node Avoiding tweaks with slower processing
@subsection Avoiding tweaks with slower processing

LilyPond peut effectuer des vérifications supplémentaires lors du 
traitement des fichiers, cependant le rendu nécessitera alors plus de
temps.  En contrepartie, il y aura moins d'ajustements manuels à réaliser.

  
@example
%%  Ceci sert à s'assurer que les indications textuelles resteront à l'intérieur des marges de la page.
\override Score.PaperColumn #'keep-inside-line = ##t 
@end example


@node Advanced tweaks with Scheme
@subsection Advanced tweaks with Scheme

Nous avons déjà vu comment le résultat obtenu avec LilyPond peut être
largement personnalisé à l'aide de commandes comme 
@code{\override TextScript #'extra-offset = ( 1 . -1)}.  Cependant,
l'utilisation de Scheme ouvre des possibilités encore plus grandes.
Pour des explications complètes là-dessus, consultez le 
@ref{Scheme tutorial}  et les @ruser{Interfaces for programmers}.

On peut utiliser Scheme simplement à l'aide des commandes @code{\override}.

@lilypond[quote,verbatim,ragged-right]
padText = #(define-music-function (parser location padding) (number?)
#{
  \once \override TextScript #'padding = #$padding
#})

\relative c''' {
  c4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" d e f
  \padText #2.6
  c4^"piu mosso" fis a g
}
@end lilypond
On peut s'en servir pour créer de nouvelles commandes :

@lilypond[quote,verbatim,ragged-right]
tempoMark = #(define-music-function (parser location padding marktext)
                                    (number? string?)
#{
  \once \override Score . RehearsalMark #'padding = $padding
  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
  \mark \markup { \bold $marktext }
#})

\relative c'' {
  c2 e
  \tempoMark #3.0 #"Allegro"
  g c
}
@end lilypond

On peut même y inclure des expressions musicales :

@lilypond[quote,verbatim,ragged-right]
pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
#{
  $x e8 a b $y b a e
#})

\relative c''{
  \pattern c8 c8\f
  \pattern {d16 dis} { ais16-> b\p }
}
@end lilypond