1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: it -*-
4 Translation of GIT committish: 79b407554f2919737845b7977b11eaba41e354ae
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}. Chi usa MacOS 10.3 o 10.4 e non riesce ad eseguire
31 @code{lilypond-book} veda @rweb{MacOS X}.
33 Questo procedimento può essere applicato ai documenti @LaTeX{}, HTML, Texinfo
42 @cindex documenti, aggiungere musica ai
43 @cindex HTML, musica in
44 @cindex Texinfo, musica in
45 @cindex DocBook, musica in
46 @cindex @LaTeX{}, musica in
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-boink.ly}
105 (Se vuoi provare, sostituisci @file{screech-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-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}.
520 Nel file di input, la musica viene specificata con uno dei seguenti comandi:
522 \begin@{lilypond@}[le,opzioni,vanno,qui]
526 \lilypond[le,opzioni,vanno,qui]@{ CODICE LILYPOND @}
528 \lilypondfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
530 \musicxmlfile[le,opzioni,vanno,qui]@{@var{nomefile}@}
532 <lilypond le opzioni vanno qui>
536 <lilypond le opzioni vanno qui: CODICE LILYPOND />
538 <lilypondfile le opzioni vanno qui>@var{nomefile}</lilypondfile>
540 <musicxmlfile le opzioni vanno qui>@var{nomefile}</musicxmlfile>
543 Ad esempio, puoi scrivere
546 <lilypond fragment relative=2>
547 \key c \minor c4 es g2
552 @command{lilypond-book} genera quindi un file HTML con gli elementi appropriati
553 per le immagini dei frammenti musicali:
555 @lilypond[fragment,relative=2]
556 \key c \minor c4 es g2
559 Per le immagini in linea, si usa @code{<lilypond ... />}, dove le opzioni
560 sono distinte dalla musica attraverso i due punti, ad esempio
563 Un po' di musica in <lilypond relative=2: a b c/> una linea di testo.
566 Per includere file separati, si usa
569 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
572 @code{<musicxmlfile>} usa la stessa sintassi di @code{<lilypondfile>}, ma semplicemente
573 si riferisce a un file MusicXML invece che a un file LilyPond.
575 Per una lista di opzioni da usare con gli elementi @code{lilypond} e
576 @code{lilypondfile}, si veda @ref{Music fragment options}.
578 Inoltre, @code{<lilypondversion/>} mostra la versione di
582 @cindex titoli in HTML
583 @cindex immagine di anteprima
588 @translationof DocBook
590 Per inserire frammenti di codice LilyPond è una buona idea mantenere la
591 conformità del documento DocBook, in modo da poter usare gli editor DocBook, la
592 validazione, etc. Quindi non si usano elementi personalizzati, ma si
593 specifica una convenzione basata sugli elementi DocBook standard.
595 @subheading Convenzioni comuni
597 Per inserire un frammento di qualsiasi tipo si usano gli elementi @code{mediaobject}
598 e @code{inlinemediaobject}, in modo che il frammento possa essere formattato
599 in linea o meno. Le opzioni di formattazione del frammento vengono sempre
600 indicate nella proprietà @code{role} dell'elemento più interno (si vedano
601 le prossime sezioni). Gli elementi sono scelti in modo da permettere agli editor
602 DocBook di ottenere una formattazione ottimale. I file DocBook da
603 elaborare con @command{lilypond-book} devono avere estensione @file{.lyxml}.
605 @subheading Includere un file LilyPond
607 Si tratta del caso più semplice. Bisogna usare l'estensione @file{.ly} per
608 il file da includere e inserirlo come uno standard @code{imageobject}, con
609 la seguente struttura:
614 <imagedata fileref="music1.ly" role="printfilename" />
619 Nota che sei libero di usare @code{mediaobject} o @code{inlinemediaobject}
620 come elemento più esterno.
622 @subheading Includere codice LilyPond
624 È possibile includere codice LilyPond all'interno di un elemento
625 @code{programlisting} in cui il linguaggio sia impostato su @code{lilypond}
626 e con la seguente struttura:
631 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
632 \context Staff \with @{
633 \remove Time_signature_engraver
634 \remove Clef_engraver@}
641 Come si vede, l'elemento più esterno è @code{mediaobject} o
642 @code{inlinemediaobject} e c'è un @code{textobject} che contiene al
643 suo interno il @code{programlisting}.
645 @subheading Elaborare il documento DocBook
647 L'esecuzione di @command{lilypond-book} su un file @file{.lyxml} creerà un
648 documento DocBook valido con estensione @file{.xml} che potrà essere
649 ulteriormente elaborato. Usando
650 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, creerà automaticamente un file
651 PDF da questo documento. Per generare l'HTML (HTML Help,
652 JavaHelp etc.) si possono usare i fogli di stile DocBook XSL ufficiali;
653 tuttavia è possibile che sia necessario modificarli un po'.
656 @node Opzioni dei frammenti musicali
657 @section Opzioni dei frammenti musicali
658 @translationof Music fragment options
660 Nelle pagine che seguono, per @q{comando LilyPond} si intende un qualsiasi
661 comando descritto nelle sezioni precedenti che sia gestito da @command{lilypond-book}
662 per produrre un frammento musicale. Per semplicità, i comandi LilyPond vengono
663 mostrati soltanto nella sintassi @LaTeX{}.
665 Nota che la stringa delle opzioni è analizzata da sinistra a destra; se un'opzione
666 ricorre più di una volta, viene applicata nella sua ultima occorrenza.
668 Sono disponibili le seguenti opzioni per i comandi LilyPond:
671 @item staffsize=@var{altezza}
672 Imposta la dimensione del pentagramma a @var{altezza}, misurata in punti.
675 Produce linee con margine destro irregolare e spaziatura naturale, ovvero
676 viene aggiunto @code{ragged-right = ##t} al frammento LilyPond. Frammenti
677 con un solo rigo avranno sempre il margine destro irregolare, a meno che
678 non venga specificato esplicitamente @code{noragged-right}.
681 Per i frammenti di una sola linea, fa sì che la lunghezza del rigo venga estesa
682 fino a coincidere con la larghezza della linea, ovvero viene aggiunto
683 @code{ragged-right = ##f} al frammento LilyPond.
686 @itemx line-width=@var{dimensione}\@var{unità}
687 Imposta la lunghezza della linea a @var{dimensione}, usando @var{unità} come
688 unità di misura. @var{unità} può essere una delle seguenti stringhe: @code{cm},
689 @code{mm}, @code{in} o @code{pt}. Questa opzione riguarda l'output LilyPond
690 (ovvero, la lunghezza del rigo del frammento musicale), non la formattazione
693 Se usato senza un argomento, imposta la lunghezza della linea a un valore
694 predefinito (calcolato da un algoritmo euristico).
696 Se non viene assegnata un'opzione @code{line-width}, @command{lilypond-book}
697 cerca di indovinare un valore predefinito per gli ambienti @code{lilypond} che
698 non usano l'opzione @code{ragged-right}.
700 @item papersize=@var{stringa}
701 Dove @var{stringa} è una delle dimensioni del foglio definite in @file{scm/paper.scm},
702 ad esempio @code{a5}, @code{quarto}, @code{11x17} etc.
704 I valori non definiti in @file{scm/paper.scm} saranno ignorati, sarà inviato
705 un messaggio di avviso e al frammento sarà assegnata la dimensione predefinita,
709 Non viene visualizzata l'indicazione di tempo e disabilita i segni relativi alla scansione ritmica
710 (segno di tempo, barre di divisione) nella partitura.
713 Fa sì che @command{lilypond-book} aggiunga del codice boilerplate in modo che
714 sia possibile inserire semplicemente, ad esempio,
721 senza @code{\layout}, @code{\score}, etc.
724 Non aggiunge del codice ulteriore per completare il codice LilyPond nei frammenti
725 musicali. Essendo l'impostazione predefinita, @code{nofragment} di norma
728 @item indent=@var{dimensione}\@var{unità}
729 Imposta l'indentazione del primo sistema musicale a @var{dimensione}, usando
730 @var{unità} come unità di misura. @var{unità} è una delle seguenti stringhe:
731 @code{cm}, @code{mm}, @code{in} o @code{pt}. Questa opzione riguarda
732 LilyPond, non la formattazione del testo.
735 Imposta l'indentazione del primo sistema musicale su zero. Questa opzione
736 interessa LilyPond, non la formattazione del testo. L'assenza di indentazione è
737 l'impostazione predefinita, dunque normalmente @code{noindent} è ridondante.
740 Riduce la lunghezza della linea di un frammento musicale di @math{2*0.4}@dmn{in}
741 e inserisce l'output in un blocco per le citazioni. Il valore @q{0.4@dmn{in}}
742 può essere controllato con l'opzione @code{exampleindent}.
745 Imposta la quantità di spazio con cui l'opzione @code{quote} indenta un
749 @itemx relative=@var{n}
750 Usa la modalità di ottava relativa. Per impostazione predefinita, le altezze delle note
751 sono riferite al Do@tie{}centrale. L'argomento opzionale del numero intero
752 specifica l'ottava della nota iniziale: il valore predefinito @code{1} è il
753 Do centrale. L'opzione @code{relative} funziona solo quando è impostata
754 l'opzione @code{fragment}, quindi @code{fragment} è implicitamente sottinteso
755 da @code{relative}, a prescindere dalla presenza dell'opzione @code{(no)fragment}
759 LilyPond usa @command{lilypond-book} anche per produrre la propria
760 documentazione. A questo scopo, esistono altre opzioni più complesse
761 per i frammenti musicali.
765 L'argomento di un comando LilyPond viene copiato nel file di output e racchiuso
766 in un blocco di testo, seguito da qualsiasi testo assegnato con l'opzione
767 @code{intertext} (non ancora implementato); quindi viene mostrata la musica
768 vera e propria. Questa opzione non funziona bene con @code{\lilypond@{@}} se
769 fa parte di un paragrafo.
771 Se @code{verbatim} viene usato in un comando @code{lilypondfile}, è possibile
772 includere il testo di una parte soltanto del file sorgente. Se il file
773 sorgente ha un commento contenente @samp{begin verbatim} (senza
774 virgolette), la citazione del sorgente nel blocco testuale inizierà dopo
775 l'ultima occorrenza di tale commento; in modo analogo, la citazione del testo
776 sorgente si fermerà proprio prima della prima occorrenza di un commento
777 contenente @samp{end verbatim}, se presente. Nel seguente file sorgente di
778 esempio, la musica viene interpretata in modalità relativa ma il blocco
779 testuale non mostrerà il blocco @code{relative}, ovvero
782 \relative c' @{ % begin verbatim
789 mostrerà il seguente blocco testuale
797 Se si desidera tradurre i commenti e i nomi delle variabili nell'output
798 verbatim ma non nei sorgenti, si può impostare la variabile d'ambiente
799 @code{LYDOC_LOCALEDIR} sul percorso di una directory; la directory deve
800 contenere un albero dei cataloghi di messaggio @file{.mo} che hanno
801 @code{lilypond-doc} come dominio.
804 (Solo per l'output Texinfo.) Aggiunge @code{\version
805 @@w@{"@@version@{@}"@}} nella prima riga dell'output di @code{verbatim}.
808 (Solo per l'output Texinfo.) Se @command{lilypond} viene lanciato con
809 l'opzione @option{--header=@/texidoc} e il file da elaborare si
810 chiama @file{foo.ly}, verrà creato un file @file{foo.texidoc} a patto che
811 ci sia un campo @code{texidoc} nel blocco @code{\header}. L'opzione @code{texidoc}
812 fa sì che @command{lilypond-book} includa tali file, aggiungendo il loro
813 contenuto in forma di blocco di documentazione proprio prima del frammento
814 di musica (ma fuori dall'ambiente @code{example} generato da un'opzione
817 Se il file @file{foo.ly} contiene
821 texidoc = "Questo file mostra il funzionamento di una singola nota."
827 e il documento Texinfo @file{test.texinfo} contiene
830 @@lilypondfile[texidoc]@{foo.ly@}
834 il seguente comando produce il risultato atteso
837 lilypond-book --pdf --process="lilypond \
838 -dbackend=eps --header=texidoc" test.texinfo
841 Per la maggior parte, i documenti di test di LilyPond (nella directory @file{input}
842 della distribuzione) sono piccoli file @file{.ly} che hanno esattamente questo
845 Ai fini della localizzazione, se il documento Texinfo document contiene
846 @code{@@documentlanguage @var{LANG}} e l'header di @file{foo.ly}
847 contiene un campo @code{texidoc@var{LANG}}, quando si lancia @command{lilypond}
848 con l'opzione @option{--header=@/texidoc@var{LANG}} verrà incluso
849 @file{foo.texidoc@var{LANG}} invece di @file{foo.texidoc}.
852 (Solo per l'output Texinfo.) Questa opzione funziona in modo simile
853 all'opzione @code{texidoc}: se @command{lilypond} viene lanciato con
854 l'opzione @option{--header=@/doctitle} e il file da elaborare si chiama
855 @file{foo.ly} e contiene un campo @code{doctitle} nel blocco
856 @code{\header}, viene creato un file @file{foo.doctitle}. Se si usa
857 l'opzione @code{doctitle}, i contenuti di @file{foo.doctitle},
858 che dovrebbero trovarsi su una singola linea di @var{text}, vengono inseriti
859 nel documento Texinfo come @code{@@lydoctitle @var{text}}.
860 @code{@@lydoctitle} è una macro definita nel documento Texinfo.
861 Lo stesso discorso relativo all'elaborazione @code{texidoc} delle lingue
862 localizzate si applica anche a @code{doctitle}.
865 (Solo per l'output Texinfo.) Non tradurre i commenti e i nomi delle
866 variabili nel blocco testuale del frammento citato.
869 Se un file di input di LilyPond viene incluso con @code{\lilypondfile}, il
870 nome del file viene mostrato immediatamente prima del frammento musicale. Per l'output
871 HTML, questo nome è un collegamento. Viene mostrata solo la base del nome del
872 file, ovvero viene tolta la parte che costituisce il percorso del file.
877 @node Utilizzo di lilypond-book
878 @section Utilizzo di @command{lilypond-book}
879 @translationof Invoking lilypond-book
881 @command{lilypond-book} crea un file con una delle seguenti
882 estensioni: @file{.tex}, @file{.texi}, @file{.html} o @file{.xml},
883 a seconda del formato dell'output. Tutti i file @file{.tex}, @file{.texi} e
884 @file{.xml} necessitano di un'ulteriore elaborazione.
886 @subheading Istruzioni specifiche di ogni formato
888 @subsubheading @LaTeX{}
890 Esistono due modi di elaborare il documento @LaTeX{} per la stampa o la
891 pubblicazione: generare direttamente un file PDF tramite PDF@LaTeX{} oppure
892 generare un file PostScript tramite @LaTeX{}, attraverso un traduttore da DVI a
893 PostScript come @command{dvips}. Il primo modo è più semplice e raccomandato@footnote{Nota
894 che PDF@LaTeX{} e @LaTeX{} potrebbero non essere entrambi utilizzabili per compilare
895 un qualsiasi documento @LaTeX{}: ecco perché vengono illustrati i due modi.}, e
896 indipendentemente da quello che userai, puoi convertire facilmente PostScript e
897 PDF con strumenti come @command{ps2pdf} e @command{pdf2ps} inclusi nel pacchetto
900 Per creare un file PDF con PDF@LaTeX{}, si usa
903 lilypond-book --pdf tuofile.lytex
907 @cindex caratteri vettoriali
908 @cindex type1, carattere
910 @cindex utilizzo di dvips
911 Per produrre l'output PDF attraverso @LaTeX{}/@command{dvips}/@command{ps2pdf},
912 bisogna usare questi comandi
915 lilypond-book tuofile.lytex
917 dvips -Ppdf tuofile.dvi
922 Il file @file{.dvi} creato da questa sequenza non conterrà le
923 teste delle note. È normale; se si seguono le istruzioni, le teste
924 verranno incluse nei file @file{.ps} e @file{.pdf}.
926 L'esecuzione di @command{dvips} potrebbe generare dei messaggi di avviso
927 relativi ai caratteri; questi messaggi sono innocui e possono
928 essere ignorati. Se esegui @command{latex} in modalità due colonne, ricorda
929 di aggiungere @option{-t landscape} alle opzioni di @command{dvips}.
931 @subsubheading Texinfo
933 Per generare un documento Texinfo (in qualsiasi formato di output), si seguono
934 le normali procedure usate con Texinfo; ovvero, si lancia @command{texi2pdf} o
935 @command{texi2dvi} o @command{makeinfo}, a seconda del formato di output
938 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, e @ref{Creating
939 an Info File, , , texinfo, GNU Texinfo}.
942 Si veda la documentazione di Texinfo per ulteriori dettagli.
946 @subheading Opzioni da linea di comando
948 @command{lilypond-book} accetta le seguenti opzioni da linea di comando:
951 @item -f @var{formato}
952 @itemx --format=@var{formato}
953 Specifica il tipo di documento da elaborare: @code{html}, @code{latex},
954 @code{texi} (il formato predefinito) o @code{docbook}. Se manca questa opzione,
955 @command{lilypond-book} cerca di rilevare il formato automaticamente, si veda
956 @ref{Filename extensions}. Attualmente, @code{texi} è equivalente a
959 @c This complicated detail is not implemented, comment it out -jm
961 The @code{texi} document type produces a Texinfo file with music
962 fragments in the printed output only. For getting images in the HTML
963 version, the format @code{texi-html} must be used instead.
966 @item -F @var{filtro}
967 @itemx --filter=@var{filtro}
968 Convoglia i frammenti attraverso il @var{filtro}. @code{lilypond-book} non
969 esegue contemporaneamente il filtro e l'elaborazione. Ad esempio,
972 lilypond-book --filter='convert-ly --from=2.0.0 -' mio-libro.tely
977 Mostra un breve messaggio di aiuto.
980 @itemx --include=@var{dir}
981 Aggiunge @var{dir} al percorso di inclusione. @command{lilypond-book} cerca
982 anche dei frammenti già compilati nel percorso di inclusione e non li riscrive
983 nella directory di output, quindi in alcuni casi è necessario eseguire
984 ulteriori comandi come @command{makeinfo} o @command{latex} con le stesse
985 opzioni @option{-I @var{dir}}.
987 @item -l @var{loglevel}
988 @itemx --loglevel=@var{loglevel}
989 Imposta la verbosità dell'output su @var{loglevel}. I valori possibili sono @code{NONE},
990 @code{ERROR}, @code{WARNING}, @code{PROGRESS} (predefinito) e @code{DEBUG}. Se
991 questa opzione non viene usata e la variabile d'ambiente @code{LILYPOND_BOOK_LOGLEVEL}
992 è impostata, il suo valore viene usato come loglevel.
995 @itemx --output=@var{dir}
996 Salva i file generati nella directory @var{dir}. L'esecuzione di
997 @command{lilypond-book} genera tanti piccoli file che LilyPond
998 elaborerà. Per evitare tutto questo disordine nella directory dei
999 sorgenti, si usa l'opzione da linea di comando @option{--output}
1000 e si entra in questa directory prima di eseguire @command{latex}
1001 o @command{makeinfo}.
1004 lilypond-book --output=out tuofile.lytex
1009 @itemx --skip-lily-check
1010 Non si arresta se non viene trovato l'output di lilypond. Viene usata per la
1011 documentazione Info di LilyPond, che è priva di immagini.
1013 @itemx --skip-png-check
1014 Non si arresta se non vengono trovate immagini PNG per i file EPS. Viene usata
1015 per la documentazione Info di LilyPond, che è priva di immagini.
1017 @itemx --lily-output-dir=@var{dir}
1018 Scrive i file lily-XXX nella directory @var{dir}, crea un link nella
1019 directory @option{--output}. Si usa questa opzione per risparmiare tempo nella
1020 compilazione di documenti situati in directory diverse che condividono
1021 molti identici frammenti.
1023 @itemx --lily-loglevel=@var{loglevel}
1024 Set the output verbosity of the invoked @command{lilypond} calls to @var{loglevel}.
1025 I valori possibili sono @code{NONE}, @code{ERROR}, @code{WARNING}, @code{BASIC_PROGRESS},
1026 @code{PROGRESS}, @code{INFO} (predefinito) e @code{DEBUG}. Se questa opzione
1027 non viene usata e la variabile d'ambiente @code{LILYPOND_LOGLEVEL} è
1028 impostata, il suo valore viene usato come loglevel.
1030 @itemx --info-images-dir=@var{dir}
1031 Formatta l'output di Texinfo in modo che Info cerchi le immagini della musica
1034 @itemx --latex-program=@var{prog}
1035 Lancia l'eseguibile @command{prog} invece di @command{latex}. Questa opzione
1036 è utile, ad esempio, se il documento è elaborato con @command{xelatex}.
1038 @itemx --left-padding=@var{quantità}
1039 Crea una spaziatura corrispondente a questa quantità tra i riquadri EPS. @var{quantità} è
1040 misurata in millimetri e il valore predefinito è 3.0. Questa opzione si usa
1041 se i righi dello spartito oltrepassano il margine destro.
1043 La larghezza di un sistema molto denso può variare in base agli elementi
1044 della notazione attaccati al margine sinistro, come i numeri di battuta e
1045 i nomi degli strumenti. Questa opzione accorcia tutte le linee e le sposta a
1046 a destra della stessa quantità.
1048 @item -P @var{comando}
1049 @itemx --process=@var{comando}
1050 Elabora i frammenti di LilyPond con @var{comando}. Il comando predefinito è
1051 @code{lilypond}. @code{lilypond-book} non userà @option{--filter} e
1052 @option{--process} contemporaneamente.
1055 Crea file PDF da usare con PDF@LaTeX{}.
1057 @item --redirect-lilypond-output
1058 Per impostazione predefinita, l'output viene mostrato sul terminale. Questa
1059 opzione redirige tutto l'output in dei file di log nella stessa directory dei
1062 @itemx --use-source-file-names
1063 Salva i file di output dei frammenti con lo stesso nome, esclusa l'estensione,
1064 dei sorgenti. Questa opzione funziona solo con i frammenti inclusi con
1065 @code{lilypondfile} e solo se le directory indicate da @option{--output-dir} e
1066 @option{--lily-output-dir} sono diverse.
1070 Mostra un output dettagliato. Questo è equivalente a @code{--loglevel=DEBUG}.
1074 Mostra informazioni sulla versione.
1079 Il comando Texinfo @code{@@pagesizes} non viene inrerpretato. Allo stesso
1080 modo, i comandi @LaTeX{} che modificano i margini e la larghezza della linea
1081 dopo il preambolo vengono ignorati.
1083 Solo il primo @code{\score} di un blocco LilyPond viene elaborato.
1086 @node Estensioni dei nomi di file
1087 @section Estensioni dei nomi di file
1088 @translationof Filename extensions
1090 Si può usare qualsiasi estensione per il file di input, ma se non si usa
1091 l'estensione raccomandata per uno specifico formato potrebbe essere
1092 necessario specificare a mano il formato di output; per i dettagli si veda
1093 @ref{Invoking lilypond-book}. Altrimenti, @command{lilypond-book} sceglie
1094 automaticamente il formato di output in base all'estensione del file di input.
1097 @multitable @columnfractions .2 .5
1098 @item @strong{estensione} @tab @strong{formato di output}
1100 @item @file{.html} @tab HTML
1101 @item @file{.htmly} @tab HTML
1102 @item @file{.itely} @tab Texinfo
1103 @item @file{.latex} @tab @LaTeX{}
1104 @item @file{.lytex} @tab @LaTeX{}
1105 @item @file{.lyxml} @tab DocBook
1106 @item @file{.tely} @tab Texinfo
1107 @item @file{.tex} @tab @LaTeX{}
1108 @item @file{.texi} @tab Texinfo
1109 @item @file{.texinfo} @tab Texinfo
1110 @item @file{.xml} @tab HTML
1114 Se si usa per il file di input la stessa estensione che @command{lilypond-book}
1115 usa per il file di output e se il file di input è nella stessa directory
1116 in cui lavora @command{lilypond-book}, bisogna usare l'opzione @option{--output}
1117 per far sì che @command{lilypond-book} sia eseguito; altrimenti si ferma e
1118 mostra un messaggio di errore simile a @qq{L'output sovrascriverebbe il file di input}.
1121 @node Modelli per lilypond-book
1122 @section Modelli per lilypond-book
1123 @translationof lilypond-book templates
1125 Ecco alcuni modelli da usare con @code{lilypond-book}. Se non hai familiarità
1126 con questo programma, consulta @ref{lilypond-book}.
1130 Si possono includere frammenti LilyPond in un documento LaTeX.
1133 \documentclass[]@{article@}
1137 Normale testo LaTeX.
1145 Altro testo LaTeX, seguito da alcune opzioni tra parentesi quadre.
1147 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1155 Si possono includere frammenti LilyPond in Texinfo; infatti questo intero
1156 manuale è scritto in Texinfo.
1159 \input texinfo @c -*-texinfo-*-
1171 Altro testo Texinfo, seguito dalle opzioni tra parentesi.
1173 @@lilypond[verbatim,fragment,ragged-right]
1184 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1190 I documenti per lilypond-book possono combinare liberamente musica e testo. Ad
1200 Ancora un po' di Lilypond, questa volta con delle opzioni:
1202 <lilypond fragment quote staffsize=26 verbatim>
1216 \documentclass{article}
1217 \usepackage{ifxetex}
1219 %elementi specifici di xetex
1220 \usepackage{xunicode,fontspec,xltxtra}
1221 \setmainfont[Numbers=OldStyle]{Times New Roman}
1224 %Questo può essere lasciato vuoto se non si usa pdftex
1225 \usepackage[T1]{fontenc}
1226 \usepackage[utf8]{inputenc}
1227 \usepackage{mathptmx}%Times
1228 \usepackage{helvet}%Helvetica
1230 %Qui è possibile inserire tutti i pacchetti inclusi anche in pdftex
1231 \usepackage[ngerman,finnish,english]{babel}
1232 \usepackage{graphicx}
1235 \title{Un breve documento con LilyPond e xelatex}
1238 I comandi abituali di \textbf{font} interni al \emph{testo} funzionano,
1239 perché \textsf{sono supportati da \LaTeX{} e XeteX.}
1240 Se vuoi usare comandi specifici come \verb+\XeTeX+, devi
1241 includerli nuovamente in un ambiente \verb+\ifxetex+.
1242 You can use this to print the \ifxetex \XeTeX{} command \else
1243 XeTeX command \fi which is not known to normal \LaTeX .
1245 Nel testo normale si possono usare semplicemente i comandi LilyPond, come in
1255 I tipi di carattere dei frammenti inseriti con LilyPond devono essere impostati
1256 all'interno dei frammenti stessi. Si legga il manuale di Uso dell'applicazione per
1257 sapere come usare lilypond-book.
1259 \selectlanguage{ngerman}
1260 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1262 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1263 unterst__tzt werden.
1268 @node Condividere l'indice
1269 @section Condividere l'indice
1270 @translationof Sharing the table of contents
1272 Queste funzioni sono già incluse nel pacchetto OrchestralLily:
1275 @url{http://repo.or.cz/w/orchestrallily.git}
1279 preferiscono esportare l'indice da lilypond e leggerlo da dentro
1280 @LaTeX{} per la sua maggiore flessibilità nella gestione del testo.
1282 @subsubheading Esportare l'indice da LilyPond
1284 Per questo esempio si presume che lo spartito abbia vari movimenti nello stesso file
1285 di output di lilypond.
1288 #(define (oly:create-toc-file layout pages)
1289 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1290 (if (not (null? label-table))
1291 (let* ((format-line (lambda (toc-item)
1292 (let* ((label (car toc-item))
1293 (text (caddr toc-item))
1294 (label-page (and (list? label-table)
1295 (assoc label label-table)))
1296 (page (and label-page (cdr label-page))))
1297 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1298 (formatted-toc-items (map format-line (toc-items)))
1299 (whole-string (string-join formatted-toc-items ",\n"))
1300 (output-name (ly:parser-output-name parser))
1301 (outfilename (format "~a.toc" output-name))
1302 (outfile (open-output-file outfilename)))
1303 (if (output-port? outfile)
1304 (display whole-string outfile)
1305 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
1306 (close-output-port outfile)))))
1309 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1313 @subsubheading Importare l'indice in LaTeX
1315 In LaTeX l'intestazione deve includere:
1317 @c no, this doesn't require the smallexample, but since the other
1318 @c two blocks on this page use it, I figured I might as well
1319 @c user it here as well, for consistency. -gp
1321 \usepackage@{pdfpages@}
1322 \includescore@{nameofthescore@}
1326 dove @code{\includescore} viene definito in questo modo:
1329 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1330 % \includescore@{PossibleExtension@}
1331 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1333 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1334 % This requires some heave latex tweaking, since reading in things from a file
1335 % and inserting it into the arguments of a macro is not (easily) possible
1337 % Solution by Patrick Fimml on #latex on April 18, 2009:
1338 % \readfile@{filename@}@{\variable@}
1339 % reads in the contents of the file into \variable (undefined if file
1341 \newread\readfile@@f
1342 \def\readfile@@line#1@{%
1343 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1344 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1345 \ifeof\readfile@@f\else%
1346 \readfile@@line@{#1@}%
1349 \def\readfile#1#2@{%
1350 \openin\readfile@@f=#1 %
1352 \typeout@{No TOC file #1 available!@}%
1355 \readfile@@line@{#2@}%
1357 \closein\readfile@@f%
1361 \newcommand@{\includescore@}[1]@{
1362 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1363 \let\oly@@addtotoc\undefined
1364 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1365 \ifx\oly@@addtotoc\undefined
1366 \includepdf[pages=-]@{\oly@@fname@}
1368 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1369 @{\oly@@fname@}@}\includeit
1375 @node Metodi alternativi per combinare testo e musica
1376 @section Metodi alternativi per combinare testo e musica
1377 @translationof Alternate methods of mixing text and music
1379 Altri modi per combinare testo e musica (senza usare
1380 @command{lilypond-book}) sono trattati in
1381 @ref{LilyPond output in other programs}.