LilyPond: manuale d'uso del programma: 3.4 Utilizzo di lilypond-book

## 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 raccomandato1, 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 `makeinfo`, 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 `makeinfo` 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`, `WARNING`, `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 `makeinfo`.

  >     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`, `WARNING`, `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.

### Note a piè di pagina

[1] Nota che PDFLaTeX e LaTeX potrebbero non essere entrambi utilizzabili per compilare un qualsiasi documento LaTeX: ecco perché vengono illustrati i due modi.

#### LilyPond — Utilizzo v2.24.4 (ramo stabile).