Documentation/fr/usage/updating.itely

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