1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-
4 Translation of GIT committish: f71ede90de06fdc16dad9ed75f38558efe819080
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @c Note: keep this node named so that `info lilypond-book' brings you here.
15 @chapter Eseguire @command{lilypond-book}
17 Se si desidera aggiungere a un documento illustrazioni musicali, si può
18 semplicemente fare nello stesso modo in cui si farebbe con altri tipi di
19 immagini: prima si creano le immagini separatamente, in formato PostScript o
20 PNG, poi le si includono in un documento @LaTeX{} o HTML.
22 @command{lilypond-book} offre la possibilità di automatizzare tale procedimento: questo
23 programma estrae i frammenti musicali dal documento, esegue @command{lilypond}
24 su di essi e crea un nuovo documento contenente le illustrazioni musicali così
25 ottenute. Le definizioni relative alla larghezza del rigo e alle dimensioni
26 dei caratteri vengono regolate per adeguarsi alla formattazione del documento.
28 Si tratta di un programma separato da @command{lilypond} e viene lanciato
29 dalla linea di comando; per maggiori informazioni, si veda @ref{Command-line
30 usage}. In caso di problemi nell'eseguire @code{lilypond-book} da linea di
31 comando su Windows o Mac OS X, si veda @rweb{Windows} o @rweb{MacOS X}.
33 Questo procedimento può essere applicato ai documenti @LaTeX{}, HTML, Texinfo
42 @cindex documenti, aggiungere musica
43 @cindex HTML, aggiungere musica
44 @cindex Texinfo, aggiungere musica
45 @cindex DocBook, aggiungere musica
46 @cindex LaTeX, aggiungere musica
49 * Un esempio di documento musicologico::
50 * Integrare musica e testo::
51 * Opzioni dei frammenti musicali::
52 * Utilizzo di lilypond-book::
53 * Estensioni dei nomi di file::
54 * Modelli per lilypond-book::
55 * Condividere l'indice::
56 * Metodi alternativi per combinare testo e musica::
60 @node Un esempio di documento musicologico
61 @section Un esempio di documento musicologico
62 @translationof An example of a musicological document
65 Alcuni testi contengono degli esempi musicali: si tratta di
66 trattati musicologici, canzonieri o manuali come questo. È possibile
67 crearli a mano, semplicemente importando un'immagine PostScript
68 nell'elaboratore di testo. Tuttavia esiste una procedura automatizzata
69 che permette di ridurre il carico di lavoro richiesto dai documenti in
70 formato HTML, @LaTeX{}, Texinfo e DocBook.
72 Uno script chiamato @code{lilypond-book} estrarrà i frammenti musicali, li
73 formatterà e restituirà la notazione risultante. Ecco un piccolo esempio
74 da usare con @LaTeX{}. L'esempio contiene anche del testo esplicativo,
75 dunque non è necessario entrare nei dettagli.
81 \documentclass[a4paper]{article}
85 I documenti per \verb+lilypond-book+ possono combinare liberamente musica e testo.
90 c2 e2 \times 2/3 { f8 a b } a2 e4
94 Le opzioni vengono specificate tra parentesi quadre.
96 \begin{lilypond}[fragment,quote,staffsize=26,verbatim]
100 Se l'esempio è più grande, è possibile metterlo in un file separato e inserirlo
101 con \verb+\lilypondfile+.
103 \lilypondfile[quote,noindent]{screech-and-boink.ly}
105 (Se vuoi provare, sostituisci @file{screech-and-boink.ly} con qualsiasi file @file{.ly}
106 che si trovi nella stessa directory di questo file.)
112 @subheading Elaborazione
114 Salva il codice precedente in un file chiamato @file{lilybook.lytex}, quindi
115 esegui in un terminale
117 @c keep space after @version{} so TeX doesn't choke
119 lilypond-book --output=out --pdf lilybook.lytex
120 @emph{lilypond-book (GNU LilyPond) @version{} }
121 @emph{Lettura di lilybook.lytex...}
122 @emph{..tagliato molto output..}
123 @emph{Compilazione di lilybook.tex...}
125 pdflatex lilybook.tex
126 @emph{..tagliato molto output..}
128 @emph{(sostituisci @command{xpdf} col tuo lettore PDF preferito)}
131 L'esecuzione di @command{lilypond-book} e @command{pdflatex} crea molti file
132 temporanei e questo potrebbe rendere disordinata la directory di lavoro. Per
133 ovviare a questo inconveniente, è consigliabile usare l'opzione @code{--output=@var{dir}}. In questo
134 modo i file verranno salvati in una sottodirectory @file{dir} separata.
136 Infine ecco il risultato dell'esempio in @LaTeX{}.@footnote{Questo
137 tutorial è elaborato da Texinfo, dunque l'esempio produce dei risultati
138 leggermente diversi nella formattazione.} Si conclude qui la parte di
145 I documenti per \verb+lilypond-book+ possono combinare liberamente musica e testo.
150 c2 e2 \times 2/3 { f8 a b } a2 e4
154 Le opzioni vengono specificate tra parentesi quadre.
156 @lilypond[fragment,quote,staffsize=26,verbatim]
160 Se l'esempio è più grande, è possibile riportarlo in un file a parte e inserirlo
161 con \verb+\lilypondfile+.
163 @lilypondfile[quote,noindent]{screech-and-boink.ly}
165 Perché sia visibile la @code{tagline}, predefinita o personalizzata, l'intero
166 frammento deve essere compreso in un costrutto @code{\book @{ @}}.
168 @lilypond[papersize=a8,verbatim]
171 title = "Una scala in LilyPond"
182 @node Integrare musica e testo
183 @section Integrare musica e testo
184 @translationof Integrating music and text
186 Questa sezione spiega come integrare LilyPond in vari formati di output.
198 @LaTeX{} costituisce lo standard de facto per le pubblicazioni nell'ambito
199 delle scienze esatte. Si basa sul motore tipografico @TeX{}, che produce la
200 migliore qualità tipografica possibile.
203 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
204 @emph{The Not So Short Introduction to @LaTeX{}}} per una panoramica
205 sull'uso di @LaTeX{}.
207 @code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
208 la musica nei file @LaTeX{}:
213 il comando @code{\lilypond@{...@}}, dove si può inserire direttamente del
214 codice lilypond corto
217 l'ambiente @code{\begin@{lilypond@}...\end@{lilypond@}}, dove si può inserire
218 direttamente del codice lilypond più lungo
221 il comando @code{\lilypondfile@{...@}} per inserire un file lilypond
224 il comando @code{\musicxmlfile@{...@}} per inserire un file MusicXML, che
225 sarà elaborato da @code{musicxml2ly} e da @code{lilypond}.
229 Nel file di input, la musica viene specificata con uno dei seguenti comandi:
232 \begin@{lilypond@}[le,opzioni,vanno,qui]
236 \lilypond[le,opzioni,vanno,qui]@{ CODICE LILYPOND @}
238 \lilypondfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
240 \musicxmlfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
245 Inoltre, @code{\lilypondversion} mostra la versione
246 di lilypond impiegata.
247 L'esecuzione di @command{lilypond-book} produce un file che può essere
248 ulteriormente elaborato con @LaTeX{}.
250 Vediamo alcuni esempi. L'ambiente @code{lilypond}
253 \begin@{lilypond@}[quote,fragment,staffsize=26]
261 @lilypond[quote,fragment,staffsize=26]
268 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
274 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
277 Attualmente non è possibile includere @code{@{} o @code{@}} all'interno di
278 @code{\lilypond@{@}}, dunque questo comando è utile solo se usato con
279 l'opzione @code{fragment}.
281 La lunghezza predefinita del rigo musicale sarà regolata in base ai
282 comandi presenti nel preambolo del documento, ovvero la parte del documento
283 che precede @code{\begin@{document@}}. Il comando @command{lilypond-book}
284 li invia a @LaTeX{} per definire la larghezza del testo. La larghezza del
285 rigo nei frammenti musicali è quindi regolato in base alla larghezza del
286 testo. Si noti che questo algoritmo euristico può fallire facilmente; in
287 questi casi occorre usare l'opzione @code{line-width} nel frammento musicale.
289 @cindex titoli e lilypond-book
290 @cindex \header nei documenti @LaTeX{}
292 Ogni frammento chiamerà le seguenti macro se sono state definite
296 @item @code{\preLilyPondExample} prima della musica,
298 @item @code{\postLilyPondExample} dopo la musica,
300 @item @code{\betweenLilyPondSystem[1]} tra i sistemi, se
301 @code{lilypond-book} ha diviso il frammento in più file
302 PostScript. Prende un parametro e riceve
303 tutti i file già inclusi in questo frammento.
304 Per impostazione predefinita inserisce semplicemente un @code{\linebreak}.
310 @cindex Latex, feta symbols
313 To include feta symbols (such as flat, segno, etc) in a LaTeX
314 document, use @code{\input@{titledefs@}}
317 \documentclass[a4paper]@{article@}
328 The font symbol names are defined in the file feta20.tex; to find
329 the location of this file, use the command
339 Talvolta si ha necessità di mostrare degli elementi musicali (ad esempio le
340 legature di portamento e di valore) che proseguono dopo la fine del
341 frammento. È possibile inserirli mandando il rigo a capo e
342 impedendo l'inclusione del restante output di LilyPond.
344 In @LaTeX{}, si definisce @code{\betweenLilyPondSystem} in modo tale che
345 l'inclusione di altri sistemi venga terminata una volta incluso il
346 numero di sistemi richiesti. Dato che @code{\betweenLilyPondSystem} viene
347 chiamato la prima volta @emph{dopo} il primo sistema, includere solo il primo
351 \def\betweenLilyPondSystem#1@{\endinput@}
353 \begin@{lilypond@}[fragment]
354 c'1\( e'( c'~ \break c' d) e f\)
358 Se serve una maggior quantità di sistemi, occorre usare un condizionale
359 @TeX{} prima di @code{\endinput}. In questo esempio, sostituisci @q{2} col
360 numero di sistemi che desideri avere nell'output.
363 \def\betweenLilyPondSystem#1@{
364 \ifnum#1<2\else\expandafter\endinput\fi
369 (Dato che @code{\endinput} arresta immediatamente l'elaborazione del file di
370 input corrente, occorre usare @code{\expandafter} per ritardare la chiamata di
371 @code{\endinput} e far sì che avvenga dopo l'esecuzione di @code{\fi}, in modo
372 da bilanciare la condizione @code{\if}-@code{\fi}.)
374 Ricorda che la definizione di @code{\betweenLilyPondSystem} è
375 efficace finché @TeX{} esce dal gruppo attuale (ad esempio l'ambiente
376 @LaTeX{}) o è sovrascritto da un'altra definizione (che vale, in
377 gran parte dei casi, per il resto del documento). Per reimpostare
378 la definizione, si scrive
381 \let\betweenLilyPondSystem\undefined
385 nel sorgente @LaTeX{}.
387 Si potrebbe semplificare la procedura creando una macro @TeX{}
390 \def\onlyFirstNSystems#1@{
391 \def\betweenLilyPondSystem##1@{%
392 \ifnum##1<#1\else\expandafter\endinput\fi@}
397 e poi specificando prima di ogni frammento la quantità di sistemi desiderata,
400 \onlyFirstNSystems@{3@}
401 \begin@{lilypond@}...\end@{lilypond@}
402 \onlyFirstNSystems@{1@}
403 \begin@{lilypond@}...\end@{lilypond@}
408 Esistono opzioni specifiche da linea di comando per @command{lilypond-book} e
409 altri dettagli da conoscere quando si elaborano documenti @LaTeX{}; si veda
410 @ref{Invoking lilypond-book}.
415 @translationof Texinfo
417 Texinfo è il formato standard per la documentazione del progetto GNU. Un
418 esempio di documento Texinfo è questo stesso manuale. Le versioni del manuale
419 in formato HTML, PDF e Info vengono generate da un documento Texinfo.
421 @code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
422 musica nei file Texinfo:
427 il comando @code{\lilypond@{...@}}, dove si può inserire direttamente del
428 codice lilypond corto
431 l'ambiente @code{\begin@{lilypond@}...\end@{lilypond@}}, dove si può inserire
432 direttamente del codice lilypond più lungo
435 il comando @code{\lilypondfile@{...@}} per inserire un file lilypond
438 il comando @code{\musicxmlfile@{...@}} per inserire un file MusicXML, che
439 sarà elaborato da @code{musicxml2ly} e da @code{lilypond}.
443 Nel file di input, la musica viene specificata con uno dei seguenti comandi
446 @@lilypond[le,opzioni,vanno,qui]
447 IL TUO CODICE LILYPOND
450 @@lilypond[le,opzioni,vanno,qui]@{ IL TUO CODICE LILYPOND @}
452 @@lilypondfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
454 @@musicxmlfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
457 Inoltre, @code{@@lilypondversion} mostra la versione di
460 Quando si esegue @command{lilypond-book} su di esso, il risultato è un
461 file Texinfo (con estensione @file{.texi}) contenente degli elementi @code{@@image}
462 per l'HTML, Info e l'output per la stampa. @command{lilypond-book} genera le
463 immagini della musica in formati EPS e PDF per l'utilizzo nell'output per la
464 stampa e in formato PNG per l'utilizzo nell'output HTML e Info.
466 Vediamo due piccoli esempi. Un ambiente @code{lilypond}
484 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
490 @lilypond[fragment,staffsize=11]{<c' e' g'>}
492 Diversamente da @LaTeX{}, @code{@@lilypond@{...@}} non genera un'immagine
493 nel testo. Prende sempre un paragrafo proprio.
500 @code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
501 musica nei file HTML:
506 il comando @code{\lilypond@{...@}}, dove si può inserire direttamente del
507 codice lilypond corto
510 l'ambiente @code{\begin@{lilypond@}...\end@{lilypond@}}, dove si può inserire
511 direttamente del codice lilypond più lungo
514 il comando @code{\lilypondfile@{...@}} per inserire un file lilypond
517 il comando @code{\musicxmlfile@{...@}} per inserire un file MusicXML, che
518 sarà elaborato da @code{musicxml2ly} e da @code{lilypond}.
522 Nel file di input, la musica viene specificata con uno dei seguenti comandi:
524 \begin@{lilypond@}[le,opzioni,vanno,qui]
528 \lilypond[le,opzioni,vanno,qui]@{ CODICE LILYPOND @}
530 \lilypondfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
532 \musicxmlfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
534 <lilypond le opzioni vanno qui>
538 <lilypond le opzioni vanno qui: CODICE LILYPOND />
540 <lilypondfile le opzioni vanno qui>@var{nomefile}</lilypondfile>
542 <musicxmlfile le opzioni vanno qui>@var{nomefile}</musicxmlfile>
545 Ad esempio, puoi scrivere
548 <lilypond fragment relative=2>
549 \key c \minor c4 es g2
554 @command{lilypond-book} genera quindi un file HTML con gli elementi appropriati
555 per le immagini dei frammenti musicali:
557 @lilypond[fragment,relative=2]
558 \key c \minor c4 es g2
561 Per le immagini in linea, si usa @code{<lilypond ... />}, dove le opzioni
562 sono distinte dalla musica attraverso i due punti, ad esempio
565 Un po' di musica in <lilypond relative=2: a b c/> una linea di testo.
568 Per includere file separati, si usa
571 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
574 @code{<musicxmlfile>} usa la stessa sintassi di @code{<lilypondfile>}, ma semplicemente
575 si riferisce a un file MusicXML invece che a un file LilyPond.
577 Per una lista di opzioni da usare con gli elementi @code{lilypond} e
578 @code{lilypondfile}, si veda @ref{Music fragment options}.
580 Inoltre, @code{<lilypondversion/>} mostra la versione di
584 @cindex titoli in HTML
585 @cindex immagine di anteprima
590 @translationof DocBook
592 Per inserire frammenti di codice LilyPond è una buona idea mantenere la
593 conformità del documento DocBook, in modo da poter usare gli editor DocBook, la
594 validazione, etc. Quindi non si usano elementi personalizzati, ma si
595 specifica una convenzione basata sugli elementi DocBook standard.
597 @subheading Convenzioni comuni
599 Per inserire un frammento di qualsiasi tipo si usano gli elementi @code{mediaobject}
600 e @code{inlinemediaobject}, in modo che il frammento possa essere formattato
601 in linea o meno. Le opzioni di formattazione del frammento vengono sempre
602 indicate nella proprietà @code{role} dell'elemento più interno (si vedano
603 le prossime sezioni). Gli elementi sono scelti in modo da permettere agli editor
604 DocBook di ottenere una formattazione ottimale. I file DocBook da
605 elaborare con @command{lilypond-book} devono avere estensione @file{.lyxml}.
607 @subheading Includere un file LilyPond
609 Si tratta del caso più semplice. Bisogna usare l'estensione @file{.ly} per
610 il file da includere e inserirlo come uno standard @code{imageobject}, con
611 la seguente struttura:
616 <imagedata fileref="music1.ly" role="printfilename" />
621 Nota che sei libero di usare @code{mediaobject} o @code{inlinemediaobject}
622 come elemento più esterno.
624 @subheading Includere codice LilyPond
626 È possibile includere codice LilyPond all'interno di un elemento
627 @code{programlisting} in cui il linguaggio sia impostato su @code{lilypond}
628 e con la seguente struttura:
633 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
634 \context Staff \with @{
635 \remove Time_signature_engraver
636 \remove Clef_engraver@}
643 Come si vede, l'elemento più esterno è @code{mediaobject} o
644 @code{inlinemediaobject} e c'è un @code{textobject} che contiene al
645 suo interno il @code{programlisting}.
647 @subheading Elaborare il documento DocBook
649 L'esecuzione di @command{lilypond-book} su un file @file{.lyxml} creerà un
650 documento DocBook valido con estensione @file{.xml} che potrà essere
651 ulteriormente elaborato. Usando
652 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, creerà automaticamente un file
653 PDF da questo documento. Per generare l'HTML (HTML Help,
654 JavaHelp etc.) si possono usare i fogli di stile DocBook XSL ufficiali;
655 tuttavia è possibile che sia necessario modificarli un po'.
658 @node Opzioni dei frammenti musicali
659 @section Opzioni dei frammenti musicali
660 @translationof Music fragment options
662 Nelle pagine che seguono, per @q{comando LilyPond} si intende un qualsiasi
663 comando descritto nelle sezioni precedenti che sia gestito da @command{lilypond-book}
664 per produrre un frammento musicale. Per semplicità, i comandi LilyPond vengono
665 mostrati soltanto nella sintassi @LaTeX{}.
667 Nota che la stringa delle opzioni è analizzata da sinistra a destra; se un'opzione
668 ricorre più di una volta, viene applicata nella sua ultima occorrenza.
670 Sono disponibili le seguenti opzioni per i comandi LilyPond:
673 @item staffsize=@var{altezza}
674 Imposta la dimensione del pentagramma a @var{altezza}, misurata in punti.
677 Produce linee con margine destro irregolare e spaziatura naturale, ovvero
678 viene aggiunto @code{ragged-right = ##t} al frammento LilyPond. Frammenti
679 con un solo rigo avranno sempre il margine destro irregolare, a meno che
680 non venga specificato esplicitamente @code{noragged-right}.
683 Per i frammenti di una sola linea, fa sì che la lunghezza del rigo venga estesa
684 fino a coincidere con la larghezza della linea, ovvero viene aggiunto
685 @code{ragged-right = ##f} al frammento LilyPond.
688 @itemx line-width=@var{dimensione}\@var{unità}
689 Imposta la lunghezza della linea a @var{dimensione}, usando @var{unità} come
690 unità di misura. @var{unità} può essere una delle seguenti stringhe: @code{cm},
691 @code{mm}, @code{in} o @code{pt}. Questa opzione riguarda l'output LilyPond
692 (ovvero, la lunghezza del rigo del frammento musicale), non la formattazione
695 Se usato senza un argomento, imposta la lunghezza della linea a un valore
696 predefinito (calcolato da un algoritmo euristico).
698 Se non viene assegnata un'opzione @code{line-width}, @command{lilypond-book}
699 cerca di indovinare un valore predefinito per gli ambienti @code{lilypond} che
700 non usano l'opzione @code{ragged-right}.
702 @item papersize=@var{stringa}
703 Dove @var{stringa} è una delle dimensioni del foglio definite in @file{scm/paper.scm},
704 ad esempio @code{a5}, @code{quarto}, @code{11x17} etc.
706 I valori non definiti in @file{scm/paper.scm} saranno ignorati, sarà inviato
707 un messaggio di avviso e al frammento sarà assegnata la dimensione predefinita,
711 Non viene visualizzata l'indicazione di tempo e disabilita i segni relativi alla scansione ritmica
712 (segno di tempo, barre di divisione) nella partitura.
715 Fa sì che @command{lilypond-book} aggiunga del codice boilerplate in modo che
716 sia possibile inserire semplicemente, ad esempio,
723 senza @code{\layout}, @code{\score}, etc.
726 Non aggiunge del codice ulteriore per completare il codice LilyPond nei frammenti
727 musicali. Essendo l'impostazione predefinita, @code{nofragment} di norma
730 @item indent=@var{dimensione}\@var{unità}
731 Imposta l'indentazione del primo sistema musicale a @var{dimensione}, usando
732 @var{unità} come unità di misura. @var{unità} è una delle seguenti stringhe:
733 @code{cm}, @code{mm}, @code{in} o @code{pt}. Questa opzione riguarda
734 LilyPond, non la formattazione del testo.
737 Imposta l'indentazione del primo sistema musicale su zero. Questa opzione
738 interessa LilyPond, non la formattazione del testo. L'assenza di indentazione è
739 l'impostazione predefinita, dunque normalmente @code{noindent} è ridondante.
742 Riduce la lunghezza della linea di un frammento musicale di @math{2*0.4}@dmn{in}
743 e inserisce l'output in un blocco per le citazioni. Il valore @q{0.4@dmn{in}}
744 può essere controllato con l'opzione @code{exampleindent}.
747 Imposta la quantità di spazio con cui l'opzione @code{quote} indenta un
751 @itemx relative=@var{n}
752 Usa la modalità di ottava relativa. Per impostazione predefinita, le altezze delle note
753 sono riferite al Do@tie{}centrale. L'argomento opzionale del numero intero
754 specifica l'ottava della nota iniziale: il valore predefinito @code{1} è il
755 Do centrale. L'opzione @code{relative} funziona solo quando è impostata
756 l'opzione @code{fragment}, quindi @code{fragment} è implicitamente sottinteso
757 da @code{relative}, a prescindere dalla presenza dell'opzione @code{(no)fragment}
761 LilyPond usa @command{lilypond-book} anche per produrre la propria
762 documentazione. A questo scopo, esistono altre opzioni più complesse
763 per i frammenti musicali.
767 L'argomento di un comando LilyPond viene copiato nel file di output e racchiuso
768 in un blocco di testo, seguito da qualsiasi testo assegnato con l'opzione
769 @code{intertext} (non ancora implementato); quindi viene mostrata la musica
770 vera e propria. Questa opzione non funziona bene con @code{\lilypond@{@}} se
771 fa parte di un paragrafo.
773 Se @code{verbatim} viene usato in un comando @code{lilypondfile}, è possibile
774 includere il testo di una parte soltanto del file sorgente. Se il file
775 sorgente ha un commento contenente @samp{begin verbatim} (senza
776 virgolette), la citazione del sorgente nel blocco testuale inizierà dopo
777 l'ultima occorrenza di tale commento; in modo analogo, la citazione del testo
778 sorgente si fermerà proprio prima della prima occorrenza di un commento
779 contenente @samp{end verbatim}, se presente. Nel seguente file sorgente di
780 esempio, la musica viene interpretata in modalità relativa ma il blocco
781 testuale non mostrerà il blocco @code{relative}, ovvero
784 \relative c' @{ % begin verbatim
791 mostrerà il seguente blocco testuale
799 Se si desidera tradurre i commenti e i nomi delle variabili nell'output
800 verbatim ma non nei sorgenti, si può impostare la variabile d'ambiente
801 @code{LYDOC_LOCALEDIR} sul percorso di una directory; la directory deve
802 contenere un albero dei cataloghi di messaggio @file{.mo} che hanno
803 @code{lilypond-doc} come dominio.
806 (Solo per l'output Texinfo.) Aggiunge @code{\version
807 @@w@{"@@version@{@}"@}} nella prima riga dell'output di @code{verbatim}.
810 (Solo per l'output Texinfo.) Se @command{lilypond} viene lanciato con
811 l'opzione @option{--header=@/texidoc} e il file da elaborare si
812 chiama @file{foo.ly}, verrà creato un file @file{foo.texidoc} a patto che
813 ci sia un campo @code{texidoc} nel blocco @code{\header}. L'opzione @code{texidoc}
814 fa sì che @command{lilypond-book} includa tali file, aggiungendo il loro
815 contenuto in forma di blocco di documentazione proprio prima del frammento
816 di musica (ma fuori dall'ambiente @code{example} generato da un'opzione
819 Se il file @file{foo.ly} contiene
823 texidoc = "Questo file mostra il funzionamento di una singola nota."
829 e il documento Texinfo @file{test.texinfo} contiene
832 @@lilypondfile[texidoc]@{foo.ly@}
836 il seguente comando produce il risultato atteso
839 lilypond-book --pdf --process="lilypond \
840 -dbackend=eps --header=texidoc" test.texinfo
843 Per la maggior parte, i documenti di test di LilyPond (nella directory @file{input}
844 della distribuzione) sono piccoli file @file{.ly} che hanno esattamente questo
847 Ai fini della localizzazione, se il documento Texinfo document contiene
848 @code{@@documentlanguage @var{LANG}} e l'header di @file{foo.ly}
849 contiene un campo @code{texidoc@var{LANG}}, quando si lancia @command{lilypond}
850 con l'opzione @option{--header=@/texidoc@var{LANG}} verrà incluso
851 @file{foo.texidoc@var{LANG}} invece di @file{foo.texidoc}.
854 (Solo per l'output Texinfo.) Questa opzione funziona in modo simile
855 all'opzione @code{texidoc}: se @command{lilypond} viene lanciato con
856 l'opzione @option{--header=@/doctitle} e il file da elaborare si chiama
857 @file{foo.ly} e contiene un campo @code{doctitle} nel blocco
858 @code{\header}, viene creato un file @file{foo.doctitle}. Se si usa
859 l'opzione @code{doctitle}, i contenuti di @file{foo.doctitle},
860 che dovrebbero trovarsi su una singola linea di @var{text}, vengono inseriti
861 nel documento Texinfo come @code{@@lydoctitle @var{text}}.
862 @code{@@lydoctitle} è una macro definita nel documento Texinfo.
863 Lo stesso discorso relativo all'elaborazione @code{texidoc} delle lingue
864 localizzate si applica anche a @code{doctitle}.
867 (Solo per l'output Texinfo.) Non tradurre i commenti e i nomi delle
868 variabili nel blocco testuale del frammento citato.
871 Se un file di input di LilyPond viene incluso con @code{\lilypondfile}, il
872 nome del file viene mostrato immediatamente prima del frammento musicale. Per l'output
873 HTML, questo nome è un collegamento. Viene mostrata solo la base del nome del
874 file, ovvero viene tolta la parte che costituisce il percorso del file.
879 @node Utilizzo di lilypond-book
880 @section Utilizzo di @command{lilypond-book}
881 @translationof Invoking lilypond-book
883 @command{lilypond-book} crea un file con una delle seguenti
884 estensioni: @file{.tex}, @file{.texi}, @file{.html} o @file{.xml},
885 a seconda del formato dell'output. Tutti i file @file{.tex}, @file{.texi} e
886 @file{.xml} necessitano di un'ulteriore elaborazione.
888 @subheading Istruzioni specifiche di ogni formato
890 @subsubheading @LaTeX{}
892 Esistono due modi di elaborare il documento @LaTeX{} per la stampa o la
893 pubblicazione: generare direttamente un file PDF tramite PDF@LaTeX{} oppure
894 generare un file PostScript tramite @LaTeX{}, attraverso un traduttore da DVI a
895 PostScript come @command{dvips}. Il primo modo è più semplice e raccomandato@footnote{Nota
896 che PDF@LaTeX{} e @LaTeX{} potrebbero non essere entrambi utilizzabili per compilare
897 un qualsiasi documento @LaTeX{}: ecco perché vengono illustrati i due modi.}, e
898 indipendentemente da quello che userai, puoi convertire facilmente PostScript e
899 PDF con strumenti come @command{ps2pdf} e @command{pdf2ps} inclusi nel pacchetto
902 Per creare un file PDF con PDF@LaTeX{}, si usa
905 lilypond-book --pdf tuofile.lytex
909 @cindex caratteri vettoriali
910 @cindex type1, carattere
912 @cindex utilizzo di dvips
913 Per produrre l'output PDF attraverso @LaTeX{}/@command{dvips}/@command{ps2pdf},
914 bisogna usare questi comandi
917 lilypond-book tuofile.lytex
919 dvips -Ppdf tuofile.dvi
924 Il file @file{.dvi} creato da questa sequenza non conterrà le
925 teste delle note. È normale; se si seguono le istruzioni, le teste
926 verranno incluse nei file @file{.ps} e @file{.pdf}.
928 L'esecuzione di @command{dvips} potrebbe generare dei messaggi di avviso
929 relativi ai caratteri; questi messaggi sono innocui e possono
930 essere ignorati. Se esegui @command{latex} in modalità due colonne, ricorda
931 di aggiungere @option{-t landscape} alle opzioni di @command{dvips}.
934 Il comando @code{\pageBreak} non funziona all'interno dell'ambiente
935 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}}.
937 Molte variabili del blocco @code{\paper} non funzionano all'interno dell'ambiente
938 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}}. Usa
939 @code{\newcommand} con @code{\betweenLilyPondSystem} nel preambolo;
942 \newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
946 @subsubheading Texinfo
948 Per generare un documento Texinfo (in qualsiasi formato di output), si seguono
949 le normali procedure usate con Texinfo; ovvero, si lancia @command{texi2pdf} o
950 @command{texi2dvi} o @command{makeinfo}, a seconda del formato di output
953 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, e @ref{Creating
954 an Info File, , , texinfo, GNU Texinfo}.
957 Si veda la documentazione di Texinfo per ulteriori dettagli.
961 @subheading Opzioni da linea di comando
963 @command{lilypond-book} accetta le seguenti opzioni da linea di comando:
966 @item -f @var{formato}
967 @itemx --format=@var{formato}
968 Specifica il tipo di documento da elaborare: @code{html}, @code{latex},
969 @code{texi} (il formato predefinito) o @code{docbook}. Se manca questa opzione,
970 @command{lilypond-book} cerca di rilevare il formato automaticamente, si veda
971 @ref{Filename extensions}. Attualmente, @code{texi} è equivalente a
974 @c This complicated detail is not implemented, comment it out -jm
976 The @code{texi} document type produces a Texinfo file with music
977 fragments in the printed output only. For getting images in the HTML
978 version, the format @code{texi-html} must be used instead.
981 @item -F @var{filtro}
982 @itemx --filter=@var{filtro}
983 Convoglia i frammenti attraverso il @var{filtro}. @code{lilypond-book} non
984 esegue contemporaneamente il filtro e l'elaborazione. Ad esempio,
987 lilypond-book --filter='convert-ly --from=2.0.0 -' mio-libro.tely
992 Mostra un breve messaggio di aiuto.
995 @itemx --include=@var{dir}
996 Aggiunge @var{dir} al percorso di inclusione. @command{lilypond-book} cerca
997 anche dei frammenti già compilati nel percorso di inclusione e non li riscrive
998 nella directory di output, quindi in alcuni casi è necessario eseguire
999 ulteriori comandi come @command{makeinfo} o @command{latex} con le stesse
1000 opzioni @option{-I @var{dir}}.
1002 @item -l @var{loglevel}
1003 @itemx --loglevel=@var{loglevel}
1004 Imposta la verbosità dell'output su @var{loglevel}. I valori possibili sono @code{NONE},
1005 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (predefinito) e @code{DEBUG}. Se
1006 questa opzione non viene usata e la variabile d'ambiente @code{LILYPOND_BOOK_LOGLEVEL}
1007 è impostata, il suo valore viene usato come loglevel.
1010 @itemx --output=@var{dir}
1011 Salva i file generati nella directory @var{dir}. L'esecuzione di
1012 @command{lilypond-book} genera tanti piccoli file che LilyPond
1013 elaborerà. Per evitare tutto questo disordine nella directory dei
1014 sorgenti, si usa l'opzione da linea di comando @option{--output}
1015 e si entra in questa directory prima di eseguire @command{latex}
1016 o @command{makeinfo}.
1019 lilypond-book --output=out tuofile.lytex
1024 @itemx --skip-lily-check
1025 Non si arresta se non viene trovato l'output di lilypond. Viene usata per la
1026 documentazione Info di LilyPond, che è priva di immagini.
1028 @itemx --skip-png-check
1029 Non si arresta se non vengono trovate immagini PNG per i file EPS. Viene usata
1030 per la documentazione Info di LilyPond, che è priva di immagini.
1032 @itemx --lily-output-dir=@var{dir}
1033 Scrive i file lily-XXX nella directory @var{dir}, crea un link nella
1034 directory @option{--output}. Si usa questa opzione per risparmiare tempo nella
1035 compilazione di documenti situati in directory diverse che condividono
1036 molti identici frammenti.
1038 @itemx --lily-loglevel=@var{loglevel}
1039 Set the output verbosity of the invoked @command{lilypond} calls to @var{loglevel}.
1040 I valori possibili sono @code{NONE}, @code{ERROR}, @code{WARNING}, @code{BASIC_PROGRESS},
1041 @code{PROGRESS}, @code{INFO} (predefinito) e @code{DEBUG}. Se questa opzione
1042 non viene usata e la variabile d'ambiente @code{LILYPOND_LOGLEVEL} è
1043 impostata, il suo valore viene usato come loglevel.
1045 @itemx --info-images-dir=@var{dir}
1046 Formatta l'output di Texinfo in modo che Info cerchi le immagini della musica
1049 @itemx --latex-program=@var{prog}
1050 Lancia l'eseguibile @command{prog} invece di @command{latex}. Questa opzione
1051 è utile, ad esempio, se il documento è elaborato con @command{xelatex}.
1053 @itemx --left-padding=@var{quantità}
1054 Crea una spaziatura corrispondente a questa quantità tra i riquadri EPS. @var{quantità} è
1055 misurata in millimetri e il valore predefinito è 3.0. Questa opzione si usa
1056 se i righi dello spartito oltrepassano il margine destro.
1058 La larghezza di un sistema molto denso può variare in base agli elementi
1059 della notazione attaccati al margine sinistro, come i numeri di battuta e
1060 i nomi degli strumenti. Questa opzione accorcia tutte le linee e le sposta a
1061 a destra della stessa quantità.
1063 @item -P @var{comando}
1064 @itemx --process=@var{comando}
1065 Elabora i frammenti di LilyPond con @var{comando}. Il comando predefinito è
1066 @code{lilypond}. @code{lilypond-book} non userà @option{--filter} e
1067 @option{--process} contemporaneamente.
1070 Crea file PDF da usare con PDF@LaTeX{}.
1072 @item --redirect-lilypond-output
1073 Per impostazione predefinita, l'output viene mostrato sul terminale. Questa
1074 opzione redirige tutto l'output in dei file di log nella stessa directory dei
1077 @itemx --use-source-file-names
1078 Salva i file di output dei frammenti con lo stesso nome, esclusa l'estensione,
1079 dei sorgenti. Questa opzione funziona solo con i frammenti inclusi con
1080 @code{lilypondfile} e solo se le directory indicate da @option{--output-dir} e
1081 @option{--lily-output-dir} sono diverse.
1085 Mostra un output dettagliato. Questo è equivalente a @code{--loglevel=DEBUG}.
1089 Mostra informazioni sulla versione.
1094 Il comando Texinfo @code{@@pagesizes} non viene inrerpretato. Allo stesso
1095 modo, i comandi @LaTeX{} che modificano i margini e la larghezza della linea
1096 dopo il preambolo vengono ignorati.
1098 Solo il primo @code{\score} di un blocco LilyPond viene elaborato.
1101 @node Estensioni dei nomi di file
1102 @section Estensioni dei nomi di file
1103 @translationof Filename extensions
1105 Si può usare qualsiasi estensione per il file di input, ma se non si usa
1106 l'estensione raccomandata per uno specifico formato potrebbe essere
1107 necessario specificare a mano il formato di output; per i dettagli si veda
1108 @ref{Invoking lilypond-book}. Altrimenti, @command{lilypond-book} sceglie
1109 automaticamente il formato di output in base all'estensione del file di input.
1112 @multitable @columnfractions .2 .5
1113 @item @strong{estensione} @tab @strong{formato di output}
1115 @item @file{.html} @tab HTML
1116 @item @file{.htmly} @tab HTML
1117 @item @file{.itely} @tab Texinfo
1118 @item @file{.latex} @tab @LaTeX{}
1119 @item @file{.lytex} @tab @LaTeX{}
1120 @item @file{.lyxml} @tab DocBook
1121 @item @file{.tely} @tab Texinfo
1122 @item @file{.tex} @tab @LaTeX{}
1123 @item @file{.texi} @tab Texinfo
1124 @item @file{.texinfo} @tab Texinfo
1125 @item @file{.xml} @tab HTML
1129 Se si usa per il file di input la stessa estensione che @command{lilypond-book}
1130 usa per il file di output e se il file di input è nella stessa directory
1131 in cui lavora @command{lilypond-book}, bisogna usare l'opzione @option{--output}
1132 per far sì che @command{lilypond-book} sia eseguito; altrimenti si ferma e
1133 mostra un messaggio di errore simile a @qq{L'output sovrascriverebbe il file di input}.
1136 @node Modelli per lilypond-book
1137 @section Modelli per lilypond-book
1138 @translationof lilypond-book templates
1140 Ecco alcuni modelli da usare con @code{lilypond-book}. Se non hai familiarità
1141 con questo programma, consulta @ref{lilypond-book}.
1145 Si possono includere frammenti LilyPond in un documento LaTeX.
1148 \documentclass[]@{article@}
1152 Normale testo LaTeX.
1160 Altro testo LaTeX, seguito da alcune opzioni tra parentesi quadre.
1162 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1170 Si possono includere frammenti LilyPond in Texinfo; infatti questo intero
1171 manuale è scritto in Texinfo.
1174 \input texinfo @c -*-texinfo-*-
1186 Altro testo Texinfo, seguito dalle opzioni tra parentesi.
1188 @@lilypond[verbatim,fragment,ragged-right]
1199 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1205 I documenti per lilypond-book possono combinare liberamente musica e testo. Ad
1215 Ancora un po' di Lilypond, questa volta con delle opzioni:
1217 <lilypond fragment quote staffsize=26 verbatim>
1231 \documentclass{article}
1232 \usepackage{ifxetex}
1234 %elementi specifici di xetex
1235 \usepackage{xunicode,fontspec,xltxtra}
1236 \setmainfont[Numbers=OldStyle]{Times New Roman}
1239 %Questo può essere lasciato vuoto se non si usa pdftex
1240 \usepackage[T1]{fontenc}
1241 \usepackage[utf8]{inputenc}
1242 \usepackage{mathptmx}%Times
1243 \usepackage{helvet}%Helvetica
1245 %Qui è possibile inserire tutti i pacchetti inclusi anche in pdftex
1246 \usepackage[ngerman,finnish,english]{babel}
1247 \usepackage{graphicx}
1250 \title{Un breve documento con LilyPond e xelatex}
1253 I comandi abituali di \textbf{font} interni al \emph{testo} funzionano,
1254 perché \textsf{sono supportati da \LaTeX{} e XeteX.}
1255 Se vuoi usare comandi specifici come \verb+\XeTeX+, devi
1256 includerli nuovamente in un ambiente \verb+\ifxetex+.
1257 You can use this to print the \ifxetex \XeTeX{} command \else
1258 XeTeX command \fi which is not known to normal \LaTeX .
1260 Nel testo normale si possono usare semplicemente i comandi LilyPond, come in
1270 I tipi di carattere dei frammenti inseriti con LilyPond devono essere impostati
1271 all'interno dei frammenti stessi. Si legga il manuale di Uso dell'applicazione per
1272 sapere come usare lilypond-book.
1274 \selectlanguage{ngerman}
1275 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1277 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1278 unterst__tzt werden.
1283 @node Condividere l'indice
1284 @section Condividere l'indice
1285 @translationof Sharing the table of contents
1287 Queste funzioni sono già incluse nel pacchetto OrchestralLily:
1290 @url{http://repo.or.cz/w/orchestrallily.git}
1294 preferiscono esportare l'indice da lilypond e leggerlo da dentro
1295 @LaTeX{} per la sua maggiore flessibilità nella gestione del testo.
1297 @subsubheading Esportare l'indice da LilyPond
1299 Per questo esempio si presume che lo spartito abbia vari movimenti nello stesso file
1300 di output di lilypond.
1303 #(define (oly:create-toc-file layout pages)
1304 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1305 (if (not (null? label-table))
1306 (let* ((format-line (lambda (toc-item)
1307 (let* ((label (car toc-item))
1308 (text (caddr toc-item))
1309 (label-page (and (list? label-table)
1310 (assoc label label-table)))
1311 (page (and label-page (cdr label-page))))
1312 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1313 (formatted-toc-items (map format-line (toc-items)))
1314 (whole-string (string-join formatted-toc-items ",\n"))
1315 (output-name (ly:parser-output-name parser))
1316 (outfilename (format "~a.toc" output-name))
1317 (outfile (open-output-file outfilename)))
1318 (if (output-port? outfile)
1319 (display whole-string outfile)
1320 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1321 (close-output-port outfile)))))
1324 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1328 @subsubheading Importare l'indice in LaTeX
1330 In LaTeX l'intestazione deve includere:
1332 @c no, this doesn't require the smallexample, but since the other
1333 @c two blocks on this page use it, I figured I might as well
1334 @c user it here as well, for consistency. -gp
1336 \usepackage@{pdfpages@}
1337 \includescore@{nameofthescore@}
1341 dove @code{\includescore} viene definito in questo modo:
1344 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1345 % \includescore@{PossibleExtension@}
1346 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1348 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1349 % This requires some heave latex tweaking, since reading in things from a file
1350 % and inserting it into the arguments of a macro is not (easily) possible
1352 % Solution by Patrick Fimml on #latex on April 18, 2009:
1353 % \readfile@{filename@}@{\variable@}
1354 % reads in the contents of the file into \variable (undefined if file
1356 \newread\readfile@@f
1357 \def\readfile@@line#1@{%
1358 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1359 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1360 \ifeof\readfile@@f\else%
1361 \readfile@@line@{#1@}%
1364 \def\readfile#1#2@{%
1365 \openin\readfile@@f=#1 %
1367 \typeout@{No TOC file #1 available!@}%
1370 \readfile@@line@{#2@}%
1372 \closein\readfile@@f%
1376 \newcommand@{\includescore@}[1]@{
1377 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1378 \let\oly@@addtotoc\undefined
1379 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1380 \ifx\oly@@addtotoc\undefined
1381 \includepdf[pages=-]@{\oly@@fname@}
1383 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1384 @{\oly@@fname@}@}\includeit
1390 @node Metodi alternativi per combinare testo e musica
1391 @section Metodi alternativi per combinare testo e musica
1392 @translationof Alternate methods of mixing text and music
1394 Altri modi per combinare testo e musica (senza usare
1395 @command{lilypond-book}) sono trattati in
1396 @ref{LilyPond output in other programs}.