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
30 @ref{Uso da linea di comando}. In caso di problemi nell'eseguire
31 @code{lilypond-book} da linea di comando su Windows o Mac OS X, si veda
32 @rweb{Windows} o @rweb{MacOS X}.
34 Questo procedimento può essere applicato ai documenti @LaTeX{}, HTML, Texinfo
43 @cindex documenti, aggiungere musica
44 @cindex HTML, aggiungere musica
45 @cindex Texinfo, aggiungere musica
46 @cindex DocBook, aggiungere musica
47 @cindex LaTeX, aggiungere musica
50 * Un esempio di documento musicologico::
51 * Integrare musica e testo::
52 * Opzioni dei frammenti musicali::
53 * Utilizzo di lilypond-book::
54 * Estensioni dei nomi di file::
55 * Modelli per lilypond-book::
56 * Condividere l'indice::
57 * Metodi alternativi per combinare testo e musica::
61 @node Un esempio di documento musicologico
62 @section Un esempio di documento musicologico
63 @translationof An example of a musicological document
66 Alcuni testi contengono degli esempi musicali: si tratta di
67 trattati musicologici, canzonieri o manuali come questo. È possibile
68 crearli a mano, semplicemente importando un'immagine PostScript
69 nell'elaboratore di testo. Tuttavia esiste una procedura automatizzata
70 che permette di ridurre il carico di lavoro richiesto dai documenti in
71 formato HTML, @LaTeX{}, Texinfo e DocBook.
73 Uno script chiamato @code{lilypond-book} estrarrà i frammenti musicali, li
74 formatterà e restituirà la notazione risultante. Ecco un piccolo esempio
75 da usare con @LaTeX{}. L'esempio contiene anche del testo esplicativo,
76 dunque non è necessario entrare nei dettagli.
82 \documentclass[a4paper]{article}
86 I documenti per \verb+lilypond-book+ possono combinare liberamente musica e testo.
91 c'2 e2 \tuplet 3/2 { f8 a b } a2 e4
95 Le opzioni vengono specificate tra parentesi quadre.
97 \begin{lilypond}[fragment,quote,staffsize=26,verbatim]
101 Se l'esempio è più grande, è possibile metterlo in un file separato e inserirlo
102 con \verb+\lilypondfile+.
104 \lilypondfile[quote,noindent]{screech-and-boink.ly}
106 (Se vuoi provare, sostituisci @file{screech-and-boink.ly} con qualsiasi file @file{.ly}
107 che si trovi nella stessa directory di questo file.)
113 @subheading Elaborazione
115 Salva il codice precedente in un file chiamato @file{lilybook.lytex}, quindi
116 esegui in un terminale
118 @c keep space after @version{} so TeX doesn't choke
120 lilypond-book --output=out --pdf lilybook.lytex
121 @emph{lilypond-book (GNU LilyPond) @version{} }
122 @emph{Lettura di lilybook.lytex...}
123 @emph{@dots{}tagliato molto output@dots{}}
124 @emph{Compilazione di lilybook.tex...}
126 pdflatex lilybook.tex
127 @emph{@dots{}tagliato molto output@dots{}}
129 @emph{(sostituisci @command{xpdf} col tuo lettore PDF preferito)}
132 L'esecuzione di @command{lilypond-book} e @command{pdflatex} crea molti file
133 temporanei e questo potrebbe rendere disordinata la directory di lavoro. Per
134 ovviare a questo inconveniente, è consigliabile usare l'opzione @code{--output=@var{dir}}. In questo
135 modo i file verranno salvati in una sottodirectory @file{dir} separata.
137 Infine ecco il risultato dell'esempio in @LaTeX{}.@footnote{Questo
138 tutorial è elaborato da Texinfo, dunque l'esempio produce dei risultati
139 leggermente diversi nella formattazione.} Si conclude qui la parte di
146 I documenti per @command{lilypond-book} possono combinare liberamente musica
151 c'2 e2 \tuplet 3/2 { f8 a b } a2 e4
155 Le opzioni vengono specificate tra parentesi quadre.
157 @lilypond[fragment,quote,staffsize=26,verbatim]
161 Se l'esempio è più grande, è possibile riportarlo in un file a parte e inserirlo
162 con \verb+\lilypondfile+.
164 @lilypondfile[quote,noindent]{screech-and-boink.ly}
166 Perché sia visibile la @code{tagline}, predefinita o personalizzata, l'intero
167 frammento deve essere compreso in un costrutto @code{\book @{ @}}.
169 @lilypond[papersize=a8,verbatim]
172 title = "Una scala in LilyPond"
183 @node Integrare musica e testo
184 @section Integrare musica e testo
185 @translationof Integrating music and text
187 Questa sezione spiega come integrare LilyPond in vari formati di output.
199 @LaTeX{} costituisce lo standard de facto per le pubblicazioni nell'ambito
200 delle scienze esatte. Si basa sul motore tipografico @TeX{}, che produce la
201 migliore qualità tipografica possibile.
204 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
205 @emph{The Not So Short Introduction to @LaTeX{}}} per una panoramica
206 sull'uso di @LaTeX{}.
208 @code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
209 la musica nei file @LaTeX{}:
214 il comando @code{\lilypond@{@dots{}@}}, dove si può inserire direttamente del
215 codice lilypond corto
218 l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, dove si può inserire
219 direttamente del codice lilypond più lungo
222 il comando @code{\lilypondfile@{@dots{}@}} per inserire un file lilypond
225 il comando @code{\musicxmlfile@{@dots{}@}} per inserire un file MusicXML, che
226 sarà elaborato da @code{musicxml2ly} e da @code{lilypond}.
230 Nel file di input, la musica viene specificata con uno dei seguenti comandi:
233 \begin@{lilypond@}[le,opzioni,vanno,qui]
237 \lilypond[le,opzioni,vanno,qui]@{ CODICE LILYPOND @}
239 \lilypondfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
241 \musicxmlfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
246 Inoltre, @code{\lilypondversion} mostra la versione
247 di lilypond impiegata.
248 L'esecuzione di @command{lilypond-book} produce un file che può essere
249 ulteriormente elaborato con @LaTeX{}.
251 Vediamo alcuni esempi. L'ambiente @code{lilypond}
254 \begin@{lilypond@}[quote,fragment,staffsize=26]
262 @lilypond[quote,fragment,staffsize=26]
269 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
275 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
278 Attualmente non è possibile includere @code{@{} o @code{@}} all'interno di
279 @code{\lilypond@{@}}, dunque questo comando è utile solo se usato con
280 l'opzione @code{fragment}.
282 La lunghezza predefinita del rigo musicale sarà regolata in base ai
283 comandi presenti nel preambolo del documento, ovvero la parte del documento
284 che precede @code{\begin@{document@}}. Il comando @command{lilypond-book}
285 li invia a @LaTeX{} per definire la larghezza del testo. La larghezza del
286 rigo nei frammenti musicali è quindi regolato in base alla larghezza del
287 testo. Si noti che questo algoritmo euristico può fallire facilmente; in
288 questi casi occorre usare l'opzione @code{line-width} nel frammento musicale.
290 @cindex titoli e lilypond-book
291 @cindex \header nei documenti @LaTeX{}
293 Ogni frammento chiamerà le seguenti macro se sono state definite
297 @item @code{\preLilyPondExample} prima della musica,
299 @item @code{\postLilyPondExample} dopo la musica,
301 @item @code{\betweenLilyPondSystem[1]} tra i sistemi, se
302 @code{lilypond-book} ha diviso il frammento in più file
303 PostScript. Prende un parametro e riceve
304 tutti i file già inclusi in questo frammento.
305 Per impostazione predefinita inserisce semplicemente un @code{\linebreak}.
311 @cindex Latex, feta symbols
314 To include feta symbols (such as flat, segno, etc) in a LaTeX
315 document, use @code{\input@{titledefs@}}
318 \documentclass[a4paper]@{article@}
329 The font symbol names are defined in the file feta20.tex; to find
330 the location of this file, use the command
340 Talvolta si ha necessità di mostrare degli elementi musicali (ad esempio le
341 legature di portamento e di valore) che proseguono dopo la fine del
342 frammento. È possibile inserirli mandando il rigo a capo e
343 impedendo l'inclusione del restante output di LilyPond.
345 In @LaTeX{}, si definisce @code{\betweenLilyPondSystem} in modo tale che
346 l'inclusione di altri sistemi venga terminata una volta incluso il
347 numero di sistemi richiesti. Dato che @code{\betweenLilyPondSystem} viene
348 chiamato la prima volta @emph{dopo} il primo sistema, includere solo il primo
352 \def\betweenLilyPondSystem#1@{\endinput@}
354 \begin@{lilypond@}[fragment]
355 c'1\( e'( c'~ \break c' d) e f\)
359 Se serve una maggior quantità di sistemi, occorre usare un condizionale
360 @TeX{} prima di @code{\endinput}. In questo esempio, sostituisci @q{2} col
361 numero di sistemi che desideri avere nell'output.
364 \def\betweenLilyPondSystem#1@{
365 \ifnum#1<2\else\expandafter\endinput\fi
370 (Dato che @code{\endinput} arresta immediatamente l'elaborazione del file di
371 input corrente, occorre usare @code{\expandafter} per ritardare la chiamata di
372 @code{\endinput} e far sì che avvenga dopo l'esecuzione di @code{\fi}, in modo
373 da bilanciare la condizione @code{\if}-@code{\fi}.)
375 Ricorda che la definizione di @code{\betweenLilyPondSystem} è
376 efficace finché @TeX{} esce dal gruppo attuale (ad esempio l'ambiente
377 @LaTeX{}) o è sovrascritto da un'altra definizione (che vale, in
378 gran parte dei casi, per il resto del documento). Per reimpostare
379 la definizione, si scrive
382 \let\betweenLilyPondSystem\undefined
386 nel sorgente @LaTeX{}.
388 Si potrebbe semplificare la procedura creando una macro @TeX{}
391 \def\onlyFirstNSystems#1@{
392 \def\betweenLilyPondSystem##1@{%
393 \ifnum##1<#1\else\expandafter\endinput\fi@}
398 e poi specificando prima di ogni frammento la quantità di sistemi desiderata,
401 \onlyFirstNSystems@{3@}
402 \begin@{lilypond@}@dots{}\end@{lilypond@}
403 \onlyFirstNSystems@{1@}
404 \begin@{lilypond@}@dots{}\end@{lilypond@}
409 Esistono opzioni specifiche da linea di comando per @command{lilypond-book} e
410 altri dettagli da conoscere quando si elaborano documenti @LaTeX{}; si veda
411 @ref{Utilizzo di lilypond-book}.
416 @translationof Texinfo
418 Texinfo è il formato standard per la documentazione del progetto GNU. Un
419 esempio di documento Texinfo è questo stesso manuale. Le versioni del manuale
420 in formato HTML, PDF e Info vengono generate da un documento Texinfo.
422 @code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
423 musica nei file Texinfo:
428 il comando @code{\lilypond@{@dots{}@}}, dove si può inserire direttamente del
429 codice lilypond corto
432 l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, dove si può inserire
433 direttamente del codice lilypond più lungo
436 il comando @code{\lilypondfile@{@dots{}@}} per inserire un file lilypond
439 il comando @code{\musicxmlfile@{@dots{}@}} per inserire un file MusicXML, che
440 sarà elaborato da @code{musicxml2ly} e da @code{lilypond}.
444 Nel file di input, la musica viene specificata con uno dei seguenti comandi
447 @@lilypond[le,opzioni,vanno,qui]
448 IL TUO CODICE LILYPOND
451 @@lilypond[le,opzioni,vanno,qui]@{ IL TUO CODICE LILYPOND @}
453 @@lilypondfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
455 @@musicxmlfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
458 Inoltre, @code{@@lilypondversion} mostra la versione di
461 Quando si esegue @command{lilypond-book} su di esso, il risultato è un
462 file Texinfo (con estensione @file{.texi}) contenente degli elementi @code{@@image}
463 per l'HTML, Info e l'output per la stampa. @command{lilypond-book} genera le
464 immagini della musica in formati EPS e PDF per l'utilizzo nell'output per la
465 stampa e in formato PNG per l'utilizzo nell'output HTML e Info.
467 Vediamo due piccoli esempi. Un ambiente @code{lilypond}
485 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
491 @lilypond[fragment,staffsize=11]{<c' e' g'>}
493 Diversamente da @LaTeX{}, @code{@@lilypond@{@dots{}@}} non genera un'immagine
494 nel testo. Prende sempre un paragrafo proprio.
501 @code{lilypond-book} fornisce i seguenti comandi e ambienti per includere
502 musica nei file HTML:
507 il comando @code{\lilypond@{@dots{}@}}, dove si può inserire direttamente del
508 codice lilypond corto
511 l'ambiente @code{\begin@{lilypond@}@dots{}\end@{lilypond@}}, dove si può inserire
512 direttamente del codice lilypond più lungo
515 il comando @code{\lilypondfile@{@dots{}@}} per inserire un file lilypond
518 il comando @code{\musicxmlfile@{@dots{}@}} per inserire un file MusicXML, che
519 sarà elaborato da @code{musicxml2ly} e da @code{lilypond}.
523 Nel file di input, la musica viene specificata con uno dei seguenti comandi:
525 \begin@{lilypond@}[le,opzioni,vanno,qui]
529 \lilypond[le,opzioni,vanno,qui]@{ CODICE LILYPOND @}
531 \lilypondfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
533 \musicxmlfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
535 <lilypond le opzioni vanno qui>
539 <lilypond le opzioni vanno qui: CODICE LILYPOND />
541 <lilypondfile le opzioni vanno qui>@var{nomefile}</lilypondfile>
543 <musicxmlfile le opzioni vanno qui>@var{nomefile}</musicxmlfile>
546 Ad esempio, puoi scrivere
549 <lilypond fragment relative=2>
550 \key c \minor c4 es g2
555 @command{lilypond-book} genera quindi un file HTML con gli elementi appropriati
556 per le immagini dei frammenti musicali:
558 @lilypond[fragment,relative=2]
559 \key c \minor c4 es g2
562 Per le immagini in linea, si usa @code{<lilypond @dots{} />}, dove le opzioni
563 sono distinte dalla musica attraverso i due punti, ad esempio
566 Un po' di musica in <lilypond relative=2: a b c/> una linea di testo.
569 Per includere file separati, si usa
572 <lilypondfile @var{opzione1} @var{opzione2} @dots{}>@var{filename}</lilypondfile>
575 @code{<musicxmlfile>} usa la stessa sintassi di @code{<lilypondfile>}, ma semplicemente
576 si riferisce a un file MusicXML invece che a un file LilyPond.
578 Per una lista di opzioni da usare con gli elementi @code{lilypond} e
579 @code{lilypondfile}, si veda @ref{Opzioni dei frammenti musicali}.
581 Inoltre, @code{<lilypondversion/>} mostra la versione di
585 @cindex titoli in HTML
586 @cindex immagine di anteprima
591 @translationof DocBook
593 Per inserire frammenti di codice LilyPond è una buona idea mantenere la
594 conformità del documento DocBook, in modo da poter usare gli editor DocBook, la
595 validazione, etc. Quindi non si usano elementi personalizzati, ma si
596 specifica una convenzione basata sugli elementi DocBook standard.
598 @subheading Convenzioni comuni
600 Per inserire un frammento di qualsiasi tipo si usano gli elementi @code{mediaobject}
601 e @code{inlinemediaobject}, in modo che il frammento possa essere formattato
602 in linea o meno. Le opzioni di formattazione del frammento vengono sempre
603 indicate nella proprietà @code{role} dell'elemento più interno (si vedano
604 le prossime sezioni). Gli elementi sono scelti in modo da permettere agli editor
605 DocBook di ottenere una formattazione ottimale. I file DocBook da
606 elaborare con @command{lilypond-book} devono avere estensione @file{.lyxml}.
608 @subheading Includere un file LilyPond
610 Si tratta del caso più semplice. Bisogna usare l'estensione @file{.ly} per
611 il file da includere e inserirlo come uno standard @code{imageobject}, con
612 la seguente struttura:
617 <imagedata fileref="music1.ly" role="printfilename" />
622 Nota che sei libero di usare @code{mediaobject} o @code{inlinemediaobject}
623 come elemento più esterno.
625 @subheading Includere codice LilyPond
627 È possibile includere codice LilyPond all'interno di un elemento
628 @code{programlisting} in cui il linguaggio sia impostato su @code{lilypond}
629 e con la seguente struttura:
634 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
635 \context Staff \with @{
636 \remove "Time_signature_engraver"
637 \remove "Clef_engraver"@}
644 Come si vede, l'elemento più esterno è @code{mediaobject} o
645 @code{inlinemediaobject} e c'è un @code{textobject} che contiene al
646 suo interno il @code{programlisting}.
648 @subheading Elaborare il documento DocBook
650 L'esecuzione di @command{lilypond-book} su un file @file{.lyxml} creerà un
651 documento DocBook valido con estensione @file{.xml} che potrà essere
652 ulteriormente elaborato. Usando
653 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, creerà automaticamente un file
654 PDF da questo documento. Per generare l'HTML (HTML Help,
655 JavaHelp etc.) si possono usare i fogli di stile DocBook XSL ufficiali;
656 tuttavia è possibile che sia necessario modificarli un po'.
659 @node Opzioni dei frammenti musicali
660 @section Opzioni dei frammenti musicali
661 @translationof Music fragment options
663 Nelle pagine che seguono, per @q{comando LilyPond} si intende un qualsiasi
664 comando descritto nelle sezioni precedenti che sia gestito da @command{lilypond-book}
665 per produrre un frammento musicale. Per semplicità, i comandi LilyPond vengono
666 mostrati soltanto nella sintassi @LaTeX{}.
668 Nota che la stringa delle opzioni è analizzata da sinistra a destra; se un'opzione
669 ricorre più di una volta, viene applicata nella sua ultima occorrenza.
671 Sono disponibili le seguenti opzioni per i comandi LilyPond:
674 @item staffsize=@var{altezza}
675 Imposta la dimensione del pentagramma a @var{altezza}, misurata in punti.
678 Produce linee con margine destro irregolare e spaziatura naturale, ovvero
679 viene aggiunto @code{ragged-right = ##t} al frammento LilyPond. Frammenti
680 con un solo rigo avranno sempre il margine destro irregolare, a meno che
681 non venga specificato esplicitamente @code{noragged-right}.
684 Per i frammenti di una sola linea, fa sì che la lunghezza del rigo venga estesa
685 fino a coincidere con la larghezza della linea, ovvero viene aggiunto
686 @code{ragged-right = ##f} al frammento LilyPond.
689 @itemx line-width=@var{dimensione}\@var{unità}
690 Imposta la lunghezza della linea a @var{dimensione}, usando @var{unità} come
691 unità di misura. @var{unità} può essere una delle seguenti stringhe: @code{cm},
692 @code{mm}, @code{in} o @code{pt}. Questa opzione riguarda l'output LilyPond
693 (ovvero, la lunghezza del rigo del frammento musicale), non la formattazione
696 Se usato senza un argomento, imposta la lunghezza della linea a un valore
697 predefinito (calcolato da un algoritmo euristico).
699 Se non viene assegnata un'opzione @code{line-width}, @command{lilypond-book}
700 cerca di indovinare un valore predefinito per gli ambienti @code{lilypond} che
701 non usano l'opzione @code{ragged-right}.
703 @item papersize=@var{stringa}
704 Dove @var{stringa} è una delle dimensioni del foglio definite in @file{scm/paper.scm},
705 ad esempio @code{a5}, @code{quarto}, @code{11x17} etc.
707 I valori non definiti in @file{scm/paper.scm} saranno ignorati, sarà inviato
708 un messaggio di avviso e al frammento sarà assegnata la dimensione predefinita,
712 Non viene visualizzata l'indicazione di tempo e disabilita i segni relativi alla scansione ritmica
713 (segno di tempo, barre di divisione) nella partitura.
716 Fa sì che @command{lilypond-book} aggiunga del codice boilerplate in modo che
717 sia possibile inserire semplicemente, ad esempio,
724 senza @code{\layout}, @code{\score}, etc.
727 Non aggiunge del codice ulteriore per completare il codice LilyPond nei frammenti
728 musicali. Essendo l'impostazione predefinita, @code{nofragment} di norma
731 @item indent=@var{dimensione}\@var{unità}
732 Imposta l'indentazione del primo sistema musicale a @var{dimensione}, usando
733 @var{unità} come unità di misura. @var{unità} è una delle seguenti stringhe:
734 @code{cm}, @code{mm}, @code{in} o @code{pt}. Questa opzione riguarda
735 LilyPond, non la formattazione del testo.
738 Imposta l'indentazione del primo sistema musicale su zero. Questa opzione
739 interessa LilyPond, non la formattazione del testo. L'assenza di indentazione è
740 l'impostazione predefinita, dunque normalmente @code{noindent} è ridondante.
743 Riduce la lunghezza della linea di un frammento musicale di @math{2*0.4}@dmn{in}
744 e inserisce l'output in un blocco per le citazioni. Il valore @q{0.4@dmn{in}}
745 può essere controllato con l'opzione @code{exampleindent}.
748 Imposta la quantità di spazio con cui l'opzione @code{quote} indenta un
752 @itemx relative=@var{n}
753 Usa la modalità di ottava relativa. Per impostazione predefinita, le altezze delle note
754 sono riferite al Do@tie{}centrale. L'argomento opzionale del numero intero
755 specifica l'ottava della nota iniziale: il valore predefinito @code{1} è il
756 Do centrale. L'opzione @code{relative} funziona solo quando è impostata
757 l'opzione @code{fragment}, quindi @code{fragment} è implicitamente sottinteso
758 da @code{relative}, a prescindere dalla presenza dell'opzione @code{(no)fragment}
762 LilyPond usa @command{lilypond-book} anche per produrre la propria
763 documentazione. A questo scopo, esistono altre opzioni più complesse
764 per i frammenti musicali.
768 L'argomento di un comando LilyPond viene copiato nel file di output e racchiuso
769 in un blocco di testo, seguito da qualsiasi testo assegnato con l'opzione
770 @code{intertext} (non ancora implementato); quindi viene mostrata la musica
771 vera e propria. Questa opzione non funziona bene con @code{\lilypond@{@}} se
772 fa parte di un paragrafo.
774 Se @code{verbatim} viene usato in un comando @code{lilypondfile}, è possibile
775 includere il testo di una parte soltanto del file sorgente. Se il file
776 sorgente ha un commento contenente @samp{begin verbatim} (senza
777 virgolette), la citazione del sorgente nel blocco testuale inizierà dopo
778 l'ultima occorrenza di tale commento; in modo analogo, la citazione del testo
779 sorgente si fermerà proprio prima della prima occorrenza di un commento
780 contenente @samp{end verbatim}, se presente. Nel seguente file sorgente di
781 esempio, la musica viene interpretata in modalità relativa ma il blocco
782 testuale non mostrerà il blocco @code{relative}, ovvero
785 \relative @{ % begin verbatim
792 mostrerà il seguente blocco testuale
800 Se si desidera tradurre i commenti e i nomi delle variabili nell'output
801 verbatim ma non nei sorgenti, si può impostare la variabile d'ambiente
802 @code{LYDOC_LOCALEDIR} sul percorso di una directory; la directory deve
803 contenere un albero dei cataloghi di messaggio @file{.mo} che hanno
804 @code{lilypond-doc} come dominio.
807 (Solo per l'output Texinfo.) Aggiunge @code{\version
808 @@w@{"@@version@{@}"@}} nella prima riga dell'output di @code{verbatim}.
811 (Solo per l'output Texinfo.) Se @command{lilypond} viene lanciato con
812 l'opzione @option{--header=@/texidoc} e il file da elaborare si
813 chiama @file{foo.ly}, verrà creato un file @file{foo.texidoc} a patto che
814 ci sia un campo @code{texidoc} nel blocco @code{\header}. L'opzione @code{texidoc}
815 fa sì che @command{lilypond-book} includa tali file, aggiungendo il loro
816 contenuto in forma di blocco di documentazione proprio prima del frammento
817 di musica (ma fuori dall'ambiente @code{example} generato da un'opzione
820 Se il file @file{foo.ly} contiene
824 texidoc = "Questo file mostra il funzionamento di una singola nota."
830 e il documento Texinfo @file{test.texinfo} contiene
833 @@lilypondfile[texidoc]@{foo.ly@}
837 il seguente comando produce il risultato atteso
840 lilypond-book --pdf --process="lilypond \
841 -dbackend=eps --header=texidoc" test.texinfo
844 Per la maggior parte, i documenti di test di LilyPond (nella directory @file{input}
845 della distribuzione) sono piccoli file @file{.ly} che hanno esattamente questo
848 Ai fini della localizzazione, se il documento Texinfo document contiene
849 @code{@@documentlanguage @var{LANG}} e l'header di @file{foo.ly}
850 contiene un campo @code{texidoc@var{LANG}}, quando si lancia @command{lilypond}
851 con l'opzione @option{--header=@/texidoc@var{LANG}} verrà incluso
852 @file{foo.texidoc@var{LANG}} invece di @file{foo.texidoc}.
855 (Solo per l'output Texinfo.) Questa opzione funziona in modo simile
856 all'opzione @code{texidoc}: se @command{lilypond} viene lanciato con
857 l'opzione @option{--header=@/doctitle} e il file da elaborare si chiama
858 @file{foo.ly} e contiene un campo @code{doctitle} nel blocco
859 @code{\header}, viene creato un file @file{foo.doctitle}. Se si usa
860 l'opzione @code{doctitle}, i contenuti di @file{foo.doctitle},
861 che dovrebbero trovarsi su una singola linea di @var{text}, vengono inseriti
862 nel documento Texinfo come @code{@@lydoctitle @var{text}}.
863 @code{@@lydoctitle} è una macro definita nel documento Texinfo.
864 Lo stesso discorso relativo all'elaborazione @code{texidoc} delle lingue
865 localizzate si applica anche a @code{doctitle}.
868 (Solo per l'output Texinfo.) Non tradurre i commenti e i nomi delle
869 variabili nel blocco testuale del frammento citato.
872 Se un file di input di LilyPond viene incluso con @code{\lilypondfile}, il
873 nome del file viene mostrato immediatamente prima del frammento musicale. Per l'output
874 HTML, questo nome è un collegamento. Viene mostrata solo la base del nome del
875 file, ovvero viene tolta la parte che costituisce il percorso del file.
880 @node Utilizzo di lilypond-book
881 @section Utilizzo di @command{lilypond-book}
882 @translationof Invoking lilypond-book
884 @command{lilypond-book} crea un file con una delle seguenti
885 estensioni: @file{.tex}, @file{.texi}, @file{.html} o @file{.xml},
886 a seconda del formato dell'output. Tutti i file @file{.tex}, @file{.texi} e
887 @file{.xml} necessitano di un'ulteriore elaborazione.
889 @subheading Istruzioni specifiche di ogni formato
891 @subsubheading @LaTeX{}
893 Esistono due modi di elaborare il documento @LaTeX{} per la stampa o la
894 pubblicazione: generare direttamente un file PDF tramite PDF@LaTeX{} oppure
895 generare un file PostScript tramite @LaTeX{}, attraverso un traduttore da DVI a
896 PostScript come @command{dvips}. Il primo modo è più semplice e raccomandato@footnote{Nota
897 che PDF@LaTeX{} e @LaTeX{} potrebbero non essere entrambi utilizzabili per compilare
898 un qualsiasi documento @LaTeX{}: ecco perché vengono illustrati i due modi.}, e
899 indipendentemente da quello che userai, puoi convertire facilmente PostScript e
900 PDF con strumenti come @command{ps2pdf} e @command{pdf2ps} inclusi nel pacchetto
903 Per creare un file PDF con PDF@LaTeX{}, si usa:
906 lilypond-book --pdf tuofile.lytex
910 @cindex caratteri vettoriali
911 @cindex type1, carattere
913 @cindex utilizzo di dvips
914 Per produrre l'output PDF attraverso @LaTeX{}/@command{dvips}/@command{ps2pdf}:
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}.
936 \begin@{lilypond@} @dots{} \end@{lilypond@}
940 non sono interpretati da @LaTeX{}. @code{lilypond-book} estrae questi
941 @q{ambienti} e li copia in file in un suo formato per poter eseguire
942 LilyPond su di essi. Prende quindi gli elementi grafici risultanti
943 e crea un file @file{.tex} dove le macro
944 @code{\begin@{lilypond@}}@dots{}@code{\end@{lilypond@}} sono poi
945 sostituite da comandi di @q{inclusione di immagini}. È a questo
946 punto che @LaTeX{} viene eseguito (anche se @LaTeX{} è stato eseguito
947 in precedenza, in realtà ha agito su un documento @q{vuoto} solo per
948 fare alcuni calcoli, come per esempio di @code{\linewidth}).
951 Il comando @code{\pageBreak} non funziona all'interno dell'ambiente
952 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}}.
954 Molte variabili del blocco @code{\paper} non funzionano all'interno dell'ambiente
955 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}}. Usa
956 @code{\newcommand} con @code{\betweenLilyPondSystem} nel preambolo;
959 \newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
963 @subsubheading Texinfo
965 Per generare un documento Texinfo (in qualsiasi formato di output), si seguono
966 le normali procedure usate con Texinfo; ovvero, si lancia @command{texi2pdf} o
967 @command{texi2dvi} o @command{makeinfo}, a seconda del formato di output
970 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, e
971 @ref{Creating an Info File, , , texinfo, GNU Texinfo}.
974 Si veda la documentazione di Texinfo per ulteriori dettagli.
978 @subheading Opzioni da linea di comando
980 @command{lilypond-book} accetta le seguenti opzioni da linea di comando:
983 @item -f @var{formato}
984 @itemx --format=@var{formato}
985 Specifica il tipo di documento da elaborare: @code{html}, @code{latex},
986 @code{texi} (il formato predefinito) o @code{docbook}. Se manca questa opzione,
987 @command{lilypond-book} cerca di rilevare il formato automaticamente, si veda
988 @ref{Estensioni dei nomi di file}. Attualmente, @code{texi} è equivalente a
991 @c This complicated detail is not implemented, comment it out -jm
993 The @code{texi} document type produces a Texinfo file with music
994 fragments in the printed output only. For getting images in the HTML
995 version, the format @code{texi-html} must be used instead.
998 @item -F @var{filtro}
999 @itemx --filter=@var{filtro}
1000 Convoglia i frammenti attraverso il @var{filtro}. @code{lilypond-book} non
1001 esegue contemporaneamente il filtro e l'elaborazione. Ad esempio,
1004 lilypond-book --filter='convert-ly --from=2.0.0 -' mio-libro.tely
1009 Mostra un breve messaggio di aiuto.
1012 @itemx --include=@var{dir}
1013 Aggiunge @var{dir} al percorso di inclusione. @command{lilypond-book} cerca
1014 anche dei frammenti già compilati nel percorso di inclusione e non li riscrive
1015 nella directory di output, quindi in alcuni casi è necessario eseguire
1016 ulteriori comandi come @command{makeinfo} o @command{latex} con le stesse
1017 opzioni @option{-I @var{dir}}.
1019 @item -l @var{loglevel}
1020 @itemx --loglevel=@var{loglevel}
1021 Imposta la verbosità dell'output su @var{loglevel}. I valori possibili sono @code{NONE},
1022 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (predefinito) e @code{DEBUG}. Se
1023 questa opzione non viene usata e la variabile d'ambiente @code{LILYPOND_BOOK_LOGLEVEL}
1024 è impostata, il suo valore viene usato come loglevel.
1027 @itemx --output=@var{dir}
1028 Salva i file generati nella directory @var{dir}. L'esecuzione di
1029 @command{lilypond-book} genera tanti piccoli file che LilyPond
1030 elaborerà. Per evitare tutto questo disordine nella directory dei
1031 sorgenti, si usa l'opzione da linea di comando @option{--output}
1032 e si entra in questa directory prima di eseguire @command{latex}
1033 o @command{makeinfo}.
1036 lilypond-book --output=out tuofile.lytex
1041 @item --skip-lily-check
1042 Non si arresta se non viene trovato l'output di lilypond. Viene usata per la
1043 documentazione Info di LilyPond, che è priva di immagini.
1045 @item --skip-png-check
1046 Non si arresta se non vengono trovate immagini PNG per i file EPS. Viene usata
1047 per la documentazione Info di LilyPond, che è priva di immagini.
1049 @item --lily-output-dir=@var{dir}
1050 Scrive i file lily-XXX nella directory @var{dir}, crea un link nella
1051 directory @option{--output}. Si usa questa opzione per risparmiare tempo nella
1052 compilazione di documenti situati in directory diverse che condividono
1053 molti identici frammenti.
1055 @item --lily-loglevel=@var{loglevel}
1056 Set the output verbosity of the invoked @command{lilypond} calls to @var{loglevel}.
1057 I valori possibili sono @code{NONE}, @code{ERROR}, @code{WARNING}, @code{BASIC_PROGRESS},
1058 @code{PROGRESS}, @code{INFO} (predefinito) e @code{DEBUG}. Se questa opzione
1059 non viene usata e la variabile d'ambiente @code{LILYPOND_LOGLEVEL} è
1060 impostata, il suo valore viene usato come loglevel.
1062 @item --info-images-dir=@var{dir}
1063 Formatta l'output di Texinfo in modo che Info cerchi le immagini della musica
1066 @item --latex-program=@var{prog}
1067 Lancia l'eseguibile @command{prog} invece di @command{latex}. Questa opzione
1068 è utile, ad esempio, se il documento è elaborato con @command{xelatex}.
1070 @item --left-padding=@var{quantità}
1071 Crea una spaziatura corrispondente a questa quantità tra i riquadri EPS. @var{quantità} è
1072 misurata in millimetri e il valore predefinito è 3.0. Questa opzione si usa
1073 se i righi dello spartito oltrepassano il margine destro.
1075 La larghezza di un sistema molto denso può variare in base agli elementi
1076 della notazione attaccati al margine sinistro, come i numeri di battuta e
1077 i nomi degli strumenti. Questa opzione accorcia tutte le linee e le sposta a
1078 a destra della stessa quantità.
1080 @item -P @var{comando}
1081 @itemx --process=@var{comando}
1082 Elabora i frammenti di LilyPond con @var{comando}. Il comando predefinito è
1083 @code{lilypond}. @code{lilypond-book} non userà @option{--filter} e
1084 @option{--process} contemporaneamente.
1087 Crea file PDF da usare con PDF@LaTeX{}.
1089 @item --redirect-lilypond-output
1090 Per impostazione predefinita, l'output viene mostrato sul terminale. Questa
1091 opzione redirige tutto l'output in dei file di log nella stessa directory dei
1094 @item --use-source-file-names
1095 Salva i file di output dei frammenti con lo stesso nome, esclusa l'estensione,
1096 dei sorgenti. Questa opzione funziona solo con i frammenti inclusi con
1097 @code{lilypondfile} e solo se le directory indicate da @option{--output-dir} e
1098 @option{--lily-output-dir} sono diverse.
1102 Mostra un output dettagliato. Questo è equivalente a @code{--loglevel=DEBUG}.
1106 Mostra informazioni sulla versione.
1111 Il comando Texinfo @code{@@pagesizes} non viene interpretato. Allo stesso
1112 modo, i comandi @LaTeX{} che modificano i margini e la larghezza della linea
1113 dopo il preambolo vengono ignorati.
1115 Solo il primo @code{\score} di un blocco LilyPond viene elaborato.
1118 @node Estensioni dei nomi di file
1119 @section Estensioni dei nomi di file
1120 @translationof Filename extensions
1122 Si può usare qualsiasi estensione per il file di input, ma se non si usa
1123 l'estensione raccomandata per uno specifico formato potrebbe essere
1124 necessario specificare a mano il formato di output; per i dettagli si veda
1125 @ref{Utilizzo di lilypond-book}. Altrimenti, @command{lilypond-book} sceglie
1126 automaticamente il formato di output in base all'estensione del file di input.
1129 @multitable @columnfractions .2 .5
1130 @item @strong{estensione} @tab @strong{formato di output}
1132 @item @file{.html} @tab HTML
1133 @item @file{.htmly} @tab HTML
1134 @item @file{.itely} @tab Texinfo
1135 @item @file{.latex} @tab @LaTeX{}
1136 @item @file{.lytex} @tab @LaTeX{}
1137 @item @file{.lyxml} @tab DocBook
1138 @item @file{.tely} @tab Texinfo
1139 @item @file{.tex} @tab @LaTeX{}
1140 @item @file{.texi} @tab Texinfo
1141 @item @file{.texinfo} @tab Texinfo
1142 @item @file{.xml} @tab HTML
1146 Se si usa per il file di input la stessa estensione che @command{lilypond-book}
1147 usa per il file di output e se il file di input è nella stessa directory
1148 in cui lavora @command{lilypond-book}, bisogna usare l'opzione @option{--output}
1149 per far sì che @command{lilypond-book} sia eseguito; altrimenti si ferma e
1150 mostra un messaggio di errore simile a @qq{L'output sovrascriverebbe il file di input}.
1153 @node Modelli per lilypond-book
1154 @section Modelli per lilypond-book
1155 @translationof lilypond-book templates
1157 Ecco alcuni modelli da usare con @code{lilypond-book}. Se non hai familiarità
1158 con questo programma, consulta @ref{lilypond-book}.
1162 Si possono includere frammenti LilyPond in un documento LaTeX.
1165 \documentclass[]@{article@}
1169 Normale testo LaTeX.
1177 Altro testo LaTeX, seguito da alcune opzioni tra parentesi quadre.
1179 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1187 Si possono includere frammenti LilyPond in Texinfo; infatti questo intero
1188 manuale è scritto in Texinfo.
1191 \input texinfo @c -*-texinfo-*-
1203 Altro testo Texinfo, seguito dalle opzioni tra parentesi.
1205 @@lilypond[verbatim,fragment,ragged-right]
1216 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1222 I documenti per lilypond-book possono combinare liberamente musica e testo. Ad
1232 Ancora un po' di LilyPond, questa volta con delle opzioni:
1234 <lilypond fragment quote staffsize=26 verbatim>
1248 \documentclass{article}
1249 \usepackage{ifxetex}
1251 %elementi specifici di xetex
1252 \usepackage{xunicode,fontspec,xltxtra}
1253 \setmainfont[Numbers=OldStyle]{Times New Roman}
1256 %Questo può essere lasciato vuoto se non si usa pdftex
1257 \usepackage[T1]{fontenc}
1258 \usepackage[utf8]{inputenc}
1259 \usepackage{mathptmx}%Times
1260 \usepackage{helvet}%Helvetica
1262 %Qui è possibile inserire tutti i pacchetti inclusi anche in pdftex
1263 \usepackage[ngerman,finnish,english]{babel}
1264 \usepackage{graphicx}
1267 \title{Un breve documento con LilyPond e xelatex}
1270 I comandi abituali di \textbf{font} interni al \emph{testo} funzionano,
1271 perché \textsf{sono supportati da \LaTeX{} e XeteX.}
1272 Se vuoi usare comandi specifici come \verb+\XeTeX+, devi
1273 includerli nuovamente in un ambiente \verb+\ifxetex+.
1274 You can use this to print the \ifxetex \XeTeX{} command \else
1275 XeTeX command \fi which is not known to normal \LaTeX .
1277 Nel testo normale si possono usare semplicemente i comandi LilyPond, come in
1287 I tipi di carattere dei frammenti inseriti con LilyPond devono essere impostati
1288 all'interno dei frammenti stessi. Si legga il manuale di Uso dell'applicazione per
1289 sapere come usare lilypond-book.
1291 \selectlanguage{ngerman}
1292 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1294 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1295 unterst__tzt werden.
1300 @node Condividere l'indice
1301 @section Condividere l'indice
1302 @translationof Sharing the table of contents
1304 Queste funzioni sono già incluse nel pacchetto OrchestralLily:
1307 @url{http://repo.or.cz/w/orchestrallily.git}
1311 preferiscono esportare l'indice da lilypond e leggerlo da dentro
1312 @LaTeX{} per la sua maggiore flessibilità nella gestione del testo.
1314 @subsubheading Esportare l'indice da LilyPond
1316 Per questo esempio si presume che lo spartito abbia vari movimenti nello stesso file
1317 di output di lilypond.
1320 #(define (oly:create-toc-file layout pages)
1321 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1322 (if (not (null? label-table))
1323 (let* ((format-line (lambda (toc-item)
1324 (let* ((label (car toc-item))
1325 (text (caddr toc-item))
1326 (label-page (and (list? label-table)
1327 (assoc label label-table)))
1328 (page (and label-page (cdr label-page))))
1329 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1330 (formatted-toc-items (map format-line (toc-items)))
1331 (whole-string (string-join formatted-toc-items ",\n"))
1332 (output-name (ly:parser-output-name))
1333 (outfilename (format "~a.toc" output-name))
1334 (outfile (open-output-file outfilename)))
1335 (if (output-port? outfile)
1336 (display whole-string outfile)
1337 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1338 (close-output-port outfile)))))
1341 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1345 @subsubheading Importare l'indice in LaTeX
1347 In LaTeX l'intestazione deve includere:
1349 @c no, this doesn't require the smallexample, but since the other
1350 @c two blocks on this page use it, I figured I might as well
1351 @c user it here as well, for consistency. -gp
1353 \usepackage@{pdfpages@}
1354 \includescore@{nameofthescore@}
1358 dove @code{\includescore} viene definito in questo modo:
1361 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1362 % \includescore@{PossibleExtension@}
1363 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1365 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1366 % This requires some heave latex tweaking, since reading in things from a file
1367 % and inserting it into the arguments of a macro is not (easily) possible
1369 % Solution by Patrick Fimml on #latex on April 18, 2009:
1370 % \readfile@{filename@}@{\variable@}
1371 % reads in the contents of the file into \variable (undefined if file
1373 \newread\readfile@@f
1374 \def\readfile@@line#1@{%
1375 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1376 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1377 \ifeof\readfile@@f\else%
1378 \readfile@@line@{#1@}%
1381 \def\readfile#1#2@{%
1382 \openin\readfile@@f=#1 %
1384 \typeout@{No TOC file #1 available!@}%
1387 \readfile@@line@{#2@}%
1389 \closein\readfile@@f%
1393 \newcommand@{\includescore@}[1]@{
1394 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1395 \let\oly@@addtotoc\undefined
1396 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1397 \ifx\oly@@addtotoc\undefined
1398 \includepdf[pages=-]@{\oly@@fname@}
1400 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1401 @{\oly@@fname@}@}\includeit
1407 @node Metodi alternativi per combinare testo e musica
1408 @section Metodi alternativi per combinare testo e musica
1409 @translationof Alternate methods of mixing text and music
1411 Altri modi per combinare testo e musica (senza usare
1412 @command{lilypond-book}) sono trattati in
1413 @ref{Inclusione di partiture LilyPond in altri programmi}.