@c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*- @ignore Translation of GIT committish: bd8e8f0193000854fef9d3de3cc0a9f667ea8fb1 When revising a translation, copy the HEAD committish of the version that you are working on. For details, see the Contributors' Guide, node Updating translation committishes.. @end ignore @c \version "2.16.0" @node Aggiornare i file con convert-ly @chapter Aggiornare i file con @command{convert-ly} @translationof Updating files with convert-ly @cindex aggiornare un file di LilyPond @cindex convert-ly 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?:: * Utilizzo di convert-ly:: * Opzioni da linea di comando per convert-ly:: * Problemi nell'eseguire convert-ly:: * Conversioni manuali:: @end menu @node Perché la sintassi cambia? @section Perché la sintassi cambia? @translationof Why does the syntax change? @cindex convert-ly @cindex aggiornare i vecchi file di input 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 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 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: @example convert-ly -e *.ly @end example 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.py -e *.ly @end example @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 find . -name '*.ly' -exec convert-ly -e '@{@}' \; @end example 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 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 @node Opzioni da linea di comando per convert-ly @section Opzioni da linea di comando per @command{convert-ly} @translationof Command line options for convert-ly Il programma viene lanciato in questo modo: @example convert-ly [@var{opzione}]@dots{} @var{nomefile}@dots{} @end example Esistono le seguenti opzioni: @table @code @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. 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: @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 -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 -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 @end table Per aggiornare i frammenti LilyPond presenti nei file texinfo, si usa @example 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=@dots{} --to=@dots{} -s @end example @node Problemi nell'eseguire convert-ly @section Problemi nell'eseguire @code{convert-ly} @translationof Problems running convert-ly Quando si esegue convert-ly in una finestra del Prompt dei comandi in Windows su un file il cui nome o percorso contengano degli spazi, è necessario includere tutto il nome del file di input con tre (!) virgolette doppie: @example convert-ly """D:/Mie Partiture/Ode.ly""" > "D:/Mie Partiture/new Ode.ly" @end example Se il semplice comando @command{convert-ly -e *.ly} non funziona perché la linea di comando espansa diventa troppo lunga, si può inserire il comando @command{convert-ly} in un loop. Questo esempio per UNIX aggiornerà tutti i file @file{.ly} nella directory corrente @example for f in *.ly; do convert-ly -e $f; done; @end example Nella finestra del Prompt dei comandi di Windows il comando corrispondente è @example for %x in (*.ly) do convert-ly -e """%x""" @end example Non vengono gestiti tutti i cambiamenti del linguaggio. Si può specificare solo un'opzione di output. È piuttosto improbabile che si aggiornino automaticamente il codice scheme e le interfacce di scheme di LilyPond; tieniti pronto a correggere a mano il codice scheme. @node Conversioni manuali @section Conversioni manuali @translationof Manual conversions In teoria, un programma come @command{convert-ly} potrebbe gestire qualsiasi cambiamento di sintassi. Dopo tutto, un programma per computer interpreta la vecchia versione e la nuova versione, quindi un altro programma può tradurre un file in un altro@footnote{O almeno questo è possibile in qualsiasi file LilyPond che non contenga codice scheme. Se c'è del codice scheme nel file, allora il file LilyPond contiene un linguaggio Turing-completo, ed è possibile imbattersi in problemi col famigerato @qq{Problema dell'arresto} in informatica.}. Tuttavia il progetto LilyPond ha risorse limitate: non tutte le conversioni sono compiute automaticamente. Di seguito è riportato l'elenco dei problemi noti. @verbatim 1.6->2.0: Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this: To be able to run convert-ly on it, I first replaced all occurrences of '{<' to some dummy like '{#' and similarly I replaced '>}' with '&}'. After the conversion, I could then change back from '{ #' to '{ <' and from '& }' to '> }'. Doesn't convert all text markup correctly. In the old markup syntax, it was possible to group a number of markup commands together within parentheses, e.g. -#'((bold italic) "string") This will incorrectly be converted into -\markup{{\bold italic} "string"} instead of the correct -\markup{\bold \italic "string"} 2.0->2.2: Doesn't handle \partcombine Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas. 2.0->2.4: \magnify isn't changed to \fontsize. - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2) remove-tag isn't changed. - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . . first-page-number isn't changed. - first-page-number no => print-first-page-number = ##f Line breaks in header strings aren't converted. - \\\\ as line break in \header strings => \markup \center-align < "First Line" "Second Line" > Crescendo and decrescendo terminators aren't converted. - \rced => \! - \rc => \! 2.2->2.4: \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted. 2.4.2->2.5.9 \markup{ \center-align <{ ... }> } should be converted to: \markup{ \center-align {\line { ... }} } but now, \line is missing. 2.4->2.6 Special LaTeX characters such as $~$ in text are not converted to UTF8. 2.8 \score{} must now begin with a music expression. Anything else (particularly \header{}) must come after the music. @end verbatim