LilyPond — Utilització

1.1 Utilització normal

Gairebé tots els usuaris executen el LilyPond per mitjà d’una interfície gràfica; consulteu Tutorial si encara no l’heu llegit.

1.2 Utilització des de la línia d’ordres

Aquesta secció conté informació addicional sobre l’ús del LilyPond a la línia d’ordres. Aquesta forma pot ser preferible per passar-li al programa algunes opcions addicionals. A més a més, existeixen alguns programes complementaris ‘de suport’ (com ara midi2ly) que sols estan disponibles a la línia d’ordres.

En parlar de la ‘línia d’ordres’, ens referim a la consola del sistema operatiu. Els usuaris del Windows possiblement estiguin més familiaritzats amb els termes ‘finestra del MS-DOS’ o ‘línia de comandes’; Els usuaris del MacOS X potser que estiguin més familiaritzats amb els termes ‘terminal’ o ‘consola’.

La descripció de l’ús d’aquesta part dels sistemes operatius excedeix l’àmbit d’aquest manual; us preguem que consulteu altres documents sobre aquest tema si no us resulta familiar la línia d’ordres.

lilypond [opció]… fitxer…

#(define output-suffix "violí")
\score { … }
#(define output-suffix "violoncel")
\score { … }

#!/bin/sh
## aquí es fixen els valors predeterminats

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# prefix (sense la barra inicial!)
lilyprefix=usr/local
# el directori en el qual el LilyPond es troba instal·lat en el sistema
lilydir=/$lilyprefix/lilypond/

userhome=$home/$username
loopfile=$userhome/loopfile
adduser $username
dd if=/dev/zero of=$loopfile bs=1k count=200000
mkdir $jaildir
losetup $loopdevice $loopfile
mkfs -t ext3 $loopdevice 200000
mount -t ext3 $loopdevice $jaildir
mkdir $jaildir/lilyhome
chown $username $jaildir/lilyhome
cd $jaildir

mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
chmod a+w tmp

cp -r -L $lilydir $lilyprefix
cp -L /bin/sh /bin/rm bin
cp -L /usr/bin/convert /usr/bin/gs usr/bin
cp -L /usr/share/fonts/truetype usr/share/fonts

# Ara la màgia de copiar les biblioteques
for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
  "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
    \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
      's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
        | sed '/.*=>.*/d'; done | sh -s

# Els fitxers compartits per al ghostcript...
      cp -L -r /usr/share/ghostscript usr/share
# Els fitxers compartits per a l'ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Ara, suposant que tenim test.ly a /mnt/lilyloop/lilyhome,
### hauríem de poder executar:
### Observeu que /$lilyprefix/bin/lilypond és un guió, que estableix
### un valor per a LD_LIBRARY_PATH : això és crucial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

1.3 Missatges d’error

Poden aparèixer diferents missatges d’error en compilar un fitxer:

Advertiment ¶

Alguna cosa té un aspecte sospitós. Si estem demanant quelcom fora del comú, entendrem el missatge i podrem ignorar-lo. Tot i així, els advertiments solen indicar que alguna cosa va mal amb el fitxer d’entrada.

Error ¶

És clar que alguna cosa va malament. El pas actual del processament (anàlisi, interpretació o format visual) es donarà per acabat, però el pas següent se saltarà.

Error fatal ¶

És clar que alguna cosa va malament, i el LilyPond no pot continuar. Poques vegades passa això. La causa més freqüent són els tipus de lletra mal instal·lats.

Error del Scheme ¶

Els errors que ocorren en executar el codi del Scheme s’intercepten per part de l’intèrpret del Scheme. Si s’està executant amb les opcions -V o --verbose (detallat) aleshores s’imprimeix una traça de crides de la funció ofensiva.

Error de programació ¶

Hi ha hagut algun tipus d’inconsistència interna. Aquests missatges d’error estan orientats a ajudar als programadors i als depuradors. Normalment es poden ignorar. En ocasions apareixen en quantitats tan grans que poden entorpir la visió d’altres missatges de sortida.

Abort (bolcat de core)

Això senyala un error de programació seriós que ha causat la interrupció abrupta del programa. Aquests errors es consideren crítics. Si es topa amb un, envieu un informe de fallada.

Si els errors i advertiments es poden lligar a un punt del fitxer d’entrada, els missatges tenen la forma següent:

fitxer:línia:columna: missatge
línia d'entrada problemàtica

S’insereix un salt de línia a la línia problemàtica per indicar la columna on es va trobar l’error. Per exemple,

prova.ly:2:19: error: no és una duració: 5
  { c'4 e'
           5 g' }

Aquestes posicions són la millor suposició del LilyPond sobre on s’ha produït el missatge d’error, però (per la seva pròpia naturalesa) els advertiment i errors es produeixen quan passa quelcom inesperat. Si no veieu un error a la línia que s’indica del fitxer d’entrada, intenteu comprovar una o dues línies per sobre de la posició indicada.

S’ofereix més informació sobre els errors a la secció Errors comuns.

1.4 Errors comuns

Les condicions d’error que es descriuen més a sota es produeixen amb freqüència, tot i que la causa no és òbvia o fàcil de trobar. Un cop se han vist i comprès, es gestionen sense problema.

\override VerticalAxisGroup.staff-affinity = ##f

\score {
  % Invàlid! Genera error: error de sintaxi, \new inesperat
  \new Staff { … }
  \new Staff { … }
}

2.1 Perquè canvia la sintaxi?

La sintaxi de l’entrada del LilyPond canvia de manera ocasional. A mesura que el propi LilyPond millora, la sintaxi (el llenguatge de l’entrada) es modifica en consonància. A vegades aquests canvis es fan per aconseguir que l’entrada sigui més fàcil de llegir i escriure, i d’altres vegades aquests canvis són per donar cabuda a noves funcionalitats del LilyPond.

Per exemple, se suposa que tots els noms de les propietats de \paper i de \layout estan escrits sota la norma primer-segon-tercer. Tot i així, a la versió 2.11.60, observem que la propietat printallheaders no seguia aquesta convenció. Hauríem de deixar-la tal com està (confonent als nous usuaris que han de tractar amb un format d’entrada inconsistent), o canviar-la (empipant als usuaris amb experiència que tenen partitures antigues)? En aquest cas, vam decidir canviar el nom a print-all-headers. Afortunadament, aquest canvi es pot automatitzar amb la nostra eina convert-ly.

Tanmateix, lamentablement convert-ly no pot tractar tots els canvis d’entrada. Per exemple, a la versió 2.4 i anteriors de LilyPond els accents i les lletres no angleses s’introdueixen utilitzant el LaTeX: per exemple No\"el (que significa ‘Nadal’ en francès). Al LilyPond 2.6 i següents el caràcter especial ë s’ha d’introduir directament al fitxer del LilyPond com un caràcter UTF-8. convert-ly no pot canviar tots els caràcters especials del LaTeX a caràcters de UTF-8: haureu d’actualitzar manualment els vostres fitxers del LilyPond antics.

Les regles de conversió de convert-ly funcionen usant correspondència i substitució de patrons de text enlloc d’una comprensió profunda de la sintaxi del LilyPond. Això té diverses conseqüències:

• El bon funcionament de la conversió depèn de la qualitat de cada conjunt de regles que s’apliquen i de la complexitat del canvi corresponent. A vegades les conversions poden necessitar correccions manuals, per la qual cosa la versió antiga hauria de conservar-se a efectes de comparació.
• Solament són possibles les conversions de formats més nous: no hi ha cap conjunt de regles per a la desactualització. Així doncs, la còpia principal de treball d’un fitxer del LilyPond solament s’ha d’actualitzar quan ja no hi ha necessitat de seguir mantenint versions antigues del LilyPond. Els sistemes de control de versions com ara el Git poden ser de gran ajuda per realitzar el manteniment de diverses versions dels mateixos fitxers.
• Els propis programes del LilyPond i de l’Scheme són força robustos enfront als espais afegits i suprimits de manera “creativa”, però les regles utilitzades per convert-ly tendeixen a fer certes suposicions d’estil. El millor que pot fer-se és seguir l’estil que s’usa als manuals per fer actualitzacions indolores, especialment perquè els propis manuals s’actualitzen usant convert-ly.

2.2 Invocació de convert-ly

convert-ly utilitza el enunciats \version dels fitxers d’entrada per detectar el número de versió antic. En gairebé tots els casos, per actualitzar el fitxer d’entrada sols cal executar

convert-ly -e elmeufitxer.ly

dins del directori que conté el fitxer. Amb això s’actualitza elmeufitxer.ly in situ i es preserva el fitxer original elmeufitxer.ly~.

Per convertir d’un cop tots els fitxers d’entrada que hi ha a un directori, useu

convert-ly -e *.ly

De forma alternativa, si volem especificar un nom diferent per al fitxer actualitzar, preservant el fitxer original amb el mateix nom, feu

convert-ly elmeufitxer.ly > elmeunoufitxer.ly

El programa imprimeix una relació dels números de versió per als que s’han fet conversions. Si no s’imprimeix cap número de versió, el fitxer ja està actualitzat.

Els usuaris del MacOS X poden executar aquesta instrucció sota el menú Compilar > Actualitzar sintaxi.

Els usuaris del Windows han d’introduir aquesta instrucció a una nova ventana del terminal del sistema, que es troba en general sota Inici > Accessoris > Símbol del sistema.

2.3 Opcions de la línia d’ordres per a convert-ly

En general, el programa s’invoca de la manera següent:

convert-ly [opció]… fitxer…

Es poden donar les opcions següents:

-d, --diff-version-update

Incrementa la cadena \version solament si el fitxer efectivament ha canviat. En tal cas, la capçalera de versió correspondrà a la versió següent a l’últim canvi efectiu. Sense aquesta opció la versió reflecteix l’última conversió que es va intentar fer.

-e, --edit

Aplica les conversions directament al fitxer d’entrada, modificant-lo in situ. El fitxer original es canvia de nom a elmeufitxer.ly~. Aquest fitxer de còpia de seguretat podria ser un fitxer ocult en alguns sistemes operatius.

-b, --backup-numbered

Quan s’usa amb l’opció ‘-e’, numera els fitxers de còpia de seguretat de forma que no se sobreescrigui cap versió anterior. Els fitxers de còpia de seguretat podrien ser fitxer ocults en alguns sistemes operatius.

-f, --from=versió_d_origen

Estableix la versió des de la qual s’ha de convertir. Si no apareix aquesta opció convert-ly intentarà endevinar-la, bastant-se en la instrucció \version del fitxer. Exemple: --from=2.10.25

-h, --help

Imprimeix l’ajuda d’utilització.

-l nivellderegistre, --loglevel=nivellderegistre

Fixa el grau en el qual la sortida és detallada a nivellderegistre. Els valors possibles són NONE (cap), ERROR (errors), WARN (advertiments), PROGRESS (avenç;predeterminat) i DEBUG (depuració).

-n, --no-version

Normalment convert-ly afegeix un indicador \version a la sortida. L’especificació d’aquesta opció el suprimeix.

-s, --show-rules

Mostra totes les conversions conegudes i surt.

-t, --to=versió_final

Fixa explícitament a quina \version convertir, en cas contrari el valor predeterminat és la versió més actual. Ha de ser més alta que la versió de partida.

convert-ly --to=2.14.1 elmeufitxer.ly

Per actualitzar fragments del LilyPond en fitxer de texinfo, useu

convert-ly --from=… --to=… --no-version *.itely

Per veure els canvis en la sintaxi del LilyPond entre dues versions donades, useu

convert-ly --from=… --to=… -s

2.4 Problemes amb convert-ly

En executar convert-ly a una finestra del Símbol de Sistema sota el Windows sobre un fitxer que té espais al nom o la ruta, és necessari tancar tot el nom del fitxer d’entrada amb tres (!) parelles de cometes:

convert-ly """D:/Les meves partitures/Oda.ly""" > "D:/Les meves partitures/nova Oda.ly"

Si l’ordre simple convert-ly -e *.ly no funciona perquè la instrucció expandida es fa massa llarga, en comptes de fer això l’ordre convert-ly es pot posar dins d’un bucle. Aquest exemple per a UNIX actualitza tots els documents .ly del directori actual

for f in *.ly; do convert-ly -e $f; done;

A la finestra del terminal d’ordres del Windows, la instrucció corresponent és

for %x in (*.ly) do convert-ly -e """%x"""

No es gestionen tots els canvis al llenguatge. Sols es pot especificar una opció de sortida. L’actualització automàtica del Scheme i les interfícies Scheme del LilyPond és força improbable; prepareu-vos per manipular el codi del Scheme a mà.

2.5 Conversions manuals

En teoria, un programa com convert-ly hauria de poder tractar qualsevol canvi de sintaxi. Després de tot, un programa d’ordinador interpreta les versions antiga i nova, per la qual cosa un altre programa d’ordinador podria traduir un fitxer a l’altre².

Tot i així, el projecte LilyPond compta amb uns recursos limitats: no totes les conversions s’efectuen automàticament. A continuació hi ha una llista de problemes coneguts.

1.6->2.0:
No sempre converteix el baix xifrat correctament, específicament
coses com ara {<
>}.  El comentari de Mats sobre com solucionar el
problema:
   Per poder executar convert-ly
   sobre ell, primer vaig sustituir totes les aparicions de '{<' a quelcom mut com ara '{#'
   i de forma semblant vaig sustituir '>}' amb '&}'.  Després de la conversió, vaig poder
   tornar a canviar-los de '{ #' a '{ <' i de '& }' a '> }'.
 No converteix tot l'etiquetatge de text correctament.  En sintaxi antiga,
 es podien agrupar diverses etiquetes entre parèntesis, per exemple
   -#'((bold italic) "cadena")
   Això es converteix incorrectament a
   -\markup{{\bold italic} "cadena"}
   en comptes del correcte
   -\markup{\bold \italic "cadena"}
2.0->2.2:
 No gestiona \partCombine
 No va \addlyrics => \lyricsto, això trenca algunes partitures amb diverses estrofes
2.0->2.4:
 \magnify no es canvia per \fontsize.
    - \magnify #m => \fontsize #f, on f = 6ln(m)/ln(2)
 remove-tag no es canvia.
    - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 first-page-number no es canvia.
    - first-page-number no => print-first-page-number = ##f
 Els salts de línia a les cadenes de capçalera no es converteixen.
    - \\\\  com salt de línia a les cadenes de \header  => \markup \center-align <
      "Primera línia" "Segona línia" >
 Els terminadors de crescendo i descrecendo no es converteixen.
    - \rced => \!
    - \rc => \!
2.2->2.4:
 \turnOff (usat a \set Staff.VoltaBracket = \turnOff) no es converteix
adequadament.
2.4.2->2.5.9
 \markup{ \center-align <{ ... }> } s'hauria de convertir a:
 \markup{ \center-align {\line { ... }} }
 però ara, falta el \line.
2.4->2.6
 Els caràcters especials del LaTeX com $~$ al text no es converteixen a UTF8.
2.8
 \score{} ara ha de començar amb una expressió musical.  Qualsevol alta cosa
 (en particular, \header{}) ha d'anar després de la música.

3.1 Un exemple de document musicològic

Certs texts contenen exemples musicals. Per exemple els tractats musicals, cançoners o manuals com aquest mateix. Aquests textos es poden fer a mà, important simplement una imatge en format PostScript a l’editor de textos. Malgrat això, hi ha un procediment automàtic per reduir la càrrega de treball que això implica amb documents HTML, LaTeX, Texinfo i DocBook. Un guió executable anomenat lilypond-book extrau els fragments de música, els dóna format i torna a posar en el seu lloc la partitura resultant. A continuació presentem un petit exemple de la seva utilització amb LaTeX. L’exemple conté també text explicatiu, per la qual cosa no el comentarem posteriorment.

Entrada

\documentclass[a4paper]{article}

\begin{document}

Els document per a \verb+lilypond-book+ poden barrejar lliurement música
i text.  Per exemple:

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

Les opcions s'escriuen entre claus.

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

Els exemples grans es poden gravar en fitxers separats i incloure'ls amb
\verb+\lilypondfile+.

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

(Si cal, substituïu @file{screech-and-boink.ly} per qualsevol fitxer
@file{.ly} ubicat al mateix directori que aquest fitxer.)

\end{document}

Processat

Deseu el codi anterior a un fitxer anomenat lilybook.lytex, i després executeu a una terminal:

lilypond-book --output=out --pdf lilybook.lytex
lilypond-book (GNU LilyPond) 2.25.21 
Llegint lilybook.lytex...
…molts missatges suprimits…
Compilant lilybook.tex…
cd out
pdflatex lilybook
…molts missatges suprimits…
xpdf lilybook
(substituïu xpdf pel vostre visualitzador favorit de PDF)

L’execució de lilypond-book i latex crea un gran nombre de fitxers temporals, que podrien omplir el directori de treball. Per solucionar això, utilitzeu l’opció --output=directori. Crearà els fitxers a un subdirectori a part directori.

Finalment el resultat de l’exemple de LaTeX que acabem de mostrar³. Així acaba la secció del tutorial.

Sortida

Els documents per lilypond-book poden barrejar lliurement música i text. Per exemple:

Les opcions s’escriuen entre claus.

c'4 f16

Els exempes grans es poden gravar en fitxers separats i introduir-se amb \lilypondfile.

Si es requereix un camp tagline, ja sigui predeterminat o personalitzat, aleshores el fragment complet s’ha d’incloure dins d’una construcció \book { }.

\book{
  \header{
    title = "Una escala al LilyPond"
  }

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

3.2 Integració de música i text

Aquí explicarem com integrar el LilyPond amb alguns altres formats de sortida.

\begin{lilypond}[las,opciones,van,aquí]
  EL CODI DEL LILYPOND
\end{lilypond}

\lilypond[le,opcions,van,aquí]{ EL CODI DEL LILYPOND }

\lilypondfile[les,opcions,van,aquí]{fitxer}

\musicxmlfile[les,opcions,van,aquí]{fitxer}

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

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

\def\betweenLilyPondSystem#1{\endinput}

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

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

\let\betweenLilyPondSystem\undefined

\def\onlyFirstNSystems#1{
    \def\betweenLilyPondSystem##1{\ifnum##1<#1\else\endinput\fi}
}

\onlyFirstNSystems{3}
\begin{lilypond}…\end{lilypond}
\onlyFirstNSystems{1}
\begin{lilypond}…\end{lilypond}

@lilypond[les,opcions,van,aquí]
  EL CODI DEL LILYPOND
@end lilypond

@lilypond[les,opcions,van,aquí]{ EL CODI DEL LILYPOND }

@lilypondfile[les,opcions,van,aquí]{fitxer}

@musicxmlfile[les,opcions,van,aquí]{fitxer}

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

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

<lilypond les opcions van aquí>
  EL CODI DEL LILYPOND
</lilypond>

<lilypond les opcions van aquí: EL CODI DEL LILYPOND />

<lilypondfile les opcions van aquí>fitxer</lilypondfile>

<musicxmlfile les opcions van aquí>fitxer</musicxmlfile>

<lilypond fragment relative=2>
\key c \minor c4 es g2
</lilypond>

Quelcom de música dins de <lilypond relative=2: a b c/> una línia de
text.

<lilypondfile opció1 opció2 …>fitxer</lilypondfile>

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

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

3.3 Opcions de fragments de música

Durant els pròxims paràgrafs, una ‘ordre del LilyPond’ es refereix a qualsevol ordre descrita en les seccions anteriors que es fa amb lilypond-book perquè produeixi un fragment de música. Per simplicitat, les ordres del LilyPond sols es mostren en la sintaxi del LaTeX.

Observeu que la cadena d’opcions s’analitza d’esquerra a dreta; si una opció apareix diverses vegades, s’agafa sols l’última.

Per a les ordres del Lilypond, hi ha disponibles les següents opcions:

staffsize=alçada

Estableix l’alçada del pentagrama com alçada, mesurada en punts.

ragged-right

Produeix línies no justificades per la dreta i amb espaiat natural, és a dir, s’afegeix ragged-right = ##t al fragment del LilyPond. Els fragments d’una sola línia sempre es graven de forma predeterminada sense justificació per la dreta, a no ser que s’usi explícitament l’opció noragged-right.

noragged-right

Per a fragments d’una sola línia, permet que la longitud del pentagrama s’amplii fins igualar l’amplada de la línia, és a dir, s’afegeix ragged-right = ##f al fragment del LilyPond.

line-width

line-width=mida\unitats

Estableix l’amplada de línia com a mida, utilitzant unitats com a unitat. unitats és una de les cadenes següents: cm, mm, in o pt. Aquesta opció afecta a la sortida del LilyPond (és a dir, a la longitud del pentagrama del fragment musical), no al format del text.

Si s’usa sense cap argument, s’estableix l’amplada de la línia a un valor predeterminat (calculat amb un algoritme heurístic).

Si no es dóna cap opció line-width, lilypond-book intenta endevinar un valor predeterminat per als entorn lilypond que no usen l’opció ragged-right.

papersize=cadena

On cadena és una mida del paper definit al fitxer scm/paper.scm, es a dir, a5, quarto, 11x17, etc.

Els valors no definits al fitxer scm/paper.scm s’ignoren, s’emet un advertiment i el fragment s’imprimeix utilitzant la mida predeterminada a4.

notime

No s’imprimeix la indicació de compàs, i es desactiven les indicacions temporals de la música (indicació del compàs i línies divisòries).

fragment

Fa que lilypond-book afegeixi alguns codis necessaris perquè podem escriure simplement, per exemple,

c'4

sense \layout, \score, etc.

nofragment

No incloure el codi addicional que completa la sintaxi del LilyPond als fragments de música. En ser l’opció predeterminada, nofragment normalment és redundant.

indent=mida\unitats

Estableix el sagnat del primer sistema de pentagrames com mida, utilitzant unitats com unitat. unitats és una de les cadenes següents: cm, mm, in o pt. Aquesta opció afecta al Lilypond, no al format del text. Atès que el valor predeterminat és que no hi hagi cap sagnat, noindent normalment es redundant.

quote

Redueix la longitud de la línia d’un fragment musical en 2*0.4in (polzades) i col·loca la sortida dins d’un bloc de cita (quotation). El valor de ‘0.4in’ es pot controlar amb l’opció exampleindent.

exampleindent

Estableix la longitud del sagnat que l’opció quote aplica al fragment musical.

relative

relative=n

Fa usar el mode d’octava relativa. De forma predeterminada, les notes s’especifiquen amb relació al Do central. L’argument sencer opcional especific l’octava de la nota inicial, on el valor predeterminat 1 és el Do central. L’opció relative sols funciona quan està establert l’opció fragment, de manera que fragment es defineix automàticament per relative, independentment de la presència de fragment o de nofragment en la font.

El LilyPond utilitza també lilypond-book per produir la seva pròpia documentació. Per fer-ho, hi ha certes opcions quelcom esotèriques per als fragments musicals.

verbatim

L’argument d’una ordre del LilyPond es copia al fitxer de sortida i s’inclou dins d’un bloc «verbatim» o reformatat, seguit del text que s’escrigui amb l’opció intertext (que encara no funciona); després s’imprimeix la música mateixa. Aquesta opció no funciona bé amb \lilypond{} si forma part d’un paràgraf.

Si s’una l’opció verbatim dins d’una ordre lilypondfile, és possible incloure amb estile preformatejat sols una part del fitxer font. Si el fitxer de codi font conté un comentari que conté ‘begin verbatim’ (sense les cometes), la cita del bloc d’estil preformatejat començarà després de l’última vegada que aparegui aquest comentari; de forma semblant, la cita del bloc preformatejat es detindrà just abans de la primera vegada que aparegui un comentari que contingui ‘end verbatim’, si n’hi ha. Al següent exemple de cori font, la música s’interpreta en el mode relatiu, però la cita formatada prèviament no presentarà el bloc relative, es dir

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

s’imprimeix com un bloc formatat prèviament com

  c4 e2 g4
  f2 e

Si volem traduir els comentaris i els noms de variable a la sortida literal però no en el codi font, podem establir el valor de la variable d’entorn LYDOC_LOCALEDIR a la ruta d’un directori; aquest directori ha de contenir un arbre de catàlegs de missatges .mo amb lilypond-doc com a domini.

texidoc

(Sols per a la sortida del Texinfo). Si es crida a lilypond amb l’opció --header=texidoc, i el fitxer que es processa es diu pepet.ly, es crea un fitxer pepet.texidoc si existeix un camp texidoc dins del bloc \header de capçalera. L’opció texidoc fa que lilypond-book inclogui aquests fitxers, afegint el seu contingut com un bloc de documentació immediatament abans del fragment musical (però fora de l’entorn immediatament abans del fragment musical (però fora de l’entorn example generat per l’opció quote).

Suposant que el fitxer pepet.ly conté

\header {
  texidoc = "Aquest fitxer és un exemple d'una sola nota."
}
{ c'4 }

i que tenim el següent al nostre document de Texinfo prova.texinfo

@lilypondfile[texidoc]{pepet.ly}

l’ordre següent dóna com a sortira el resultat esperat:

lilypond-book --pdf --process="lilypond \
  --header=texidoc" prova.texinfo

La majoria dels documents de prova del LilyPond (al directori input de la distribució) són petits fitxers .ly que contenent exactament aquest aspecte.

Per motius de localització d’idioma, si el document de Texinfo conté @documentlanguage LANG i la capçalera de loquesea.ly conté un camp texidocLANG, i lilypond s’executa amb --header=texidocLANG, aleshores s’inclourà loquesea.texidocLANG enlloc de loquesea.texidoc.

doctitle

(Sols per a la sortida de Texinfo.) Aquesta opció funciona de forma semblada a l’opció texidoc: si lilypond es crida amb l’opció --header=doctitle, y el fitxer a processar es diu elquesigui.ly i conté un camp doctitle al bloc \header, es crea un fitxer elquesigui.doctitle. Quan s’usa l’opció doctitle, el contingut de elquesigui.doctitle, que hauria de ser una línia única de text, s’insereix en el document de Texinfo com @lydoctitle text. @lydoctitle ha de ser un macro definit en el document de Texinfo. La mateixa indicació referida al processat de texidoc amb llengües localitzades s’aplica a doctitle.

nogettext

(Sols per a la sortida de Texinfo.) No traduïu els comentaris i noms de variable en el fragment de codi literal citat.

printfilename

Si un fitxer d’entrada del LilyPond s’inclou amb \lilypondfile, imprimeix el nom del fitxer immediatament abans del fragment musical. Per a la sortida HTML, això és un enllaç. Sols s’imprimeix el nom del base del fitxer, és a dir, s’elimina la part del directori de la ruta del fitxer.

3.4 Invocació lilypond-book

lilypond-book produeix un fitxer amb una de les extensions següents: .tex, .texi, .html o .xml, depenent del format de sortida. A tots els fitxers .tex, .texi i .xml els cal un processat posterior.

Instruccions específiques de format

LaTeX

Hi ha dues formes de processar el document en LaTeX per a la seva impressió o publicació: fer un fitxer PDF directament amb PDFLaTeX, o generar un fitxer PostScript amb LaTeX mitjançant un traductor de DVI a Postscript com dvips. La primera forma és senzilla i és la que es recomana⁴, i qualsevol que sigui el mètode que utilitzeu, podreu convertir fàcilment entre PostScript i PDF amb eines com ps2pdf i pdf2ps que venen incloses amb Ghostscript.

Per produir un fitxer PDF mitjançant PDFLaTeX, utilitzeu:

lilypond-book --pdf elmeufitxer.pdftex
pdflatex elmeufitxer.tex

Per produir una sortida PDF per mitjà de LaTeX/dvips/ps2pdf:

lilypond-book elmefitxer.lytex
latex elmeufitxer.tex
dvips -Ppdf elmeufitxer.dvi
ps2pdf elmeufitxer.ps

El fitxer .dvi creat per aquest procés no conté els caps de les notes. Això és normal; si segueix les instruccions, els caps apareixeran als fitxers .ps i .pdf.

El fitxer .dvi creat per aquest procés no conté els caps de les notes. Això és normal; si seguiu les instruccions, els caps apareixeran als fitxers .ps i .pdf.

L’execució de dvips pot donar com a resultat alguns advertiments sobre els tipus de lletra; són innocus i es poden ignorar. Si esteu executant latex en mode de dos columnes, recordeu afegir -t landscape a les opcions de dvips.

Entorns como ara:

\begin{lilypond} … \end{lilypond}

no s’interpreten per part de LaTeX. En canvi, el programa lilypond-book extrau aquests ‘entorns’ com fitxers independents i executa el LilyPond sobre ells. Després, agafa les imatges resultants i crea un fitxer .tex en el qual les macros \begin{lilypond}…\end{lilypond} se substitueixen per ordres de ‘inserció de gràfics’. A continuació, s’executa LaTeX (tot i que LaTeX se ha executat anteriorment, ho haurà fet sobre un fitxer ‘buit’ per calcular coses com ara el \linewidth).

Advertiments i problemes coneguts

L’ordre \pageBreak no funciona dins d’un entorn \begin{lilypond} … \end{lilypond}.

Moltes variables del bloc \paper tampoc funcionen dins d’un entorn \begin{lilypond} … \end{lilypond}. Useu \newcommand amb \betweenLilyPondSystem al preàmbul:

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

Texinfo

Per produir un document de Texinfo (en qualsevol format de sortida), seguiu el procediment normal per a Texinfo, això és: o bé crideu a texi2pdf o a texi2dvi o a texi2any, segons el format de la sortida que voleu crear. Consulteu la documentació de Texinfo per veure més detalls.

Opcions de la línia d’ordres

lilypond-book accepta les opcions següents de la línia d’ordres:

-f formato

--format=formato

Especificació del tipus de document que es processarà: html, latex, texi (predeterminat) o docbook. Si falta aquesta opció, lilypond-book intentarà detectar el format automàticament, vegeu Extensions de noms de fitxer. Per ara, texi és el mateix que texi-html.

-F filtro

--filter=filtro

Conducció de fragments a través de filter per mitjà d’una canonada. lilypond-book no obeirà –filter i –process al mateix temps. Per exemple,

lilypond-book --filter='convert-ly --from=2.0.0 -' el-meu-llibre.tely

-h

--help

Impressió d’un breu missatge d’ajuda.

-I directori

--include=directori

Afegir directori a la ruta d’inclusió. lilypond-book busca també els fragments compilats a la ruta d’inclusió, i no els torna a escriure al directori de sortida, de manera que en certs casos cal invocar ordres de processat posteriors com ara texi2any o latex amb les mateixes opcions -I directori.

-l nivell_de_registre

--loglevel=nivel_de_registre

Fixació del nivell en el qual la sortida és neta, al valor nivell_de_registre. Els valors possibles són NONE (res), ERROR (errors), WARN (advertiments), PROGRESS (avanç; predeterminat) y DEBUG (depuració). Si aquesta opció no es fa servir, i està establerta la variable d’entorn LILYPOND_BOOK_LOGLEVEL, s’usa el seu valor com a nivell de registre.

-o directori

--output=directori

Col·locació dels fitxers generats al directori. L’execució de lilypond-book genera un munt de petits fitxers que després processarà el Lilypond. Per evitar tots aquests fitxers al mateix directori que el codi font, feu servir l’opció --output, i canvieu a aquest directori abans d’executar latex o texi2any.

lilypond-book --output=out elmeufitxer.lytex
cd out
…

--skip-lily-check

Obviar la fallada si no es troba cap sortida del lilypond. Es fa servir per a la documentació del Lilypond en format info sense imatges.

--skip-png-check

Obviar la fallada si no es troben les imatges PNG dels fitxers EPS. S’usa per a la documentació del Liypond en format info sense imatges.

--lily-output-dir=directorio

Escriptura de fitxers lily-XXX al directori directori, enllaç al directori de --output. Useu aquesta opció per estalviar temps de construcció per a documents de diferents directoris que comparteixen molts fragments idèntics de codi.

--lily-loglevel=nivell de registre

Establiment del nivell en el qual la sortida és neta per a les crides de l’ordre invocat lilypond, al valor nivell _de_registre. Els valors possibles sónNONE (res), ERROR (errors), WARN (advertiments), BASIC (avanç bàsic), PROGRESS (avanç), INFO (informació; predeterminat) i DEBUG (depuració). Si no es fa servi aquesta opció i la variable d’entorn LILYPOND_LOGLEVEL està establerta, el seu valor es fa servir com a nivell de registre.

--info-images-dir=directori

Formatat de la sortida del Texinfo de manera que info busqui les imatges de música a directorio.

--latex-program=prog

Execució del programa prog en comptes de latex. Això és útil si el nostre document es processa amb xelatex, per exemple.

--left-padding=quantitat

Ompliment el voltant de les caixes EPS per la quantitat donada. quantitat es mesura en mil·límetres, amb 3.0 com a valor predeterminat. Aquesta opció s’ha d’usar si les línies de música estan massa pegades al marge dret.

L’amplada d’un sistema que està molt ajustat dins del seu rectangle pot variar, a causa dels elements de notació que estan pegats al marge esquerre, com ara els nombres de compàs i el nom de l’instrument. Aquesta opció fa més curts totes les línies i les mou a la dreta en la mateixa mesura.

-P instrucció

--process=instrucció

Processament dels fragments del Lilypond utilitzant ordre. L’ordre predeterminada és lilypond. lilypond-book no obeirà a --filter i a --process al mateix temps.

--pdf

Creació de fitxers PDF per al seu ús amb PDFLaTeX.

--redirect-lilypond-output

De forma predeterminada, la sortida s’imprimeix per la consola. Aquesta opció redirigeix tota la sortida cap a fitxers de registre ubicats al mateix directori que els fitxers font.

--use-source-file-names

Escriptura dels fitxers de sortida dels fragments de música amb el mateix nom de base que el seu fitxer font. Aquesta opció sols funciona per a fragments inclosos amb lilypondfile i sols si els directoris determinats per les opcions --output-dir i --lily-output-dir són diferents.

-V

--verbose

Sigues net. Qeuival a --loglevel=DEBUG.

-v

--version

Impressió de la informació de la versió.

Advertiments i problemes coneguts

L’ordre del Texinfo @pagesizes no s’interpreta. De manera semblant, s’ignoren les ordre del LaTeX que canvien els marges i amplades de línia després del preàmbul.

Sols es processa el primer \score d’un bloc Lilypond.

3.5 Extensions de noms de fitxer

Podeu fer servir qualsevol extensió per al nom del fitxer d’entrada, però si no useu l’extensió recomanada per a un format en particular, haureu d’especificar manualment el format de sortida; per veure més detalls, consulteu Invocació lilypond-book. En cas contrari, lilypond-book selecciona automàticament el format de sortida basant-se en l’extensió del nom del fitxer d’entrada.

extensió	format de sortida
.html	HTML
.htmly	HTML
.itely	Texinfo
.latex	LaTeX
.lytex	LaTeX
.lyxml	DocBook
.tely	Texinfo
.tex	LaTeX
.texi	Texinfo
.texinfo	Texinfo
.xml	HTML

Si useu la mateixa extensió per al fitxer d’entrada que la que usa el lilypond-book per al fitxer de sortida, i si el fitxer d’entrada està al mateix directori que el directori de treball de lilypond-book, heu d’usar l’opció --output perquè funcioni lilypond-book, atès que en cas contrari s’emetrà un missatge d’error com per exemple “La sortida sobreescriurà el fitxer d’entrada”.

3.6 Plantilles de lilypond-book

Aquestes plantilles s’usen per a lilypond-book. Si no esteu familiaritzat amb aquest programa, consulteu Execució de lilypond-book.

LaTeX

Podem inserir fragments del LilyPond dins d’un document del LaTeX.

\documentclass[]{article}

\begin{document}

Text normal en LaTeX.

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

Més text en LaTeX, i les opcions dins de les claus.

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

Texinfo

Podem inserir fragments del LilyPond dins del Texinfo; de fet, tot aquest manual està escrit en Texinfo.

\input texinfo @node Top
@top

Text en Texinfo

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

Més text en Texinfo, i les opcions dins de les claus.

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

@bye

html

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

<p>
El documents per al lilypond-book poden barrejar música i text
lliurement.  Per exemple,
<lilypond>
\relative {
  a'4 b c d
}
</lilypond>
</p>

<p>
Una mica més de LilyPond, aquest cop amb opcions:

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

</body>
</html>

xelatex

\documentclass{article}
\usepackage{ifxetex}
\ifxetex
%material específic xetex
\usepackage{xunicode,fontspec,xltxtra}
\setmainfont[Numbers=OldStyle]{Times New Roman}
\setsansfont{Arial}
\else
%Això es pot deixar buit si no farem servir pdftex
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{mathptmx}%Times
\usepackage{helvet}%Helvetica
\fi
%Aquí inserim tots els paquets que el pdftex també entén
\usepackage[ngerman,finnish,english]{babel}
\usepackage{graphicx}

\begin{document}
\title{Un document breu amb el LilyPond i xelatex}
\maketitle

Les ordres \textbf{font} normals dins del \emph{text}
funcionen, perquè \textsf{tenen suport al \LaTeX{} i
el XeTeX.}  Si volem usar ordres específiques com ara
\verb+\XeTeX+, hem d'incloure-les de nou dins d'un entorn
\verb+\ifxetex+.  Podem utilitzar això per imprimir l'ordre
\ifxetex \XeTeX{} \else XeTeX \fi que no està inclosa al
\LaTeX\ normal.

Dins del text normal podem utilitzar ordres del LilyPond
fàcilment, d'aquesta forma:

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

\noindent
i així successivament.

El tipus de lletra dels fragments, establerta amb el LilyPond,
haurà d'establir-se de dins el fragment.  Per això podeu llegir la
part del lilypond-book al manual d'utilització.

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

3.7 Compartir l’índex general

Aquestes funcions ja existeixen al paquet OrchestralLily:

http://repo.or.cz/w/orchestrallily.git

Per aconseguir més flexibilitat en el processament del text, alguns usuaris prefereixen exporta l’índex general o taula de continguts des del Lilypond i llegir-lo dins del LaTeX.

Exportació de l’index general des del LilyPond

Això suposa que la nostra partitura té diversos moviments dins del mateix fitxer de sortida del LilyPond.

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

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

Importació de l’índex general dins del LaTeX

Al LaTeX, la capçalera ha d’incloure el següent:

\usepackage{pdfpages}
\includescore{nombredelapartitura}

donde \includescore està definit com:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \includescore{PossibleExtension}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Llegir els budells de l'índex genera per a un fitxer PDF
% a partir del fitxer .toc corresponent.
% Això requereix de força ajustaments del LaTeX, perquè no és
% fàcil llegir coses d'un fitxer i inserir-les dins dels arguments
% d'un macro.

% Solució del Patrick Fimml en el canal #latex el 18 d'abril de 2009:
% \readfile{filename}{\variable}
% llegeix el contingut del fitxer en \variable (no definida si el
% fitxer no existeix)
\newread\readfile@f
\def\readfile@line#1{%
{\catcode`\^^M=10\global\read\readfile@f to \readfile@tmp}%
\edef\do{\noexpand\g@addto@macro{\noexpand#1}{\readfile@tmp}}\do%
\ifeof\readfile@f\else%
\readfile@line{#1}%
\fi%
}
\def\readfile#1#2{%
\openin\readfile@f=#1 %
\ifeof\readfile@f%
\typeout{No TOC file #1 available!}%
\else%
\gdef#2{}%
\readfile@line{#2}%
\fi
\closein\readfile@f%
}%


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

3.8 Mètodes alternatius per barrejar text i música

Altres formes de barrejar text i música (sense lilypond-book) s’estudien a Altres programes.

4.1 Point and click

Point and click lets you find notes in the input by clicking on them in the PDF viewer. This makes it easier to find input that causes some error in the sheet music.

export LYEDITOR=atom

atom %(file)s:%(line)s:%(column)s

export LYEDITOR="code --goto %(file)s:%(line)s:%(column)s"

[Desktop Entry]
Version=1.0
Name=lilypond-invoke-editor
GenericName=Textedit URI handler
Comment=URI handler for textedit:
Exec=lilypond-invoke-editor %u
Terminal=false
Type=Application
MimeType=x-scheme-handler/textedit;
Categories=Editor
NoDisplay=true

xdg-desktop-menu install ./lilypond-invoke-editor.desktop
xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit

xdg-open textedit:///etc/issue:1:0:0

# For Textedit links
/usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,

sudo apparmor_parser -r -T -W /etc/apparmor.d/usr.bin.evince

\pointAndClickOff

\pointAndClickOn

lilypond -dno-point-and-click file.ly

4.2 Text editor support

There is support for different text editors for LilyPond.

(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))

filetype off
set runtimepath+=/usr/local/share/lilypond/current/vim/
filetype on
syntax on

4.3 Converting from other formats

Music can be entered also by importing it from other formats. This chapter documents the tools included in the distribution to do so. There are other tools that produce LilyPond input, for example GUI sequencers and XML converters. Refer to the website for more details.

These are separate programs from lilypond itself, and are run on the command line; see Utilització des de la línia d’ordres for more information.

Advertiments i problemes coneguts

We unfortunately do not have the resources to maintain these programs; please consider them “as-is”. Patches are appreciated, but bug reports will almost certainly not be resolved.

midi2ly [option]… midi-file

musicxml2ly [option]… file.xml

abc2ly [option]… abc-file

%%LY voices \set autoBeaming = ##f

%%LY slyrics more words

etf2ly [option]… etf-file

4.4 LilyPond output in other programs

This section shows methods to integrate text and music, different than the automated method with lilypond-book.

lilypond -dseparate-page-formats=pdf myfile.ly

lilypond -dtall-page-formats=png myfile.ly

lilypond -dseparate-page-formats=eps,pdf -dtall-page-formats=png,svg myfile.ly

\paper{
  indent=0\mm
  oddFooterMarkup=##f
  oddHeaderMarkup=##f
  bookTitleMarkup = ##f
  scoreTitleMarkup = ##f
}

… music …

4.5 Independent includes

Some users have produced files that can be \included with LilyPond to produce certain effects and those listed below are part of the LilyPond distribution. Also see Working with input files.

5.1 Suggeriments de tipus general

Us presentem alguns suggeriments que us poden servir d’ajuda per evitar o corregir problemes:

• Incloeu els números de \version a tots els fitxers. Adoneu-vos que totes les plantilles contenen informació sobre la versió (\version). Us recomanem molt que sempre incloeu la versió, tot i que els vostre fitxer pugui ser molt petit. Des de l’experiència personal us podem dir que força frustrant intentar recordar el número de versió del LilyPond que estàveu fent servir fa uns anys. convert-ly requereix que declareu quina versió del LilyPond fèieu servir.
• Incloeu comprovacions: Comprovació de compàs i de número de compàs, Comprovació d’octava. Si incloeu comprovacions de tant en tant, en cas que cometeu un error podreu localitzar-lo molt més ràpidament. Amb quina freqüència és ‘de tant en tant’? Depèn de la complexitat de la música. Per a una música molt senzilla, potser tan sols una o dues vegades. Per a una música molt complexa, potser a cada compàs.
• Un compàs per cada línia de text. Si hi ha quelcom molt complicat, ja sigui a la pròpia música o a la sortida que desitgeu produir, sovint convé escriure un sol compàs per a cada línia. L’estalvi en espai de pantalla que s’obté acumulant nou compassos per línia no paga la pena si després heu de ‘depurar’ els fitxers.
• Comenteu els fitxers. Utilitzeu o bé números de compàs (de tant en tant), o referències a temes musicals (‘segon tema dels violins,’ ‘quarta variació,’ etc.). Potser que no us calguin comentaris quan introduïu una peça per primer cop, però si voleu tornar a ella o modificar quelcom al cap de dos o tres anys, i també si li passeu la font a un amic, serà tot un desafiament determinar les seves intencions o de quina menara estava estructurat el fitxer si no li heu afegit els comentaris.
• Apliqueu marges a les claus. Molts problemes estan casat per una falta d’equilibri en el nombre de { i }.
• Escriviu les duracions explícitament al començament de les seccions i identificadors. Si especifiqueu c4 d e al principi d’una frase (en lloc de sols c d e) us podeu estalviar problemes si reelaboreu la música més tard.
• Separeu els ajustaments de les definicions musicals. Consulteu Estalvi de tecleig mitjançant variables i funcions i Fulls d’estil

5.2 Gravació de música existent

Si esteu introduint música a partir d’una partitura existent (és a dir, gravant un full de música ja imprès),

• Introduïu al LilyPond cada sistema del manuscrit, o còpia física, per separat (però manteniu la pràctica d’escriure un compàs per línia de text), i comproveu cada sistema quan l’hàgiu acabat. Podeu usar les propietats showLastLength o showFirstLength per accelerar el procés (vegeu Salts sobre la música corregida.
• Definiu mBreak = { \break } i inseriu \mBreak dins del fitxer d’entrada on el manuscrit tingui un salt de línia. D’aquesta forma us resultarà molt més fàcil comparar la música del LilyPond amb l’original. Quan hageu acabat de revisar la vostra partitura podreu definir mBreak = { } per treure tots aquests salts de línia. Així permetreu el LilyPond col·locar els salts on el LilyPond el consideri més oportú.
• En escriure una part per a un instrument transpositor dins d’una variable, es recomana que les notes estiguin envoltades dins de

  \transpose c altura-natural {…}
  

  (on altura-natural és l’afinació natural de l’instrument) de forma que la música dins de la variable estigui realment en Do major. Després podem tornar a transportar-les en sentit invers quan s’utilitza la variable, si és necessari, però potser no vulguem fer-lo (per exemple en imprimir una partitura en afinació de concert, en convertir una part de trombó de clau de Sol a clau de Fa, etc.). És menys probable cometre errors als transports si tota la música que està dins de les variables es troba en un to coherent.

  A més a més, feu els transport exclusivament cap o des de Do major. Això significa que a part de Do major, les úniques tonalitats que usarem seran els tons d’afinació dels instruments transpositors: bes per a una trompeta en Si bemoll, aes per a un clarinet en La bemoll, etc.

5.3 Projectes grans

En treballar en projectes grans es fa essencial tenir una estructura clara als fitxers dels LilyPond:

• Utilitzeu un identificador per a cada veu, amb un mínim d’estructura dins de la definició. L’estructura de la secció \score és la que canviarà amb major probabilitat: per contra, és extremadament improbable que canviï la definició de violí a versions noves del LilyPond.

  violí = \relative {
  g'4 c'8. e16
  }
  …
  \score {
    \new GrandStaff {
      \new Staff {
        \violí
      }
    }
  }
  

• Separeu els ajustaments de les definicions musicals. Ja s’ha mencionat amb anterioritat, però per a projectes grans és vital. Potser haurem de canviar la definició de fdesprésp, però en aquest cas sols ho haurem de fer un cop, i encara podrem evitar tocar res dins de violí.

  fdesprésp = _\markup{
    \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
  violí = \relative {
  g'4\fluegop c'8. e16
  }
  

5.4 Solució de problemes

Abans o després escriureu un fitxer que el LilyPond no podrà compilar. Els missatges que el LilyPond proporciona poden ajudar-vos a trobar l’error, però en molts casos haureu de portar endavant algun tipus d’investigació per determinar l’origen del problema. Les eines més poderoses per a aquest propòsit son el comentari d’una sola línia (indicat per %) i el comentari de bloc (indicat per %{…%}). Si no sabeu on és el problema, comenceu convertint seccions grans del fitxer d’entrada en un comentari. Després d’eliminar una secció convertint-la en un comentari, proveu a compilar un fitxer un altre cop. Si funciona, aleshores el problema hauria d’estar a la porció que havíeu eliminat. Si no funciona, continueu eliminant material (transformant-lo en comentaris) fins que tingueu quelcom que funcioni.

En un cas extrem podríeu acabat amb sols

\score {
  <<
    % \melodia
    % \armonia
    % \baix
  >>
  \layout{}
}

(en altres paraules: un fitxer sense música)

Si passa això, no abandoneu. Traieu el comentari d’una secció petita – diguem-ne la part del baix – i observeu si funciona. Si no és així, transformeu en comentaris tota la música del baix (però deixeu el \baix de la secció \score no comentat.

bajo = \relative {
%{
  c'4 c c c
  d d d d
%}
}

Ara comenceu poc a poc traient comentaris a cada cop més fraccions de la part del baix fins que trobeu la línia del problema.

Una altra tècnica de depuració molt útil és la construcció de Exemples mínims.

5.5 Make i els Makefiles

Possiblement totes les plataformes on pot executar-se el LilyPond contemplen una possibilitat de programari anomenada make. Aquest programa llegeix un fitxer especial anomenat Makefile que defineix les relacions de dependència entre els fitxers i quines instruccions necessitem donar al sistema operatiu per produir un fitxer a partir d’un altre. Per exemple, el fitxer de make detallaria com obtenir balada.pdf i balada.midi a partir de balada.ly mitjançant l’execució del LilyPond.

Hi ha ocasions en les quals és una bona idea crear un Makefile per al nostre projecte, bé sigui per la nostra pròpia comoditat o com a cortesia per a altres que possiblement tinguin accés als nostres fitxers font. Això és cert per a projectes molt grans amb molts fitxers d’inclusió i diferents opcions de sortida (per exemple partitura completa, particel·les, partitura del director, reducció per a piano, etc.), o per a projectes que requereixen ordres difícils per muntar-los (com els projectes de lilypond-book). La complexitat i flexibilitat dels Mekfiles varia enormement segons les necessitats i l’habilitat dels autors. El programa GNU Make ve instal·lat a les distribucions del GNU/Linux i al MacOS X, i també existeix per al Windows.

Consulteu el Manual de GNU Make per veure tots els detalls sobre l’ús de make, atès que el segueix a continuació ofereix sols una pinzellada de tot els és capaç de fer.

Les instruccions que defineixen les regles a un fitxer de make difereixen en funció de la plataforma; per exemple, les diferents formes del GNU/Linux i del MacOS usen bash, mentre que el Windows usa cmd. Observeu que al MacOS C, hem de configurar el sistema perquè faci servir l’interpret d’ordres. A continuació presentem alguns makefiles d’exemple, amb versions tant per al GNU/Linux/MacOS com per al Windows.

El primer exemple és per a una obra orquestral en quatre moviments amb l’estructura de directoris següent:

Sinfonia/
|-- MIDI/
|-- Makefile
|-- Notes/
|   |-- cello.ily
|   |-- xifres.ily
|   |-- trompa.ily
|   |-- oboe.ily
|   |-- trioCordes.ily
|   |-- viola.ily
|   |-- violiU.ily
|   `-- violiDos.ily
|-- PDF/
|-- Particelles/
|   |-- sinfonia-cello.ly
|   |-- sinfonia-trompa.ly
|   |-- sinfonia-oboes.ly
|   |-- sinfonia-viola.ly
|   |-- sinfonia-violiU.ly
|   `-- sinfonia-violiDos.ly
|-- Partitures/
|   |-- sinfonia.ly
|   |-- sinfoniaI.ly
|   |-- sinfoniaII.ly
|   |-- sinfoniaIII.ly
|   `-- sinfoniaIV.ly
`-- sinfoniaDefs.ily

Els fitxers .ly dels directoris Partitures i Particelles obtenen les notes de fitxers .ily que estan al directori Notes:

%%% principi del fitxer "sinfonia-cello.ly"
\include ../definicionsSinf.ily
\include ../Notes/cello.ily

El makefile tindrà els objectius de partitura (la peça completa en tot el seu esplendor), moviments (partitura completa dels moviments individuals) i particel·les (parts individuals per als faristols). També hi ha un objectiu fitxer que produeix un fitxer tar de distribució (tarball) dels fitxers font, adequat per compartir-lo a través de la web o per correu electrònic. A continuació presentem el makefile per a GNU/Linux o MacOS C. S’ha de desar amb el nom exacte Makefile al directori superior del projecte:

# nom principal dels fitxers de sortida
nom = sinfonia
# determinació del nombre de processadors
CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
# L'ordre per executar el LilyPond
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click -djob-count=$(CPU_CORES)

# Els sufixos utilitzats a aquest Makefile.
.SUFFIXES: .ly .ily .pdf .midi

# Els fitxers d'entrada i de sortida es busquen dins dels directoris relacionats a
# la variable VPATH.  Tots ells són subdirectoris del directori
# en curs (donat per la variable de GNU make `CURDIR').
VPATH = \
  $(CURDIR)/Partitures \
  $(CURDIR)/PDF \
  $(CURDIR)/Particelles \
  $(CURDIR)/Notes

# La regla de patró per crear fitxers PDF i MIDI a partir fitxers d'entrada LY
# Els fitxers de sortida .pdf es col·loquen al subdirectori `PDF', i els fitxers
# .midi van al subdirectori `MIDI'.
%.pdf %.midi: %.ly
        $(LILY_CMD) $<; \           # Aquesta línia comença amb un salt de tabulació
        if test -f "$*.pdf"; then \
            mv "$*.pdf" PDF/; \
        fi; \
        if test -f "$*.midi"; then \
            mv "$*.midi" MIDI/; \
        fi

notes = \
  cello.ily \
  trompa.ily \
  oboe.ily \
  viola.ily \
  violiU.ily \
  violiDos.ily

# Dependències dels moviments
$(nom)I.pdf: $(nom)I.ly $(notes)
$(nom)II.pdf: $(nom)II.ly $(notes)
$(nom)III.pdf: $(nom)III.ly $(notes)
$(nom)IV.pdf: $(nom)IV.ly $(notes)

# Dependències de la partitura completa.
$(nom).pdf: $(nom).ly $(notes)

# Dependències de les particel·les.
$(nom)-cello.pdf: $(nom)-cello.ly cello.ily
$(nom)-trompa.pdf: $(nom)-trompa.ly trompa.ily
$(nom)-oboes.pdf: $(nom)-oboes.ly oboe.ily
$(nom)-viola.pdf: $(nom)-viola.ly viola.ily
$(nom)-violiU.pdf: $(nom)-violiU.ly violiU.ily
$(nom)-violiDos.pdf: $(nom)-violiDos.ly violiDos.ily

# Teclegeu `make partitura' per generar la partitura completa dels quatre
# moviments com un fitxer únic.
.PHONY: partitura
partitura: $(nom).pdf

# Teclegeu `make particelles' per generar totes les particel·les
# Teclegeu `make pepet.pdf' per generar la particel·la de
# l'instrument `pepet'.

# Exemple: `make sinfonia-cello.pdf'.
.PHONY: particellas
particellas: $(nom)-cello.pdf \
       $(nom)-violinUno.pdf \
       $(nom)-violinDos.pdf \
       $(nom)-viola.pdf \
       $(nom)-oboes.pdf \
       $(nom)-trompa.pdf

# Teclegeu `make moviments' per generar els fitxers dels
# quatre moviments de forma separada.
.PHONY: moviments
moviments: $(nom)I.pdf \
           $(nom)II.pdf \
           $(nom)III.pdf \
           $(nom)IV.pdf

all: partitura particelles moviments

fitxer:
        tar -cvvf stamitz.tar \       # aquesta línia comença amb un salt de tabulació
        --exclude=*pdf --exclude=*~ \
        --exclude=*midi --exclude=*.tar \
        ../Stamitz/*

A la plataforma Windows hi ha certes complicacions. Després de descarregar i instal·lar el programa GNU Make per al Windows, haurem de configurar la ruta adequada a las variables d’entorn del sistema de que l’intèrpret d’ordres del DOS pugui trobar el programa Make. Per fer-lo, polseu amb el botó dret sobre "El meu ordinador", escolliu Propietats i Avançades. Polseu sobre Variables d'entorn, i després a la pestanya Variables del sistema, seleccioneu Ruta, polseu sobre edita i afegiu la ruta al fitxer executable de GNU Make, amb la qual cosa quedarà quelcom semblant al següent:

C:\Fitxers de programa\GnuWin32\bin

El makefile en si s’ha de modificar perquè gestioni diverses instruccions de l’intèrpret d’ordres i perquè pugui tractar amb els espais que apareixen al nom d’alguns directoris del sistema predeterminats. L’objectiu fitxer s’elimina perquè el Windows no té l’ordre tar, i el Windows a més té una extensió predeterminada diferent per als fitxers MIDI.

## VERSIÓ PER AL WINDOWS
##
nom = sinfonia
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click \
                    -djob-count=$(NUMBER_OF_PROCESSORS)

#obtenció del nom 8.3 de CURDIR (truc per als espais a PATH)
workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
          do @echo %%~sb)

.SUFFIXES: .ly .ily .pdf .mid

VPATH = \
  $(workdir)/Partitures \
  $(workdir)/PDF \
  $(workdir)/Particelles \
  $(workdir)/Notes

%.pdf %.mid: %.ly
        $(LILY_CMD) $<      # aquesta línia comença amb un salt de tabulació
        if exist "$*.pdf"  move /Y "$*.pdf"  PDF/ # començament amb tab
        if exist "$*.mid" move /Y "$*.mid" MIDI/  # començament amb tab

notes = \
  cello.ily \
  xifres.ily \
  trompa.ily \
  oboe.ily \
  trioCordes.ily \
  viola.ily \
  violiU.ily \
  violiDos.ily

$(nom)I.pdf: $(nom)I.ly $(notes)
$(nom)II.pdf: $(nom)II.ly $(notes)
$(nom)III.pdf: $(nom)III.ly $(notes)
$(nom)IV.pdf: $(nom)IV.ly $(notes)

$(nom).pdf: $(nom).ly $(notes)

$(nom)-cello.pdf: $(nom)-cello.ly cello.ily
$(nom)-trompa.pdf: $(nom)-trompa.ly trompa.ily
$(nom)-oboes.pdf: $(nom)-oboes.ly oboe.ily
$(nom)-viola.pdf: $(nom)-viola.ly viola.ily
$(nom)-violiU.pdf: $(nom)-violiU.ly violiU.ily
$(nom)-violiDos.pdf: $(nom)-violiDos.ly violiDos.ily

.PHONY: partitura
partitura: $(nom).pdf

.PHONY: particelles
particelles: $(nom)-cello.pdf \
       $(nom)-violiU.pdf \
       $(nom)-violiDos.pdf \
       $(nom)-viola.pdf \
       $(nom)-oboes.pdf \
       $(nom)-trompa.pdf

.PHONY: moviments
moviments: $(nom)I.pdf \
           $(nom)II.pdf \
           $(nom)III.pdf \
           $(nom)IV.pdf

all: partitura particelles moviments

El Makefile següent és per a un document de lilypond-book fet en LaTeX. Aquest projecte té un índex, que requereix executar l’ordre latex dues vegades per actualitzar els enllaços. Tots els fitxers de sortida s’emmagatzemen al directori sortida per als documents .pdf i al directori sortidahtml per a la sortida en format html.

SHELL=/bin/sh
NOM=elmeuprojecte
DIR_SORTIDA=sortida
DIR_WEB=sortidahtml
VISUALITZADOR=acroread
NAVEGADOR=firefox
LILYBOOK_PDF=lilypond-book --output=$(DIR_SORTIDA) --pdf $(NOM).lytex
LILYBOOK_HTML=lilypond-book --output=$(DIR_WEB) $(NOM).lytex
PDF=cd $(DIR_SORTIDA) && pdflatex $(NOM)
HTML=cd $(DIR_WEB) && latex2html $(NOM)
INDEX=cd $(DIR_SORTIDA) && makeindex $(NOM)
VISTA_PREVIA=$(VISUALITZADOR) $(DIR_SORTIDA)/$(NOM).pdf &

all: pdf web desar

pdf:
        $(LILYBOOK_PDF)  # comença amb un tab
        $(PDF)           # comença amb un tab
        $(INDEX)        # comença amb un tab
        $(PDF)           # comença amb un tab
        $(VISTA_PREVIA)  # comença amb un tab

web:
        $(LILYBOOK_HTML) # comença amb un tab
        $(HTML)          # comença amb un tab
        cp -R $(DIR_WEB)/$(NOM)/ ./  #
        $(NAVEGADOR) $(NOM)/$(NOM).html &  # comença amb un tab

desar: pdf
        cp $(DIR_SORTIDA)/$(NOM).pdf $(NOM).pdf  # comença amb un tab

clean:
        rm -rf $(DIR_SORTIDA) # comença amb un tab

web-clean:
        rm -rf $(DIR_WEB) # comença amb un tab

fitxer:
        tar -cvvf elmeuprojecte.tar \ # comença amb un tab
        --exclude=sortida/* \
        --exclude=sortidahtml/* \
        --exclude=elmeuprojecte/* \
        --exclude=*midi \
        --exclude=*pdf \
        --exclude=*~ \
        ../ElMeuProjecte/*

PERFER: aconseguir que funcioni a windows

El makefile anterior no funciona al Windows. Una alternativa per als usuaris del Windows seria crear un fitxer de lots senzill que contingui les ordres de muntatge. Això no segueix les dependències com ho fa un makefile, però almenys redueix el procés de construcció a una sola instrucció. Deseu el codi següent com muntatge.bat o muntatge.cmd. El fitxer de lots es pot executar en la línia d’ordres del DOS o simplement fent doble clic sobre la seva icona.

lilypond-book --output=sortida --pdf elmeuprojecte.lytex
cd sortida
pdflatex elmeuprojecte
makeindex elmeuprojecte
pdflatex elmeuprojecte
cd ..
copy sortida\elmeuprojecte.pdf ElMeuProjecte.pdf

Vegeu també

Manual d’utilització del programa: Utilització des de la línia d’ordres, Execució de lilypond-book