3.4 Utilizzo di lilypond-book

lilypond-book crea un file con una delle seguenti estensioni: .tex, .texi, .html o .xml, a seconda del formato dell’output. Tutti i file .tex, .texi e .xml necessitano di un’ulteriore elaborazione.

Istruzioni specifiche di ogni formato

LaTeX

Esistono due modi di elaborare il documento LaTeX per la stampa o la pubblicazione: generare direttamente un file PDF tramite PDFLaTeX oppure generare un file PostScript tramite LaTeX, attraverso un traduttore da DVI a PostScript come dvips. Il primo modo è più semplice e raccomandato⁴, e indipendentemente da quello che userai, puoi convertire facilmente PostScript e PDF con strumenti come ps2pdf e pdf2ps inclusi nel pacchetto Ghostscript.

Per creare un file PDF con PDFLaTeX, si usa:

lilypond-book --pdf tuofile.lytex
pdflatex tuofile.tex

Per produrre l’output PDF attraverso LaTeX/dvips/ps2pdf:

lilypond-book tuofile.lytex
latex tuofile.tex
dvips -Ppdf tuofile.dvi
ps2pdf tuofile.ps

Il file .dvi creato da questa sequenza non conterrà le teste delle note. È normale; se si seguono le istruzioni, le teste verranno incluse nei file .ps e .pdf.

L’esecuzione di dvips potrebbe generare dei messaggi di avviso relativi ai caratteri; questi messaggi sono innocui e possono essere ignorati. Se esegui latex in modalità due colonne, ricorda di aggiungere -t landscape alle opzioni di dvips.

Gli ambienti come:

\begin{lilypond} … \end{lilypond}

non sono interpretati da LaTeX. lilypond-book estrae questi ‘ambienti’ e li copia in file in un suo formato per poter eseguire LilyPond su di essi. Prende quindi gli elementi grafici risultanti e crea un file .tex dove le macro \begin{lilypond}…\end{lilypond} sono poi sostituite da comandi di ‘inclusione di immagini’. È a questo punto che LaTeX viene eseguito (anche se LaTeX è stato eseguito in precedenza, in realtà ha agito su un documento ‘vuoto’ solo per fare alcuni calcoli, come per esempio di \linewidth).

Problemi noti e avvertimenti

Il comando \pageBreak non funziona all’interno dell’ambiente \begin{lilypond} … \end{lilypond}.

Molte variabili del blocco \paper non funzionano all’interno dell’ambiente \begin{lilypond} … \end{lilypond}. Usa \newcommand con \betweenLilyPondSystem nel preambolo;

\newcommand{\betweenLilyPondSystem}[1]{\vspace{36mm}\linebreak}

Texinfo

Per generare un documento Texinfo (in qualsiasi formato di output), si seguono le normali procedure usate con Texinfo; ovvero, si lancia texi2pdf o texi2dvi o texi2any, a seconda del formato di output che si vuole creare. Per impostazione predefinita, texi2pdf usa pdftex per l’elaborazione, come si può verificare nella console di output. In questo caso, eseguire lilypond-book con l’opzione --pdf per creare frammenti .pdf invece di file .eps. Altrimenti pdftex, non essendo capace di includere i file in formato EPS, emetterà un messaggio di errore.

Si veda la documentazione di Texinfo per ulteriori dettagli.

Opzioni da linea di comando

lilypond-book accetta le seguenti opzioni da linea di comando.

-f formato

--format=formato

Specifica il tipo di documento da elaborare: html, latex, texi (il formato predefinito), texi-html o docbook. Se manca questa opzione, lilypond-book cerca di rilevare il formato automaticamente, si veda Estensioni dei nomi di file. Attualmente, texi-html è equivalente a texi.

-F filtro

--filter=filtro

Convoglia i frammenti attraverso il filtro. lilypond-book non esegue contemporaneamente il filtro e l’elaborazione. Ad esempio,

lilypond-book --filter='convert-ly --from=2.0.0 -' mio-libro.tely

lilypond-book non accetta le opzioni --filter e --process in contemporanea.

-h

--help

Mostra un breve messaggio di aiuto.

-I dir

--include=dir

Aggiunge dir al percorso di inclusione. Dato che lilypond-book cerca anche dei frammenti già compilati nel percorso di inclusione e non li riscrive nella directory di output, in alcuni casi è necessario eseguire ulteriori comandi come texi2any o latex con le stesse opzioni -I dir.

-l loglevel

--loglevel=loglevel

Imposta la verbosità dell’output su loglevel. I valori possibili sono NONE, ERROR, WARN, PROGRESS (predefinito) e DEBUG. Se questa opzione non viene usata e la variabile d’ambiente LILYPOND_BOOK_LOGLEVEL è impostata, il suo valore viene usato come livello di log.

-o dir

--output=dir

Salva i file generati nella directory dir. L’esecuzione di lilypond-book genera tanti piccoli file che LilyPond elaborerà. Per evitare tutto questo disordine nella directory dei sorgenti, si usa l’opzione da linea di comando --output e si entra in questa directory prima di eseguire latex o texi2any.

lilypond-book --output=out tuofile.lytex
cd out
…

--skip-lily-check

Non si arresta se non viene trovato l’output di LilyPond. Viene usata per generare la documentazione Info di LilyPond, che è priva di immagini.

--skip-png-check

Non si arresta se non vengono trovate immagini PNG per i file EPS. Viene usata per generare la documentazione Info di LilyPond, che è priva di immagini.

--lily-output-dir=dir

Scrive i file lily-XXX nella directory dir e crea un link nella directory --output. Si usa questa opzione per risparmiare tempo nella compilazione di documenti situati in directory diverse che condividono molti identici frammenti.

--lily-loglevel=loglevel

Imposta la verbosità dell’output del comando lilypond su loglevel. I valori possibili sono NONE, ERROR, WARN, BASIC, PROGRESS, INFO (predefinito) e DEBUG. Se questa opzione non viene usata e la variabile d’ambiente LILYPOND_LOGLEVEL è impostata, il suo valore viene usato come livello di log.

--info-images-dir=dir

Formatta l’output di Texinfo in modo che Info cerchi le immagini della musica nella directory dir.

--latex-program=prog

Lancia l’eseguibile prog invece di latex. Questa opzione è utile, ad esempio, se il documento è elaborato con xelatex.

--left-padding=quantità

Crea una spaziatura a sinistra tra i frammenti LilyPond utilizzando gli spazi bianchi.

quantità è arrotondata per eccesso in modo da essere un numero intero multiplo di un big point (bp). Un bp è 1/72 di un pollice (circa 0.353mm). quantità è assegnato in millimetri rispetto all’inizio del rigo. Il valore predefinito è 3.175mm (che equivale a 9bp).

La larghezza di sistemi molto densi può variare in base agli elementi della notazione come i numeri di battuta e i nomi degli strumenti che sono posti a sinistra dell’inizio del rigo. La spaziatura imposta la distanza minima tra il margine sinistro delle immagini dei frammenti e l’inizio dei righi (non indentati); ciò consente l’allineamento verticale desiderato dei frammenti nel documento principale.

Oltre a aggiungere la spaziatura a sinistra, questa opzione accorcia ciascun rigo di quantità. Di conseguenza, ciascuna linea viene spostata visivamente a destra.

-P comando

--process=comando

Elabora i frammenti di LilyPond con comando. Il comando predefinito è lilypond. lilypond-book non accetta le opzioni --filter e --process contemporaneamente.

--pdf

Crea i file PDF dei frammenti. Se non è impostato, vengono generati solo i file PNG e EPS. Utilizzare questa opzione se si vuole incorporare direttamente i file PDF nei file LaTeX o Texinfo.

--redirect-lilypond-output

Per impostazione predefinita, l’output dei log viene mostrato sul terminale. Questa opzione redirige tutto l’output in dei file di log nella stessa directory dei file sorgente.

--use-source-file-names

Salva i file di output dei frammenti con lo stesso nome, esclusa l’estensione, dei sorgenti. Questa opzione funziona solo con i frammenti inclusi col comando lilypondfile e solo se le directory indicate da --output-dir e --lily-output-dir sono diverse.

-V

--verbose

Mostra un output dettagliato. Questo è equivalente a --loglevel=DEBUG.

-v

--version

Mostra informazioni sulla versione.

Problemi noti e avvertimenti

Il comando Texinfo @pagesizes non viene interpretato. Allo stesso modo, i comandi LaTeX che modificano i margini e la larghezza della linea dopo il preambolo vengono ignorati.

Solo il primo \score di un blocco LilyPond viene elaborato.