Documentation/it/usage/updating.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-
   2
   3 @ignore
   4     Translation of GIT committish: 45d0e015edc53abebada17a0fdb1d665f7edf900
   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}, che permette di gestire
  25 gran parte dei cambiamenti di sintassi tra le 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 @code{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.  @code{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
  70 @node Utilizzo di convert-ly
  71 @section Utilizzo di @command{convert-ly}
  72 @translationof Invoking convert-ly
  73
  74 @command{convert-ly} usa la dichiarazione @code{\version} nel file di input
  75 per determinare il vecchio numero di versione.  Nella maggior parte dei casi
  76 per aggiornare il file di input è sufficiente eseguire
  77
  78 @example
  79 convert-ly -e miofile.ly
  80 @end example
  81
  82 @noindent
  83 nella directory che contiene il file.  Questo comando aggiornerà
  84 @file{miofile.ly} e preserverà il file originale in
  85 @file{miofile.ly~}.
  86
  87 @warning{@command{convert-ly} converte sempre fino all'ultimo cambiamento di
  88 sintassi gestito.  Questo significa che il numero di @code{\version}
  89 che appare nel file convertito è di solito inferiore al numero di versione di
  90 @command{convert-ly}.}
  91
  92 Per convertire in una volta sola tutti i file di input in una directory si usa
  93
  94 @example
  95 convert-ly -e *.ly
  96 @end example
  97
  98 Altrimenti, se si desidera specificare un nome diverso per il file
  99 aggiornato, senza modificare il file originale e il suo nome, si usa
 100
 101 @example
 102 convert-ly miofile.ly > mionuovofile.ly
 103 @end example
 104
 105 Il programma elencherà i numeri di versione per i quali sono state eseguite
 106 le conversioni.  Se non vengono elencati dei numeri di versione il file è
 107 già aggiornato.
 108
 109 Gli utenti MacOS@tie{}X possono eseguire questi comandi dalla voce di menu
 110 @code{Compila > Aggiorna la sintassi}.
 111
 112 Gli utenti Windows devono inserire questi comandi nella finestra del Prompt
 113 dei comandi, che di solito si trova in
 114 @code{Start > Accessori > Prompt dei comandi}.
 115
 116
 117 @node Opzioni da linea di comando per convert-ly
 118 @section Opzioni da linea di comando per @command{convert-ly}
 119 @translationof Command line options for convert-ly
 120
 121 Il programma viene lanciato in questo modo:
 122
 123 @example
 124 convert-ly [@var{opzione}]@dots{} @var{nomefile}@dots{}
 125 @end example
 126
 127
 128 Esistono le seguenti opzioni:
 129
 130 @table @code
 131 @item -d, --diff-version-update
 132 aggiorna @code{\version} all'ultima versione oppure, se questa è maggiore, non
 133 fa niente.
 134
 135 @item -e, --edit
 136 Applica le conversioni direttamente nel file di input, modificando
 137 l'originale.
 138
 139 @item -f, --from=@var{from-patchlevel}
 140 Imposta la versione da cui convertire.  Se non viene impostata, @command{convert-ly}
 141 la ricaverà dalla stringa @code{\version} presente nel file.
 142 Esempio: @option{--from=2.10.25}
 143
 144 @item -h, --help
 145 Mostra la schermata di aiuto.
 146
 147 @item -l @var{loglevel}, --loglevel=@var{loglevel}
 148 Imposta la verbosità dell'output su @var{loglevel}. I valori possibili, in
 149 caratteri maiuscoli, sono @code{PROGRESS} (predefinito), @code{NONE},
 150 @code{WARNING}, @code{ERROR} e @code{DEBUG}.
 151
 152 @item -n, --no-version
 153 Normalmente @command{convert-ly} aggiunge un indicatore @code{\version}
 154 nell'output.  Questa opzione lo impedisce.
 155
 156 @item -s, --show-rules
 157 Mostra tutte le conversioni conosciute ed esce.
 158
 159 @item -t, --to=@var{to-patchlevel}
 160 Imposta esplicitamente la versione obiettivo della conversione, altrimenti
 161 viene usato il valore più recente.
 162 @example
 163 convert-ly --to=2.14.1 miofile.ly
 164 @end example
 165
 166 @end table
 167
 168 Per aggiornare i frammenti LilyPond presenti nei file texinfo, si usa
 169
 170 @example
 171 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
 172 @end example
 173
 174 Per vedere i cambiamenti della sintassi di LilyPond tra due versioni, si usa
 175
 176 @example
 177 convert-ly --from=@dots{} --to=@dots{} -s
 178 @end example
 179
 180
 181 @node Problemi nell'eseguire convert-ly
 182 @section Problemi nell'eseguire @code{convert-ly}
 183 @translationof Problems running convert-ly
 184
 185 Quando si esegue convert-ly in una finestra del Prompt dei comandi in Windows
 186 su un file il cui nome o percorso contengano degli spazi,
 187 è necessario includere tutto il nome del file di input con tre
 188 (!) virgolette doppie:
 189
 190 @example
 191 convert-ly """D:/Mie Partiture/Ode.ly""" > "D:/Mie Partiture/new Ode.ly"
 192 @end example
 193
 194 Se il semplice comando @command{convert-ly -e *.ly} non funziona perché la
 195 linea di comando espansa diventa troppo lunga, si può inserire il comando
 196 @command{convert-ly} in un loop.  Questo esempio per UNIX
 197 aggiornerà tutti i file @file{.ly} nella directory corrente
 198
 199 @example
 200 for f in *.ly; do convert-ly -e $f; done;
 201 @end example
 202
 203 Nella finestra del Prompt dei comandi di Windows il comando corrispondente è
 204
 205 @example
 206 for %x in (*.ly) do convert-ly -e """%x"""
 207 @end example
 208
 209 Non vengono gestiti tutti i cambiamenti del linguaggio.  Si può specificare solo
 210 un'opzione di output.  È piuttosto improbabile che si aggiornino automaticamente
 211 il codice scheme e le interfacce di scheme di LilyPond; tieniti pronto a
 212 correggere a mano il codice scheme.
 213
 214
 215 @node Conversioni manuali
 216 @section Conversioni manuali
 217 @translationof Manual conversions
 218
 219 In teoria, un programma come @command{convert-ly} potrebbe gestire qualsiasi
 220 cambiamento di sintassi.  Dopo tutto, un programma per computer interpreta
 221 la vecchia versione e la nuova versione, quindi un altro programma
 222 può tradurre un file in un altro@footnote{O almeno questo è possibile
 223 in qualsiasi file LilyPond che non contenga codice scheme.  Se c'è del
 224 codice scheme nel file, allora il file LilyPond contiene un linguaggio
 225 Turing-completo, ed è possibile imbattersi in problemi col famigerato
 226 @qq{Problema dell'arresto} in informatica.}.
 227
 228 Tuttavia il progetto LilyPond ha risorse limitate: non tutte le
 229 conversioni sono compiute automaticamente.  Di seguito è riportato l'elenco
 230 dei problemi noti.
 231
 232
 233 @verbatim
 234 1.6->2.0:
 235  Doesn't always convert figured bass correctly, specifically things like {<
 236 >}.  Mats' comment on working around this:
 237    To be able to run convert-ly
 238    on it, I first replaced all occurrences of '{<' to some dummy like '{#'
 239    and similarly I replaced '>}' with '&}'.  After the conversion, I could
 240    then change back from '{ #' to '{ <' and from '& }' to '> }'.
 241  Doesn't convert all text markup correctly.  In the old markup syntax,
 242  it was possible to group a number of markup commands together within
 243 parentheses, e.g.
 244    -#'((bold italic) "string")
 245    This will incorrectly be converted into
 246    -\markup{{\bold italic} "string"}
 247    instead of the correct
 248    -\markup{\bold \italic "string"}
 249 2.0->2.2:
 250  Doesn't handle \partcombine
 251  Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
 252 stanzas.
 253 2.0->2.4:
 254  \magnify isn't changed to \fontsize.
 255     - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 256  remove-tag isn't changed.
 257     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 258  first-page-number isn't changed.
 259     - first-page-number no => print-first-page-number = ##f
 260  Line breaks in header strings aren't converted.
 261     - \\\\  as line break in \header strings => \markup \center-align <
 262       "First Line" "Second Line" >
 263  Crescendo and decrescendo terminators aren't converted.
 264     - \rced => \!
 265     - \rc => \!
 266 2.2->2.4:
 267  \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
 268 converted.
 269 2.4.2->2.5.9
 270  \markup{ \center-align <{ ... }> } should be converted to:
 271  \markup{ \center-align {\line { ... }} }
 272  but now, \line is missing.
 273 2.4->2.6
 274  Special LaTeX characters such as $~$ in text are not converted to UTF8.
 275 2.8
 276  \score{} must now begin with a music expression.  Anything else
 277  (particularly \header{}) must come after the music.
 278 @end verbatim
 279
 280