1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-
4 Translation of GIT committish: 094be7d770e887169f70249804e1e96e04a44ca5
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..
14 @node Aggiornare i file con convert-ly
15 @chapter Aggiornare i file con @command{convert-ly}
16 @translationof Updating files with convert-ly
18 @cindex aggiornare un file di LilyPond
21 Via via che LilyPond migliora, la sintassi (il linguaggio di input) di
22 alcuni comandi e funzioni può cambiare. Ciò può causare errori imprevisti,
23 avvisi e perfino output errato se i file di input, creati in precedenza per
24 versioni più vecchie, vengono usati con versioni più recenti.
26 Per superare questo problema, si può usare il comando @command{convert-ly} per
27 aggiornare questi file di input più vecchi alla nuova sintassi.
30 * Perché la sintassi cambia?::
31 * Utilizzo di convert-ly::
32 * Opzioni da linea di comando per convert-ly::
33 * Problemi nell'eseguire convert-ly::
34 * Conversioni manuali::
35 * Scrivere codice che funzioni su molteplici versioni::
39 @node Perché la sintassi cambia?
40 @section Perché la sintassi cambia?
41 @translationof Why does the syntax change?
44 @cindex aggiornare i vecchi file di input
46 Le modifiche della sintassi di solito servono a rendere l'input più
47 facile sia da leggere che da scrivere e talvolta ad aggiungere a
48 LilyPond nuove funzionalità o miglioramenti di funzioni esistenti.
50 Ecco un esempio reale:
52 Tutti i nomi delle proprietà di @code{\paper} e @code{\layout} dovrebbero essere
53 scritte nella forma @code{primo-secondo-terzo}. Tuttavia, nella versione 2.11.60
54 è emerso che la proprietà @code{printallheaders} non seguiva questa convenzione.
55 Questa proprietà doveva essere lasciata così come era (confondendo i nuovi
56 utenti con un formato di input incoerente), o doveva essere cambiata
57 (disturbando i vecchi utenti con file di input già scritti)?
59 Fu deciso di cambiare il nome della proprietà in @code{print-all-headers}, e
60 tramite il comando @command{convert-ly} i vecchi utenti avevano a disposizione
61 uno strumento per aggiornare automaticamente i propri file di input.
63 Tuttavia il comando @command{convert-ly} non è sempre in grado di gestire tutti
64 i cambiamenti di sintassi. Nelle versioni di LilyPond precedenti la versione
65 2.4.2, gli accenti e i caratteri non inglesi venivano inseriti con la notazione
66 standard di LaTeX. Per esempio, per inserire la parola francese che significa
67 @q{Natale} si usava @code{No\"el}. Ma nelle versioni successive di LilyPond, il
68 carattere speciale @code{ë} deve essere inserito direttamente come carattere
69 UTF-8. Il comando @command{convert-ly} non può sostituire i caratteri speciali
70 di LaTeX con i rispettivi caratteri UTF-8, dunque è necessario aggiornare a mano
71 i vecchi file di input di LilyPond.
73 Le regole di conversione del comando @command{convert-ly} si basano sulla ricerca
74 e sostituzione di parole chiave (piuttosto che su una completa @q{comprensione}
75 del contesto di ciò che sta cambiando in un certo file di input). Ciò comporta
80 L'affidabilità della conversione dipende dalla qualità di ciascun insieme
81 di regole applicate e dalla complessità del rispettivo cambiamento. Talvolta
82 le conversioni richiedono correzioni manuali ulteriori, quindi il file originale
83 deve essere conservato per poterlo confrontare in caso di necessità.
86 Sono possibili solo conversioni ai cambi di sintassi più recenti: non ci
87 sono regole per tornare a una versione precedente di LilyPond. Dunque il file
88 di input deve essere aggiornato soltanto quando le versioni precedenti di
89 LilyPond non sono più mantenute. Di nuovo, il file di input originale deve
90 essere conservato per ogni evenienza, magari usando sistemi di controllo di
91 versione (es.: Git) per semplificare la gestione di versioni multiple dei
95 LilyPond ha delle robuste difese quando elabora spazi omessi o posizionati
96 in modo @q{originale}, ma le regole usate da @command{convert-ly} tendono spesso
97 a dare per scontato certe forme stilistiche. Seguire lo stile di input usato
98 nei manuali di LilyPond è dunque la via più sicura per aggiornamenti indolori,
99 soprattutto perché gli esempi dei manuali stessi sono tutti aggiornati col
100 comando @command{convert-ly}.
104 @node Utilizzo di convert-ly
105 @section Utilizzo di @command{convert-ly}
106 @translationof Invoking convert-ly
108 Il comando @command{convert-ly} usa il numero specificato da @code{\version} nel
109 file di input per determinare versioni precedenti. Nella maggior parte dei casi
110 per aggiornare il file di input è sufficiente eseguire:
113 convert-ly -e miofile.ly
117 nella directory che contiene il file di input. Questo comando aggiornerà
118 @file{miofile.ly} e preserverà il file originale rinominandolo
119 @file{miofile.ly~}. Verrà modificato anche il numero di @code{\version}
120 nel file di input aggiornato, insieme agli aggiornamenti di sintassi
123 Dopo averlo lanciato, il comando @command{convert-ly} elencherà i numeri di
124 versione per i quali sono state eseguite le conversioni. Se non vengono
125 elencati dei numeri di versione il file è già aggiornato e utilizza la sintassi
126 LilyPond più recente.
128 @warning{Per ogni nuova versione di LilyPond, viene creato un nuovo
129 @command{convert-ly}, ma non tutte le versioni di LilyPond necessitano
130 di cambi di sintassi per i propri file di input creati da una versione
131 precedente. Ciò significa che il comando @command{convert-ly} converterà
132 i file di input solo fino all'ultimo cambio di sintassi in suo possesso
133 e di conseguenza il numero di @code{\version} nel file di input aggiornato
134 è talvolta precedente alla versione del comando @command{convert-ly} stesso.}
136 Per convertire tutti i file di input in una directory si usa:
142 Sia gli utenti Linux che MacOS@tie{}X possono usare le rispettive applicazioni
143 del terminale, ma gli utenti MacOS@tie{}X possono anche eseguire questo comando
144 direttamente dalla voce di menu @code{Compila > Aggiorna la sintassi}.
146 Un utente Windows deve eseguire il comando:
149 convert-ly.py -e *.ly
153 inserendolo in un @code{prompt dei comandi}, che di solito si trova in
154 @code{Start > Accessori > Prompt dei comandi} o, per gli utenti della
155 versione 8, scrivendo @q{prompt dei comandi} nella finestra di ricerca.
157 Per convertire tutti i file di input che si trovano in diverse sottodirectory:
160 find . -name '*.ly' -exec convert-ly -e '@{@}' \;
163 Questo esempio cerca e converte tutti i file di input nella directory
164 corrente e in tutte le sue sottodirectory ricorsivamente. I file
165 convertiti saranno salvati nella stessa directory insieme all'originale
166 rinominato. Dovrebbe funzionare anche per gli utenti MacOS@tie{}X, anche
167 se solo tramite l'applicazione del terminale.
169 Gli utenti Windows devono usare:
172 forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@file"
175 Altrimenti, si può indicare un percorso esplicito alla cartella che
176 contiene tutte le sottocartelle con i file di input tramite l'opzione
180 forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c convert-ly.py -e @@file"
183 Tale percorso, se contiene spazi, deve essere racchiuso tra
187 forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c convert-ly.py -e @@file"
192 @node Opzioni da linea di comando per convert-ly
193 @section Opzioni da linea di comando per @command{convert-ly}
194 @translationof Command line options for convert-ly
196 Il programma viene lanciato in questo modo:
199 convert-ly [@var{opzione}]@dots{} @var{nomefile}@dots{}
203 Esistono le seguenti opzioni:
206 @item -d, --diff-version-update
207 aumenta il numero di versione in @code{\version} solo se il file è stato
208 modificato da @command{convert-ly}. In questo caso, la dichiarazione di
209 versione corrisponderà alla versione successiva all'ultimo reale cambiamento.
210 Il numero di una versione instabile sarà arrotondato al numero della versione
211 stabile successiva, a meno che ciò non vada oltre il numero di versione
212 obiettivo. Senza questa opzione, la versione rifletterà l'ultima
213 conversione @emph{tentata}.
216 Applica le conversioni direttamente nel file di input, modificando
217 l'originale. Il file originale viene rinominato @file{nomefile.ly~}. Questo
218 file di backup può essere un file nascosto in alcuni sistemi operativi.
219 Altrimenti, se si desidera specificare un nome diverso per il file
220 aggiornato senza usare il predefinito @code{~} dell'opzione @code{-e}
221 appeso al vecchio file di input, si può usare la redirezione dell'output:
224 convert-ly miofile.ly > mionuovofile.ly
227 Gli utenti Windows devono usare:
230 convert-ly.py miofile.ly > mionuovofile.ly
233 @item -b, --backup-numbered
234 Se usato insieme all'opzione @samp{-e}, aggiunge un numero al nome dei file
235 di backup, in modo da non sovrascrivere i backup precedenti. I file di
236 backup possono essere nascosti in alcuni sistemi operativi.
238 @item -f, --from=@var{from-patchlevel}
239 Imposta la versione da cui convertire. Se non viene impostata, @command{convert-ly}
240 la ricaverà dalla stringa @code{\version} presente nel file.
241 Esempio: @option{--from=2.10.25}
244 Mostra la schermata di aiuto.
246 @item -l @var{loglevel}, --loglevel=@var{loglevel}
247 Imposta la verbosità dell'output su @var{loglevel}. I valori possibili, in
248 caratteri maiuscoli, sono @code{PROGRESS} (predefinito), @code{NONE},
249 @code{WARNING}, @code{ERROR} e @code{DEBUG}.
251 @item -n, --no-version
252 Normalmente @command{convert-ly} aggiunge un indicatore @code{\version}
253 nell'output. Questa opzione lo impedisce.
255 @item -s, --show-rules
256 Mostra tutte le conversioni conosciute ed esce.
258 @item -t, --to=@var{to-patchlevel}
259 Imposta esplicitamente la versione obiettivo della conversione, altrimenti
260 viene usato il valore più recente. Deve essere maggiore della versione iniziale.
262 convert-ly --to=2.14.1 miofile.ly
267 Per aggiornare i frammenti LilyPond presenti nei file texinfo, si usa
270 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
273 Per vedere i cambiamenti della sintassi di LilyPond tra due versioni, si usa
276 convert-ly --from=@dots{} --to=@dots{} -s
280 @node Problemi nell'eseguire convert-ly
281 @section Problemi nell'eseguire @code{convert-ly}
282 @translationof Problems running convert-ly
284 Quando si esegue convert-ly in una finestra del Prompt dei comandi in Windows
285 su un file il cui nome o percorso contengano degli spazi,
286 è necessario includere tutto il nome del file di input con tre
287 (!) virgolette doppie:
290 convert-ly """D:/Mie Partiture/Ode.ly""" > "D:/Mie Partiture/new Ode.ly"
293 Se il semplice comando @command{convert-ly -e *.ly} non funziona perché la
294 linea di comando espansa diventa troppo lunga, si può inserire il comando
295 @command{convert-ly} in un loop. Questo esempio per UNIX
296 aggiornerà tutti i file @file{.ly} nella directory corrente
299 for f in *.ly; do convert-ly -e $f; done;
302 Nella finestra del Prompt dei comandi di Windows il comando corrispondente è
305 for %x in (*.ly) do convert-ly -e """%x"""
308 Non vengono gestiti tutti i cambiamenti del linguaggio. Si può specificare solo
309 un'opzione di output. È piuttosto improbabile che si aggiornino automaticamente
310 il codice scheme e le interfacce di scheme di LilyPond; tieniti pronto a
311 correggere a mano il codice scheme.
314 @node Conversioni manuali
315 @section Conversioni manuali
316 @translationof Manual conversions
318 In teoria, un programma come @command{convert-ly} potrebbe gestire qualsiasi
319 cambiamento di sintassi. Dopo tutto, un programma per computer interpreta
320 la vecchia versione e la nuova versione, quindi un altro programma
321 può tradurre un file in un altro@footnote{O almeno questo è possibile
322 in qualsiasi file LilyPond che non contenga codice scheme. Se c'è del
323 codice scheme nel file, allora il file LilyPond contiene un linguaggio
324 Turing-completo, ed è possibile imbattersi in problemi col famigerato
325 @qq{Problema dell'arresto} in informatica.}.
327 Tuttavia il progetto LilyPond ha risorse limitate: non tutte le
328 conversioni sono compiute automaticamente. Di seguito è riportato l'elenco
334 Doesn't always convert figured bass correctly, specifically things like {<
335 >}. Mats' comment on working around this:
336 To be able to run convert-ly
337 on it, I first replaced all occurrences of '{<' to some dummy like '{#'
338 and similarly I replaced '>}' with '&}'. After the conversion, I could
339 then change back from '{ #' to '{ <' and from '& }' to '> }'.
340 Doesn't convert all text markup correctly. In the old markup syntax,
341 it was possible to group a number of markup commands together within
343 -#'((bold italic) "string")
344 This will incorrectly be converted into
345 -\markup{{\bold italic} "string"}
346 instead of the correct
347 -\markup{\bold \italic "string"}
349 Doesn't handle \partcombine
350 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
353 \magnify isn't changed to \fontsize.
354 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
355 remove-tag isn't changed.
356 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
357 first-page-number isn't changed.
358 - first-page-number no => print-first-page-number = ##f
359 Line breaks in header strings aren't converted.
360 - \\\\ as line break in \header strings => \markup \center-align <
361 "First Line" "Second Line" >
362 Crescendo and decrescendo terminators aren't converted.
366 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
369 \markup{ \center-align <{ ... }> } should be converted to:
370 \markup{ \center-align {\line { ... }} }
371 but now, \line is missing.
373 Special LaTeX characters such as $~$ in text are not converted to UTF8.
375 \score{} must now begin with a music expression. Anything else
376 (particularly \header{}) must come after the music.
379 @node Scrivere codice che funzioni su molteplici versioni
380 @section Scrivere codice che funzioni su molteplici versioni
381 @translationof Writing code to support multiple versions
383 In alcuni casi, in particolare quando si scrive codice destinato a funzionare
384 come @emph{libreria}, è opportuno far sì che supporti molteplici versioni di
385 LilyPond nonostante le modifiche della sintassi. Per farlo si possono
386 avvolgere porzioni alternative di codice in espressioni condizionali che
387 dipendono dalla versione di LilyPond attualmente eseguita. La funzione
388 Scheme @code{ly:version?} prevede un operatore di confronto @var{op}
389 e una versione di riferimento @var{ver} passata come elenco di interi di
390 massimo tre elementi. Gli elementi mancanti vengono ignorati, quindi
391 @code{'(2 20)} equivale a @emph{qualsiasi} versione della serie di versioni
392 2.20. Sono possibili costrutti come il seguente:
396 ((ly:version? > '(2 20))
397 (ly:message "Questo è il codice da eseguire per LilyPond 2.20 o successivi"))
398 ((ly:version? = '(2 19 57))
399 (ly:message "Questo verrà eseguito soltanto con LilyPond 2.19.57"))
400 (else (ly:message "Questo verrà eseguito con qualsiasi altra versione")))
403 Solitamente questa funzione viene integrata nelle funzioni di una libreria,
404 per consentire l'uso di sintassi alternativa, ma è anche possibile usare il
405 confronto direttamente nell'input musicale, come nell'esempio seguente:
410 #(if (ly:version? = '(2 21))
411 #{ \override NoteHead.color = #red #}
412 #{ \override NoteHead.color = #blue #})
417 @strong{Nota:} Questa funzione è stata introdotta in LilyPond 2.19.57, dunque
418 non è possibile fare confronti usando versioni precedenti.