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

@ignore
    Translation of GIT committish: d36171e34d236d890f5dc511b895037188c6c7cb

    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.19.21"

@node Consigli su come scrivere i file
@chapter Consigli su come scrivere i file
@translationof Suggestions for writing files

Ora puoi iniziare a scrivere file di input di LilyPond più grandi --
non più i piccoli esempi del tutorial, ma pezzi completi.
Ma qual è il modo migliore di farlo?

Finché LilyPond comprende i file di input e produce l'output che
desideri, non importa quale aspetto abbiano i file di input.  Tuttavia,
ci sono altri aspetti da tenere a mente quando si scrivono
file di input di LilyPond.

@itemize
@item Che fare in caso di errore?  La struttura data a un file LilyPond può
rendere l'individuazione di certi tipi di errore più facile (o più difficile).

@item Che fare se vuoi inviare i tuoi file di input a qualcuno?  E se decidi di
modificare i tuoi file di input dopo qualche anno?  Alcuni file di input di
LilyPond sono comprensibili a prima vista; altri ti possono lasciare a grattarti
la testa per un'ora.

@item Che fare se vuoi aggiornare il tuo file per poterlo usare con una
versione più recente di LilyPond?  Con l'evolversi di LilyPond, la sintassi di
input si trova soggetta a occasionali cambiamenti.  Alcune modifiche possono
essere fatte in automatico con @code{convert-ly}, ma altre potrebbero richiedere
un intervento manuale.  I file di input di LilyPond possono essere strutturati
in moda da essere poi aggiornati in modo più semplice (o più difficile).

@end itemize

@menu
* Consigli generali::
* Scrivere musica esistente::
* Grandi progetti::
* Risoluzione dei problemi::
* Make e Makefile::
@end menu


@node Consigli generali
@section Consigli generali
@translationof General suggestions

Ecco alcuni consigli che possono aiutare a evitare (e risolvere) i
problemi più comuni in fase di scrittura:

@itemize
@item @strong{Includere sempre il numero di @code{\version} in ogni file di input},
non importa quanto piccolo possa essere il file.  Ciò impedisce di dover
ricordare con quale versione di LilyPond è stato creato il file ed è
importante soprattutto per @ref{Updating files with convert-ly} (che ha
bisogno della dichiarazione @code{\version}); o quando si inviano i file
di input a altri utenti (per esempio, quando si chiede aiuto nelle mailing
list).  Nota che tutti i modelli contengono l'informazione su @code{\version}.

@item
@strong{Scrivere ciascuna battuta su una singola riga del file di input}.  Ciò
semplifica molto l'analisi dei problemi del file di input.

@item
@strong{Inserire i @ruser{Controlli di battuta e del numero di battuta} e
i @ruser{Controlli di ottava}}.  Inserendo @q{controlli} di questo tipo nei
file di input, si può individuare un errore più rapidamente.  Quanto spesso
aggiungere i controlli dipende dalla complessità della musica da scrivere.  Per
composizioni semplici, aggiungere controlli in pochi punti strategici può essere
sufficiente, ma per musica più complessa, con molte voci e/o righi, è consigliabile
inserire i controlli dopo ogni battuta.

@item
@strong{Inserire commenti nei file di input}.  Riferimenti a temi musicali
(@q{secondo tema nei violini,} @q{quarta variazione,} etc.) o numeri di battuta
inseriti come commenti rendono molto più semplice la lettura del file di input,
specialmente se occorre modificare qualcosa successivamente o passare i file
di input di LilyPond a un'altra persona.

@item
@strong{Aggiungere durate esplicite all'inizio delle @q{sezioni}}.
Per esempio, @code{c4 d e} invece di @code{c d e f} può semplificare il
riarrangiamento della musica in un momento successivo.

@item
@strong{Imparare a allineare e indentare le parentesi e la musica parallela}.
Molti problemi sono spesso causati da parentesi @q{mancanti}.  Indentare
chiaramente le parentesi di @q{apertura} e di @q{chiusura} (o gli indicatori
@code{<<} e @code{>>}) aiuta a evitare tali problemi.  Per esempio,

@example
\new Staff @{
  \relative @{
    r4 g'8 g c8 c4 d |
    e4 r8 |
    % Sezione Ossia
    <<
      @{ f8 c c | @}
      \new Staff @{
        f8 f c |
      @}
    >>
    r4 |
  @}
@}
@end example

@noindent
è molto più semplice da leggere di

@example
\new Staff @{ \relative @{ r4 g'8 g c4 c8 d | e4 r8
% Sezione Ossia
<< @{ f8 c c @} \new Staff @{ f8 f c @} >> r4 | @} @}
@end example

@item
@strong{Tenere separato il contenuto musicale dallo stile} mettendo gli
@code{\override} nel blocco @code{\layout}:

@example
\score @{
  @var{@dots{}music@dots{}}
  \layout @{
   \override TabStaff.Stemstencil = ##f
 @}
@}
@end example

Ciò non creerà un nuovo contesto ma sarà applicato quando ne viene creato
uno.  Vedi anche @rlearning{Ridurre l'input grazie a variabili e funzioni} e
@rlearning{Fogli di stile}.

@end itemize


@node Scrivere musica esistente
@section Scrivere musica esistente
@translationof Typesetting existing music

Se stai riportando della musica da una partitura esistente (ovvero il brano
contenuto in uno spartito già scritto),

@itemize

@item Inserisci in LilyPond le note del manoscritto (la copia fisica della
musica) un sistema alla volta (ma sempre una battuta per linea di testo),
e controlla ogni sistema completato.  Puoi usare le proprietà
@code{showLastLength} o @code{showFirstLength} per velocizzare
l'elaborazione -- vedi @ruser{Skipping corrected music}.

@item Definisci @code{mBreak = @{ \break @}} e inserisci @code{\mBreak}
nel file di input ogni volta che nel manoscritto c'è un a capo.  In questo
modo è più semplice confrontare la musica generata da LilyPond con quella
originale.  Quando hai finito la revisione della partitura, puoi
definire @code{mBreak = @{ @}} per eliminare tutte queste interruzioni di
riga.  Così LilyPond potrà inserire le interruzioni dove ritiene stiano
meglio.

@item Quando si inserisce una parte per strumento traspositore all'interno
di una variabile, è consigliabile racchiudere le note tra parentesi graffe

@example
\transpose c altezza-naturale @{@dots{}@}
@end example

@noindent
(dove @code{altezza-naturale} corrisponde all'intonazione di base dello
strumento) così che la musica contenuta nella variabile sia effettivamente
scritta in Do. La puoi presentare trasposta quando la variabile viene usata,
se necessario, ma potresti non desiderarlo (ad esempio quando si stampa una
partitura in intonazione reale, quando si traspone una parte per trombone
dalla chiave di Sol alla chiave di basso, etc.).  Errori nelle trasposizioni
sono meno probabili se tutta la musica contenuta nelle variabili è ad
un'altezza costante.

Inoltre, trasponi sempre in relazione al Do.  Questo significa che le uniche
altre tonalità che userai saranno le altezze naturali degli strumenti - bes
per una tromba in Si bemolle, aes per un clarinetto in La bemolle, etc.

@end itemize


@node Grandi progetti
@section Grandi progetti
@translationof Large projects

Quando si lavora a un grande progetto, definire una struttura chiara nel
file di input diventa vitale.

@itemize

@item @strong{Usa una variabile per ogni voce}, con un minimo di
struttura nella definizione.  La struttura della sezione
@code{\score} è la parte più probabilmente soggetta a cambiamenti;
è invece molto improbabile che la definizione di @code{violin} cambi
in una nuova versione di LilyPond.

@example
violin = \relative @{
g'4 c'8. e16
@}
@dots{}
\score @{
  \new GrandStaff @{
    \new Staff @{
      \violin
    @}
  @}
@}
@end example

@item @strong{Separa le modifiche manuali (tweak) dalle definizioni musicali}.  Questo
punto è stato menzionato prima; nei grandi progetti diventa di vitale
importanza.  Potrebbe essere necessario modificare la definizione
di @code{fthenp}, ma si dovrebbe farlo una volta sola e senza toccare
niente in @code{violin}.

@example
fthenp = _\markup@{
  \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
violin = \relative @{
g'4\fthenp c'8. e16
@}
@end example

@end itemize


@node Risoluzione dei problemi
@section Risoluzione dei problemi
@translationof Troubleshooting

Prima o poi ti capiterà di scrivere un file che LilyPond non
riesce a compilare.  I messaggi inviati da LilyPond potrebbero aiutarti
a trovare l'errore, ma in molti casi sarà necessario fare qualche ricerca
per individuare l'origine del problema.

Gli strumenti più potenti a questo riguardo sono il commento della
linea singola (indicato da @code{%}) e il commento di blocco
(indicato da @code{%@{ @dots{} %@}}).  Se non sai dove sia il problema,
inizia col commentare ampie parti del file di input.  Dopo aver commentato
una sezione, prova a compilare di nuovo il file.  Se funziona, allora il
problema deve trovarsi nella parte che hai appena commentato.  Se non
funziona, continua a commentare il materiale finché non ottieni un codice
funzionante.

Nel caso estremo, potresti finire con soltanto

@example
\score @{
  <<
    % \melody
    % \harmony
    % \bass
  >>
  \layout@{@}
@}
@end example

@noindent
(in altre parole, un file senza musica)

Se dovesse succedere, non rinunciare.  Decommenta un pezzetto -- ad esempio,
la parte di basso -- e vedi se funziona.  Se non funziona,
allora commenta tutta la musica del basso (ma lascia
@code{\bass} in @code{\score} non commentato).

@example
bass = \relative @{
%@{
  c'4 c c c
  d d d d
%@}
@}
@end example

Ora inizia a decommentare mano a mano la parte di
@code{bass} finché non trovi la linea che causa il problema.

Un'altra tecnica di debug molto utile consiste nel creare
@rweb{Esempi minimi}.


@node Make e Makefile
@section Make e Makefile
@translationof Make and Makefiles

@cindex makefile
@cindex make

Tutte le piattaforme su cui Lilypond può essere installato supportano un
software chiamato @code{make}.  Questo software legge un file speciale chiamato
@code{Makefile} che definisce quali file dipendono da quali altri e quali
comandi occorra dare al sistema operativo per produrre un file da un
altro.  Ad esempio Makefile può spiegare come generare
@file{ballad.pdf} e @file{ballad.midi} da @file{ballad.ly} eseguendo
Lilypond.

In alcune situazioni, è una buona idea creare un @code{Makefile}
per il proprio progetto, per proprio comodo o come cortesia
per quanti altri possano avere accesso ai file sorgente.
Questo vale per i progetti molto ampi con tanti file inclusi e
diverse opzioni di output (ad esempio, partitura completa, parti, partitura
del direttore, riduzione per pianoforte, etc.) o per progetti che
richiedono comandi difficili per la compilazione (come i progetti che
usano @code{lilypond-book}).  I Makefile variano molto in complessità
e flessibilità, in base alle necessità e alle abilità degli autori.
Il programma GNU Make è installato nelle distribuzioni GNU/Linux
e su MacOS X ed è disponibile anche per Windows.

Si veda il @strong{Manuale di GNU Make} per conoscere in dettaglio l'uso di
@code{make}, dato che quel che segue dà solo un'idea delle sue potenzialità.

I comandi per definire delle regole in un Makefile cambiano in base
alla piattaforma; ad esempio le varie distribuzioni di GNU/Linux e
MacOS usano @code{bash}, mentre Windows usa @code{cmd}.  Nota che su
MacOS X è necessario configurare il sistema per usare l'interprete da linea
di comando.  Di seguito alcuni Makefile di esempio, con versioni sia per
GNU/Linux/MacOS sia per Windows.

Il primo esempio è per una composizione per orchestra in quattro
movimenti e presenta una directory strutturata come segue:

@example
Symphony/
|-- MIDI/
|-- Makefile
|-- Notes/
|   |-- cello.ily
|   |-- figures.ily
|   |-- horn.ily
|   |-- oboe.ily
|   |-- trioString.ily
|   |-- viola.ily
|   |-- violinOne.ily
|   `-- violinTwo.ily
|-- PDF/
|-- Parts/
|   |-- symphony-cello.ly
|   |-- symphony-horn.ly
|   |-- symphony-oboes.ly
|   |-- symphony-viola.ly
|   |-- symphony-violinOne.ly
|   `-- symphony-violinTwo.ly
|-- Scores/
|   |-- symphony.ly
|   |-- symphonyI.ly
|   |-- symphonyII.ly
|   |-- symphonyIII.ly
|   `-- symphonyIV.ly
`-- symphonyDefs.ily
@end example

I file @file{.ly} nelle directory @file{Scores} e
@file{Parts} prendono le note dai file @file{.ily}
nella directory @file{Notes}:

@example
%%% inizio del file "symphony-cello.ly"
\include ../symphonyDefs.ily
\include ../Notes/cello.ily
@end example

Il Makefile avrà i target di @code{score} (l'intero brano in partitura
completa), @code{movements} (singoli movimenti in partitura completa),
e @code{parts} (singole parti per i musicisti).  C'è anche un
target @code{archive} che creerà un archivio compresso dei file sorgenti,
utile per la condivisione via web o email.  Ecco un esempio di
Makefile per GNU/Linux e MacOS X.  Dovrebbe essere salvato col
nome @code{Makefile} nella directory principale del progetto:

@warning{Quando si definisce un target o una regola di pattern, le
linee successive devono iniziare con i tabulatori, non con gli spazi.}

@example
# Il prefisso al nome dei file di output
piece = symphony
# Determinazione del numero dei processori
CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
# Il comando per eseguire lilypond
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click -djob-count=$(CPU_CORES)

# I suffissi usati in questo Makefile.
.SUFFIXES: .ly .ily .pdf .midi

# I file di input e di output vengono cercati nelle directory elencate
# nella variabile VPATH.  Tutte queste sono sottodirectory della directory
# corrente (assegnata dalla variabile `CURDIR' di GNU make).
VPATH = \
  $(CURDIR)/Scores \
  $(CURDIR)/PDF \
  $(CURDIR)/Parts \
  $(CURDIR)/Notes

# La regola di pattern per creare i file PDF e MIDI da un file di input LY.
# I file di output .pdf vengono messi nella sottodirectory `PDF', mentre i file
# .midi vanno nella sottodirectory `MIDI'.
%.pdf %.midi: %.ly
        $(LILY_CMD) $<; \           # questa linea inizia con una tabulazione
        if test -f "$*.pdf"; then \
            mv "$*.pdf" PDF/; \
        fi; \
        if test -f "$*.midi"; then \
            mv "$*.midi" MIDI/; \
        fi

notes = \
  cello.ily \
  horn.ily \
  oboe.ily \
  viola.ily \
  violinOne.ily \
  violinTwo.ily

# Le dipendenze dei movimenti.
$(piece)I.pdf: $(piece)I.ly $(notes)
$(piece)II.pdf: $(piece)II.ly $(notes)
$(piece)III.pdf: $(piece)III.ly $(notes)
$(piece)IV.pdf: $(piece)IV.ly $(notes)

# Le dipendenze della partitura completa.
$(piece).pdf: $(piece).ly $(notes)

# Le dipendenze delle parti.
$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily

# Lanciare `make score' per generare la partitura completa di tutti i quattro
# movimenti in un unico file.
.PHONY: score
score: $(piece).pdf

# Lanciare `make parts' per generare tutte le parti.
# Lanciare `make foo.pdf' per generare la parte per lo strumento `foo'.
# Esempio: `make symphony-cello.pdf'.
.PHONY: parts
parts: $(piece)-cello.pdf \
       $(piece)-violinOne.pdf \
       $(piece)-violinTwo.pdf \
       $(piece)-viola.pdf \
       $(piece)-oboes.pdf \
       $(piece)-horn.pdf

# Lanciare `make movements' per generare i file per i
# quattro movimenti separatamente.
.PHONY: movements
movements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parts movements

archive:
        tar -cvvf stamitz.tar \       # questa linea inizia con una tabulazione
        --exclude=*pdf --exclude=*~ \
        --exclude=*midi --exclude=*.tar \
        ../Stamitz/*
@end example


Ci sono alcune complicazioni specifiche della piattaforma Windows.  Dopo aver
scaricato e installato GNU Make per Windows, bisogna impostare il percorso
corretto nelle variabili d'ambiente di sistema perché la
shell DOS possa trovare il programma Make.  Per farlo, clicca col tasto destro
del mouse su "My Computer," poi scegli @code{Proprietà} e
@code{Avanzate}.  Clicca su @code{Variabili di ambiente}, e poi nel
pannello @code{Variabili di Sistema}, nella sezione @code{Percorso}, clicca su
@code{modifica} e aggiungi il percorso al file eseguibile GNU Make, che
avrà un aspetto simile:

@example
C:\Program Files\GnuWin32\bin
@end example

Lo stesso Makefile deve essere modificato per gestire diversi comandi
shell e gli spazi che sono presenti in alcune directory predefinite
di sistema.  Il target @code{archive} target viene tolto perché Windows
non ha il comando @code{tar}; inoltre Windows ha una diversa estensione
predefinita per i file midi.


@example
## VERSIONE DI WINDOWS
##
piece = symphony
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click \
                    -djob-count=$(NUMBER_OF_PROCESSORS)

#get the 8.3 name of CURDIR (workaround for spaces in PATH)
workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
          do @@echo %%~sb)

.SUFFIXES: .ly .ily .pdf .mid

VPATH = \
  $(workdir)/Scores \
  $(workdir)/PDF \
  $(workdir)/Parts \
  $(workdir)/Notes

%.pdf %.mid: %.ly
        $(LILY_CMD) $<      # questa linea inizia con una tabulazione
        if exist "$*.pdf"  move /Y "$*.pdf"  PDF/
        if exist "$*.mid" move /Y "$*.mid" MIDI/

notes = \
  cello.ily \
  figures.ily \
  horn.ily \
  oboe.ily \
  trioString.ily \
  viola.ily \
  violinOne.ily \
  violinTwo.ily

$(piece)I.pdf: $(piece)I.ly $(notes)
$(piece)II.pdf: $(piece)II.ly $(notes)
$(piece)III.pdf: $(piece)III.ly $(notes)
$(piece)IV.pdf: $(piece)IV.ly $(notes)

$(piece).pdf: $(piece).ly $(notes)

$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily

.PHONY: score
score: $(piece).pdf

.PHONY: parts
parts: $(piece)-cello.pdf \
       $(piece)-violinOne.pdf \
       $(piece)-violinTwo.pdf \
       $(piece)-viola.pdf \
       $(piece)-oboes.pdf \
       $(piece)-horn.pdf

.PHONY: movements
movements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parts movements
@end example


Il Makefile seguente è per un documento @command{lilypond-book} fatto con
LaTeX.  Questo progetto ha un indice, dunque il comando @command{latex} deve
essere eseguito due volte per aggiornare i collegamenti.  I file di output
sono tutti salvati nella directory @code{out} per i file .pdf e nella directory
@code{htmlout} per i file html.

@example
SHELL=/bin/sh
FILE=myproject
OUTDIR=out
WEBDIR=htmlout
VIEWER=acroread
BROWSER=firefox
LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
PDF=cd $(OUTDIR) && pdflatex $(FILE)
HTML=cd $(WEBDIR) && latex2html $(FILE)
INDEX=cd $(OUTDIR) && makeindex $(FILE)
PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &

all: pdf web keep

pdf:
        $(LILYBOOK_PDF)  # inizia con una tabulazione
        $(PDF)           # inizia con una tabulazione
        $(INDEX)         # inizia con una tabulazione
        $(PDF)           # inizia con una tabulazione
        $(PREVIEW)       # inizia con una tabulazione

web:
        $(LILYBOOK_HTML) # inizia con una tabulazione
        $(HTML)          # inizia con una tabulazione
        cp -R $(WEBDIR)/$(FILE)/ ./  # inizia con una tabulazione
        $(BROWSER) $(FILE)/$(FILE).html &  # inizia con una tabulazione

keep: pdf
        cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf  # inizia con una tabulazione

clean:
        rm -rf $(OUTDIR) # inizia con una tabulazione

web-clean:
        rm -rf $(WEBDIR) # inizia con una tabulazione

archive:
        tar -cvvf myproject.tar \ # inizia questa linea con una tabulazione
        --exclude=out/* \
        --exclude=htmlout/* \
        --exclude=myproject/* \
        --exclude=*midi \
        --exclude=*pdf \
        --exclude=*~ \
        ../MyProject/*
@end example

@c TODO: make this thing work on Windows

Il Makefile precedente non funziona su Windows.  Un'alternativa per
gli utenti Windows consiste nel creare un semplice file batch
contenente i comandi per la compilazione.  Questo file non terrà
traccia delle dipendenze come fa invece un Makefile, ma almeno riduce
il processo di compilazione a un solo comando.  Salva il codice
seguente come @command{build.bat} o @command{build.cmd}.
Il file batch può essere eseguito nel prompt DOS o semplicemente con
un doppio clic sulla sua icona.

@example
lilypond-book --output=out --pdf myproject.lytex
cd out
pdflatex myproject
makeindex myproject
pdflatex myproject
cd ..
copy out\myproject.pdf MyProject.pdf
@end example


@seealso

Questo manuale:
@ref{Uso da linea di comando},
@ref{lilypond-book}