1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 3e251ec33b325f3af4adb31df9752422eb2b9f4c
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::
40 * Écriture de code supportant différentes versions::
44 @node LilyPond est une langue vivante
45 @section LilyPond est une langue vivante
46 @translationof Why does the syntax change?
49 @cindex mise à jour d'anciens fichiers
51 La syntaxe de LilyPond change de temps en temps, que ce soit pour rendre
52 les fichiers plus faciles à lire et à écrire, ou pour intégrer de
53 nouvelles fonctionnalités.
55 En voici un exemple flagrant :
57 Tous les noms des propriétés de @code{\paper} et @code{\layout} sont
58 libellés sous la forme @code{@w{premier-deuxième-troisième}}. Nous
59 avons constaté, une fois la version 2.11.60 mise à disposition, que la
60 propriété @code{printallheaders} ne respectait pas cette convention.
61 Aurions-nous dû la laisser telle que, au risque de dérouter les nouveaux
62 utilisateurs par cette exception au formatage, ou bien la modifier -- ce
63 qui allait obliger ceux qui l'avaient déjà utilisée à se mettre en
66 Pour ce cas d'espèce, nous avons décidé de changer le nom de cette
67 propriété en @code{print-all-headers} et de permettre à ceux qui
68 avaient utilisé l'ancienne syntaxe de modifier automatiquement leurs
69 fichiers à l'aide de notre utilitaire @command{convert-ly}.
71 Malheureusement, @command{convert-ly} ne peut pas réaliser toutes les
72 modifications. Par exemple, dans les versions de LilyPond antérieures à
73 la 2.4.2, les accents et les lettres non anglaises étaient entrées en
74 utilisant @LaTeX{} -- par exemple, @code{No\"el}. À partir de la
75 version 2.6, le caractère @code{ë} doit être entré directement dans
76 le fichier LilyPond comme caractère UTF-8. @command{convert-ly} ne
77 peut pas changer tous les caractères @LaTeX{} en caractères UTF-8 ; vous
78 devez mettre à jour vos vieux fichiers LilyPond manuellement.
80 Les règles de conversion de @command{convert-ly} reposent sur la
81 recherche et le remplacement de motifs textuels plutôt que sur les
82 capacités intellectuelles de LilyPond, en conséquence de quoi :
86 La fiabilité de la conversion dépend de la qualité même de chaque jeu de
87 règles ainsi que sur la complexité des modifications respectives à
88 apporter. Certaines conversions peuvent donc requérir une intervention
89 manuelle ; la version de « départ » devrait toujours rester disponible
93 Seules des conversions à une syntaxe plus récente sont possibles ;
94 aucune règle ne permet de revenir en arrière. La copie de travail d'un
95 fichier LilyPond ne devrait donc être mise à jour que lorsque la version
96 sur laquelle il repose n'est plus maintenue. Des système de gestion de
97 version tels que Git permettent de se tenir à jour sur plusieurs
101 LilyPond, ainsi que Scheme, gèrent plutôt bien l'emplacement ou
102 l'absence d'espaces ; les règles utilisées par @command{convert-ly}
103 tendent cependant à effectuer certains postulats en matière de style.
104 Suivre le style adopté dans les différent manuels est un gage de mise à
105 jour sans problème si l'on considère que ces manuels sont eux-même mis à
106 jour avec @command{convert-ly}.
110 @node Exécution de convert-ly
111 @section Exécution de @command{convert-ly}
112 @translationof Invoking convert-ly
114 La commande @command{convert-ly} utilise les mentions de @code{\version}
115 -- que vous n'avez sûrement pas oublié de porter dans vos fichiers -- pour
116 déterminer le numéro de l'ancienne version. Mettre à jour votre fichier
117 ne vous demande que de lancer
120 convert-ly -e monfichier.ly
124 dans le dossier où il se trouve. @file{monfichier.ly} sera mis à jour,
125 avec un nouveau buméro en argument à @code{\version}, et vous aurez une
126 copie de l'original : @file{monfichier.ly~}.
128 @warning{@command{convert-ly} effectuera les conversions jusqu'aux
129 modifications de syntaxe les plus récentes qu'il contient. C'est la
130 raison pour laquelle le numéro de @code{@bs{}version} modifié est la
131 plupart du temps inférieur au propre numéro de version de
132 @command{convert-ly}.}
134 Vous pouvez convertir tous les fichiers d'un dossier en lançant
140 Les utilisatuers de Gnu/Linux ou de MacOS X peuvent lancer cette
141 commande dans un terminal. Les utilisateurs de MacOS X disposent d'une
142 entrée spécifique dans le menu : @code{Compile > Update syntax}.
144 Un utilisateur de Windows lancera la commande
147 convert-ly.py -e *.ly
151 dans l'@code{interpréteur de commandes}, qui se trouve normalement sous
152 @code{Démarrer > Accessoires > Interpréteur de commandes} ou, pour la
153 version 8, en faisant une recherche sur « interpréteur de commande ».
155 La conversion d'un jeu de fichiers répartis dans différents
156 sous-répertoires s'obtient en lançant
159 find . -name '*.ly' -exec convert-ly -e '@{@}' \;
162 Ceci aura pour effet de rechercher et convertir tous les fichiers
163 sources dans le répertoire en cours et dans tous ses sous-répertoires.
164 les fichiers convertis se trouveront à leur emplacement d'orignie, tout
165 comme les fichiers originels après renommage. Cette commande, bien
166 qu'effective uniquement dans un terminal, devrait etre fonctnionnelle
167 aussi pour les utilisateurs de MacOS X.
170 Les utilisateurs de windows utiliseront l'instruction
173 forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@fichier"
176 Par ailleurs, il est possible de spécifier de manière explicite le chemin
177 d'accès au dossier comportant des sous-répertoires où se trouvent les
178 fichiers sources, à l'aide de l'option @code{/p} :
181 forfiles /s /p C:\Documents\MesPartitions /M *.ly /c "cmd /c convert-ly.py -e @@fichier"
184 Dans le cas où ce chemin d'accès comporte des espaces, l'intégralité de
185 ce chemin devra être borné par des guillemets informatiques :
188 forfiles /s /p "C:\Documents\Mes Partitions" /M *.ly /c "cmd /c convert-ly.py -e @@fichier"
192 @node Options en ligne de commande pour convert-ly
193 @section Options en ligne de commande pour @command{convert-ly}
194 @translationof Command line options for convert-ly
196 L'utilitaire @command{convert-ly} se lance de la manière suivante :
199 convert-ly [@var{option}]@dots{} @var{fichier}@dots{}
202 Vous pouvez utiliser les options :
205 @item -d, --diff-version-update
206 actualise la valeur de @code{\version}, uniquement si le fichier a été
207 effectivement modifié. Un numéro de version instable sera « arrondi »
208 au niveau de la version stable suivante à moins que celui-ci ne
209 soit supérieur à la version cible. En l'absence de cette option,
210 ou bien si une conversion quelle qu'elle soit a modifié le
211 fichier, la mention de version est porté à la valeur de la règle
212 appliquée la plus récente.
215 pour éditer directement le fichier d'origine. Le fichier originel est
216 renommé en que @file{monfichier.ly~}. Ce fichier de sauvegarde, selon
217 le système d'exploitation, peut être « caché ».
219 Vous pouvez aussi affecter un autre nom au fichier mis à jour et
220 conserver votre fichier original en l'état :
223 convert-ly monfichier.ly > monnouveaufichier.ly
226 @noindent et, pour les utilisateurs de windows :
229 convert-ly.py monfichier.ly > monnouveaufichier.ly
232 @item -b, --backup-numbered
233 combine à l'option @samp{-e}, pour numéroter les sauvegardes de telle
234 sorte qu'aucune version antérieure ne soit écrasée. Les fichiers de
235 sauvegarde, selon le système d'exploitation, peuvent être « cachés ».
237 @item -f, --from=@var{from-patchlevel}
238 pour définir le numéro de version à partir duquel vous voulez effectuer
239 les conversions. Lorsque cette option n'est pas activée,
240 @command{convert-ly} tentera de le déterminer sur la foi de la mention
241 de @code{\version} contenue dans le fichier. Cette option s'utilise
242 sous la forme : @code{--from=2.10.25}
245 visualiser l'aide et quitter.
247 @item -l @var{loglevel}, --loglevel=@var{loglevel}
248 pour régler le degré de verbosité à @var{loglevel}. Les différentes
249 valeurs sont @code{NONE}, @code{ERROR}, @code{WARNING}, @code{PROGRESS}
250 (par défaut) et @code{DEBUG}.
252 @item -n, --no-version
253 Normalement, @command{convert-ly} ajoutera une indication de
254 @code{\version} à votre fichier s'il n'en comporte pas. Cette option
255 permet de passer outre.
257 @item -s, --show-rules
258 pour afficher les conversions applicables.
260 @item -t, --to=@var{to-patchlevel}
261 pour n'appliquer les conversions que jusqu'à une version déterminée. Il
262 s'agit par défaut de la dernière version disponible. Le niveau demandé
263 doit être supérieur à la version de départ.
266 convert-ly --to=2.14.1 monfichier.ly
271 Lorsqu'il s'agit de fragments inclus dans un fichier texinfo, il
275 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
278 Lorsque vous désirez savoir quels changements de syntaxe sont intervenus
279 entre deux versions de LilyPond, lancez
282 convert-ly --from=@var{ancienne} --to=@var{récente} -s
286 @node Problèmes d'exécution de convert-ly
287 @section Problèmes d'exécution de @code{convert-ly}
288 @translationof Problems running convert-ly
290 Sous Windows, lorsque le nom du fichier original ou le chemin qui y mène
291 comporte des espaces, l'interpréteur de commande requiert qu'il soit
292 entouré de triples guillemets comme ci-dessous :
295 convert-ly """D:/Mes Partitions/Ode.ly""" > "D:/Mes Partitions/nouveau Ode.ly"
298 Lorsque la commande @command{convert-ly -e *.ly} échoue parce que
299 son expansion dépasse la taille maximale d'une ligne, vous pouvez lancer
300 @command{convert-ly} dans une boucle. L'exemple suivant permet, sous
301 Unix, de convertir tous les fichiers @file{.ly} d'un même répertoire :
304 for f in *.ly; do convert-ly -e $f; done;
307 Avec l'interpréteur de commandes de Windows, la syntaxe consacrée est :
310 for %x in (*.ly) do convert-ly -e """%x"""
313 Toutes les évolutions du langage ne sont pas forcément prises en charge.
314 @command{convert-ly} ne tolère qu'une seule option de sortie à la fois.
315 La mise à jour automatique du code Scheme inclus dans les fichiers
316 LilyPond est plus qu'hasardeuse ; attendez-vous à devoir mettre les
317 mains dans le cambouis.
320 @node Conversions manuelles
321 @section Conversions manuelles
322 @translationof Manual conversions
324 En théorie, un programme tel que @command{convert-ly} devrait pouvoir
325 traiter n'importe quel changement de syntaxe. En effet, si un programme
326 informatique sait interpréter aussi bien une version que l'autre, un
327 autre programme informatique doit alors être capable de traduire un
328 fichier donné@footnote{Ceci est réalisable tant que le fichier LilyPond
329 ne contient pas de Scheme. Dès lors qu'un fichier contient du Scheme,
330 des bribes de langage évolué se retrouvent danas le fichier LilyPond, ce
331 qui conduit immanquablement au « problème de l'arrêt » bien connu en
334 Le projet LilyPond ne dispose cependant que de ressources limitées : les
335 conversions ne sont pas toutes automatisées. Voici une liste de
336 problèmes clairement identifiés :
341 Doesn't always convert figured bass correctly, specifically things like {<
342 >}. Mats' comment on working around this:
343 To be able to run convert-ly
344 on it, I first replaced all occurrences of '{<' to some dummy like '{#'
345 and similarly I replaced '>}' with '&}'. After the conversion, I could
346 then change back from '{ #' to '{ <' and from '& }' to '> }'.
347 Doesn't convert all text markup correctly. In the old markup syntax,
348 it was possible to group a number of markup commands together within
350 -#'((bold italic) "string")
351 This will incorrectly be converted into
352 -\markup{{\bold italic} "string"}
353 instead of the correct
354 -\markup{\bold \italic "string"}
356 Doesn't handle \partcombine
357 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
360 \magnify isn't changed to \fontsize.
361 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
362 remove-tag isn't changed.
363 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
364 first-page-number isn't changed.
365 - first-page-number no => print-first-page-number = ##f
366 Line breaks in header strings aren't converted.
367 - \\\\ as line break in \header strings => \markup \center-align <
368 "First Line" "Second Line" >
369 Crescendo and decrescendo terminators aren't converted.
373 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
376 \markup{ \center-align <{ ... }> } should be converted to:
377 \markup{ \center-align {\line { ... }} }
378 but now, \line is missing.
380 Special LaTeX characters such as $~$ in text are not converted to UTF8.
382 \score{} must now begin with a music expression. Anything else
383 (particularly \header{}) must come after the music.
387 @node Écriture de code supportant différentes versions
388 @section Écriture de code supportant différentes versions
389 @translationof Writing code to support multiple versions
391 Dans certains cas, et tout particulièrement lorsque l'on se contitue une
392 @emph{bibliothèque} de code, il est souhaitable de pouvoir supporter
393 différentes versions de LilyPond indépendamment des changements de
394 syntaxe. Il est possible d'y parvenir à l'aide de portions de code
395 englobées dans une expression conditionnelle et dont l'exécution se fera
396 relativement à la version utilisée de LilyPond. La fonction
397 @code{ly:version?} requiert un opérateur de comparaison @var{op} et une
398 version de référence @var{ver} sous forme de liste d'entiers jusqu'à
399 trois éléments. Les éléments absents sont ignorés, de telle sorte que
400 @code{'(2 20)} est équivalent à @emph{toute} version de la série 2.20.
401 On peut donc en arriver à des constructions telles que :
405 ((ly:version? > '(2 20))
406 (ly:message "Ce code sera exécuté avec un LilyPond postérieur à 2.20"))
407 ((ly:version? = '(2 19 57))
408 (ly:message "Ce code ne sera exécuté qu'avec LilyPond 2.19.57"))
409 (else (ly:message "Ceci sera exécuté pour toutes les autres versions")))
412 Ceci viendra naturellement s'intégrer aux fonctions de bibliothèques
413 pour permettre l'utilisation de syntaxes différentes. Une comparaison
414 peut aussi apparaître au sein même de la musique comme ici :
419 #(if (ly:version? = '(2 21))
420 #{ \override NoteHead.color = #red #}
421 #{ \override NoteHead.color = #blue #})
426 @strong{Note :} Cette fonction ayant été introduite avec LilyPond
427 2.19.57, il n'est pas possible d'établir des comparaisons avec des
428 versions qui lui sont antérieures.