Documentation/it/usage/updating.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-
   2
   3 @ignore
   4     Translation of GIT committish: 15b9d5a33fe02826075a651e96ae21d2ae66a680
   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 La sintassi di input di LilyPond viene regolarmente modificata per semplificarla
  22 o per migliorarla in vari modi.  L'effetto collaterale è che l'interprete di LilyPond
  23 spesso non è più compatibile con i vecchi file di input.  Per ovviare a questo
  24 problema, si può usare il programma @command{convert-ly} per aggiornare
  25 i file alle nuove versioni di LilyPond.
  26
  27 @menu
  28 * Perché la sintassi cambia?::
  29 * Utilizzo di convert-ly::
  30 * Opzioni da linea di comando per convert-ly::
  31 * Problemi nell'eseguire convert-ly::
  32 * Conversioni manuali::
  33 @end menu
  34
  35
  36 @node Perché la sintassi cambia?
  37 @section Perché la sintassi cambia?
  38 @translationof Why does the syntax change?
  39
  40 @cindex convert-ly
  41 @cindex aggiornare i vecchi file di input
  42
  43 La sintassi di input di LilyPond talvolta cambia.  Via via che LilyPond
  44 migliora, la sintassi (il linguaggio dell'input) viene modificata di
  45 conseguenza.  Queste modifiche vengono fatte a volte per far sì che l'input
  46 sia più facile da leggere e da scrivere e a volte per aggiungere a LilyPond
  47 nuove funzionalità.
  48
  49 Ad esempio, tutti i nomi delle proprietà di @code{\paper} e @code{\layout}
  50 dovrebbero essere scritte nella forma @code{primo-secondo-terzo}.
  51 Tuttavia, nella versione 2.11.60 ci siamo accorti che la proprietà
  52 @code{printallheaders} non seguiva questa convenzione.
  53 Dovevamo lasciarla così come era (confondendo i nuovi utenti che devono avere
  54 a che fare con un formato di input incoerente), o cambiarla (disturbando i
  55 vecchi utenti che avevano già delle partiture)?  In questo caso decidemmo di
  56 cambiare il nome in @code{print-all-headers}.  Fortunatamente, questa modifica
  57 può essere automatizzata con @command{convert-ly}.
  58
  59 Purtroppo @command{convert-ly} non è in grado di gestire tutti i cambiamenti
  60 dell'input.  Ad esempio, in LilyPond 2.4 e precedenti, gli accenti e le lettere
  61 non inglesi venivano inserite con LaTeX -- per mostrare la parola francese per
  62 Natale si usava @code{No\"el}.  Ma in LilyPond
  63 @c keep "-matching straight in fancy editors
  64 2.6 e superiori, il carattere speciale @code{ë} deve essere inserito direttamente
  65 nel file LilyPond come carattere UTF-8.  @command{convert-ly} non può sostituire
  66 tutti i caratteri speciali di LaTeX con i rispettivi caratteri UTF-8; è necessario
  67 aggiornare a mano i vecchi file di input di LilyPond.
  68
  69 Le regole di conversione di @command{convert-ly} si basano sulla ricerca
  70 e sostituzione di parole chiave piuttosto che su una completa comprensione
  71 di LilyPond.  Ciò comporta varie conseguenze:
  72 @itemize @bullet
  73 @item
  74 L'affidabilità della conversione dipende dalla qualità di ciascun insieme
  75 di regole applicate e dalla complessità del rispettivo cambiamento.  Talvolta
  76 le conversioni richiedono correzioni manuali, quindi la vecchia versione
  77 deve essere tenuta a disposizione per poterle confrontare.
  78 @item
  79 Sono possibili solo conversioni nei formati più recenti: non ci sono regole
  80 per tornare a una versione precedente.  Dunque la copia di lavoro principale
  81 di un file LilyPond deve essere aggiornata soltanto quando non è più necessario
  82 compilarlo con le versioni precedenti di LilyPond.  Sistemi di controllo di
  83 versione come Git possono essere utili per gestire più di una versione.
  84 @item
  85 LilyPond e Scheme hanno delle robuste difese in caso di spazi omessi o
  86 posizionati in modo originale, ma le regole usate da @command{convert-ly} tendono
  87 a dare per scontato certe forme stilistiche.  Seguire lo stile usato nei manuali
  88 è la via più sicura per aggiornamenti indolori, soprattutto perché i manuali
  89 stessi sono aggiornati con @command{convert-ly}.
  90 @end itemize
  91
  92
  93
  94 @node Utilizzo di convert-ly
  95 @section Utilizzo di @command{convert-ly}
  96 @translationof Invoking convert-ly
  97
  98 @command{convert-ly} usa la dichiarazione @code{\version} nel file di input
  99 per determinare il vecchio numero di versione.  Nella maggior parte dei casi
 100 per aggiornare il file di input è sufficiente eseguire
 101
 102 @example
 103 convert-ly -e miofile.ly
 104 @end example
 105
 106 @noindent
 107 nella directory che contiene il file.  Questo comando aggiornerà
 108 @file{miofile.ly} e preserverà il file originale in
 109 @file{miofile.ly~}.
 110
 111 @warning{@command{convert-ly} converte sempre fino all'ultimo cambiamento di
 112 sintassi gestito.  Questo significa che il numero di @code{\version}
 113 che appare nel file convertito è di solito inferiore al numero di versione di
 114 @command{convert-ly}.}
 115
 116 Per convertire in una volta sola tutti i file di input in una directory si usa
 117
 118 @example
 119 convert-ly -e *.ly
 120 @end example
 121
 122 Altrimenti, se si desidera specificare un nome diverso per il file
 123 aggiornato, senza modificare il file originale e il suo nome, si usa
 124
 125 @example
 126 convert-ly miofile.ly > mionuovofile.ly
 127 @end example
 128
 129 Il programma elencherà i numeri di versione per i quali sono state eseguite
 130 le conversioni.  Se non vengono elencati dei numeri di versione il file è
 131 già aggiornato.
 132
 133 Gli utenti MacOS@tie{}X possono eseguire questi comandi dalla voce di menu
 134 @code{Compila > Aggiorna la sintassi}.
 135
 136 Gli utenti Windows devono inserire questi comandi nella finestra del Prompt
 137 dei comandi, che di solito si trova in
 138 @code{Start > Accessori > Prompt dei comandi}.
 139
 140
 141 @node Opzioni da linea di comando per convert-ly
 142 @section Opzioni da linea di comando per @command{convert-ly}
 143 @translationof Command line options for convert-ly
 144
 145 Il programma viene lanciato in questo modo:
 146
 147 @example
 148 convert-ly [@var{opzione}]@dots{} @var{nomefile}@dots{}
 149 @end example
 150
 151
 152 Esistono le seguenti opzioni:
 153
 154 @table @code
 155 @item -d, --diff-version-update
 156 aumenta il numero di versione in @code{\version} solo se il file è stato
 157 modificato da @command{convert-ly}. In questo caso, la dichiarazione di
 158 versione corrisponderà alla versione successiva all'ultimo reale cambiamento.
 159 Il numero di una versione instabile sarà arrotondato al numero della versione
 160 stabile successiva, a meno che ciò non vada oltre il numero di versione
 161 obiettivo.  Senza questa opzione, la versione rifletterà l'ultima
 162 conversione @emph{tentata}.
 163
 164 @item -e, --edit
 165 Applica le conversioni direttamente nel file di input, modificando
 166 l'originale.  Il file originale viene rinominato @file{nomefile.ly~}.  Questo
 167 file di backup può essere un file nascosto in alcuni sistemi operativi.
 168
 169 @item -b, --backup-numbered
 170 Se usato insieme all'opzione @samp{-e}, aggiunge un numero al nome dei file
 171 di backup, in modo da non sovrascrivere i backup precedenti.  I file di
 172 backup possono essere nascosti in alcuni sistemi operativi.
 173
 174 @item -f, --from=@var{from-patchlevel}
 175 Imposta la versione da cui convertire.  Se non viene impostata, @command{convert-ly}
 176 la ricaverà dalla stringa @code{\version} presente nel file.
 177 Esempio: @option{--from=2.10.25}
 178
 179 @item -h, --help
 180 Mostra la schermata di aiuto.
 181
 182 @item -l @var{loglevel}, --loglevel=@var{loglevel}
 183 Imposta la verbosità dell'output su @var{loglevel}. I valori possibili, in
 184 caratteri maiuscoli, sono @code{PROGRESS} (predefinito), @code{NONE},
 185 @code{WARNING}, @code{ERROR} e @code{DEBUG}.
 186
 187 @item -n, --no-version
 188 Normalmente @command{convert-ly} aggiunge un indicatore @code{\version}
 189 nell'output.  Questa opzione lo impedisce.
 190
 191 @item -s, --show-rules
 192 Mostra tutte le conversioni conosciute ed esce.
 193
 194 @item -t, --to=@var{to-patchlevel}
 195 Imposta esplicitamente la versione obiettivo della conversione, altrimenti
 196 viene usato il valore più recente.  Deve essere maggiore della versione iniziale.
 197 @example
 198 convert-ly --to=2.14.1 miofile.ly
 199 @end example
 200
 201 @end table
 202
 203 Per aggiornare i frammenti LilyPond presenti nei file texinfo, si usa
 204
 205 @example
 206 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
 207 @end example
 208
 209 Per vedere i cambiamenti della sintassi di LilyPond tra due versioni, si usa
 210
 211 @example
 212 convert-ly --from=@dots{} --to=@dots{} -s
 213 @end example
 214
 215
 216 @node Problemi nell'eseguire convert-ly
 217 @section Problemi nell'eseguire @code{convert-ly}
 218 @translationof Problems running convert-ly
 219
 220 Quando si esegue convert-ly in una finestra del Prompt dei comandi in Windows
 221 su un file il cui nome o percorso contengano degli spazi,
 222 è necessario includere tutto il nome del file di input con tre
 223 (!) virgolette doppie:
 224
 225 @example
 226 convert-ly """D:/Mie Partiture/Ode.ly""" > "D:/Mie Partiture/new Ode.ly"
 227 @end example
 228
 229 Se il semplice comando @command{convert-ly -e *.ly} non funziona perché la
 230 linea di comando espansa diventa troppo lunga, si può inserire il comando
 231 @command{convert-ly} in un loop.  Questo esempio per UNIX
 232 aggiornerà tutti i file @file{.ly} nella directory corrente
 233
 234 @example
 235 for f in *.ly; do convert-ly -e $f; done;
 236 @end example
 237
 238 Nella finestra del Prompt dei comandi di Windows il comando corrispondente è
 239
 240 @example
 241 for %x in (*.ly) do convert-ly -e """%x"""
 242 @end example
 243
 244 Non vengono gestiti tutti i cambiamenti del linguaggio.  Si può specificare solo
 245 un'opzione di output.  È piuttosto improbabile che si aggiornino automaticamente
 246 il codice scheme e le interfacce di scheme di LilyPond; tieniti pronto a
 247 correggere a mano il codice scheme.
 248
 249
 250 @node Conversioni manuali
 251 @section Conversioni manuali
 252 @translationof Manual conversions
 253
 254 In teoria, un programma come @command{convert-ly} potrebbe gestire qualsiasi
 255 cambiamento di sintassi.  Dopo tutto, un programma per computer interpreta
 256 la vecchia versione e la nuova versione, quindi un altro programma
 257 può tradurre un file in un altro@footnote{O almeno questo è possibile
 258 in qualsiasi file LilyPond che non contenga codice scheme.  Se c'è del
 259 codice scheme nel file, allora il file LilyPond contiene un linguaggio
 260 Turing-completo, ed è possibile imbattersi in problemi col famigerato
 261 @qq{Problema dell'arresto} in informatica.}.
 262
 263 Tuttavia il progetto LilyPond ha risorse limitate: non tutte le
 264 conversioni sono compiute automaticamente.  Di seguito è riportato l'elenco
 265 dei problemi noti.
 266
 267
 268 @verbatim
 269 1.6->2.0:
 270  Doesn't always convert figured bass correctly, specifically things like {<
 271 >}.  Mats' comment on working around this:
 272    To be able to run convert-ly
 273    on it, I first replaced all occurrences of '{<' to some dummy like '{#'
 274    and similarly I replaced '>}' with '&}'.  After the conversion, I could
 275    then change back from '{ #' to '{ <' and from '& }' to '> }'.
 276  Doesn't convert all text markup correctly.  In the old markup syntax,
 277  it was possible to group a number of markup commands together within
 278 parentheses, e.g.
 279    -#'((bold italic) "string")
 280    This will incorrectly be converted into
 281    -\markup{{\bold italic} "string"}
 282    instead of the correct
 283    -\markup{\bold \italic "string"}
 284 2.0->2.2:
 285  Doesn't handle \partcombine
 286  Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
 287 stanzas.
 288 2.0->2.4:
 289  \magnify isn't changed to \fontsize.
 290     - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 291  remove-tag isn't changed.
 292     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 293  first-page-number isn't changed.
 294     - first-page-number no => print-first-page-number = ##f
 295  Line breaks in header strings aren't converted.
 296     - \\\\  as line break in \header strings => \markup \center-align <
 297       "First Line" "Second Line" >
 298  Crescendo and decrescendo terminators aren't converted.
 299     - \rced => \!
 300     - \rc => \!
 301 2.2->2.4:
 302  \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
 303 converted.
 304 2.4.2->2.5.9
 305  \markup{ \center-align <{ ... }> } should be converted to:
 306  \markup{ \center-align {\line { ... }} }
 307  but now, \line is missing.
 308 2.4->2.6
 309  Special LaTeX characters such as $~$ in text are not converted to UTF8.
 310 2.8
 311  \score{} must now begin with a music expression.  Anything else
 312  (particularly \header{}) must come after the music.
 313 @end verbatim