@c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-
@ignore
- Translation of GIT committish: 26a079ca2393d053315ef8dbef626c897dc9645a
+ Translation of GIT committish: 094be7d770e887169f70249804e1e96e04a44ca5
When revising a translation, copy the HEAD committish of the
version that you are working on. For details, see the Contributors'
@chapter Aggiornare i file con @command{convert-ly}
@translationof Updating files with convert-ly
-@cindex Aggiornare un file di LilyPond
+@cindex aggiornare un file di LilyPond
@cindex convert-ly
-La sintassi di input di LilyPond viene regolarmente modificata per semplificarla
-o per migliorarla in vari modi. L'effetto collaterale è che l'interprete di LilyPond
-spesso non è più compatibile con i vecchi file di input. Per ovviare a questo
-problema, si può usare il programma @command{convert-ly}, che permette di gestire
-gran parte dei cambiamenti di sintassi tra le versioni di LilyPond.
+Via via che LilyPond migliora, la sintassi (il linguaggio di input) di
+alcuni comandi e funzioni può cambiare. Ciò può causare errori imprevisti,
+avvisi e perfino output errato se i file di input, creati in precedenza per
+versioni più vecchie, vengono usati con versioni più recenti.
+
+Per superare questo problema, si può usare il comando @command{convert-ly} per
+aggiornare questi file di input più vecchi alla nuova sintassi.
@menu
* Perché la sintassi cambia?::
* Opzioni da linea di comando per convert-ly::
* Problemi nell'eseguire convert-ly::
* Conversioni manuali::
+* Scrivere codice che funzioni su molteplici versioni::
@end menu
@cindex convert-ly
@cindex aggiornare i vecchi file di input
-La sintassi di input di LilyPond talvolta cambia. Via via che LilyPond
-migliora, la sintassi (il linguaggio dell'input) viene modificata di
-conseguenza. Queste modifiche vengono fatte a volte per far sì che l'input
-sia più facile da leggere e da scrivere e a volte per aggiungere a LilyPond
-nuove funzionalità.
-
-Ad esempio, tutti i nomi delle proprietà di @code{\paper} e @code{\layout}
-dovrebbero essere scritte nella forma @code{primo-secondo-terzo}.
-Tuttavia, nella versione 2.11.60 ci siamo accorti che la proprietà
-@code{printallheaders} non seguiva questa convenzione.
-Dovevamo lasciarla così come era (confondendo i nuovi utenti che devono avere
-a che fare con un formato di input incoerente), o cambiarla (disturbando i
-vecchi utenti che avevano già delle partiture)? In questo caso decidemmo di
-cambiare il nome in @code{print-all-headers}. Fortunatamente, questa modifica
-può essere automatizzata con @command{convert-ly}.
-
-Purtroppo @code{convert-ly} non è in grado di gestire tutti i cambiamenti
-dell'input. Ad esempio, in LilyPond 2.4 e precedenti, gli accenti e le lettere
-non inglesi venivano inserite con LaTeX -- per mostrare la parola francese per
-Natale si usava @code{No\"el}. Ma in LilyPond
-@c keep "-matching straight in fancy editors
-2.6 e superiori, il carattere speciale @code{ë} deve essere inserito direttamente
-nel file LilyPond come carattere UTF-8. @code{convert-ly} non può sostituire
-tutti i caratteri speciali di LaTeX con i rispettivi caratteri UTF-8; è necessario
-aggiornare a mano i vecchi file di input di LilyPond.
+Le modifiche della sintassi di solito servono a rendere l'input più
+facile sia da leggere che da scrivere e talvolta ad aggiungere a
+LilyPond nuove funzionalità o miglioramenti di funzioni esistenti.
+
+Ecco un esempio reale:
+
+Tutti i nomi delle proprietà di @code{\paper} e @code{\layout} dovrebbero essere
+scritte nella forma @code{primo-secondo-terzo}. Tuttavia, nella versione 2.11.60
+è emerso che la proprietà @code{printallheaders} non seguiva questa convenzione.
+Questa proprietà doveva essere lasciata così come era (confondendo i nuovi
+utenti con un formato di input incoerente), o doveva essere cambiata
+(disturbando i vecchi utenti con file di input già scritti)?
+
+Fu deciso di cambiare il nome della proprietà in @code{print-all-headers}, e
+tramite il comando @command{convert-ly} i vecchi utenti avevano a disposizione
+uno strumento per aggiornare automaticamente i propri file di input.
+
+Tuttavia il comando @command{convert-ly} non è sempre in grado di gestire tutti
+i cambiamenti di sintassi. Nelle versioni di LilyPond precedenti la versione
+2.4.2, gli accenti e i caratteri non inglesi venivano inseriti con la notazione
+standard di LaTeX. Per esempio, per inserire la parola francese che significa
+@q{Natale} si usava @code{No\"el}. Ma nelle versioni successive di LilyPond, il
+carattere speciale @code{ë} deve essere inserito direttamente come carattere
+UTF-8. Il comando @command{convert-ly} non può sostituire i caratteri speciali
+di LaTeX con i rispettivi caratteri UTF-8, dunque è necessario aggiornare a mano
+i vecchi file di input di LilyPond.
+
+Le regole di conversione del comando @command{convert-ly} si basano sulla ricerca
+e sostituzione di parole chiave (piuttosto che su una completa @q{comprensione}
+del contesto di ciò che sta cambiando in un certo file di input). Ciò comporta
+varie conseguenze:
+
+@itemize @bullet
+@item
+L'affidabilità della conversione dipende dalla qualità di ciascun insieme
+di regole applicate e dalla complessità del rispettivo cambiamento. Talvolta
+le conversioni richiedono correzioni manuali ulteriori, quindi il file originale
+deve essere conservato per poterlo confrontare in caso di necessità.
+
+@item
+Sono possibili solo conversioni ai cambi di sintassi più recenti: non ci
+sono regole per tornare a una versione precedente di LilyPond. Dunque il file
+di input deve essere aggiornato soltanto quando le versioni precedenti di
+LilyPond non sono più mantenute. Di nuovo, il file di input originale deve
+essere conservato per ogni evenienza, magari usando sistemi di controllo di
+versione (es.: Git) per semplificare la gestione di versioni multiple dei
+file di input.
+
+@item
+LilyPond ha delle robuste difese quando elabora spazi omessi o posizionati
+in modo @q{originale}, ma le regole usate da @command{convert-ly} tendono spesso
+a dare per scontato certe forme stilistiche. Seguire lo stile di input usato
+nei manuali di LilyPond è dunque la via più sicura per aggiornamenti indolori,
+soprattutto perché gli esempi dei manuali stessi sono tutti aggiornati col
+comando @command{convert-ly}.
+@end itemize
@node Utilizzo di convert-ly
@section Utilizzo di @command{convert-ly}
@translationof Invoking convert-ly
-@command{convert-ly} usa la dichiarazione @code{\version} nel file di input
-per determinare il vecchio numero di versione. Nella maggior parte dei casi
-per aggiornare il file di input è sufficiente eseguire
+Il comando @command{convert-ly} usa il numero specificato da @code{\version} nel
+file di input per determinare versioni precedenti. Nella maggior parte dei casi
+per aggiornare il file di input è sufficiente eseguire:
@example
convert-ly -e miofile.ly
@end example
@noindent
-nella directory che contiene il file. Questo comando aggiornerà
-@file{miofile.ly} e preserverà il file originale in
-@file{miofile.ly~}.
+nella directory che contiene il file di input. Questo comando aggiornerà
+@file{miofile.ly} e preserverà il file originale rinominandolo
+@file{miofile.ly~}. Verrà modificato anche il numero di @code{\version}
+nel file di input aggiornato, insieme agli aggiornamenti di sintassi
+richiesti.
+
+Dopo averlo lanciato, il comando @command{convert-ly} elencherà i numeri di
+versione per i quali sono state eseguite le conversioni. Se non vengono
+elencati dei numeri di versione il file è già aggiornato e utilizza la sintassi
+LilyPond più recente.
+
+@warning{Per ogni nuova versione di LilyPond, viene creato un nuovo
+@command{convert-ly}, ma non tutte le versioni di LilyPond necessitano
+di cambi di sintassi per i propri file di input creati da una versione
+precedente. Ciò significa che il comando @command{convert-ly} converterà
+i file di input solo fino all'ultimo cambio di sintassi in suo possesso
+e di conseguenza il numero di @code{\version} nel file di input aggiornato
+è talvolta precedente alla versione del comando @command{convert-ly} stesso.}
+
+Per convertire tutti i file di input in una directory si usa:
-@warning{@command{convert-ly} converte sempre fino all'ultimo cambiamento di
-sintassi gestito. Questo significa che il numero di @code{\version}
-che appare nel file convertito è di solito inferiore al numero di versione di
-@command{convert-ly}.}
+@example
+convert-ly -e *.ly
+@end example
-Per convertire in una volta sola tutti i file di input in una directory si usa
+Sia gli utenti Linux che MacOS@tie{}X possono usare le rispettive applicazioni
+del terminale, ma gli utenti MacOS@tie{}X possono anche eseguire questo comando
+direttamente dalla voce di menu @code{Compila > Aggiorna la sintassi}.
+
+Un utente Windows deve eseguire il comando:
@example
-convert-ly -e *.ly
+convert-ly.py -e *.ly
@end example
-Altrimenti, se si desidera specificare un nome diverso per il file
-aggiornato, senza modificare il file originale e il suo nome, si usa
+@noindent
+inserendolo in un @code{prompt dei comandi}, che di solito si trova in
+@code{Start > Accessori > Prompt dei comandi} o, per gli utenti della
+versione 8, scrivendo @q{prompt dei comandi} nella finestra di ricerca.
+
+Per convertire tutti i file di input che si trovano in diverse sottodirectory:
@example
-convert-ly miofile.ly > mionuovofile.ly
+find . -name '*.ly' -exec convert-ly -e '@{@}' \;
@end example
-Il programma elencherà i numeri di versione per i quali sono state eseguite
-le conversioni. Se non vengono elencati dei numeri di versione il file è
-già aggiornato.
+Questo esempio cerca e converte tutti i file di input nella directory
+corrente e in tutte le sue sottodirectory ricorsivamente. I file
+convertiti saranno salvati nella stessa directory insieme all'originale
+rinominato. Dovrebbe funzionare anche per gli utenti MacOS@tie{}X, anche
+se solo tramite l'applicazione del terminale.
-Gli utenti MacOS@tie{}X possono eseguire questi comandi dalla voce di menu
-@code{Compila > Aggiorna la sintassi}.
+Gli utenti Windows devono usare:
+
+@example
+forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
+
+Altrimenti, si può indicare un percorso esplicito alla cartella che
+contiene tutte le sottocartelle con i file di input tramite l'opzione
+@code{/p}:
+
+@example
+forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
+
+Tale percorso, se contiene spazi, deve essere racchiuso tra
+virgolette doppie:
+
+@example
+forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
-Gli utenti Windows devono inserire questi comandi nella finestra del Prompt
-dei comandi, che di solito si trova in
-@code{Start > Accessori > Prompt dei comandi}.
@node Opzioni da linea di comando per convert-ly
Esistono le seguenti opzioni:
@table @code
-@item -e,--edit
+@item -d, --diff-version-update
+aumenta il numero di versione in @code{\version} solo se il file è stato
+modificato da @command{convert-ly}. In questo caso, la dichiarazione di
+versione corrisponderà alla versione successiva all'ultimo reale cambiamento.
+Il numero di una versione instabile sarà arrotondato al numero della versione
+stabile successiva, a meno che ciò non vada oltre il numero di versione
+obiettivo. Senza questa opzione, la versione rifletterà l'ultima
+conversione @emph{tentata}.
+
+@item -e, --edit
Applica le conversioni direttamente nel file di input, modificando
-l'originale.
+l'originale. Il file originale viene rinominato @file{nomefile.ly~}. Questo
+file di backup può essere un file nascosto in alcuni sistemi operativi.
+Altrimenti, se si desidera specificare un nome diverso per il file
+aggiornato senza usare il predefinito @code{~} dell'opzione @code{-e}
+appeso al vecchio file di input, si può usare la redirezione dell'output:
-@item -f,--from=@var{from-patchlevel}
+@example
+convert-ly miofile.ly > mionuovofile.ly
+@end example
+
+Gli utenti Windows devono usare:
+
+@example
+convert-ly.py miofile.ly > mionuovofile.ly
+@end example
+
+@item -b, --backup-numbered
+Se usato insieme all'opzione @samp{-e}, aggiunge un numero al nome dei file
+di backup, in modo da non sovrascrivere i backup precedenti. I file di
+backup possono essere nascosti in alcuni sistemi operativi.
+
+@item -f, --from=@var{from-patchlevel}
Imposta la versione da cui convertire. Se non viene impostata, @command{convert-ly}
la ricaverà dalla stringa @code{\version} presente nel file.
Esempio: @option{--from=2.10.25}
-@item -n,--no-version
+@item -h, --help
+Mostra la schermata di aiuto.
+
+@item -l @var{loglevel}, --loglevel=@var{loglevel}
+Imposta la verbosità dell'output su @var{loglevel}. I valori possibili, in
+caratteri maiuscoli, sono @code{PROGRESS} (predefinito), @code{NONE},
+@code{WARNING}, @code{ERROR} e @code{DEBUG}.
+
+@item -n, --no-version
Normalmente @command{convert-ly} aggiunge un indicatore @code{\version}
nell'output. Questa opzione lo impedisce.
@item -s, --show-rules
Mostra tutte le conversioni conosciute ed esce.
-@item --to=@var{to-patchlevel}
-Imposta la versione obiettivo della conversione. L'impostazione predefinita
-è l'ultima versione disponibile. Esempio: @option{--to=2.12.2}
-
-@item -h, --help
-Mostra la schermata di aiuto.
+@item -t, --to=@var{to-patchlevel}
+Imposta esplicitamente la versione obiettivo della conversione, altrimenti
+viene usato il valore più recente. Deve essere maggiore della versione iniziale.
+@example
+convert-ly --to=2.14.1 miofile.ly
+@end example
-@item -l @var{loglevel}, --loglevel=@var{loglevel}
-Imposta la verbosità dell'output su @var{loglevel}. I valori possibili sono @code{NONE},
-@code{ERROR}, @code{WARNING}, @code{PROGRESS} (predefinito) e @code{DEBUG}.
@end table
Per aggiornare i frammenti LilyPond presenti nei file texinfo, si usa
@example
-convert-ly --from=... --to=... --no-version *.itely
+convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
@end example
Per vedere i cambiamenti della sintassi di LilyPond tra due versioni, si usa
@example
-convert-ly --from=... --to=... -s
+convert-ly --from=@dots{} --to=@dots{} -s
@end example
(particularly \header{}) must come after the music.
@end verbatim
+@node Scrivere codice che funzioni su molteplici versioni
+@section Scrivere codice che funzioni su molteplici versioni
+@translationof Writing code to support multiple versions
+
+In alcuni casi, in particolare quando si scrive codice destinato a funzionare
+come @emph{libreria}, è opportuno far sì che supporti molteplici versioni di
+LilyPond nonostante le modifiche della sintassi. Per farlo si possono
+avvolgere porzioni alternative di codice in espressioni condizionali che
+dipendono dalla versione di LilyPond attualmente eseguita. La funzione
+Scheme @code{ly:version?} prevede un operatore di confronto @var{op}
+e una versione di riferimento @var{ver} passata come elenco di interi di
+massimo tre elementi. Gli elementi mancanti vengono ignorati, quindi
+@code{'(2 20)} equivale a @emph{qualsiasi} versione della serie di versioni
+2.20. Sono possibili costrutti come il seguente:
+
+@verbatim
+#(cond
+ ((ly:version? > '(2 20))
+ (ly:message "Questo è il codice da eseguire per LilyPond 2.20 o successivi"))
+ ((ly:version? = '(2 19 57))
+ (ly:message "Questo verrà eseguito soltanto con LilyPond 2.19.57"))
+ (else (ly:message "Questo verrà eseguito con qualsiasi altra versione")))
+@end verbatim
+
+Solitamente questa funzione viene integrata nelle funzioni di una libreria,
+per consentire l'uso di sintassi alternativa, ma è anche possibile usare il
+confronto direttamente nell'input musicale, come nell'esempio seguente:
+
+@verbatim
+{
+ c' d' e' f'
+ #(if (ly:version? = '(2 21))
+ #{ \override NoteHead.color = #red #}
+ #{ \override NoteHead.color = #blue #})
+ g' a' b' c''
+}
+@end verbatim
+@strong{Nota:} Questa funzione è stata introdotta in LilyPond 2.19.57, dunque
+non è possibile fare confronti usando versioni precedenti.
projects / lilypond.git / blobdiff