1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 88a5dbc589b0d0434f8e640467b5ab57d14dc461
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..
13 @c Translators: Jean-Charles Malahieude
14 @c Translation checkers:
16 @node Mise à jour avec convert-ly
17 @chapter Mise à jour avec @command{convert-ly}
18 @translationof Updating files with convert-ly
20 @cindex mise à jour de fichiers LilyPond
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
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
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::
43 @node LilyPond est une langue vivante
44 @section LilyPond est une langue vivante
45 @translationof Why does the syntax change?
48 @cindex mise à jour d'anciens fichiers
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.
54 En voici un exemple flagrant :
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
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}.
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.
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 :
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
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
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}.
109 @node Exécution de convert-ly
110 @section Exécution de @command{convert-ly}
111 @translationof Invoking convert-ly
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
119 convert-ly -e monfichier.ly
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~}.
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}.}
133 Vous pouvez convertir tous les fichiers d'un dossier en lançant
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}.
143 Un utilisateur de Windows lancera la commande
146 convert-ly.py -e *.ly
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 ».
154 La conversion d'un jeu de fichiers répartis dans différents
155 sous-répertoires s'obtient en lançant
158 find . -name '*.ly' -exec convert-ly -e '@{@}' \;
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.
169 Les utilisateurs de windows utiliseront l'instruction
172 forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@fichier"
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} :
180 forfiles /s /p C:\Documents\MesPartitions /M *.ly /c "cmd /c convert-ly.py -e @@fichier"
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 :
187 forfiles /s /p "C:\Documents\Mes Partitions" /M *.ly /c "cmd /c convert-ly.py -e @@fichier"
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
195 L'utilitaire @command{convert-ly} se lance de la manière suivante :
198 convert-ly [@var{option}]@dots{} @var{fichier}@dots{}
201 Vous pouvez utiliser les options :
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.
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é ».
218 Vous pouvez aussi affecter un autre nom au fichier mis à jour et
219 conserver votre fichier original en l'état :
222 convert-ly monfichier.ly > monnouveaufichier.ly
225 @noindent et, pour les utilisateurs de windows :
228 convert-ly.py monfichier.ly > monnouveaufichier.ly
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 ».
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}
244 visualiser l'aide et quitter.
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}.
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.
256 @item -s, --show-rules
257 pour afficher les conversions applicables.
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.
265 convert-ly --to=2.14.1 monfichier.ly
270 Lorsqu'il s'agit de fragments inclus dans un fichier texinfo, il
274 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
277 Lorsque vous désirez savoir quels changements de syntaxe sont intervenus
278 entre deux versions de LilyPond, lancez
281 convert-ly --from=@var{ancienne} --to=@var{récente} -s
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
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 :
294 convert-ly """D:/Mes Partitions/Ode.ly""" > "D:/Mes Partitions/nouveau Ode.ly"
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 :
303 for f in *.ly; do convert-ly -e $f; done;
306 Avec l'interpréteur de commandes de Windows, la syntaxe consacrée est :
309 for %x in (*.ly) do convert-ly -e """%x"""
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.
319 @node Conversions manuelles
320 @section Conversions manuelles
321 @translationof Manual conversions
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
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 :
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
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"}
355 Doesn't handle \partcombine
356 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
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.
372 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
375 \markup{ \center-align <{ ... }> } should be converted to:
376 \markup{ \center-align {\line { ... }} }
377 but now, \line is missing.
379 Special LaTeX characters such as $~$ in text are not converted to UTF8.
381 \score{} must now begin with a music expression. Anything else
382 (particularly \header{}) must come after the music.