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

@ignore
    Translation of GIT committish: d378daa101069ce6497292b0f4a7f6ce2e9b51f0

    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

@include included/generating-output.itexi

@c \version "2.16.0"

@node Tutorial
@chapter Tutorial

Questo capitolo fornisce un'introduzione di base all'uso di LilyPond.

@menu
* Compilare un file::
* Come scrivere i file di input::
* Gestire gli errori::
* Come leggere i manuali::
@end menu

@node Compilare un file
@section Compilare un file
@translationof Compiling a file

@menu
* Inserire l'input::
* MacOS X::
* Windows::
* Linea di comando::
@end menu

@node Inserire l'input
@subsection Inserire l'input
@translationof Entering input

@cindex compilazione
@cindex esempio iniziale
@cindex esempio, iniziale
@cindex maiuscole, sensibile alle

@menu
* Generare l'output::
@end menu

@qq{Compilazione} è il termine usato per indicare l'elaborazione di un
file di input in formato LilyPond per produrre uno o più file di output.  I
file di output generalmente sono PDF (per la stampa e la visualizzazione),
MIDI (per la riproduzione audio) e PNG (per l'utilizzo online).  I file di
input di LilyPond sono semplici file di testo.

Questo esempio mostra un semplice file di input:

@example
\version "@w{@version{}}"
@{
  c' e' g' e'
@}
@end example

L'output grafico è:

@c  in this case we don't want verbatim
@lilypond[quote]
{
  c' e' g' e'
}
@end lilypond

@warning{Le note e i testi nel file LilyPond devono essere sempre
scritti tra @w{@strong{@{ parentesi graffe @}}}.  Per evitare ambiguità, le
parentesi dovrebbero essere delimitate da degli spazi, a meno che non si
trovino all'inizio o alla fine di una linea.  Può darsi che in alcuni esempi
di questo manuale le parentesi verranno omesse, ma non dimenticarle
nella tua musica! Per maggiori informazioni sull'aspetto degli esempi
nel manuale, si veda @ref{Come leggere i manuali}.}

Inoltre, l'input di LilyPond è @strong{sensibile alle maiuscole}.
@w{@samp{@{ c d e @}}} è un input valido; @w{@samp{@{ C D E @}}} invece
produrrà un messaggio di errore.

@smallspace

@node Generare l'output
@unnumberedsubsubsec Generare l'output
@translationof Producing output

@c TODO: move index entries
@cindex PDF file
@cindex vedere la musica
@cindex editor di testo

Come generare l'output di LilyPond dipende dal tuo sistema operativo e dai
programmi che usi.

@itemize

@item
@ref{MacOS X, @sourceimage{logo-macosx,,,}}
@ref{MacOS X, MacOS X} (grafico)

@item
@ref{Windows, @sourceimage{logo-windows,,,}}
@ref{Windows, Microsoft Windows} (grafico)

@item
@ref{Linea di comando, @sourceimage{logo-linux,,,}
@sourceimage{logo-freebsd,,,}
@sourceimage{logo-macosx,,,}
@sourceimage{logo-windows,,,}
}
@ref{Linea di comando, Tutti i sistemi operativi} (linea di comando)

@end itemize

Si noti che sono disponibili molti altri editor di testo con
un miglior supporto per LilyPond.  Per maggiori informazioni, si veda
@rweb{Editing facilitato}.

@warning{La prima volta che si esegue LilyPond la compilazione potrà richiedere
uno o due minuti perché tutti i font di sistema devono essere prima
analizzati.  In seguito, LilyPond sarà molto più veloce!}

@node MacOS X
@subsection MacOS X

@cindex eseguire LilyPond in MacOS X
@cindex MacOS X, eseguire LilyPond

@lilypadOSX


@node Windows
@subsection Windows

@cindex eseguire LilyPond in Windows
@cindex Windows, eseguire LilyPond

@lilypadWindows


@node Linea di comando
@subsection Linea di comando
@translationof Command-line

@cindex eseguire LilyPond in Unix
@cindex Unix, eseguire LilyPond

@lilypadCommandLine


@node Come scrivere i file di input
@section Come scrivere i file di input
@translationof How to write input files

Questa sezione introduce le basi della sintassi di LilyPond e ha l'obiettivo
di aiutarti ad iniziare a scrivere i file di input.

@menu
* Notazione semplice::
* Lavorare sui file di input::
@end menu

@node Notazione semplice
@subsection Notazione semplice
@translationof Simple notation

@cindex notazione semplice
@cindex notazione, semplice

@menu
* Altezze::
* Durate (ritmi)::
* Pause::
* Indicazione di tempo::
* Indicazioni di tempo::
* Chiave::
* Tutto insieme::
@end menu

LilyPond aggiungerà automaticamente alcuni elementi della notazione.  Nell'esempio
seguente, abbiamo specificato soltanto quattro note, ma LilyPond
ha aggiunto una chiave, il tempo e le durate.

@lilypond[verbatim,quote]
{
  c' e' g' e'
}
@end lilypond

@noindent
Questo comportamento può essere modificato, ma nella maggior parte dei
casi questi valori sono utili.


@node Altezze
@unnumberedsubsubsec Altezze
@translationof Pitches

@cindex altezze
@cindex modo relativo
@cindex apostrofo
@cindex virgola
@cindex alterazioni e modo relativo
@cindex modo relativo, e alterazioni

@funindex \relative
@funindex relative
@funindex '
@funindex ,

Glossario musicale: @rglosnamed{pitch,altezza}, @rglosnamed{interval,intervallo},
@rglosnamed{scale,scala}, @rglosnamed{middle C,Do centrale}, @rglosnamed{octave,ottava},
@rglosnamed{accidental,alterazione}.

Il modo più semplice per inserire le note è usare il modo @code{\relative}
(relativo). In questo modo, l'ottava viene scelta automaticamente in
base al principio per cui la nota che segue deve essere posizionata vicino
a quella precedente, ovvero deve essere posizionata nell'ottava che si trova
entro tre spazi di pentagramma dalla nota precedente.  Per iniziare, scriveremo
il pezzo musicale più elementare, una @notation{scala}, in cui ogni nota
si trova entro una distanza di appena uno spazio di pentagramma dalla nota precedente.

@lilypond[verbatim,quote]
% set the starting point to middle C
\relative c' {
  c d e f
  g a b c
}
@end lilypond

La nota iniziale è un @notation{Do centrale}.  Ogni nota successiva viene
posta il più vicino possibile alla nota precedente -- in altre parole, la prima
@code{c} è il Do più vicino al Do centrale.  Questo è seguito dal Re
più vicino alla nota precedente.  Possiamo creare melodie che hanno
intervalli più ampi, sempre usando soltanto il modo @code{\relative}:

@lilypond[verbatim,quote]
\relative c' {
  d f a g
  c b f d
}
@end lilypond

@noindent
Non è necessario che la prima nota della melodia inizi con
la nota che specifica l'altezza iniziale.  Nell'esempio
precedente, la prima nota -- il @code{Re} -- è il Re più vicino al
Do centrale.

Se si aggiungono (o si rimuovono) apostrofi @code{'} o virgole @code{,} dal
comando @q{@w{@code{@bs{}relative c'}}}, possiamo cambiare l'ottava di
partenza:

@lilypond[verbatim,quote]
% one octave above middle C
\relative c'' {
  e c a c
}
@end lilypond

Il modo relativo all'inizio può apparire disorientante, ma è il sistema più
semplice per inserire gran parte delle melodie.  Vediamo come questo calcolo
relativo funziona in pratica.  Se si parte da un Si, che si trova sulla linea
centrale in chiave di violino, si possono raggiungere un Do, un Re e un Mi
entro 3 spazi di pentagramma andando in su, e un La, un Sol e un Fa entro 3
spazi di pentagramma andando in giù.  Quindi se la nota che segue il Si è
un Do, un Re o un Mi, si troverà sopra il Si, mentre il La, il Sol
o il Fa si troveranno sotto.

@lilypond[verbatim,quote]
\relative c'' {
  b c  % c is 1 staff space up, so is the c above
  b d  % d is 2 up or 5 down, so is the d above
  b e  % e is 3 up or 4 down, so is the e above
  b a  % a is 6 up or 1 down, so is the a below
  b g  % g is 5 up or 2 down, so is the g below
  b f  % f is 4 up or 3 down, so is the f below
}
@end lilypond

Accade esattamente lo stesso quando qualcuna di queste note ha un
diesis o un bemolle.  Le @notation{Alterazioni} sono
@strong{completamente ignorate} nel calcolo della posizione relativa.
Viene fatto lo stesso conteggio dello spazio del pentagramma da
una nota in una qualsiasi altra posizione sul pentagramma.

Per inserire intervalli che sono più ampi di tre spazi di pentagramma, si può
alzare l'@notation{ottava} aggiungendo al nome della nota una virgoletta
ad apice singolo @code{'} (o apostrofo).  Si può abbassare l'ottava
aggiungendo al nome della nota una virgola @code{,}.

@lilypond[verbatim,quote]
\relative c'' {
  a a, c' f,
  g g'' a,, f'
}
@end lilypond

@noindent
Per cambiare una nota di due (o più!) ottave, si usano multipli di
@code{''} o @code{,,} -- ma stai attento a usare due virgolette ad
apici semplici @code{''} e non quelle a doppi apici @code{"}@tie{}!
@c " - keeps quotes in order for context-sensitive editor -td

@node Durate (ritmi)
@unnumberedsubsubsec Durate (ritmi)
@translationof Duration (rhythms)

@cindex durate della nota
@cindex durate
@cindex ritmi
@cindex semibreve
@cindex minima
@cindex semiminima
@cindex nota puntata
@cindex notazione delle durate

Glossario musicale: @rglosnamed{beam,coda}, @rglosnamed{duration,durata},
@rglosnamed{whole note,semibreve}, @rglosnamed{half note,minima}, @rglosnamed{quarter note,semiminima},
@rglosnamed{dotted note,nota puntata}.

La @notation{durata} di una nota viene indicata da un numero che segue
il nome della nota:  @code{1} per una @notation{semibreve}, @code{2} per
una @notation{minima}, @code{4} per una @notation{semiminima} e
così via.  Le @notation{Code} vengono aggiunte in automatico.

Se non si specifica una durata, si usa la durata precedente anche
per la nota successiva.  La durata predefinita della prima nota è di un
quarto.

@lilypond[verbatim,quote]
\relative c'' {
  a1
  a2 a4 a8 a
  a16 a a a a32 a a a a64 a a a a a a a a2
}
@end lilypond

Per creare @notation{note puntate}, aggiungi un punto @code{.} al
numero di durata.  La durata di una nota puntata deve essere dichiarata
esplicitamente (cioè con un numero).

@lilypond[verbatim,quote]
\relative c'' {
  a a a4. a8
  a8. a16 a a8. a8 a4.
}
@end lilypond


@node Pause
@unnumberedsubsubsec Pause
@translationof Rests

@cindex pausa
@cindex notazione delle pause

Glossario musicale: @rglosnamed{rest,pausa}.

Una @notation{pausa} viene inserita proprio come una nota ma col nome
@code{r}@tie{}:

@lilypond[verbatim,quote]
\relative c'' {
  a4 r r2
  r8 a r4 r4. r8
}
@end lilypond


@node Indicazione di tempo
@unnumberedsubsubsec Indicazione di tempo
@translationof Time signature

@cindex tempo, indicazione di

@funindex \time
@funindex time

Glossario musicale: @rglosnamed{time signature,indicazione di tempo}.

Il @notation{tempo} si imposta con il comando @code{\time}:

@lilypond[verbatim,quote]
\relative c'' {
  \time 3/4
  a4 a a
  \time 6/8
  a4. a
  \time 4/4
  a4 a a a
}
@end lilypond

@node Indicazioni di tempo
@unnumberedsubsubsec Indicazioni di tempo
@translationof Tempo marks

@cindex indicazioni di tempo
@cindex indicazioni metronomiche

@funindex \tempo
@funindex tempo

Glossario musicale: @rglosnamed{tempo indication,indicazione di tempo},
@rglosnamed{metronome,metronomo}.

L' @notation{indicazione di tempo} e l' @notation{indicazione metronomica} si
impostano col comando @code{\tempo}:

@lilypond[verbatim,quote]
\relative c'' {
  \time 3/4
  \tempo "Andante"
  a4 a a
  \time 6/8
  \tempo 4. = 96
  a4. a
  \time 4/4
  \tempo  "Presto" 4 = 120
  a4 a a a
}
@end lilypond


@node Chiave
@unnumberedsubsubsec Chiave
@translationof Clef

@cindex chiave
@cindex chiave di violino
@cindex contralto
@cindex tenore
@cindex basso

@funindex \clef
@funindex clef

Glossario musicale: @rglosnamed{clef,chiave}.

La @notation{chiave} si imposta con il comando @code{\clef}:

@lilypond[verbatim,quote]
\relative c' {
  \clef treble
  c1
  \clef alto
  c1
  \clef tenor
  c1
  \clef bass
  c1
}
@end lilypond


@node Tutto insieme
@unnumberedsubsubsec Tutto insieme
@translationof All together

Ecco un piccolo esempio che mostra tutti questi elementi insieme:

@lilypond[verbatim,quote]
\relative c, {
  \clef "bass"
  \time 3/4
  \tempo "Andante" 4 = 120
  c2 e8 c'
  g'2.
  f4 e d
  c4 c, r
}
@end lilypond


@seealso
Guida alla notazione: @ruser{Inserimento delle altezze},
@ruser{Inserimento delle durate}, @ruser{Inserimento delle pause},
@ruser{Indicazione di tempo}, @ruser{Chiave}.


@node Lavorare sui file di input
@subsection Lavorare sui file di input
@translationof Working on input files

@cindex parentesi graffe
@cindex graffe, parentesi
@cindex commenti
@cindex commento di linea
@cindex linea, commento di
@cindex commento di blocco
@cindex blocco, commento di
@cindex sensibile alle maiuscole
@cindex insensibile agli spazi
@cindex espressioni
@cindex versionamento
@cindex versione
@cindex numero di versione

@funindex \version
@funindex { ... }
@funindex %
@funindex %@{ ... %@}

I file di input di LilyPond sono simili ai file sorgenti di molti comuni
linguaggi di programmazione.  Contengono una dichiarazione di versione, sono
sensibili alle maiuscole, e in generale gli spazi bianchi vengono ignorati.  Le
espressioni musicali si formano con parentesi graffe @w{@code{@{ @}}}, e i commenti
sono indicati con @code{%} o @w{@code{%@{ @dots{} %@}}}@tie{}.

Se le frasi precedenti ti sembrano assurde, non preoccuparti!  Spiegheremo
cosa significano tutti questi termini:

@itemize

@item
@strong{Dichiarazione di versione}:
Ogni file LilyPond deve contenere una dichiarazione di versione.  Una
dichiarazione di versione è una linea che indica la versione di LilyPond per la
quale il file è stato scritto, come nel seguente esempio:

@example
\version "@w{@version{}}"
@end example

Per convenzione, la dichiarazione di versione viene posta all'inizio del file
LilyPond.

La dichiarazione di versione è importante per almeno due ragioni.  Primo,
permette l'aggiornamento automatico del file di input file via via che la
sintassi di LilyPond cambia.  Secondo, indica la versione di LilyPond richiesta
per compilare il file.

Se la dichiarazione di versione è omessa dal file di input, LilyPond mostra
un avvertimento durante la compilazione del file.

@item
@strong{Sensibile alle maiuscole}:
distingue tra lettere in minuscolo (es:
@w{@code{a, b, s, t}}) o in maiuscolo (es:  @w{@code{A, B, S, T}}).
Le note sono in minuscolo: @w{@code{@{ c d e @}}} è un input valido;
@w{@code{@{ C D E @}}} causerà un messaggio di errore.

@item
@strong{Insensibile agli spazi}:
non importa quanti spazi (o tabulazioni o nuove linee) aggiungi.
@w{@samp{@{ c4 d e @}}} ha lo stesso significato di
@w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} e:

@example
@{ c4                       d
                   e   @}
@end example

@noindent
Certo, l'esempio precedente è scomodo da leggere.  Una buona regola
pratica è indentare i blocchi di codice con una tabulazione o due spazi:

@example
@{
  c4 d e
@}
@end example

Tuttavia, uno spazio bianco @emph{è} necessario per separare molti elementi
sintattici gli uni dagli altri.  In altre parole, lo spazio bianco può essere
@emph{aggiunto}, ma non può essere @emph{eliminato}.  Dal momento che uno
spazio bianco mancante può dare adito a strani errori, si consiglia di
inserire sempre uno spazio bianco prima e dopo ogni elemento sintattico,
ad esempio, prima e dopo ogni parentesi graffa.

@item
@strong{Espressioni}:
ogni parte dell'input di LilyPond deve avere @strong{@{@tie{}parentesi@tie{}graffe@tie{}@}}
intorno.  Queste parentesi dicono a LilyPond che l'input costituisce
un'espressione musicale singola, proprio come le parentesi @code{()} in
matematica.  Per evitare ambiguità, le parentesi dovrebbero essere
racchiuse tra spazi, a meno che non si trovino all'inizio o alla fine di una linea.

Anche un comando di LilyPond seguito da un'espressione semplice in
parentesi (come @q{@w{@code{@bs{}relative c' @{ @dots{} @}}}}) conta come
un'espressione musicale singola.

@cindex commenti
@cindex commento di linea
@cindex commento di blocco
@item
@strong{Commenti}:
un commento è un appunto per il lettore umano dell'input musicale; viene
ignorato quando l'input viene analizzato, dunque non ha alcun effetto
sull'output finale.  Ci sono due tipi di commenti.  Il simbolo di percentuale
@code{%} introduce un commento di linea; tutto quello che sta dopo @code{%}
su quella linea verrà ignorato.  Per convenzione, un commento di linea viene
posto @emph{sopra} il codice a cui si riferisce.

@example
a4 a a a
% questo commento si riferisce ai Si
b2 b
@end example

Un commento di blocco segna come commento un'intera sezione di input musicale.
Tutto ciò che è compreso tra @code{%@{} e @code{%@}} viene ignorato.
Tuttavia, i commenti di blocco non si @q{annidano}.  Ovvero non si può
inserire un commento di blocco dentro a un altro commento di blocco.  Se
ci provi, il primo @code{%@}} interromperà @emph{entrambi} i commenti di
blocco.  Il seguente frammento mostra gli usi possibili per i commenti:

@example
% ecco le note di "Ah! Vous dirai-je, Maman"
  c4 c g' g a a g2

%@{
  Questa linea e le note sotto vengono ignorate,
  perché si trovano in un commento di blocco.

  f4 f e e d d c2
%@}
@end example

@end itemize


@node Gestire gli errori
@section Gestire gli errori
@translationof Dealing with errors

@cindex risoluzione dei problemi

Talvolta LilyPond non genera l'output che desideri.  Questa
sezione fornisce alcuni link che possono aiutarti a risolvere i
problemi che potrai incontrare.


@menu
* Consigli generali per la risoluzione dei problemi::
* Alcuni errori comuni::
@end menu

@node Consigli generali per la risoluzione dei problemi
@subsection Consigli generali per la risoluzione dei problemi
@translationof General troubleshooting tips

La risoluzione dei problemi in LilyPond può essere un compito impegnativo
per le persone che sono abituate a un'interfaccia grafica, perché è possibile
creare dei file di input non validi.  Quando questo accade, un approccio logico
è il modo migliore per identificare e risolvere il problema.  Alcune linee guida
che ti aiutano a imparare questo sono indicate in @rprogram{Risoluzione dei problemi}.


@node Alcuni errori comuni
@subsection Alcuni errori comuni
@translationof Some common errors

@cindex errori comuni

Ci sono alcuni errori comuni che sono difficili da risolvere basandosi
soltanto sui messaggi di errore che compaiono.  Questi sono
descritti in @rprogram{Errori comuni}.


@node Come leggere i manuali
@section Come leggere i manuali
@translationof How to read the manuals

Questa sezione spiega come leggere la documentazione in modo efficiente e
introduce alcune utili funzionalità interattive che sono disponibili
nella versione online della documentazione.

@menu
* Materiale omesso::
* Esempi cliccabili::
* Panoramica dei manuali::
@end menu


@node Materiale omesso
@subsection Materiale omesso
@translationof Omitted material

@cindex come leggere il manuale
@cindex manuale, leggere
@cindex leggere il manuale
@cindex cliccabili, esempi
@cindex esempi cliccabili
@cindex consigli su come costruire i file
@cindex modelli
@cindex costruire i file, consigli
@cindex file, consigli per costruirli

L'input di LilyPond deve essere compreso dai segni @code{@{ @}} o da
@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}}, come abbiamo visto in @ref{Lavorare
sui file di input}.  Nel resto di questo manuale gran parte degli esempi
ometterà questi segni.  Per replicare gli esempi, puoi copiare
e incollare l'input mostrato, ma @strong{devi} aggiungere
@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} in questo modo:

@example
\relative c'' @{
  @dots{}inserire qui l'esempio@dots{}
@}
@end example

Perché omettere le parentesi?  Gran parte degli esempi in questo manuale
possono essere inseriti nel mezzo di un pezzo più ampio.  Per questi esempi,
non ha senso includere @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} --
non si deve mettere un @code{\relative} dentro un altro
@code{\relative}!  Se includessimo @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}}
in ogni esempio, non potresti copiare un piccolo esempio della
documentazione e incollarlo dentro a un tuo brano più
esteso.  La maggior parte delle persone vuole aggiungere del materiale a
un brano esistente, per questo abbiamo strutturato il manuale in questo modo.

Ricorda che i file LilyPond devono avere una dichiarazione di
versione (@code{\version}).  Nei manuali la dichiarazione è omessa
perché gli esempi sono frammenti di codice e non file completi.
Ma dovresti prendere l'abitudine di includerla nei tuoi file.

@node Esempi cliccabili
@subsection Esempi cliccabili
@translationof Clickable examples

@warning{Queste funzionalità sono disponibili soltanto nei manuali in HTML.}

Molte persone imparano ad usare un programma provando e smanettando.
Questo è possibile anche con LilyPond.  Se clicchi su un'immagine
nella versione HTML di questo manuale, vedrai l'esatto input
LilyPond usato per generare quell'immagine.  Provalo su
questa immagine:

@c no verbatim here
@lilypond[quote]
\relative c'' {
  c4-\markup { \bold \huge { Clicca qui.  } }
}
@end lilypond

Tagliando e copiando quel che si trova nella sezione @qq{ly snippet},
puoi ricavare un modello di partenza per sperimentare.  Per vedere esattamente
lo stesso output (larghezza della linea e tutto il resto), copia tutto da @qq{Start
cut-&-pastable section} alla fine del file.

@ignore
This is item 825

@n ode Keyboard navigation
@s ubsection Keyboard navigation

@warning{This features is only available in the HTML manuals.}

@c TODO: once this is figured out, insert it here.

We are currently working on this feature.
@end ignore


@node Panoramica dei manuali
@subsection Panoramica dei manuali
@translationof Overview of manuals

La documentazione su LilyPond è vasta.  I nuovi utenti talvolta
sono confusi su quali parti dovrebbero leggere, e ogni tanto
saltano la lettura di parti fondamentali.

@warning{Non saltare le parti importanti della
documentazione.  Altrimenti ti risulterà molto più difficile
comprendere le sezioni successive.}

@itemize

@item
@strong{Prima di fare @emph{qualsiasi} tentativo}: leggi il @ref{Tutorial}
e la @ref{Notazione comunemente utilizzata} del Manuale di apprendimento.  Se
ti imbatti in termini musicali che non conosci, cercali nel @rglosnamed{Top, Glossario}.

@item
@strong{Prima di tentare di scrivere un pezzo musicale completo}: leggi
i @ref{Concetti fondamentali} del Manuale di apprendimento.  Dopo puoi dare
un'occhiata alle sezioni rilevanti della @rusernamed{Top, Guida alla notazione}.

@item
@strong{Prima di cercare di cambiare l'output predefinito}: leggi
@ref{Tweaking output} del Manuale di apprendimento.

@item
@strong{Prima di iniziare un grande progetto}: leggi il documento
@rprogram{Consigli su come scrivere i file} del manuale di Uso del programma.

@end itemize


