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

@ignore
    Translation of GIT committish: d272756a48b2090def953e747107de155ea603b9

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

@c Note: keep this node named so that `info lilypond-book' brings you here.
@node lilypond-book
@chapter Eseguire @command{lilypond-book}

Se si desidera aggiungere a un documento illustrazioni musicali, si può
semplicemente fare nello stesso modo in cui si farebbe con altri tipi di
immagini: prima si creano le immagini separatamente, in formato PostScript o
PNG, poi le si includono in un documento @LaTeX{} o HTML.

@command{lilypond-book} offre la possibilità di automatizzare tale procedimento: questo
programma estrae i frammenti musicali dal documento, esegue @command{lilypond}
su di essi e crea un nuovo documento contenente le illustrazioni musicali così
ottenute.  Le definizioni relative alla larghezza del rigo e alle dimensioni
dei caratteri vengono regolate per adeguarsi alla formattazione del documento.

Si tratta di un programma separato da @command{lilypond} e viene lanciato
dalla linea di comando; per maggiori informazioni, si veda
@ref{Uso da linea di comando}.  In caso di problemi nell'eseguire
@code{lilypond-book} da linea di comando su Windows o Mac OS X, si veda
@rweb{Windows} o @rweb{MacOS X}.

Questo procedimento può essere applicato ai documenti @LaTeX{}, HTML, Texinfo
o DocBook.

@cindex texinfo
@cindex LaTeX
@cindex texinfo
@cindex texi
@cindex HTML
@cindex docbook
@cindex documenti, aggiungere musica
@cindex HTML, aggiungere musica
@cindex Texinfo, aggiungere musica
@cindex DocBook, aggiungere musica
@cindex LaTeX, aggiungere musica

@menu
* Un esempio di documento musicologico::
* Integrare musica e testo::
* Opzioni dei frammenti musicali::
* Utilizzo di lilypond-book::
* Estensioni dei nomi di file::
* Modelli per lilypond-book::
* Condividere l'indice::
* Metodi alternativi per combinare testo e musica::
@end menu


@node Un esempio di documento musicologico
@section Un esempio di documento musicologico
@translationof An example of a musicological document

@cindex musicologia
Alcuni testi contengono degli esempi musicali: si tratta di
trattati musicologici, canzonieri o manuali come questo.  È possibile
crearli a mano, semplicemente importando un'immagine PostScript
nell'elaboratore di testo.  Tuttavia esiste una procedura automatizzata
che permette di ridurre il carico di lavoro richiesto dai documenti in
formato HTML, @LaTeX{}, Texinfo e DocBook.

Uno script chiamato @code{lilypond-book} estrarrà i frammenti musicali, li
formatterà e restituirà la notazione risultante.  Ecco un piccolo esempio
da usare con @LaTeX{}.  L'esempio contiene anche del testo esplicativo,
dunque non è necessario entrare nei dettagli.

@subheading Input

@quotation
@verbatim
\documentclass[a4paper]{article}

\begin{document}

I documenti per \verb+lilypond-book+ possono combinare liberamente musica e testo.
Ad esempio,

\begin{lilypond}
\relative {
  c'2 e2 \tuplet 3/2 { f8 a b } a2 e4
}
\end{lilypond}

Le opzioni vengono specificate tra parentesi quadre.

\begin{lilypond}[fragment,quote,staffsize=26,verbatim]
  c'4 f16
\end{lilypond}

Se l'esempio è più grande, è possibile metterlo in un file separato e inserirlo
con \verb+\lilypondfile+.

\lilypondfile[quote,noindent]{screech-and-boink.ly}

(Se vuoi provare, sostituisci @file{screech-and-boink.ly} con qualsiasi file @file{.ly}
che si trovi nella stessa directory di questo file.)

\end{document}
@end verbatim
@end quotation

@subheading Elaborazione

Salva il codice precedente in un file chiamato @file{lilybook.lytex}, quindi
esegui in un terminale

@c keep space after @version{} so TeX doesn't choke
@example
lilypond-book --output=out --pdf lilybook.lytex
@emph{lilypond-book (GNU LilyPond) @version{} }
@emph{Lettura di lilybook.lytex...}
@emph{@dots{}tagliato molto output@dots{}}
@emph{Compilazione di lilybook.tex...}
cd out
pdflatex lilybook.tex
@emph{@dots{}tagliato molto output@dots{}}
xpdf lilybook.pdf
@emph{(sostituisci @command{xpdf} col tuo lettore PDF preferito)}
@end example

L'esecuzione di @command{lilypond-book} e @command{pdflatex} crea molti file
temporanei e questo potrebbe rendere disordinata la directory di lavoro.  Per
ovviare a questo inconveniente, è consigliabile usare l'opzione @code{--output=@var{dir}}.  In questo
modo i file verranno salvati in una sottodirectory @file{dir} separata.

Infine ecco il risultato dell'esempio in @LaTeX{}.@footnote{Questo
tutorial è elaborato da Texinfo, dunque l'esempio produce dei risultati
leggermente diversi nella formattazione.}  Si conclude qui la parte di
tutorial.

@page

@subheading Output

I documenti per @command{lilypond-book} possono combinare liberamente musica
e testo.  Usando la sintassi di Texinfo, questo esempio

@example
@@lilypond
\relative @{
  c'2 e2 \tuplet 3/2 @{ f8 a b @} a2 e4
@}
@@end lilypond
@end example

@noindent
produce

@lilypond
\relative {
  c'2 e2 \tuplet 3/2 { f8 a b } a2 e4
}
@end lilypond

Si possono aggiungere delle opzioni per modificare l'aspetto dei frammenti.
Usando la sintassi di @LaTeX{}, questo esempio

@example
\begin@{lilypond@}[fragment, quote, staffsize=26]
c'4 f16
\end@{lilypond@}
@end example

@noindent
produce

@lilypond[fragment,quote,staffsize=26]
c'4 f16
@end lilypond

Frammenti musicali più grandi possono essere messi in file indipendenti.
Usando la sintassi HTML, questo esempio

@example
<lilypondfile quote noindent>
  snippets/screech-and-boink.ly
</lilypondfile>
@end example

@noindent
produce

@lilypondfile[quote,noindent]{snippets/screech-and-boink.ly}

Perché sia visibile la @code{tagline}, predefinita o personalizzata, l'intero
frammento deve essere compreso in un costrutto @code{\book @{ @}}.

@lilypond[papersize=a7,verbatim]
\book{
  \header{ title = "Una scala in LilyPond" }

  \relative { c' d e f g a b c }
}
@end lilypond

@page

@node Integrare musica e testo
@section Integrare musica e testo
@translationof Integrating music and text

Questa sezione spiega in dettaglio come integrare LilyPond in vari
formati di output.

@menu
* LaTeX::
* Texinfo::
* HTML::
* DocBook::
@end menu

@node LaTeX
@subsection @LaTeX{}

@LaTeX{} costituisce lo standard de facto per le pubblicazioni nell'ambito
delle scienze esatte.  Si basa sul motore tipografico @TeX{}, che produce la
migliore qualità tipografica possibile.

Si veda
@uref{https://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
@emph{The Not So Short Introduction to @LaTeX{}}} per una panoramica
sull'uso di @LaTeX{}.

@code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
la musica nei file @LaTeX{}:

@itemize

@item
il comando @code{\lilypond@{@dots{}@}}, per inserire direttamente un
breve codice LilyPond,

@item
l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, per inserire
direttamente codice LilyPond più lungo,

@item
il comando @code{\lilypondfile@{@dots{}@}} per inserire un file LilyPond,

@item
il comando @code{\musicxmlfile@{@dots{}@}} per inserire un file MusicXML, che
viene elaborato da @code{musicxml2ly} e da @code{lilypond}.

@end itemize

Nel file di input, la musica viene specificata con uno dei seguenti comandi:

@example
\begin@{lilypond@}[@var{le},@var{opzioni},@var{vanno},@var{qui}]
  CODICE LILYPOND
\end@{lilypond@}

\begin[@var{le},@var{opzioni},@var{vanno},@var{qui}]@{lilypond@}
  CODICE LILYPOND
\end@{lilypond@}

\lilypondfile[@var{le},@var{opzioni},@var{vanno},@var{qui}]@{@var{nomefile}@}

\musicxmlfile[@var{le},@var{opzioni},@var{vanno},@var{qui}]@{@var{nomefile}@}
@end example

@noindent

Inoltre, @code{\lilypondversion} mostra la versione
di LilyPond impiegata.
L'esecuzione di @command{lilypond-book} produce un file che può essere
ulteriormente elaborato con @LaTeX{}.

Vediamo alcuni esempi.  L'ambiente @code{lilypond}

@example
\begin@{lilypond@}[quote,fragment,staffsize=26]
  c' d' e' f' g'2 g'2
\end@{lilypond@}
@end example

@noindent
genera

@lilypond[quote,fragment,staffsize=26]
c'4 d' e' f' g'2 g'
@end lilypond

La versione breve

@example
\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
@end example

@noindent
genera

@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}

La larghezza predefinita del rigo musicale è calcolata in base ai
comandi presenti nel preambolo del documento, ovvero la parte del documento
che precede @code{\begin@{document@}}.  Il comando @command{lilypond-book}
li invia a @LaTeX{} per definire la larghezza del testo.  La larghezza del
rigo nei frammenti musicali è quindi regolato in base alla larghezza del
testo.  Si noti che questo algoritmo euristico può fallire facilmente; in
questi casi occorre usare l'opzione @code{line-width} nel frammento musicale.

@cindex titoli e lilypond-book
@cindex \header nei documenti @LaTeX{}

Ogni frammento richiama le seguenti macro se sono state definite
dall'utente:

@itemize @bullet
@item @code{\preLilyPondExample} viene richiamata prima della musica,

@item @code{\postLilyPondExample} viene richiamata dopo la musica,

@item @code{\betweenLilyPondSystem[1]} viene richiamata tra i sistemi, se
@code{lilypond-book} divide il frammento in più pezzi.
Deve essere definita in modo da accettare un parametro, che è il numero
dei file già inclusi in questo frammento.
Per impostazione predefinita inserisce semplicemente @code{\linebreak}.
@end itemize

@ignore
Broken stuff.  :(

@cindex Latex, feta symbols
@cindex fetachar

To include feta symbols (such as flat, segno, etc) in a LaTeX
document, use @code{\input@{titledefs@}}

@example
\documentclass[a4paper]@{article@}

\input@{titledefs@}

\begin@{document@}

\fetachar\fetasharp

\end@{document@}
@end example

The font symbol names are defined in the file feta20.tex; to find
the location of this file, use the command

@example
kpsewhich feta20.tex
@end example

@end ignore

@snippets

Talvolta si ha necessità di mostrare degli elementi musicali (ad esempio le
legature di portamento e di valore) che proseguono dopo la fine del
frammento.  È possibile inserirli mandando il rigo a capo e
impedendo l'inclusione del restante output di LilyPond.

In @LaTeX{}, si definisce @code{\betweenLilyPondSystem} in modo tale che
l'inclusione di altri sistemi venga terminata una volta incluso il
numero di sistemi richiesti.  Dato che @code{\betweenLilyPondSystem} viene
chiamato la prima volta @emph{dopo} il primo sistema, includere solo il primo
sistema è semplice.

@example
\def\betweenLilyPondSystem#1@{\endinput@}

\begin@{lilypond@}[fragment]
  c'1\( e'( c'~ \break c' d) e f\)
\end@{lilypond@}
@end example

Se serve una maggior quantità di sistemi, occorre usare un condizionale
@TeX{} prima di @code{\endinput}.  In questo esempio, sostituisci il
valore@tie{}2 col numero di sistemi che desideri avere nell'output.

@example
\def\betweenLilyPondSystem#1@{
    \ifnum#1<2\else\expandafter\endinput\fi
@}
@end example

@noindent
(Dato che @code{\endinput} arresta immediatamente l'elaborazione del file di
input corrente, occorre usare @code{\expandafter} per ritardare la chiamata di
@code{\endinput} e far sì che avvenga dopo l'esecuzione di @code{\fi}, in modo
da bilanciare la condizione @code{\if...}-@code{\fi}.)

Ricorda che la definizione di @code{\betweenLilyPondSystem} è
efficace finché il gruppo corrente è terminato (ad esempio, l'ambiente
@LaTeX{}) o è sovrascritto da un'altra definizione (che vale, in
gran parte dei casi, per il resto del documento).  Per reimpostare
la definizione, si scrive

@example
\let\betweenLilyPondSystem\undefined
@end example

@noindent
nel sorgente @LaTeX{}.

Si potrebbe semplificare la procedura creando una macro @TeX{}

@example
\def\onlyFirstNSystems#1@{
    \def\betweenLilyPondSystem##1@{%
      \ifnum##1<#1\else\expandafter\endinput\fi@}
@}
@end example

@noindent
e poi specificando prima di ogni frammento la quantità di sistemi desiderata,

@example
\onlyFirstNSystems@{3@}
\begin@{lilypond@}@dots{}\end@{lilypond@}
\onlyFirstNSystems@{1@}
\begin@{lilypond@}@dots{}\end@{lilypond@}
@end example


@morerefs
Esistono opzioni specifiche da linea di comando per @command{lilypond-book} e
altri dettagli da conoscere quando si elaborano documenti @LaTeX{}; si veda
@ref{Utilizzo di lilypond-book}.
@endmorerefs


@node Texinfo
@subsection Texinfo
@translationof Texinfo

Texinfo è il formato standard per la documentazione del progetto GNU.  Un
esempio di documento Texinfo è questo stesso manuale.  Le versioni del manuale
in formato HTML, PDF e Info vengono generate da un documento Texinfo.

@code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
musica nei file Texinfo:

@itemize

@item
il comando @code{\lilypond@{@dots{}@}}, per inserire direttamente del
codice LilyPond breve,

@item
l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, per inserire
direttamente del codice LilyPond più lungo,

@item
il comando @code{\lilypondfile@{@dots{}@}} per inserire un file LilyPond,

@item
il comando @code{\musicxmlfile@{@dots{}@}} per inserire un file MusicXML, che
viene elaborato da @code{musicxml2ly} e da @code{lilypond}.

@end itemize

Nel file di input, la musica viene specificata con uno dei seguenti comandi

@example
@@lilypond[@var{le},@var{opzioni},@var{vanno},@var{qui}]
  IL TUO CODICE LILYPOND
@@end lilypond

@@lilypond[@var{le},@var{opzioni},@var{vanno},@var{qui}]@{ IL TUO CODICE LILYPOND @}

@@lilypondfile[@var{le},@var{opzioni},@var{vanno},@var{qui}]@{@var{nomefile}@}

@@musicxmlfile[@var{le},@var{opzioni},@var{vanno},@var{qui}]@{@var{nomefile}@}
@end example

@noindent
Inoltre, @code{@@lilypondversion} mostra la versione di
LilyPond impiegata.

Quando si esegue @command{lilypond-book} su di esso, il risultato è un
file Texinfo (con estensione @file{.texi}) contenente degli elementi @code{@@image}
per l'HTML, Info e l'output per la stampa.  @command{lilypond-book} genera le
immagini della musica in formati EPS e PDF per l'utilizzo nell'output per la
stampa e in formato PNG per l'utilizzo nell'output HTML e Info.

Vediamo alcuni esempi.  L'ambiente @code{lilypond}

@example
@@lilypond[quote,fragment]
c'4 d' e' f' g'2 g'
@@end lilypond
@end example

@noindent
genera

@lilypond[quote,fragment]
c'4 d' e' f' g'2 g'
@end lilypond

La versione breve

@example
@@lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
@end example

@noindent
genera

@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}

@morerefs
Esistono opzioni da linea di comando specifiche di @command{lilypond-book} e
altri dettagli da conoscere quando si elaborano documenti Texinfo, vedi
@ref{Utilizzo di lilypond-book}.
@endmorerefs


@node HTML
@subsection HTML
@translationof HTML

@code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
musica nei file HTML:

@itemize

@item
il comando @code{\lilypond@{@dots{}@}}, per inserire direttamente del
codice LilyPond breve,

@item
l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, per inserire
direttamente del codice LilyPond più lungo,

@item
il comando @code{\lilypondfile@{@dots{}@}} per inserire un file LilyPond,

@item
il comando @code{\musicxmlfile@{@dots{}@}} per inserire un file MusicXML, che
viene elaborato da @code{musicxml2ly} e da @code{lilypond}.

@end itemize

Nel file di input, la musica viene specificata con uno dei seguenti comandi:

@example
<lilypond @var{le} @var{opzioni} @var{vanno} @var{qui}>
  CODICE LILYPOND
</lilypond>

<lilypond @var{le} @var{opzioni} @var{vanno} @var{qui}: CODICE LILYPOND />

<lilypondfile @var{le} @var{opzioni} @var{vanno} @var{qui}>@var{nomefile}</lilypondfile>

<musicxmlfile @var{le} @var{opzioni} @var{vanno} @var{qui}>@var{nomefile}</musicxmlfile>
@end example

@noindent
Inoltre, @code{<lilypondversion/>} mostra la versione corrente di LilyPond.

Mostriamo alcuni esempi. L'ambiente @code{lilypond}

@example
<lilypond quote fragment staffsize=26>
  c'4 d' e' f' g'2 g'
</lilypond>
@end example

@noindent
genera

@lilypond[quote,fragment,staffsize=26]
  c'4 d' e' f' g'2 g'
@end lilypond

La versione breve

@example
<lilypond quote fragment staffsize=11: <c' e' g'> />
@end example

@noindent
genera

@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}

@morerefs
Esistono opzioni da linea di comando specifici di @command{lilypond-book} e
altri dettagli da conoscere quando si elaborano documenti HTML, vedi
@ref{Utilizzo di lilypond-book}.
@endmorerefs

@cindex titoli in HTML
@cindex immagine di anteprima
@cindex miniatura


@node DocBook
@subsection DocBook
@translationof DocBook

Per inserire frammenti di codice LilyPond è una buona idea mantenere la
conformità dei documenti DocBook, in modo da poter usare gli editor DocBook, la
validazione, etc.  Per questo motivo non vengono forniti elementi personalizzati,
ma soltanto delle convenzioni di specifica basate sugli elementi DocBook standard.

@subheading Convenzioni comuni

Per inserire un frammento di qualsiasi tipo si usano gli elementi @code{mediaobject}
e @code{inlinemediaobject}, in modo che il frammento possa essere formattato
in linea o meno.  Le opzioni di formattazione del frammento vengono sempre
indicate nella proprietà @code{role} dell'elemento più interno (si vedano
le prossime sezioni).  Gli elementi sono scelti in modo da permettere agli editor
DocBook di ottenere una formattazione ottimale.  I file DocBook da
elaborare con @command{lilypond-book} devono avere estensione @file{.lyxml}.

@subheading Includere un file LilyPond

Si tratta del caso più semplice.  Bisogna usare l'estensione @file{.ly} per
il file da includere e inserirlo come uno standard @code{imageobject}, con
la seguente struttura:

@example
<mediaobject>
  <imageobject>
    <imagedata fileref="music1.ly" role="printfilename" />
  </imageobject>
</mediaobject>
@end example

Nota che sei libero di usare @code{mediaobject} o @code{inlinemediaobject}
come elemento più esterno.

@subheading Includere codice LilyPond

È possibile includere codice LilyPond all'interno di un elemento
@code{programlisting} in cui il linguaggio sia impostato su @code{lilypond},
con la seguente struttura:

@example
<inlinemediaobject>
  <textobject>
    <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
\context Staff \with @{
  \remove Time_signature_engraver
  \remove Clef_engraver@}
  @{ c4( fis) @}
    </programlisting>
  </textobject>
</inlinemediaobject>
@end example

Come si vede, l'elemento più esterno è @code{mediaobject} o
@code{inlinemediaobject} e c'è un @code{textobject} che contiene al
suo interno il @code{programlisting}.

@subheading Elaborare il documento DocBook

L'esecuzione di @command{lilypond-book} su un file @file{.lyxml} crea un
documento DocBook valido (con estensione @file{.xml}) che potrà essere
ulteriormente elaborato.  Usando
@uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, crea automaticamente
un file PDF da questo documento.  Per generare l'HTML (HTML Help,
JavaHelp etc.) si possono usare i fogli di stile DocBook XSL ufficiali;
tuttavia è possibile che sia necessario modificarli un po'.


@node Opzioni dei frammenti musicali
@section Opzioni dei frammenti musicali
@translationof Music fragment options

Nelle pagine che seguono, per @q{comando LilyPond} si intende un qualsiasi
comando descritto nelle sezioni precedenti che sia gestito da @command{lilypond-book}
per produrre un frammento musicale.  Per semplicità, i comandi LilyPond vengono
mostrati soltanto nella sintassi @LaTeX{}.

Nota che la stringa delle opzioni è analizzata da sinistra a destra; se un'opzione
ricorre più di una volta, viene applicata nella sua ultima occorrenza.

Sono disponibili le seguenti opzioni per i comandi LilyPond:

@table @code
@item staffsize=@var{altezza}
Imposta la dimensione del pentagramma a @var{altezza}, misurata in punti.

@item ragged-right
Produce linee con margine destro irregolare e spaziatura naturale, ovvero
viene aggiunto @code{ragged-right = ##t} al frammento LilyPond.  Frammenti
con un solo rigo avranno sempre il margine destro irregolare, a meno che
non venga specificato esplicitamente @code{noragged-right}.

@item noragged-right
Per i frammenti di una sola linea, fa sì che la lunghezza del rigo venga estesa
fino a coincidere con la larghezza della linea, ovvero viene aggiunto
@code{ragged-right = ##f} al frammento LilyPond.

@item line-width
@itemx line-width=@var{dimensione}\@var{unità}
Imposta la lunghezza della linea a @var{dimensione} (espressa in @var{unità}).
@var{unità} può essere una delle seguenti: @code{cm}, @code{mm}, @code{in} o
@code{pt}.  Questa opzione riguarda l'output LilyPond (ovvero, la lunghezza
del rigo del frammento musicale), non la formattazione del testo.

Se usato senza un argomento, imposta la lunghezza della linea a un valore
predefinito (calcolato da un algoritmo euristico).

Se non viene assegnata un'opzione @code{line-width}, @command{lilypond-book}
cerca di indovinare un valore predefinito per gli ambienti @code{lilypond} che
non usano l'opzione @code{ragged-right}.

@item papersize=@var{stringa}
Imposta la dimensione del foglio su @var{stringa} (ad esempio, @code{a5} o
@code{letter}) per i frammenti musicali che usano @code{\book}. Vedi
@ruser{Formati carta predefiniti} per un elenco delle dimensioni
del foglio disponibili.

Questa opzione riguarda l'output LilyPond (ovvero, la dimensione del foglio
del frammento musicale), non la formattazione del testo.  Valori sconosciuti
di @var{stringa} vengono ignorati: viene emesso un avviso e il frammento
viene elaborato usando la dimensione predefinita @code{a4}.

@item paper-width=@var{dimensione}\@var{unità}
Imposta la larghezza del foglio su @var{dimensione} (espressa in @var{unità})
per i frammenti musicali che usano @code{\book}.  @var{unità} è uno dei
seguenti: @code{cm}, @code{mm}, @code{in} o @code{pt}.

Questa opzione riguarda l'output LilyPond (ovvero, la larghezza del foglio
del frammento musicale), non la formattazione del testo.  Se impostata, sovrascrive
l'opzione @option{papersize} se presente.  Se l'opzione @option{paper-height}
non è specificata, l'altezza del foglio è impostata sull'altezza del foglio
A4 predefinito (296@dmn{mm}).

@item paper-height=@var{dimensione}\@var{unità}
Imposta l'altezza del foglio su @var{dimensione} (espressa in @var{unit}) per
i frammenti musicali che usano @code{\book}.  @var{unità} è uno dei seguenti:
@code{cm}, @code{mm}, @code{in} o @code{pt}.

Questa opzione riguarda l'output LilyPond (ovvero, l'altezza del foglio
del frammento musicale), non la formattazione del testo.  Se impostata, sovrascrive
l'opzione @option{papersize} se presente.  Se l'opzione @option{paper-width}
non è specificata, la larghezza del foglio è impostata sulla larghezza del foglio
A4 predefinito (210@dmn{mm}).

Example:
@example
\lilypond[paper-width=10\cm, paper-height=57\mm]@{
  \book @{
    ...
  @}
@}
@end example

@item notime
Non viene visualizzata l'indicazione di tempo e disabilita i segni relativi
alla scansione ritmica (segno di tempo, barre di divisione) nella partitura.

@item fragment
Fa sì che @command{lilypond-book} aggiunga del codice boilerplate in modo che
sia possibile inserire semplicemente, ad esempio,

@example
c'4
@end example

@noindent
senza @code{\layout}, @code{\score}, etc.

@item nofragment
Non aggiunge del codice ulteriore per completare il codice LilyPond nei frammenti
musicali.  Essendo l'impostazione predefinita, @code{nofragment} di norma
è ridondante.

@item inline
Imposta il frammento per l'uso @qq{in linea}, ovvero all'interno di un paragrafo.
Il frammento viene formattato con un padding sinistro molto piccolo (circa
lo stesso del padding destro), ignorando il valore dato dall'opzione a linea
di comando @option{--left-padding}.

Per l'output Texinfo, sopprime l'inserimento di una riga vuota prima e
dopo il frammento.  Per l'output HTML, sopprime l'inserimento di
@code{<p>} prima e di @code{</p>} dopo il frammento.

Per far sì che un frammento appaia davvero in linea nella modalità @LaTeX{} e
Texinfo, è necessario posizionarlo all'interno di un paragrafo, evitando
una riga vuota prima e dopo il frammento.  Per esempio

@example
Il motivo
\lilypond[inline,staffsize=11]@{
  @{ \time 2/4 r8 g'[ g' g'] | es'2 @}
@}
è ben noto.
@end example

@noindent
diventa

@indentedBlock
Il motivo
@lilypond[inline,staffsize=11]{
  { \time 2/4 r8 g'[ g' g'] | es'2 }
}
è ben noto.
@endIndentedBlock

@item indent=@var{dimensione}\@var{unità}
Imposta l'indentazione del primo sistema musicale a @var{dimensione} (espressa
in @var{unità}).  @var{unità} è una delle seguenti:
@code{cm}, @code{mm}, @code{in} o @code{pt}.  Questa opzione riguarda
LilyPond, non la formattazione del testo.

@item noindent
Imposta l'indentazione del primo sistema musicale su zero.  Questa opzione
interessa LilyPond, non la formattazione del testo.  L'assenza di indentazione è
l'impostazione predefinita, dunque normalmente @code{noindent} è ridondante.

@item quote
Riduce la lunghezza della linea di un frammento musicale di @math{2*0.4}@dmn{in}
e inserisce l'output in un blocco per le citazioni.  Il valore @q{0.4@dmn{in}}
può essere controllato con l'opzione @code{exampleindent}.

@item exampleindent
Imposta la quantità di spazio con cui l'opzione @code{quote} indenta un
frammento musicale.

@item relative
@itemx relative=@var{n}
Usa la modalità di ottava relativa.  Per impostazione predefinita, le altezze delle note
sono riferite al Do@tie{}centrale.  L'argomento opzionale del numero intero
specifica l'ottava della nota iniziale: il valore predefinito @code{1} è il
Do centrale.  L'opzione @code{relative} funziona solo quando è impostata
l'opzione @code{fragment}, quindi @code{fragment} è implicitamente sottinteso
da @code{relative}, a prescindere dalla presenza dell'opzione @code{(no)fragment}
nel sorgente.
@end table

LilyPond usa @command{lilypond-book} anche per produrre la propria
documentazione.  A questo scopo, esistono altre opzioni più complesse
per i frammenti musicali.

@table @code
@item verbatim
L'argomento di un comando LilyPond viene copiato nel file di output e racchiuso
in un blocco di testo, seguito da qualsiasi testo assegnato con l'opzione
@code{intertext} (non ancora implementato); quindi viene mostrata la musica
vera e propria.  Questa opzione non funziona bene con @code{\lilypond@{@}} se
fa parte di un paragrafo.

Se @code{verbatim} viene usato in un comando @code{lilypondfile}, è possibile
includere il testo di una parte soltanto del file sorgente.  Se il file
sorgente ha un commento contenente @samp{begin verbatim} (senza
virgolette), la citazione del sorgente nel blocco testuale inizierà dopo
l'ultima occorrenza di tale commento; in modo analogo, la citazione del testo
sorgente si fermerà proprio prima della prima occorrenza di un commento
contenente @samp{end verbatim}, se presente.  Nel seguente file sorgente di
esempio, la musica viene interpretata in modalità relativa ma il blocco
testuale non mostrerà il blocco @code{relative}, ovvero

@example
\relative @{ % begin verbatim
  c'4 e2 g4
  f2 e % end verbatim
@}
@end example

@noindent
mostrerà il seguente blocco testuale

@example
  c4 e2 g4
  f2 e
@end example

@noindent
Se si desidera tradurre i commenti e i nomi delle variabili nell'output
verbatim ma non nei sorgenti, si può impostare la variabile d'ambiente
@code{LYDOC_LOCALEDIR} sul percorso di una directory; la directory deve
contenere un albero dei cataloghi di messaggio @file{.mo} che hanno
@code{lilypond-doc} come dominio.

@item texidoc
(Solo per l'output Texinfo.)  Se @command{lilypond} viene lanciato con
l'opzione @option{--header=@/texidoc} e il file da elaborare si
chiama @file{foo.ly}, verrà creato un file @file{foo.texidoc} a patto che
ci sia un campo @code{texidoc} nel blocco @code{\header}.  L'opzione @code{texidoc}
fa sì che @command{lilypond-book} includa tali file, aggiungendo il loro
contenuto in forma di blocco di documentazione proprio prima del frammento
di musica (ma fuori dall'ambiente @code{example} generato da un'opzione
@code{quote}).

Se il file @file{foo.ly} contiene

@example
\header @{
  texidoc = "Questo file mostra il funzionamento di una singola nota."
@}
@{ c'4 @}
@end example

@noindent
e il documento Texinfo @file{test.texinfo} contiene

@example
@@lilypondfile[texidoc]@{foo.ly@}
@end example

@noindent
il seguente comando produce il risultato atteso

@example
lilypond-book --pdf --process="lilypond \
  --header=texidoc" test.texinfo
@end example

Per la maggior parte, i documenti di test di LilyPond (nella directory @file{input}
della distribuzione) sono piccoli file @file{.ly} che hanno esattamente questo
aspetto.

Ai fini della localizzazione, se il documento Texinfo document contiene
@code{@@documentlanguage @var{LANG}} e l'header di @file{foo.ly}
contiene un campo @code{texidoc@var{LANG}}, quando si lancia @command{lilypond}
con l'opzione @option{--header=@/texidoc@var{LANG}} verrà incluso
@file{foo.texidoc@var{LANG}} invece di @file{foo.texidoc}.

@item doctitle
(Solo per l'output Texinfo.) Questa opzione funziona in modo simile
all'opzione @code{texidoc}: se @command{lilypond} viene lanciato con
l'opzione @option{--header=@/doctitle} e il file da elaborare si chiama
@file{foo.ly} e contiene un campo @code{doctitle} nel blocco
@code{\header}, viene creato un file @file{foo.doctitle}.  Se si usa
l'opzione @code{doctitle}, i contenuti di @file{foo.doctitle},
che dovrebbero trovarsi su una singola linea di @var{text}, vengono inseriti
nel documento Texinfo come @code{@@lydoctitle @var{text}}.
@code{@@lydoctitle} è una macro definita nel documento Texinfo.
Lo stesso discorso relativo all'elaborazione @code{texidoc} delle lingue
localizzate si applica anche a @code{doctitle}.

@item nogettext
(Solo per l'output Texinfo.) Non tradurre i commenti e i nomi delle
variabili nel blocco testuale del frammento citato.

@item printfilename
Se un file di input di LilyPond viene incluso con @code{\lilypondfile}, il
nome del file viene mostrato immediatamente prima del frammento musicale.  Per l'output
HTML, questo nome è un collegamento.  Viene mostrata solo la base del nome del
file, ovvero viene tolta la parte che costituisce il percorso del file.

@end table


@node Utilizzo di lilypond-book
@section Utilizzo di @command{lilypond-book}
@translationof Invoking lilypond-book

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

@subheading Istruzioni specifiche di ogni formato

@subsubheading @LaTeX{}

Esistono due modi di elaborare il documento @LaTeX{} per la stampa o la
pubblicazione: generare direttamente un file PDF tramite PDF@LaTeX{} oppure
generare un file PostScript tramite @LaTeX{}, attraverso un traduttore da DVI a
PostScript come @command{dvips}.  Il primo modo è più semplice e raccomandato@footnote{Nota
che PDF@LaTeX{} e @LaTeX{} potrebbero non essere entrambi utilizzabili per compilare
un qualsiasi documento @LaTeX{}: ecco perché vengono illustrati i due modi.}, e
indipendentemente da quello che userai, puoi convertire facilmente PostScript e
PDF con strumenti come @command{ps2pdf} e @command{pdf2ps} inclusi nel pacchetto
Ghostscript.

Per creare un file PDF con PDF@LaTeX{}, si usa:

@example
lilypond-book --pdf tuofile.lytex
pdflatex tuofile.tex
@end example

@cindex caratteri vettoriali
@cindex type1, carattere
@cindex dvips
@cindex utilizzo di dvips
Per produrre l'output PDF attraverso @LaTeX{}/@command{dvips}/@command{ps2pdf}:

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

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

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

Gli ambienti come:

@example
\begin@{lilypond@} @dots{} \end@{lilypond@}
@end example

@noindent
non sono interpretati da @LaTeX{}.  @code{lilypond-book} estrae questi
@q{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 @file{.tex} dove le macro
@code{\begin@{lilypond@}}@dots{}@code{\end@{lilypond@}} sono poi
sostituite da comandi di @q{inclusione di immagini}.  È a questo
punto che @LaTeX{} viene eseguito (anche se @LaTeX{} è stato eseguito
in precedenza, in realtà ha agito su un documento @q{vuoto} solo per
fare alcuni calcoli, come per esempio di @code{\linewidth}).

@knownissues
Il comando @code{\pageBreak} non funziona all'interno dell'ambiente
@code{\begin@{lilypond@} @dots{} \end@{lilypond@}}.

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

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


@subsubheading Texinfo

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

@ifinfo
@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, e
@ref{Creating an Info File, , , texinfo, GNU Texinfo}.
@end ifinfo
@ifnotinfo
Si veda la documentazione di Texinfo per ulteriori dettagli.
@end ifnotinfo


@subheading Opzioni da linea di comando

@command{lilypond-book} accetta le seguenti opzioni da linea di comando.

@table @code
@item -f @var{formato}
@itemx --format=@var{formato}
Specifica il tipo di documento da elaborare: @code{html}, @code{latex},
@code{texi} (il formato predefinito), @code{texi-html} o @code{docbook}.
Se manca questa opzione, @command{lilypond-book} cerca di rilevare il
formato automaticamente, si veda @ref{Estensioni dei nomi di file}.
Attualmente, @code{texi-html} è equivalente a @code{texi}.

@c This complicated detail is not implemented, comment it out -jm
@ignore
The @code{texi} document type produces a Texinfo file with music
fragments in the printed output only.  For getting images in the HTML
version, the format @code{texi-html} must be used instead.
@end ignore

@item -F @var{filtro}
@itemx --filter=@var{filtro}
Convoglia i frammenti attraverso il @var{filtro}.  @code{lilypond-book} non
esegue contemporaneamente il filtro e l'elaborazione.  Ad esempio,

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

@code{lilypond-book} non accetta le opzioni @option{--filter} e
@option{--process} in contemporanea.

@item -h
@itemx --help
Mostra un breve messaggio di aiuto.

@item -I @var{dir}
@itemx --include=@var{dir}
Aggiunge @var{dir} al percorso di inclusione.  Dato che @command{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 @command{makeinfo} o @command{latex} con le stesse
opzioni @option{-I @var{dir}}.

@item -l @var{loglevel}
@itemx --loglevel=@var{loglevel}
Imposta la verbosità dell'output su @var{loglevel}. I valori possibili sono @code{NONE},
@code{ERROR}, @code{WARNING}, @code{PROGRESS} (predefinito) e @code{DEBUG}. Se
questa opzione non viene usata e la variabile d'ambiente @code{LILYPOND_BOOK_LOGLEVEL}
è impostata, il suo valore viene usato come livello di log.

@item -o @var{dir}
@itemx --output=@var{dir}
Salva i file generati nella directory @var{dir}.  L'esecuzione di
@command{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 @option{--output}
e si entra in questa directory prima di eseguire @command{latex}
o @command{makeinfo}.

@example
lilypond-book --output=out tuofile.lytex
cd out
@dots{}
@end example

@item --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.

@item --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.

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

@item --lily-loglevel=@var{loglevel}
Imposta la verbosità dell'output del comando @command{lilypond} su @var{loglevel}.
I valori possibili sono @code{NONE}, @code{ERROR}, @code{WARNING}, @code{BASIC},
@code{PROGRESS}, @code{INFO} (predefinito) e @code{DEBUG}. Se questa opzione
non viene usata e la variabile d'ambiente @code{LILYPOND_LOGLEVEL} è
impostata, il suo valore viene usato come livello di log.

@item --info-images-dir=@var{dir}
Formatta l'output di Texinfo in modo che Info cerchi le immagini della musica
nella directory @var{dir}.

@item --latex-program=@var{prog}
Lancia l'eseguibile @command{@var{prog}} invece di @command{latex}.  Questa opzione
è utile, ad esempio, se il documento è elaborato con @command{xelatex}.

@item --left-padding=@var{quantità}
Crea una spaziatura a sinistra tra i frammenti LilyPond utilizzando gli spazi
bianchi.

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

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 @var{quantità}.  Di conseguenza, ciascuna linea viene spostata
visivamente a destra.

@item -P @var{comando}
@itemx --process=@var{comando}
Elabora i frammenti di LilyPond con @command{@var{comando}}.  Il comando
predefinito è @code{lilypond}.  @code{lilypond-book} non accetta le opzioni
@option{--filter} e @option{--process} contemporaneamente.

@item --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.

@item --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.

@item --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 @code{lilypondfile} e solo se le directory indicate da
@option{--output-dir} e @option{--lily-output-dir} sono diverse.

@item -V
@itemx --verbose
Mostra un output dettagliato.  Questo è equivalente a @code{--loglevel=DEBUG}.

@item -v
@itemx --version
Mostra informazioni sulla versione.
@end table

@knownissues

Il comando Texinfo @code{@@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 @code{\score} di un blocco LilyPond viene elaborato.


@node Estensioni dei nomi di file
@section Estensioni dei nomi di file
@translationof Filename extensions

Si può usare qualsiasi estensione per il file di input, ma se non si usa
l'estensione raccomandata per uno specifico formato potrebbe essere
necessario specificare a mano il formato di output; per i dettagli si veda
@ref{Utilizzo di lilypond-book}.  Altrimenti, @command{lilypond-book} sceglie
automaticamente il formato di output in base all'estensione del file di input.

@quotation
@multitable @columnfractions .2 .5
@item @strong{estensione} @tab @strong{formato di output}
@item
@item @file{.html} @tab HTML
@item @file{.htmly} @tab HTML
@item @file{.itely} @tab Texinfo
@item @file{.latex} @tab @LaTeX{}
@item @file{.lytex} @tab @LaTeX{}
@item @file{.lyxml} @tab DocBook
@item @file{.tely} @tab Texinfo
@item @file{.tex} @tab @LaTeX{}
@item @file{.texi} @tab Texinfo
@item @file{.texinfo} @tab Texinfo
@item @file{.xml} @tab HTML
@end multitable
@end quotation

Se si usa per il file di input la stessa estensione che @command{lilypond-book}
usa per il file di output e se il file di input è nella stessa directory
in cui lavora @command{lilypond-book}, bisogna usare l'opzione @option{--output}
per far sì che @command{lilypond-book} sia eseguito; altrimenti si ferma e
mostra un messaggio di errore simile a @qq{L'output sovrascriverebbe il file di input}.


@node Modelli per lilypond-book
@section Modelli per lilypond-book
@translationof lilypond-book templates

Ecco alcuni modelli da usare con @code{lilypond-book}.  Se non hai familiarità
con questo programma, consulta @ref{lilypond-book}.

@subsection LaTeX

Si possono includere frammenti LilyPond in un documento LaTeX.

@example
\documentclass[]@{article@}

\begin@{document@}

Normale testo LaTeX.

\begin@{lilypond@}
\relative @{
  a'4 b c d
@}
\end@{lilypond@}

Altro testo LaTeX, seguito da alcune opzioni tra parentesi quadre.

\begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
d4 c b a
\end@{lilypond@}
\end@{document@}
@end example

@subsection Texinfo

Si possono includere frammenti LilyPond in Texinfo; infatti questo intero
manuale è scritto in Texinfo.

@example
\input texinfo @c -*-texinfo-*-

@@ifnottex
@@node Top
@@top
@@end ifnottex

Testo Texinfo

@@lilypond
\relative @{
  a4 b c d
@}
@@end lilypond

Altro testo Texinfo, seguito dalle opzioni tra parentesi.

@@lilypond[verbatim,fragment,ragged-right]
d4 c b a
@@end lilypond

@@bye
@end example


@subsection html

@example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<body>

<p>
I documenti per lilypond-book possono combinare liberamente musica e testo.  Ad
esempio,
<lilypond>
\relative @{
  a'4 b c d
@}
</lilypond>
</p>

<p>
Ancora un po' di LilyPond, questa volta con delle opzioni:

<lilypond fragment quote staffsize=26 verbatim>
a4 b c d
</lilypond>
</p>

</body>
</html>


@end example

@subsection xelatex

@verbatim
\documentclass{article}
\usepackage{ifxetex}
\ifxetex
%elementi specifici di xetex
\usepackage{xunicode,fontspec,xltxtra}
\setmainfont[Numbers=OldStyle]{Times New Roman}
\setsansfont{Arial}
\else
%Questo può essere lasciato vuoto se non si usa pdftex
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{mathptmx}%Times
\usepackage{helvet}%Helvetica
\fi
%Qui è possibile inserire tutti i pacchetti inclusi anche in pdftex
\usepackage[ngerman,finnish,english]{babel}
\usepackage{graphicx}

\begin{document}
\title{Un breve documento con LilyPond e xelatex}
\maketitle

I comandi abituali di \textbf{font} interni al \emph{testo} funzionano,
perché \textsf{sono supportati da \LaTeX{} e XeteX.}
Se vuoi usare comandi specifici come \verb+\XeTeX+, devi
includerli nuovamente in un ambiente \verb+\ifxetex+.
You can use this to print the \ifxetex \XeTeX{} command \else
XeTeX command \fi which is not known to normal \LaTeX .

Nel testo normale si possono usare semplicemente i comandi LilyPond, come in
questo esempio:

\begin{lilypond}
{a2 b c'8 c' c' c'}
\end{lilypond}

\noindent
e così via.

I tipi di carattere dei frammenti inseriti con LilyPond devono essere impostati
all'interno dei frammenti stessi.  Si legga il manuale di Uso dell'applicazione per
sapere come usare lilypond-book.

\selectlanguage{ngerman}
Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
anderen
seltsamen Zeichen: __ ______, wenn sie von der Schriftart
unterst__tzt werden.
\end{document}
@end verbatim


@node Condividere l'indice
@section Condividere l'indice
@translationof Sharing the table of contents

Queste funzioni sono già incluse nel pacchetto OrchestralLily:

@example
@url{https://repo.or.cz/w/orchestrallily.git}
@end example

Alcuni utenti
preferiscono esportare l'indice da lilypond e leggerlo da dentro
@LaTeX{} per la sua maggiore flessibilità nella gestione del testo.

@subsubheading Esportare l'indice da LilyPond

Per questo esempio si presume che lo spartito abbia vari movimenti nello stesso file
di output di lilypond.

@smallexample
#(define (oly:create-toc-file layout pages)
  (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
    (if (not (null? label-table))
      (let* ((format-line (lambda (toc-item)
             (let* ((label (car toc-item))
                    (text  (caddr toc-item))
                    (label-page (and (list? label-table)
                                     (assoc label label-table)))
                    (page (and label-page (cdr label-page))))
               (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
             (formatted-toc-items (map format-line (toc-items)))
             (whole-string (string-join formatted-toc-items ",\n"))
             (output-name (ly:parser-output-name))
             (outfilename (format #f "~a.toc" output-name))
             (outfile (open-output-file outfilename)))
        (if (output-port? outfile)
            (display whole-string outfile)
            (ly:warning (G_ "Unable to open output file ~a for the TOC information") outfilename))
        (close-output-port outfile)))))

\paper @{
  #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
@}
@end smallexample

@subsubheading Importare l'indice in LaTeX

In LaTeX l'intestazione deve includere:

@c no, this doesn't require the smallexample, but since the other
@c two blocks on this page use it, I figured I might as well
@c user it here as well, for consistency. -gp
@smallexample
\usepackage@{pdfpages@}
\includescore@{nameofthescore@}
@end smallexample

@noindent
dove @code{\includescore} viene definito in questo modo:

@smallexample
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \includescore@{PossibleExtension@}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Read in the TOC entries for a PDF file from the corresponding .toc file.
% This requires some heave latex tweaking, since reading in things from a file
% and inserting it into the arguments of a macro is not (easily) possible

% Solution by Patrick Fimml on #latex on April 18, 2009:
% \readfile@{filename@}@{\variable@}
% reads in the contents of the file into \variable (undefined if file
% doesn't exist)
\newread\readfile@@f
\def\readfile@@line#1@{%
@{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
\edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
\ifeof\readfile@@f\else%
\readfile@@line@{#1@}%
\fi%
@}
\def\readfile#1#2@{%
\openin\readfile@@f=#1 %
\ifeof\readfile@@f%
\typeout@{No TOC file #1 available!@}%
\else%
\gdef#2@{@}%
\readfile@@line@{#2@}%
\fi
\closein\readfile@@f%
@}%


\newcommand@{\includescore@}[1]@{
\def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
\let\oly@@addtotoc\undefined
\readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
\ifx\oly@@addtotoc\undefined
\includepdf[pages=-]@{\oly@@fname@}
\else
\edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
@{\oly@@fname@}@}\includeit
\fi
@}
@end smallexample


@node Metodi alternativi per combinare testo e musica
@section Metodi alternativi per combinare testo e musica
@translationof Alternate methods of mixing text and music

Altri modi per combinare testo e musica (senza usare
@command{lilypond-book}) sono trattati in
@ref{Inclusione di partiture LilyPond in altri programmi}.
