3.3.1 Inclusione di file LilyPond

Se un progetto è grande e complesso, conviene suddividerlo in file separati. Per citare un altro file si usa

\include "altrofile.ly"

La riga \include "altrofile.ly" equivale a incollare i contenuti di altrofile.ly nel file corrente nel punto in cui appare il comando \include. Per esempio, in un progetto complesso si possono scrivere file separati per ogni parte strumentale e creare un file per l’“intera partitura” che raccoglie i file dei singoli strumenti. Di norma il file incluso definisce una serie di variabili che poi diventano disponibili nel file della partitura completa. Le sezioni contrassegnate con delle etichette nei file inclusi possono essere usate in varie parti di una partitura, vedi Edizioni diverse da un unico sorgente.

I file nella directory di lavoro corrente possono essere citati indicando semplicemente il nome del file dopo il comando \include. I file in altre posizioni possono essere inclusi sia con un percorso assoluto che con un percorso relativo (ma come separatore delle directory occorre usare la barra, o slash, come in UNIX, piuttosto che la barra inversa, o backslash, come in DOS/Windows). Per esempio, se cose.ly si trova una directory prima della directory di lavoro corrente, usare

\include "../cose.ly"

oppure se le parti orchestrali incluse si trovano tutte in una sottodirectory chiamata parti all’interno della directory corrente, usare

\include "parti/VI.ly"
\include "parti/VII.ly"
… etc

I file che devono essere inclusi possono contenere essi stessi delle dichiarazioni \include. Per impostazione predefinita, queste dichiarazioni \include di secondo livello non sono interpretate finché non vengono portate nel file principale, dunque i nomi dei file che specificano devono essere tutti relativi alla directory del file principale, non alla directory del file incluso. Tuttavia tale comportamento può essere cambiato globalmente tramite l’opzione -drelative-includes da linea di comando (oppure agggiungendo #(ly:set-option 'relative-includes #t) in cima al file di input principale).

Quando relative-includes viene impostato su #t, il percorso di ogni comando \include sarà considerato relativo al file che contiene quel comando. Questo comportamento è raccomandato e diventerà il comportamento predefinito in una versione futura di lilypond.

È possibile includere sia file relativi alla directory principale sia file relativi a qualche altra directory impostando relative-includes su #t o #f nei punti giusti dei file. Per esempio, se è stata creata una libreria generale, libA, che usa altri file inclusi dal file di base di quella libreria, tali dichiarazioni \include dovranno essere precedute da #(ly:set-option 'relative-includes #t) per poter essere interpretate correttamente quando riportate nel file .ly principale:

libA/
  libA.ly
  A1.ly
  A2.ly
  …

quindi il file di base, libA.ly, conterrà

#(ly:set-option 'relative-includes #t)
\include "A1.ly"
\include "A2.ly"
…
% ritorna alle impostazioni predefinite
#(ly:set-option 'relative-includes #f)

Qualsiasi file .ly può quindi includere l’intera libreria semplicemente con

\include "~/libA/libA.ly"

Si possono ideare strutture di file più complesse facendo dei cambi nei punti giusti.

È possibile includere dei file anche da una directory che si trova in un percorso di ricerca specificato come opzione quando si lancia LilyPond da linea di comando. I file inclusi possono allora essere specificati usando soltanto il loro nome. Per esempio, per compilare con questo metodo il file principale.ly che include i file di una sottodirectory chiamata parti, entrare nella directory di principale.ly e eseguire questo comando

lilypond --include=parti principale.ly

e in principale.ly scrivere

\include "VI.ly"
\include "VII.ly"
… etc

I file che devono essere inclusi in molte partiture possono essere salvati nella directory di installazione di LilyPond ../ly. La posizione di questa directory dipende dal tipo di installazione (vedi Altre fonti di informazione). Questi file possono quindi essere inclusi semplicemente nominandoli in una dichiarazione \include. Questo è il modo in cui sono inclusi i file che dipendono dalla lingua, come english.ly.

LilyPond include un certo numero di file quando si lancia il programma. Queste inclusioni non sono evidenti all’utente, ma i file possono essere identificati eseguendo lilypond --verbose dalla linea di comando. Così si vedrà un elenco di percorsi e file che LilyPond usa, insieme a tante altre informazioni. I più importanti di questi file sono trattati in Altre fonti di informazione. Tali file possono essere modificati, ma le modifiche saranno perse quando si installa una nuova versione di LilyPond.

Alcuni semplici esempi d’uso di \include si trovano in Partiture e parti.

Vedi anche

Manuale di apprendimento: Altre fonti di informazione, Partiture e parti.

Problemi noti e avvertimenti

Se a un file incluso viene assegnato un nome identico a uno dei file di installazione di LilyPond, quest’ultimo ha la precedenza.