Documentation/it/usage/updating.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-
   2
   3 @ignore
   4     Translation of GIT committish: bd8e8f0193000854fef9d3de3cc0a9f667ea8fb1
   5
   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..
   9 @end ignore
  10
  11 @c \version "2.16.0"
  12
  13
  14 @node Aggiornare i file con convert-ly
  15 @chapter Aggiornare i file con @command{convert-ly}
  16 @translationof Updating files with convert-ly
  17
  18 @cindex aggiornare un file di LilyPond
  19 @cindex convert-ly
  20
  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.
  25
  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.
  28
  29 @menu
  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 @end menu
  36
  37
  38 @node Perché la sintassi cambia?
  39 @section Perché la sintassi cambia?
  40 @translationof Why does the syntax change?
  41
  42 @cindex convert-ly
  43 @cindex aggiornare i vecchi file di input
  44
  45 Le modifiche della sintassi di solito servono a rendere l'input più
  46 facile sia da leggere che da scrivere e talvolta ad aggiungere a
  47 LilyPond nuove funzionalità o miglioramenti di funzioni esistenti.
  48
  49 Ecco un esempio reale:
  50
  51 Tutti i nomi delle proprietà di @code{\paper} e @code{\layout} dovrebbero essere
  52 scritte nella forma @code{primo-secondo-terzo}. Tuttavia, nella versione 2.11.60
  53 è emerso che la proprietà @code{printallheaders} non seguiva questa convenzione.
  54 Questa proprietà doveva essere lasciata così come era (confondendo i nuovi
  55 utenti con un formato di input incoerente), o doveva essere cambiata
  56 (disturbando i vecchi utenti con file di input già scritti)?
  57
  58 Fu deciso di cambiare il nome della proprietà in @code{print-all-headers}, e
  59 tramite il comando @command{convert-ly} i vecchi utenti avevano a disposizione
  60 uno strumento per aggiornare automaticamente i propri file di input.
  61
  62 Tuttavia il comando @command{convert-ly} non è sempre in grado di gestire tutti
  63 i cambiamenti di sintassi.  Nelle versioni di LilyPond precedenti la versione
  64 2.4.2, gli accenti e i caratteri non inglesi venivano inseriti con la notazione
  65 standard di LaTeX.  Per esempio, per inserire la parola francese che significa
  66 @q{Natale} si usava @code{No\"el}.  Ma nelle versioni successive di LilyPond, il
  67 carattere speciale @code{ë} deve essere inserito direttamente come carattere
  68 UTF-8.  Il comando @command{convert-ly} non può sostituire i caratteri speciali
  69 di LaTeX con i rispettivi caratteri UTF-8, dunque è necessario aggiornare a mano
  70 i vecchi file di input di LilyPond.
  71
  72 Le regole di conversione del comando @command{convert-ly} si basano sulla ricerca
  73 e sostituzione di parole chiave (piuttosto che su una completa @q{comprensione}
  74 del contesto di ciò che sta cambiando in un certo file di input).  Ciò comporta
  75 varie conseguenze:
  76
  77 @itemize @bullet
  78 @item
  79 L'affidabilità della conversione dipende dalla qualità di ciascun insieme
  80 di regole applicate e dalla complessità del rispettivo cambiamento.  Talvolta
  81 le conversioni richiedono correzioni manuali ulteriori, quindi il file originale
  82 deve essere conservato per poterlo confrontare in caso di necessità.
  83
  84 @item
  85 Sono possibili solo conversioni ai cambi di sintassi più recenti: non ci
  86 sono regole per tornare a una versione precedente di LilyPond.  Dunque il file
  87 di input deve essere aggiornato soltanto quando le versioni precedenti di
  88 LilyPond non sono più mantenute.  Di nuovo, il file di input originale deve
  89 essere conservato per ogni evenienza, magari usando sistemi di controllo di
  90 versione (es.: Git) per semplificare la gestione di versioni multiple dei
  91 file di input.
  92
  93 @item
  94 LilyPond ha delle robuste difese quando elabora spazi omessi o posizionati
  95 in modo @q{originale}, ma le regole usate da @command{convert-ly} tendono spesso
  96 a dare per scontato certe forme stilistiche.  Seguire lo stile di input usato
  97 nei manuali di LilyPond è dunque la via più sicura per aggiornamenti indolori,
  98 soprattutto perché gli esempi dei manuali stessi sono tutti aggiornati col
  99 comando @command{convert-ly}.
 100 @end itemize
 101
 102
 103 @node Utilizzo di convert-ly
 104 @section Utilizzo di @command{convert-ly}
 105 @translationof Invoking convert-ly
 106
 107 Il comando @command{convert-ly} usa il numero specificato da @code{\version} nel
 108 file di input per determinare versioni precedenti.  Nella maggior parte dei casi
 109 per aggiornare il file di input è sufficiente eseguire:
 110
 111 @example
 112 convert-ly -e miofile.ly
 113 @end example
 114
 115 @noindent
 116 nella directory che contiene il file di input.  Questo comando aggiornerà
 117 @file{miofile.ly} e preserverà il file originale rinominandolo
 118 @file{miofile.ly~}.  Verrà modificato anche il numero di @code{\version}
 119 nel file di input aggiornato, insieme agli aggiornamenti di sintassi
 120 richiesti.
 121
 122 Dopo averlo lanciato, il comando @command{convert-ly} elencherà i numeri di
 123 versione per i quali sono state eseguite le conversioni.  Se non vengono
 124 elencati dei numeri di versione il file è già aggiornato e utilizza la sintassi
 125 LilyPond più recente.
 126
 127 @warning{Per ogni nuova versione di LilyPond, viene creato un nuovo
 128 @command{convert-ly}, ma non tutte le versioni di LilyPond necessitano
 129 di cambi di sintassi per i propri file di input creati da una versione
 130 precedente.  Ciò significa che il comando @command{convert-ly} converterà
 131 i file di input solo fino all'ultimo cambio di sintassi in suo possesso
 132 e di conseguenza il numero di @code{\version} nel file di input aggiornato
 133 è talvolta precedente alla versione del comando @command{convert-ly} stesso.}
 134
 135 Per convertire tutti i file di input in una directory si usa:
 136
 137 @example
 138 convert-ly -e *.ly
 139 @end example
 140
 141 Sia gli utenti Linux che MacOS@tie{}X possono usare le rispettive applicazioni
 142 del terminale, ma gli utenti MacOS@tie{}X possono anche eseguire questo comando
 143 direttamente dalla voce di menu @code{Compila > Aggiorna la sintassi}.
 144
 145 Un utente Windows deve eseguire il comando:
 146
 147 @example
 148 convert-ly.py -e *.ly
 149 @end example
 150
 151 @noindent
 152 inserendolo in un @code{prompt dei comandi}, che di solito si trova in
 153 @code{Start > Accessori > Prompt dei comandi} o, per gli utenti della
 154 versione 8, scrivendo @q{prompt dei comandi} nella finestra di ricerca.
 155
 156 Per convertire tutti i file di input che si trovano in diverse sottodirectory:
 157
 158 @example
 159 find . -name '*.ly' -exec convert-ly -e '@{@}' \;
 160 @end example
 161
 162 Questo esempio cerca e converte tutti i file di input nella directory
 163 corrente e in tutte le sue sottodirectory ricorsivamente.  I file
 164 convertiti saranno salvati nella stessa directory insieme all'originale
 165 rinominato.  Dovrebbe funzionare anche per gli utenti MacOS@tie{}X, anche
 166 se solo tramite l'applicazione del terminale.
 167
 168 Gli utenti Windows devono usare:
 169
 170 @example
 171 forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@file"
 172 @end example
 173
 174 Altrimenti, si può indicare un percorso esplicito alla cartella che
 175 contiene tutte le sottocartelle con i file di input tramite l'opzione
 176 @code{/p}:
 177
 178 @example
 179 forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c convert-ly.py -e @@file"
 180 @end example
 181
 182 Tale percorso, se contiene spazi, deve essere racchiuso tra
 183 virgolette doppie:
 184
 185 @example
 186 forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c convert-ly.py -e @@file"
 187 @end example
 188
 189
 190
 191 @node Opzioni da linea di comando per convert-ly
 192 @section Opzioni da linea di comando per @command{convert-ly}
 193 @translationof Command line options for convert-ly
 194
 195 Il programma viene lanciato in questo modo:
 196
 197 @example
 198 convert-ly [@var{opzione}]@dots{} @var{nomefile}@dots{}
 199 @end example
 200
 201
 202 Esistono le seguenti opzioni:
 203
 204 @table @code
 205 @item -d, --diff-version-update
 206 aumenta il numero di versione in @code{\version} solo se il file è stato
 207 modificato da @command{convert-ly}. In questo caso, la dichiarazione di
 208 versione corrisponderà alla versione successiva all'ultimo reale cambiamento.
 209 Il numero di una versione instabile sarà arrotondato al numero della versione
 210 stabile successiva, a meno che ciò non vada oltre il numero di versione
 211 obiettivo.  Senza questa opzione, la versione rifletterà l'ultima
 212 conversione @emph{tentata}.
 213
 214 @item -e, --edit
 215 Applica le conversioni direttamente nel file di input, modificando
 216 l'originale.  Il file originale viene rinominato @file{nomefile.ly~}.  Questo
 217 file di backup può essere un file nascosto in alcuni sistemi operativi.
 218 Altrimenti, se si desidera specificare un nome diverso per il file
 219 aggiornato senza usare il predefinito @code{~} dell'opzione @code{-e}
 220 appeso al vecchio file di input, si può usare la redirezione dell'output:
 221
 222 @example
 223 convert-ly miofile.ly > mionuovofile.ly
 224 @end example
 225
 226 Gli utenti Windows devono usare:
 227
 228 @example
 229 convert-ly.py miofile.ly > mionuovofile.ly
 230 @end example
 231
 232 @item -b, --backup-numbered
 233 Se usato insieme all'opzione @samp{-e}, aggiunge un numero al nome dei file
 234 di backup, in modo da non sovrascrivere i backup precedenti.  I file di
 235 backup possono essere nascosti in alcuni sistemi operativi.
 236
 237 @item -f, --from=@var{from-patchlevel}
 238 Imposta la versione da cui convertire.  Se non viene impostata, @command{convert-ly}
 239 la ricaverà dalla stringa @code{\version} presente nel file.
 240 Esempio: @option{--from=2.10.25}
 241
 242 @item -h, --help
 243 Mostra la schermata di aiuto.
 244
 245 @item -l @var{loglevel}, --loglevel=@var{loglevel}
 246 Imposta la verbosità dell'output su @var{loglevel}. I valori possibili, in
 247 caratteri maiuscoli, sono @code{PROGRESS} (predefinito), @code{NONE},
 248 @code{WARNING}, @code{ERROR} e @code{DEBUG}.
 249
 250 @item -n, --no-version
 251 Normalmente @command{convert-ly} aggiunge un indicatore @code{\version}
 252 nell'output.  Questa opzione lo impedisce.
 253
 254 @item -s, --show-rules
 255 Mostra tutte le conversioni conosciute ed esce.
 256
 257 @item -t, --to=@var{to-patchlevel}
 258 Imposta esplicitamente la versione obiettivo della conversione, altrimenti
 259 viene usato il valore più recente.  Deve essere maggiore della versione iniziale.
 260 @example
 261 convert-ly --to=2.14.1 miofile.ly
 262 @end example
 263
 264 @end table
 265
 266 Per aggiornare i frammenti LilyPond presenti nei file texinfo, si usa
 267
 268 @example
 269 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
 270 @end example
 271
 272 Per vedere i cambiamenti della sintassi di LilyPond tra due versioni, si usa
 273
 274 @example
 275 convert-ly --from=@dots{} --to=@dots{} -s
 276 @end example
 277
 278
 279 @node Problemi nell'eseguire convert-ly
 280 @section Problemi nell'eseguire @code{convert-ly}
 281 @translationof Problems running convert-ly
 282
 283 Quando si esegue convert-ly in una finestra del Prompt dei comandi in Windows
 284 su un file il cui nome o percorso contengano degli spazi,
 285 è necessario includere tutto il nome del file di input con tre
 286 (!) virgolette doppie:
 287
 288 @example
 289 convert-ly """D:/Mie Partiture/Ode.ly""" > "D:/Mie Partiture/new Ode.ly"
 290 @end example
 291
 292 Se il semplice comando @command{convert-ly -e *.ly} non funziona perché la
 293 linea di comando espansa diventa troppo lunga, si può inserire il comando
 294 @command{convert-ly} in un loop.  Questo esempio per UNIX
 295 aggiornerà tutti i file @file{.ly} nella directory corrente
 296
 297 @example
 298 for f in *.ly; do convert-ly -e $f; done;
 299 @end example
 300
 301 Nella finestra del Prompt dei comandi di Windows il comando corrispondente è
 302
 303 @example
 304 for %x in (*.ly) do convert-ly -e """%x"""
 305 @end example
 306
 307 Non vengono gestiti tutti i cambiamenti del linguaggio.  Si può specificare solo
 308 un'opzione di output.  È piuttosto improbabile che si aggiornino automaticamente
 309 il codice scheme e le interfacce di scheme di LilyPond; tieniti pronto a
 310 correggere a mano il codice scheme.
 311
 312
 313 @node Conversioni manuali
 314 @section Conversioni manuali
 315 @translationof Manual conversions
 316
 317 In teoria, un programma come @command{convert-ly} potrebbe gestire qualsiasi
 318 cambiamento di sintassi.  Dopo tutto, un programma per computer interpreta
 319 la vecchia versione e la nuova versione, quindi un altro programma
 320 può tradurre un file in un altro@footnote{O almeno questo è possibile
 321 in qualsiasi file LilyPond che non contenga codice scheme.  Se c'è del
 322 codice scheme nel file, allora il file LilyPond contiene un linguaggio
 323 Turing-completo, ed è possibile imbattersi in problemi col famigerato
 324 @qq{Problema dell'arresto} in informatica.}.
 325
 326 Tuttavia il progetto LilyPond ha risorse limitate: non tutte le
 327 conversioni sono compiute automaticamente.  Di seguito è riportato l'elenco
 328 dei problemi noti.
 329
 330
 331 @verbatim
 332 1.6->2.0:
 333  Doesn't always convert figured bass correctly, specifically things like {<
 334 >}.  Mats' comment on working around this:
 335    To be able to run convert-ly
 336    on it, I first replaced all occurrences of '{<' to some dummy like '{#'
 337    and similarly I replaced '>}' with '&}'.  After the conversion, I could
 338    then change back from '{ #' to '{ <' and from '& }' to '> }'.
 339  Doesn't convert all text markup correctly.  In the old markup syntax,
 340  it was possible to group a number of markup commands together within
 341 parentheses, e.g.
 342    -#'((bold italic) "string")
 343    This will incorrectly be converted into
 344    -\markup{{\bold italic} "string"}
 345    instead of the correct
 346    -\markup{\bold \italic "string"}
 347 2.0->2.2:
 348  Doesn't handle \partcombine
 349  Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
 350 stanzas.
 351 2.0->2.4:
 352  \magnify isn't changed to \fontsize.
 353     - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 354  remove-tag isn't changed.
 355     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 356  first-page-number isn't changed.
 357     - first-page-number no => print-first-page-number = ##f
 358  Line breaks in header strings aren't converted.
 359     - \\\\  as line break in \header strings => \markup \center-align <
 360       "First Line" "Second Line" >
 361  Crescendo and decrescendo terminators aren't converted.
 362     - \rced => \!
 363     - \rc => \!
 364 2.2->2.4:
 365  \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
 366 converted.
 367 2.4.2->2.5.9
 368  \markup{ \center-align <{ ... }> } should be converted to:
 369  \markup{ \center-align {\line { ... }} }
 370  but now, \line is missing.
 371 2.4->2.6
 372  Special LaTeX characters such as $~$ in text are not converted to UTF8.
 373 2.8
 374  \score{} must now begin with a music expression.  Anything else
 375  (particularly \header{}) must come after the music.
 376 @end verbatim