Documentation/fr/usage/updating.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
   2
   3 @ignore
   4     Translation of GIT committish: 6ec0d3283b9e23f2d21658d71ac6801c3aab69b8
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  For details, see the Contributors'
   8     Guide, node Updating translation committishes..
   9 @end ignore
  10
  11 @c \version "2.16.0"
  12
  13 @c Translators: Jean-Charles Malahieude
  14 @c Translation checkers:
  15
  16 @node Mise à jour avec convert-ly
  17 @chapter Mise à jour avec @command{convert-ly}
  18 @translationof Updating files with convert-ly
  19
  20 @cindex mise à jour de fichiers LilyPond
  21 @cindex convert-ly
  22
  23 La syntaxe des fichiers LilyPond évolue avec le temps, que ce soit dans
  24 le but de la simplifier ou pour l'améliorer.  Il en résulte que
  25 l'interpréteur de LilyPond se retrouve incapable de traiter d'anciens
  26 fichiers.  L'utilitaire @command{convert-ly} permet cependant de
  27 mettre ces fichiers en conformité au fur et à mesure que de nouvelles
  28 versions de LilyPond sont disponibles.
  29
  30 @menu
  31 * LilyPond est une langue vivante::
  32 * Exécution de convert-ly::
  33 * Options en ligne de commande pour convert-ly::
  34 * Problèmes d'exécution de convert-ly::
  35 * Conversions manuelles::
  36 @end menu
  37
  38
  39 @node LilyPond est une langue vivante
  40 @section LilyPond est une langue vivante
  41 @translationof Why does the syntax change?
  42
  43 @cindex convert-ly
  44 @cindex mise à jour d'anciens fichiers
  45
  46 La syntaxe de LilyPond change de temps en temps.  Ces changements de
  47 syntaxe -- le langage d'entrée -- accompagnent les améliorations du
  48 logiciel.  Ces changements sont parfois destinés à rendre les fichiers
  49 plus faciles à lire et à écrire, ou permettent d'intégrer de nouvelles
  50 fonctionnalités.
  51
  52 Par exemple, tous les noms des propriétés de @code{\paper} et
  53 @code{\layout} devaient être libellées sous la forme
  54 @code{@w{premier-deuxième-troisième}}.  Nous avons constaté, une fois la
  55 version 2.11.60 mise à disposition, que la propriété
  56 @code{printallheaders} ne respectait pas cette convention.  Aurions-nous
  57 dû la laisser telle que, au risque de dérouter les nouveaux utilisateurs
  58 par cette exception au formatage, ou bien la modifier -- ce qui allait
  59 obliger ceux qui l'avaient déjà utilisée à se mettre en chasse ?
  60 Pour ce cas d'espèce, nous avons décidé de changer pour
  61 @code{print-all-headers}.  Cette modification peut heureusement être
  62 automatisée par notre utilitaire @command{convert-ly}.
  63
  64 Malheureusement, @command{convert-ly} ne peut pas réaliser toutes les
  65 modifications.  Par exemple, dans les versions 2.4 et antérieures de
  66 LilyPond, les accents et les lettres non anglaises étaient entrées en
  67 utilisant @LaTeX{} -- par exemple, @code{No\"el}.  À partir de la
  68 version 2.6, le caractère @code{ë} doit être entré directement dans
  69 le fichier LilyPond comme caractère UTF-8.   @command{convert-ly} ne
  70 peut pas changer tous les caractères @LaTeX{} en caractères UTF-8 ; vous
  71 devez mettre à jour vos vieux fichiers LilyPond manuellement.
  72
  73 Les règles de conversion de @command{convert-ly} reposent sur la
  74 recherche et le remplacement de motifs textuels plutôt que sur les
  75 capacités intellectuelles de LilyPond, en conséquence de quoi :
  76
  77 @itemize @bullet
  78 @item
  79 La fiabilité de la conversion dépend de la qualité même de chaque jeu de
  80 règles ainsi que sur la complexité des modifications respectives à
  81 apporter.  Certaines conversions peuvent donc requérir une intervention
  82 manuelle ; la version de « départ » devrait toujours rester disponible
  83 pour comparaison.
  84
  85 @item
  86 Seules des conversions à un format plus récent sont possibles ; aucune
  87 règle ne permet de revenir en arrière.  La copie de travail d'un fichier
  88 LilyPond ne devrait donc être mise à jour que lorsque la version sur
  89 laquelle il repose n'est plus disponible.  Des système de gestion de
  90 version tels que Git permettent de se tenir à jour sur plusieurs
  91 versions.
  92
  93 @item
  94 LilyPond, ainsi que Scheme, gèrent plutôt bien l'emplacement ou
  95 l'absence d'espaces ; les règles utilisées par @command{convert-ly}
  96 tendent cependant à effectuer certains postulats en matière de style.
  97 Suivre le style adopté dans les différent manuels est un gage de mise à
  98 jour sans problème si l'on considère que ces manuels sont eux-même mis à
  99 jour avec @command{convert-ly}.
 100 @end itemize
 101
 102
 103 @node Exécution de convert-ly
 104 @section Exécution de @command{convert-ly}
 105 @translationof Invoking convert-ly
 106
 107 @command{convert-ly} utilise les mentions de @code{\version} -- que vous
 108 n'avez sûrement pas oublié de porter dans vos fichiers --  pour
 109 déterminer le numéro de l'ancienne version.  Mettre à jour votre fichier
 110 ne vous demande que de lancer
 111
 112 @example
 113 convert-ly -e monfichier.ly
 114 @end example
 115
 116 @noindent
 117 dans le dossier où il se trouve.  @file{monfichier.ly} sera mis à jour,
 118 et vous aurez une copie de l'original : @file{monfichier.ly~}.
 119
 120 @warning{@command{convert-ly} effectuera les conversions jusqu'aux
 121 modifications de syntaxe les plus récentes qu'il contient.  C'est la
 122 raison pour laquelle le numéro de @code{@bs{}version} modifié est la
 123 plupart du temps inférieur au propre numéro de version de
 124 @command{convert-ly}.}
 125
 126 Vous pouvez convertir tous les fichiers d'un dossier en lançant
 127
 128 @example
 129 convert-ly -e *.ly
 130 @end example
 131
 132 Vous pouvez aussi affecter un autre nom au fichier mis à jour et
 133 conserver votre fichier original en l'état :
 134
 135 @example
 136 convert-ly monfichier.ly > monnouveaufichier.ly
 137 @end example
 138
 139 Le programme affichera les numéros de version correspondant aux
 140 différentes conversions effectuées.  Si aucun numéro de version
 141 n'apparaît, considérez que le fichier ne comporte pas de syntaxe
 142 obsolète.
 143
 144 Les utilisateurs de MacOS X disposent d'une entrée spécifique dans
 145 le menu : @code{Compile > Update syntax}.
 146
 147 Si vous utilisez windows, ouvrez un interpréteur de commande en faisant
 148 @code{Démarrer > Accessoires > Interpréteur de commandes}.
 149
 150
 151 @node Options en ligne de commande pour convert-ly
 152 @section Options en ligne de commande pour @command{convert-ly}
 153 @translationof Command line options for convert-ly
 154
 155 L'utilitaire @command{convert-ly} se lance de la manière suivante :
 156
 157 @example
 158 convert-ly [@var{option}]@dots{} @var{fichier}@dots{}
 159 @end example
 160
 161 Vous pouvez utiliser les options :
 162
 163 @table @code
 164 @item -d, --diff-version-update
 165 actualise la valeur de @code{\version}, uniquement si le fichier a été
 166 effectivement modifié.  Un numéro de version instable sera « arrondi »
 167 au niveau de la version stable suivante à moins que celui-ci ne
 168 soit supérieur à la version cible.  En l'absence de cette option,
 169 ou bien si une conversion quelle qu'elle soit a modifié le
 170 fichier, la mention de version est porté à la valeur de la règle
 171 appliquée la plus récente.
 172
 173 @item -e, --edit
 174 pour éditer directement le fichier d'origine.  Le fichier originel est
 175 renommé en que @file{monfichier.ly~}.  Ce fichier de sauvegarde, selon
 176 le système d'exploitation, peut être « caché ».
 177
 178 @item -b, --backup-numbered
 179 combine à l'option @samp{-e}, pour numéroter les sauvegardes de telle
 180 sorte qu'aucune version antérieure ne soit écrasée.  Les fichiers de
 181 sauvegarde, selon le système d'exploitation, peuvent être « cachés ».
 182
 183 @item -f, --from=@var{from-patchlevel}
 184 pour définir le numéro de version à partir duquel vous voulez effectuer
 185 les conversions.  Lorsque cette option n'est pas activée,
 186 @command{convert-ly} tentera de le déterminer sur la foi de la mention
 187 de @code{\version} contenue dans le fichier.  Cette option s'utilise
 188 sous la forme : @code{--from=2.10.25}
 189
 190 @item -h, --help
 191 visualiser l'aide et quitter.
 192
 193 @item -l @var{loglevel}, --loglevel=@var{loglevel}
 194 pour régler le degré de verbosité à @var{loglevel}.  Les différentes
 195 valeurs sont @code{NONE}, @code{ERROR}, @code{WARNING}, @code{PROGRESS}
 196 (par défaut) et @code{DEBUG}.
 197
 198 @item -n, --no-version
 199 Normalement, @command{convert-ly} ajoutera une indication de
 200 @code{\version} à votre fichier s'il n'en comporte pas.  Cette option
 201 permet de passer outre.
 202
 203 @item -s, --show-rules
 204 pour afficher les conversions applicables.
 205
 206 @item -t, --to=@var{to-patchlevel}
 207 pour n'appliquer les conversions que jusqu'à une version déterminée.  Il
 208 s'agit par défaut de la dernière version disponible.  Le niveau demandé
 209 doit être supérieur à la version de départ.
 210
 211 @example
 212 convert-ly --to=2.14.1 monfichier.ly
 213 @end example
 214
 215 @end table
 216
 217 Lorsqu'il s'agit de fragments inclus dans un fichier texinfo, il
 218 vous faudra lancer
 219
 220 @example
 221 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
 222 @end example
 223
 224 Lorsque vous désirez savoir quels changements de syntaxe sont intervenus
 225 entre deux versions de LilyPond, lancez
 226
 227 @example
 228 convert-ly --from=@var{ancienne} --to=@var{récente} -s
 229 @end example
 230
 231
 232 @node Problèmes d'exécution de convert-ly
 233 @section Problèmes d'exécution de @code{convert-ly}
 234 @translationof Problems running convert-ly
 235
 236 Sous Windows, lorsque le nom du fichier original ou le chemin qui y mène
 237 comporte des espaces, l'interpréteur de commande requiert qu'il soit
 238 entouré de triples guillemets comme ci-dessous :
 239
 240 @example
 241 convert-ly """D:/Mes Partitions/Ode.ly""" > "D:/Mes Partitions/nouveau Ode.ly"
 242 @end example
 243
 244 Lorsque la commande @command{convert-ly -e *.ly} échoue parce que
 245 son expansion dépasse la taille maximale d'une ligne, vous pouvez lancer
 246 @command{convert-ly} dans une boucle.  L'exemple suivant permet, sous
 247 Unix, de convertir tous les fichiers @file{.ly} d'un même répertoire :
 248
 249 @example
 250 for f in *.ly; do convert-ly -e $f; done;
 251 @end example
 252
 253 Avec l'interpréteur de commandes de Windows, la syntaxe consacrée est :
 254
 255 @example
 256 for %x in (*.ly) do convert-ly -e """%x"""
 257 @end example
 258
 259 Toutes les évolutions du langage ne sont pas forcément prises en charge.
 260 @command{convert-ly} ne tolère qu'une seule option de sortie à la fois.
 261 La mise à jour automatique du code Scheme inclus dans les fichiers
 262 LilyPond est plus qu'hasardeuse ; attendez-vous à devoir mettre les
 263 mains dans le cambouis.
 264
 265
 266 @node Conversions manuelles
 267 @section Conversions manuelles
 268 @translationof Manual conversions
 269
 270 En théorie, un programme tel que @command{convert-ly} devrait pouvoir
 271 traiter n'importe quel changement de syntaxe.  En effet, si un programme
 272 informatique sait interpréter aussi bien une version que l'autre, un
 273 autre programme informatique doit alors être capable de traduire un
 274 fichier donné@footnote{Ceci est réalisable tant que le fichier LilyPond
 275 ne contient pas de Scheme.  Dès lors qu'un fichier contient du Scheme,
 276 des bribes de langage évolué se retrouvent danas le fichier LilyPond, ce
 277 qui conduit immanquablement au « problème de l'arrêt » bien connu en
 278 informatique.}.
 279
 280 Le projet LilyPond ne dispose cependant que de ressources limitées : les
 281 conversions ne sont pas toutes automatisées.  Voici une liste de
 282 problèmes clairement identifiés :
 283
 284
 285 @verbatim
 286 1.6->2.0:
 287  Doesn't always convert figured bass correctly, specifically things like {<
 288 >}.  Mats' comment on working around this:
 289    To be able to run convert-ly
 290    on it, I first replaced all occurrences of '{<' to some dummy like '{#'
 291    and similarly I replaced '>}' with '&}'.  After the conversion, I could
 292    then change back from '{ #' to '{ <' and from '& }' to '> }'.
 293  Doesn't convert all text markup correctly.  In the old markup syntax,
 294  it was possible to group a number of markup commands together within
 295 parentheses, e.g.
 296    -#'((bold italic) "string")
 297    This will incorrectly be converted into
 298    -\markup{{\bold italic} "string"}
 299    instead of the correct
 300    -\markup{\bold \italic "string"}
 301 2.0->2.2:
 302  Doesn't handle \partcombine
 303  Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
 304 stanzas.
 305 2.0->2.4:
 306  \magnify isn't changed to \fontsize.
 307     - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 308  remove-tag isn't changed.
 309     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 310  first-page-number isn't changed.
 311     - first-page-number no => print-first-page-number = ##f
 312  Line breaks in header strings aren't converted.
 313     - \\\\  as line break in \header strings => \markup \center-align <
 314       "First Line" "Second Line" >
 315  Crescendo and decrescendo terminators aren't converted.
 316     - \rced => \!
 317     - \rc => \!
 318 2.2->2.4:
 319  \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
 320 converted.
 321 2.4.2->2.5.9
 322  \markup{ \center-align <{ ... }> } should be converted to:
 323  \markup{ \center-align {\line { ... }} }
 324  but now, \line is missing.
 325 2.4->2.6
 326  Special LaTeX characters such as $~$ in text are not converted to UTF8.
 327 2.8
 328  \score{} must now begin with a music expression.  Anything else
 329  (particularly \header{}) must come after the music.
 330 @end verbatim