path: root/Documentation/it/usage/updating.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-

@ignore
    Translation of GIT committish: 15b9d5a33fe02826075a651e96ae21d2ae66a680

    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

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} per aggiornare
i file alle nuove versioni di LilyPond.

@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

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 @command{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.  @command{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 regole di conversione di @command{convert-ly} si basano sulla ricerca
e sostituzione di parole chiave piuttosto che su una completa comprensione
di LilyPond.  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, quindi la vecchia versione
deve essere tenuta a disposizione per poterle confrontare.
@item
Sono possibili solo conversioni nei formati più recenti: non ci sono regole
per tornare a una versione precedente.  Dunque la copia di lavoro principale
di un file LilyPond deve essere aggiornata soltanto quando non è più necessario
compilarlo con le versioni precedenti di LilyPond.  Sistemi di controllo di
versione come Git possono essere utili per gestire più di una versione.
@item
LilyPond e Scheme hanno delle robuste difese in caso di spazi omessi o
posizionati in modo originale, ma le regole usate da @command{convert-ly} tendono
a dare per scontato certe forme stilistiche.  Seguire lo stile usato nei manuali
è la via più sicura per aggiornamenti indolori, soprattutto perché i manuali
stessi sono aggiornati con @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

@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~}.

@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}.}

Per convertire in una volta sola tutti i file di input in una directory si usa

@example
convert-ly -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

@example
convert-ly miofile.ly > mionuovofile.ly
@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.

Gli utenti MacOS@tie{}X possono eseguire questi comandi dalla voce di menu
@code{Compila > Aggiorna la sintassi}.

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
@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.

@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