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

@ignore
    Translation of GIT committish: 7ba0a22641cb0c7f5949d66a06d1e2e1fd0b3033

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

@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 aiutarti a evitare o risolvere
i problemi:

@itemize
@item @strong{Includi il numero di @code{\version} in ogni file}.  Nota che tutti
i modelli contengono l'informazione su @code{\version}.  Si consiglia vivamente
di includere sempre @code{\version}, non importa quanto piccolo possa essere
il file.  L'esperienza personale insegna come sia frustrante cercare di ricordare
quale versione di LilyPond si usava alcuni anni prima!  @command{convert-ly}
richiede che si dichiari la versione di LilyPond utilizzata.

@item @strong{Includi i controlli}: @ruser{Bar and bar number checks},
@ruser{Octave checks}.  Includendo i controlli ogni tanto, se fai
un errore lo puoi individuare più rapidamente.  Cosa si intende per
@q{ogni tanto}?  Dipende dalla complessità della musica.  Se la musica
è molto semplice, anche solo una volta o due.  Se la musica è molto
complessa, a ogni battuta.

@item @strong{Una battuta per ogni linea di testo}.  Se c'è qualcosa di
complicato, nella musica stessa o nell'output che desideri, di solito è
preferibile scrivere una sola battuta per linea.  Risparmiare spazio sullo
schermo concentrando otto battute per ogni riga non è affatto conveniente
se poi devi fare il @q{debug} dei file di input.

@item @strong{Inserisci dei commenti nei file di input}.  Puoi usare i numeri
di battuta (ogni tanto) o dei riferimenti ai temi musicali
(@q{secondo tema nei violini,} @q{quarta variazione,} etc.).  Potresti non
aver bisogno dei commenti mentre scrivi il brano la prima volta, ma se due
o tre anni dopo vuoi cambiare qualcosa o se vuoi dare il sorgente a un amico,
sarà molto più difficile capire le tue intenzioni e la struttura del file
se mancano i commenti.

@item @strong{Indenta le parentesi graffe}.  Molti problemi sono causati
da mancata corrispondenza tra le quantità di @code{@{} e di @code{@}}.

@item @strong{Esplicita le durate} all'inizio delle sezioni e delle
variabili.  Se specifichi @code{c4 d e} all'inizio di una frase
(invece di @code{c d e} soltanto) puoi evitare l'insorgere di problemi
al momento di rimetter mano alla musica.

@item @strong{Separa le modifiche manuali (tweak)} dalle definizioni
musicali.  Vedi @rlearning{Ridurre l’input grazie a variabili e funzioni}, e
@rlearning{Style sheets}.

@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 @{...@}
@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 c'' @{
g4 c'8. e16
@}
...
\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 c'' @{
g4\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{%@{ ... %@}}).  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' @{
%@{
  c4 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 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
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 ../definitions.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}