1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-
4 Translation of GIT committish: 7f48cb638958a728209577caa41bbaca8a2e4ef2
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 c'2 e2 \tuplet 3/2 { 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{@dots{}tagliato molto output@dots{}}
123 @emph{Compilazione di lilybook.tex...}
125 pdflatex lilybook.tex
126 @emph{@dots{}tagliato molto output@dots{}}
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 c'2 e2 \tuplet 3/2 { 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@{@dots{}@}}, dove si può inserire direttamente del
214 codice lilypond corto
217 l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, dove si può inserire
218 direttamente del codice lilypond più lungo
221 il comando @code{\lilypondfile@{@dots{}@}} per inserire un file lilypond
224 il comando @code{\musicxmlfile@{@dots{}@}} 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@}@dots{}\end@{lilypond@}
402 \onlyFirstNSystems@{1@}
403 \begin@{lilypond@}@dots{}\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@{@dots{}@}}, dove si può inserire direttamente del
428 codice lilypond corto
431 l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, dove si può inserire
432 direttamente del codice lilypond più lungo
435 il comando @code{\lilypondfile@{@dots{}@}} per inserire un file lilypond
438 il comando @code{\musicxmlfile@{@dots{}@}} 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@{@dots{}@}} 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@{@dots{}@}}, dove si può inserire direttamente del
507 codice lilypond corto
510 l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, dove si può inserire
511 direttamente del codice lilypond più lungo
514 il comando @code{\lilypondfile@{@dots{}@}} per inserire un file lilypond
517 il comando @code{\musicxmlfile@{@dots{}@}} 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 @dots{} />}, 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{opzione1} @var{opzione2} @dots{}>@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 @{ % 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}:
916 lilypond-book tuofile.lytex
918 dvips -Ppdf tuofile.dvi
923 Il file @file{.dvi} creato da questa sequenza non conterrà le
924 teste delle note. È normale; se si seguono le istruzioni, le teste
925 verranno incluse nei file @file{.ps} e @file{.pdf}.
927 L'esecuzione di @command{dvips} potrebbe generare dei messaggi di avviso
928 relativi ai caratteri; questi messaggi sono innocui e possono
929 essere ignorati. Se esegui @command{latex} in modalità due colonne, ricorda
930 di aggiungere @option{-t landscape} alle opzioni di @command{dvips}.
935 \begin@{lilypond@} @dots{} \end@{lilypond@}
939 non sono interpretati da @LaTeX{}. @code{lilypond-book} estrae questi
940 @q{ambienti} e li copia in file in un suo formato per poter eseguire
941 LilyPond su di essi. Prende quindi gli elementi grafici risultanti
942 e crea un file @file{.tex} dove le macro
943 @code{\begin@{lilypond@}}@dots{}@code{\end@{lilypond@}} sono poi
944 sostituite da comandi di @q{inclusione di immagini}. È a questo
945 punto che @LaTeX{} viene eseguito (anche se @LaTeX{} è stato eseguito
946 in precedenza, in realtà ha agito su un documento @q{vuoto} solo per
947 fare alcuni calcoli, come per esempio di @code{\linewidth}).
950 Il comando @code{\pageBreak} non funziona all'interno dell'ambiente
951 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}}.
953 Molte variabili del blocco @code{\paper} non funzionano all'interno dell'ambiente
954 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}}. Usa
955 @code{\newcommand} con @code{\betweenLilyPondSystem} nel preambolo;
958 \newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
962 @subsubheading Texinfo
964 Per generare un documento Texinfo (in qualsiasi formato di output), si seguono
965 le normali procedure usate con Texinfo; ovvero, si lancia @command{texi2pdf} o
966 @command{texi2dvi} o @command{makeinfo}, a seconda del formato di output
969 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, e @ref{Creating
970 an Info File, , , texinfo, GNU Texinfo}.
973 Si veda la documentazione di Texinfo per ulteriori dettagli.
977 @subheading Opzioni da linea di comando
979 @command{lilypond-book} accetta le seguenti opzioni da linea di comando:
982 @item -f @var{formato}
983 @itemx --format=@var{formato}
984 Specifica il tipo di documento da elaborare: @code{html}, @code{latex},
985 @code{texi} (il formato predefinito) o @code{docbook}. Se manca questa opzione,
986 @command{lilypond-book} cerca di rilevare il formato automaticamente, si veda
987 @ref{Filename extensions}. Attualmente, @code{texi} è equivalente a
990 @c This complicated detail is not implemented, comment it out -jm
992 The @code{texi} document type produces a Texinfo file with music
993 fragments in the printed output only. For getting images in the HTML
994 version, the format @code{texi-html} must be used instead.
997 @item -F @var{filtro}
998 @itemx --filter=@var{filtro}
999 Convoglia i frammenti attraverso il @var{filtro}. @code{lilypond-book} non
1000 esegue contemporaneamente il filtro e l'elaborazione. Ad esempio,
1003 lilypond-book --filter='convert-ly --from=2.0.0 -' mio-libro.tely
1008 Mostra un breve messaggio di aiuto.
1011 @itemx --include=@var{dir}
1012 Aggiunge @var{dir} al percorso di inclusione. @command{lilypond-book} cerca
1013 anche dei frammenti già compilati nel percorso di inclusione e non li riscrive
1014 nella directory di output, quindi in alcuni casi è necessario eseguire
1015 ulteriori comandi come @command{makeinfo} o @command{latex} con le stesse
1016 opzioni @option{-I @var{dir}}.
1018 @item -l @var{loglevel}
1019 @itemx --loglevel=@var{loglevel}
1020 Imposta la verbosità dell'output su @var{loglevel}. I valori possibili sono @code{NONE},
1021 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (predefinito) e @code{DEBUG}. Se
1022 questa opzione non viene usata e la variabile d'ambiente @code{LILYPOND_BOOK_LOGLEVEL}
1023 è impostata, il suo valore viene usato come loglevel.
1026 @itemx --output=@var{dir}
1027 Salva i file generati nella directory @var{dir}. L'esecuzione di
1028 @command{lilypond-book} genera tanti piccoli file che LilyPond
1029 elaborerà. Per evitare tutto questo disordine nella directory dei
1030 sorgenti, si usa l'opzione da linea di comando @option{--output}
1031 e si entra in questa directory prima di eseguire @command{latex}
1032 o @command{makeinfo}.
1035 lilypond-book --output=out tuofile.lytex
1040 @item --skip-lily-check
1041 Non si arresta se non viene trovato l'output di lilypond. Viene usata per la
1042 documentazione Info di LilyPond, che è priva di immagini.
1044 @item --skip-png-check
1045 Non si arresta se non vengono trovate immagini PNG per i file EPS. Viene usata
1046 per la documentazione Info di LilyPond, che è priva di immagini.
1048 @item --lily-output-dir=@var{dir}
1049 Scrive i file lily-XXX nella directory @var{dir}, crea un link nella
1050 directory @option{--output}. Si usa questa opzione per risparmiare tempo nella
1051 compilazione di documenti situati in directory diverse che condividono
1052 molti identici frammenti.
1054 @item --lily-loglevel=@var{loglevel}
1055 Set the output verbosity of the invoked @command{lilypond} calls to @var{loglevel}.
1056 I valori possibili sono @code{NONE}, @code{ERROR}, @code{WARNING}, @code{BASIC_PROGRESS},
1057 @code{PROGRESS}, @code{INFO} (predefinito) e @code{DEBUG}. Se questa opzione
1058 non viene usata e la variabile d'ambiente @code{LILYPOND_LOGLEVEL} è
1059 impostata, il suo valore viene usato come loglevel.
1061 @item --info-images-dir=@var{dir}
1062 Formatta l'output di Texinfo in modo che Info cerchi le immagini della musica
1065 @item --latex-program=@var{prog}
1066 Lancia l'eseguibile @command{prog} invece di @command{latex}. Questa opzione
1067 è utile, ad esempio, se il documento è elaborato con @command{xelatex}.
1069 @item --left-padding=@var{quantità}
1070 Crea una spaziatura corrispondente a questa quantità tra i riquadri EPS. @var{quantità} è
1071 misurata in millimetri e il valore predefinito è 3.0. Questa opzione si usa
1072 se i righi dello spartito oltrepassano il margine destro.
1074 La larghezza di un sistema molto denso può variare in base agli elementi
1075 della notazione attaccati al margine sinistro, come i numeri di battuta e
1076 i nomi degli strumenti. Questa opzione accorcia tutte le linee e le sposta a
1077 a destra della stessa quantità.
1079 @item -P @var{comando}
1080 @itemx --process=@var{comando}
1081 Elabora i frammenti di LilyPond con @var{comando}. Il comando predefinito è
1082 @code{lilypond}. @code{lilypond-book} non userà @option{--filter} e
1083 @option{--process} contemporaneamente.
1086 Crea file PDF da usare con PDF@LaTeX{}.
1088 @item --redirect-lilypond-output
1089 Per impostazione predefinita, l'output viene mostrato sul terminale. Questa
1090 opzione redirige tutto l'output in dei file di log nella stessa directory dei
1093 @item --use-source-file-names
1094 Salva i file di output dei frammenti con lo stesso nome, esclusa l'estensione,
1095 dei sorgenti. Questa opzione funziona solo con i frammenti inclusi con
1096 @code{lilypondfile} e solo se le directory indicate da @option{--output-dir} e
1097 @option{--lily-output-dir} sono diverse.
1101 Mostra un output dettagliato. Questo è equivalente a @code{--loglevel=DEBUG}.
1105 Mostra informazioni sulla versione.
1110 Il comando Texinfo @code{@@pagesizes} non viene interpretato. Allo stesso
1111 modo, i comandi @LaTeX{} che modificano i margini e la larghezza della linea
1112 dopo il preambolo vengono ignorati.
1114 Solo il primo @code{\score} di un blocco LilyPond viene elaborato.
1117 @node Estensioni dei nomi di file
1118 @section Estensioni dei nomi di file
1119 @translationof Filename extensions
1121 Si può usare qualsiasi estensione per il file di input, ma se non si usa
1122 l'estensione raccomandata per uno specifico formato potrebbe essere
1123 necessario specificare a mano il formato di output; per i dettagli si veda
1124 @ref{Invoking lilypond-book}. Altrimenti, @command{lilypond-book} sceglie
1125 automaticamente il formato di output in base all'estensione del file di input.
1128 @multitable @columnfractions .2 .5
1129 @item @strong{estensione} @tab @strong{formato di output}
1131 @item @file{.html} @tab HTML
1132 @item @file{.htmly} @tab HTML
1133 @item @file{.itely} @tab Texinfo
1134 @item @file{.latex} @tab @LaTeX{}
1135 @item @file{.lytex} @tab @LaTeX{}
1136 @item @file{.lyxml} @tab DocBook
1137 @item @file{.tely} @tab Texinfo
1138 @item @file{.tex} @tab @LaTeX{}
1139 @item @file{.texi} @tab Texinfo
1140 @item @file{.texinfo} @tab Texinfo
1141 @item @file{.xml} @tab HTML
1145 Se si usa per il file di input la stessa estensione che @command{lilypond-book}
1146 usa per il file di output e se il file di input è nella stessa directory
1147 in cui lavora @command{lilypond-book}, bisogna usare l'opzione @option{--output}
1148 per far sì che @command{lilypond-book} sia eseguito; altrimenti si ferma e
1149 mostra un messaggio di errore simile a @qq{L'output sovrascriverebbe il file di input}.
1152 @node Modelli per lilypond-book
1153 @section Modelli per lilypond-book
1154 @translationof lilypond-book templates
1156 Ecco alcuni modelli da usare con @code{lilypond-book}. Se non hai familiarità
1157 con questo programma, consulta @ref{lilypond-book}.
1161 Si possono includere frammenti LilyPond in un documento LaTeX.
1164 \documentclass[]@{article@}
1168 Normale testo LaTeX.
1176 Altro testo LaTeX, seguito da alcune opzioni tra parentesi quadre.
1178 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1186 Si possono includere frammenti LilyPond in Texinfo; infatti questo intero
1187 manuale è scritto in Texinfo.
1190 \input texinfo @c -*-texinfo-*-
1202 Altro testo Texinfo, seguito dalle opzioni tra parentesi.
1204 @@lilypond[verbatim,fragment,ragged-right]
1215 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1221 I documenti per lilypond-book possono combinare liberamente musica e testo. Ad
1231 Ancora un po' di Lilypond, questa volta con delle opzioni:
1233 <lilypond fragment quote staffsize=26 verbatim>
1247 \documentclass{article}
1248 \usepackage{ifxetex}
1250 %elementi specifici di xetex
1251 \usepackage{xunicode,fontspec,xltxtra}
1252 \setmainfont[Numbers=OldStyle]{Times New Roman}
1255 %Questo può essere lasciato vuoto se non si usa pdftex
1256 \usepackage[T1]{fontenc}
1257 \usepackage[utf8]{inputenc}
1258 \usepackage{mathptmx}%Times
1259 \usepackage{helvet}%Helvetica
1261 %Qui è possibile inserire tutti i pacchetti inclusi anche in pdftex
1262 \usepackage[ngerman,finnish,english]{babel}
1263 \usepackage{graphicx}
1266 \title{Un breve documento con LilyPond e xelatex}
1269 I comandi abituali di \textbf{font} interni al \emph{testo} funzionano,
1270 perché \textsf{sono supportati da \LaTeX{} e XeteX.}
1271 Se vuoi usare comandi specifici come \verb+\XeTeX+, devi
1272 includerli nuovamente in un ambiente \verb+\ifxetex+.
1273 You can use this to print the \ifxetex \XeTeX{} command \else
1274 XeTeX command \fi which is not known to normal \LaTeX .
1276 Nel testo normale si possono usare semplicemente i comandi LilyPond, come in
1286 I tipi di carattere dei frammenti inseriti con LilyPond devono essere impostati
1287 all'interno dei frammenti stessi. Si legga il manuale di Uso dell'applicazione per
1288 sapere come usare lilypond-book.
1290 \selectlanguage{ngerman}
1291 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1293 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1294 unterst__tzt werden.
1299 @node Condividere l'indice
1300 @section Condividere l'indice
1301 @translationof Sharing the table of contents
1303 Queste funzioni sono già incluse nel pacchetto OrchestralLily:
1306 @url{http://repo.or.cz/w/orchestrallily.git}
1310 preferiscono esportare l'indice da lilypond e leggerlo da dentro
1311 @LaTeX{} per la sua maggiore flessibilità nella gestione del testo.
1313 @subsubheading Esportare l'indice da LilyPond
1315 Per questo esempio si presume che lo spartito abbia vari movimenti nello stesso file
1316 di output di lilypond.
1319 #(define (oly:create-toc-file layout pages)
1320 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1321 (if (not (null? label-table))
1322 (let* ((format-line (lambda (toc-item)
1323 (let* ((label (car toc-item))
1324 (text (caddr toc-item))
1325 (label-page (and (list? label-table)
1326 (assoc label label-table)))
1327 (page (and label-page (cdr label-page))))
1328 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1329 (formatted-toc-items (map format-line (toc-items)))
1330 (whole-string (string-join formatted-toc-items ",\n"))
1331 (output-name (ly:parser-output-name))
1332 (outfilename (format "~a.toc" output-name))
1333 (outfile (open-output-file outfilename)))
1334 (if (output-port? outfile)
1335 (display whole-string outfile)
1336 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1337 (close-output-port outfile)))))
1340 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1344 @subsubheading Importare l'indice in LaTeX
1346 In LaTeX l'intestazione deve includere:
1348 @c no, this doesn't require the smallexample, but since the other
1349 @c two blocks on this page use it, I figured I might as well
1350 @c user it here as well, for consistency. -gp
1352 \usepackage@{pdfpages@}
1353 \includescore@{nameofthescore@}
1357 dove @code{\includescore} viene definito in questo modo:
1360 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1361 % \includescore@{PossibleExtension@}
1362 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1364 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1365 % This requires some heave latex tweaking, since reading in things from a file
1366 % and inserting it into the arguments of a macro is not (easily) possible
1368 % Solution by Patrick Fimml on #latex on April 18, 2009:
1369 % \readfile@{filename@}@{\variable@}
1370 % reads in the contents of the file into \variable (undefined if file
1372 \newread\readfile@@f
1373 \def\readfile@@line#1@{%
1374 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1375 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1376 \ifeof\readfile@@f\else%
1377 \readfile@@line@{#1@}%
1380 \def\readfile#1#2@{%
1381 \openin\readfile@@f=#1 %
1383 \typeout@{No TOC file #1 available!@}%
1386 \readfile@@line@{#2@}%
1388 \closein\readfile@@f%
1392 \newcommand@{\includescore@}[1]@{
1393 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1394 \let\oly@@addtotoc\undefined
1395 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1396 \ifx\oly@@addtotoc\undefined
1397 \includepdf[pages=-]@{\oly@@fname@}
1399 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1400 @{\oly@@fname@}@}\includeit
1406 @node Metodi alternativi per combinare testo e musica
1407 @section Metodi alternativi per combinare testo e musica
1408 @translationof Alternate methods of mixing text and music
1410 Altri modi per combinare testo e musica (senza usare
1411 @command{lilypond-book}) sono trattati in
1412 @ref{LilyPond output in other programs}.