LilyPond – Usage

1.1 Übliche Programmbenutzung

Die meisten Benutzer führen LilyPond von einer graphischen Benutzeroberfläche aus. Siehe Tutorium, falls Sie dies nicht bereits getan haben. Wenn Sie einen alternativen Editor für Ihre LilyPond-Dateien verwenden, lesen Sie bitte die Dokumentation dieses Editors.

1.2 Benutzung auf der Kommandozeile

Dieser Abschnitt enthält zusätzliche Informationen, wie Sie LilyPond von der Kommandozeile ausführen können. Dies kann erforderlich sein, um etwa zusätzliche Optionen an das Programm zu übergeben. Außerdem sind einige Zusatzprogramme (wie etwa midi2ly) nur von der Kommandozeile verfügbar.

Unter ‚Kommandozeile‘ verstehen wir die Kommandozeile des jeweiligen Betriebssystems. Windows Benutzern ist sie vielleicht eher unter den englischen Begriffen ‚DOS shell‘ oder ‚command shell‘ bekannt. MacOS X Benutzer kennen sie eher unter ‚Terminal‘ oder ‚Konsole‘.

Wie die Kommandozeile im jeweiligen Betriebssystem benutzt werden kann, soll in diesem Handbuch nicht näher beschrieben werden. Sehen Sie bitte im Handbuch Ihres Betriebssystems nach oder informieren Sie sich im Internet, wenn Sie mit der Kommandozeile nicht vertraut sind.

lilypond [Option]… Dateiname…

#(define output-suffix "Geige")
\score { … }
#(define output-suffix "Cello")
\score { … }

#!/bin/sh
## defaults set here

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# the prefix (without the leading slash!)
lilyprefix=usr/local
# the directory where lilypond is installed on the system
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

# Now the library copying magic
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

# The shared files for Ghostscript...
      cp -L -r /usr/share/ghostscript usr/share
# The shared files for ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
### you should be able to run:
### Note that /$lilyprefix/bin/lilypond is a script, which sets the
### LD_LIBRARY_PATH - this is crucial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly

1.3 Fehlermeldungen

Während der Verarbeitung einer Dateien können diverse Meldungen an der Kommandozeile auftreten:

Warnung (Warning) ¶

Irgendetwas ist verdächtig. Wenn Sie etwas Ungewöhnliches in Ihrer Datei durchführen, dann werden Sie die Meldung verstehen und können sie gegebenenfalls ignorieren. Im Normalfall jedoch bedeutet eine Warnung, dass mit Ihrer Datei etwas nicht stimmt, LilyPond jedoch trotzdem versucht, die Datei soweit wie möglich korrekt zu übersetzen.

Fehler (Error) ¶

Irgendetwas stimmt definitiv nicht. Der aktuelle Bearbeitungsschritt (Einlesen, Interpretieren oder Formatieren der Datei) wird noch fertig ausgeführt, danach bricht die Bearbeitung aber ab.

Fataler Fehler (Fatal error) ¶

Irgendetwas stimmt definitiv nicht und LilyPond kann nicht weiter ausgeführt werden. Dies ist nur sehr selten der Fall, meist sind die Schriftarten nicht korrekt installiert.

Scheme Fehler (Scheme error) ¶

Fehler, die während der Ausführung von Scheme-Code auftreten, werden vom Scheme-Interpreter aufgefangen und an der Kommandozeile ausgegeben. Wenn Sie LilyPond mit der --verbose Option (auch -V) ausführen, wird der sogenannte ‚Call trace‘ ausgegeben, der die aufgerufenen Funktionen zur Zeit des Fehlers angibt.

Programmierfehler (Programming error) ¶

Eine interne Inkonsistenz ist aufgetreten. Diese Fehlermeldungen sollen den Programmierern die Fehlersuche erleichtern und können meistens einfach ignoriert werden. In manchen Fällen werden so viele Meldungen ausgegeben, dass die Lesbarkeit der restliche Ausgabe davon beeinträchtigt wird.

Abgebrochen (core dumped)

Dies bezeichnet einen ernsten Programmierfehler, der das Programm zum Absturz gebracht hat. Solche Fehler werden als kritisch angesehen. Falls daher einer auftritt, senden Sie bitte einen Bug-Report!

Wenn Warnungen oder Fehlermeldungen mit einer konkreten Stelle in der Eingabedatei verknüpft werden können, dann hat die Meldung die folgende Form:

Dateiname:Zeile:Spalte: Meldung
Fehlerhafte Eingabezeile

Ein Zeilenumbruch wird in der fehlerhaften Zeile an jener Stelle eingefügt, wo der Fehler aufgetreten ist. Zum Beispiel

test.ly:2:19: Fehler: keine gültige Dauer: 5
  { c'4 e'
             5 g' }

Diese Stellen sind LilyPonds Vermutung, wo die Warnung oder der Fehler aufgetreten ist, allerdings treten Warnungen und Fehler ja gerade in unerwarteten Fällen auf. Manchmal kann LilyPond auch eine fehlerhafte Stelle zwar noch problemlos verarbeiten, ein paar Zeilen später wirkt sich der Fehler aber dann doch noch aus. In solchen Fällen, wo Sie in der angegebenen Zeile keinen Fehler erkennen, sollten Sie auch die Zeilen oberhalb der angegebenen Stelle genauer unter die Lupe nehmen.

Mehr Information darüber findet sich in Häufige Fehlermeldungen.

1.4 Häufige Fehlermeldungen

Die Fehlermeldungen, die unten beschrieben werden, treten of auf, es ist jedoch nicht immer einfach, die Urache zu finden. Wenn der Fehler einmal verstanden ist, kann er einfach behoben werden.

\override VerticalAxisGroup.staff-affinity = ##f

2.1 Warum verändert sich die Syntax?

Die LilyPond-Eingabesyntax verändert sich von Zeit zu Zeit. Wenn das Programm LilyPond verbessert wird, wird auch die Syntax (die Eingabesprache) entsprechend angepasst. Manche Änderungen machen den Eingabetext leichter zum Schreiben und zum Lesen, andere implementieren neue Eigenschaften in LilyPond.

Beispielsweise alle \paper- und \layout-Eigenschaftsnamen sollen in der Form erstens-zweitens-drittens geschrieben werden. In der Version 2.11.60 bemerkten wir jedoch, dass die printallheaders-Eigenschaft sich nicht an diese Regel hielt. Sollten wir das jetzt lassen (womit neue Benutzer verwirrt werden, weil die Eingabe nicht logisch ist), oder sollten wir es ändern (womit wir alte Benutzer mit ihren schon geschriebenen Partituren ärgern)? In diesem Fall haben wir uns entschieden, den Namen in print-all-headers zu ändern. Zum Glück kann diese Änderung mit dem convert-ly-Programm automatisch vorgenommen werden.

Leider kann convert-ly nicht mit allen Syntax-Änderungen umgehen. Beispielsweise wurden in LilyPond 2.4 und früher Akzente für verschiedene Sprachen mit LaTeX-Befehlen eingegeben – beispielsweise Änderung wurde geschrieben \"Anderung. Ab Version 2.6 jedoch muss man Akzente und Sonderzeichen dirket als UTF-8-Zeichen notieren. convert-ly kann nicht alle LaTeX-Zeichen umwandeln, sodass man das manuell übernehmen muss.

2.2 convert-ly aufrufen

convert-ly benutzt den Befehl \version mit Angabe der Versionsnummer der ursprünglichen LilyPond-Version. In den meisten Fällen genügt es, einfach auf der Kommandozeile

convert-ly -e meineDatei.ly

im Verzeichnis, in welchem die Datei liegt, aufzurufen. Hierdurch wird meineDatei.ly direkt aktualisiert und das Original nach meineDatei.ly~ gesichert.

Um alle Dateien in einem Verzeichnis zu konvertieren, schreibt man auf der Kommandozeile:

convert-ly -e *.ly

Man kann auch einen neuen Namen für die konvertierte Datei angeben, sodass die originale Datei unverändert bleibt. Dazu schreibt man auf der Kommandozeile

convert-ly meineDatei.ly > meineneueDatei.ly

Das Programm gibt die Versionsnummern für alle Versione aus, für die eine Konversion durchgeführt wurde. Wenn keine Versionsnummern ausgegeben werden, ist die Datei aktuell.

MacOS X-Benutzer können die Befehle unter dem Menü-Eintrag Compile > Update syntax ausführen.

Windows-Benutzer sollten diese Befehle auf der Kommandozeile (Eingabeaufforderung), die sich normalerweise unter Start > Zubehör > Eingabeaufforderung findet.

2.3 Optionen auf der Kommandozeile für convert-ly

Das Programm wird folgendermaßen aufgerufen:

convert-ly [Option]… Dateiname…

Folgende Optionen können benutzt werden:

-e, --edit

Die Konvertierung direkt am Original vornehmen, sodass es direkt verändert wird.

-f, --from=von-Versionsnummer

Stellt die Versionsnummer ein, ab welcher die Konvertierung begonnen werden soll. Wenn die Option nicht benutzt wird, rät convert-ly die Versionsnummer anhand des \version-Eintrags in der Datei. Beispielsweise --from=2.10.25

-n, --no-version

Normalerweise fügt convert-ly einen \version-Eintrag zu der konvertierten Datei hinzu. Mit dieser Option wird das unterdrückt.

-s, --show-rules

Zeige alle bekannten Konversionen und beende.

--to=bis-Versionsnummer

Die Zielversion der Konversion setzen. Standard ist die letzte mögliche Version, die das Programm beherrscht. Beispielsweise --to=2.12.2

-h, --help

Zeigt Hilfe zur Benutzung.

-l Logstufe, --loglevel=Logstufe

Passt die Ausführlichkeit der Ausgabe entsprechend Logstufe an. Mögliche Werte sind NONE, ERROR, WARN, PROGRESS (Standard) und DEBUG.

Um LilyPond-Schnipsel in texinfo-Dateien zu aktualisieren, kann

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

benutzt werden.

Um sich die Änderungen der LilyPond-Syntax zwischen zwei Versionen anzeigen zu lassen, schreibt man

convert-ly --from=... --to=... -s

2.4 Probleme mit convert-ly

Wenn man convert-ly auf einer Eingabeaufforderung unter Windows mit einer Datei benutzt, die Leerzeichen im Dateinamen oder Pfad hat, muss der gesamte Dateiname mit drei (!) doppelten Anführungszeichen umgeben werden:

convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"

Wenn der einfache convert-ly -e *.ly-Befehl nicht funktioniert, weil die ausgeschriebene Kommandozeile zu lang wird, kann man convert-ly auch als Loop wiederholt laufen lassen. Dieses Beispiel für UNIX konvertiert alle -ly-Dateien im aktuellen Verzeichnis:

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

Für die Windows-Eingabeaufforderung lautet der entsprechende Befehl:

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

Nicht alle Syntax-Änderungen werden konvertiert. Nur eine Ausgabeoption kann angegeben werden. Automatische Aktualisierung von Scheme- und LilyPond Scheme-Code ist eher unwahrscheinlich, sehr wahrscheinlich muss hier manuell aktualisiert werden.

2.5 Manuelle Konversion

Theoretisch könnte ein Programm wie convert-ly alle möglichen Syntax-Änderungen berücksichtigen. Schließlich ist es auch ein Computerprogramm, das die alte und die neue Version der Notationsdatei interpretiert, so dass ein anderes Computerprogramm eine Datei in die andere verwandeln könnte.²

Das LilyPond-Team ist jedoch verhältnismäßig klein, sodass nicht alle Konversionen automatisch funktionieren. Unten eine Liste der bekannten Probleme:

1.6->2.0:
 Bezifferter Bass wird nicht immer richtig konvertiert, besonders {<
 >}.  Mats' Kommentar zu einer Lösung:
   To be able to run convert-ly
   on it, I first replaced all occurrences of '{<' to some dummy like '{#'
   and similarly I replaced '>}' with '&}'.  After the conversion, I could
   then change back from '{ #' to '{ <' and from '& }' to '> }'.
 Nicht alle Textbeschriftung wird richtig konvertiert.  In der alten Syntax
 konnte man mehrere Beschriftungen mit Klammern gruppieren, etwa:
   -#'((bold italic) "string")
   Das wird falsch konvertiert zu:
   -\markup{{\bold italic} "string"}
   anstelle von:
   -\markup{\bold \italic "string"}
2.0->2.2:
 Versteht nicht \partCombine
 Kann nicht \addlyrics => \lyricsto, sodass einige Dateien mit vielen Strophen nicht
 funktionieren
2.0->2.4:
 \magnify wird nicht nach \fontsize verändert.
    - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 remove-tag wird nicht verändert.
    - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 first-page-number wird nicht verändert.
    - first-page-number no => print-first-page-number = ##f
 Zeilenumbrüche in Titelköpfen werden nicht umgewandelt.
    - \\\\  als Zeilenumbruch in \header-Feldern => \markup \center-align <
      "Erste Zeile" "Zweite Zeile" >
 Crescendo und decrescendo-Endpunkte werden nicht umgewandelt.
    - \rced => \!
    - \rc => \!
2.2->2.4:
 \turnOff (benutzt in \set Staff.VoltaBracket = \turnOff) wird nicht richtig konvertiert
2.4.2->2.5.9
 \markup{ \center-align <{ ... }> } sollte konvertiert werden in:
 \markup{ \center-align {\line { ... }} }
 jetzt fehlt aber \line.
2.4->2.6
 Besondere LaTeX-Zeicehn wie $~$ in Text werden nicht in UTF-8 umgewandelt.
2.8
 \score{} muss jetzt immer mit einem musikalischen Ausdruck beginnen. Alles
andere (insbesondere \header{}) darf erst nach den Noten kommen.

3.1 Ein musikwissenschaftlicher Text als Beispiel

Zahlreiche Texte enthalten Musikbeispiele: musikwissenschaftliche Abhandlungen, Liederbücher oder Handbücher wie dieses. Solche Texte können händisch erzeugt werden, indem einfach die Musikbeispiele als Grafik (PostScript, PNG, GIF, etc.) im Textverarbeitungsprogramm eingefügt werden. Für HTML, LaTeX, Texinfo und DocBook Dokumente existiert jedoch ein Weg, dies automatisiert durchzuführen.

Das Programm lilypond-book extrahiert die Musikfragmente aus dem Dokument, formatiert sie automatisiert in eine Grafik und fügt die resultierenden Notenbeispiele dann wieder in das Dokument ein. Dies soll hier an einem einfachen LaTeX-Beispiel verdeutlicht werden. Das Beispiel selbst enthält schon Erklärungen, sodass wir es hier nicht weiter diskutieren müssen.

Eingabe

\documentclass[a4paper]{article}

\begin{document}

Dokumente für \verb+lilypond-book+ können Musik und Text nach Belieben
kombinieren. Zum Beispiel:

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

Optionen für \verb+lilypond+ werden dabei in eckige Klammern gesetzt.

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

Größere Beispiele können auch in einer eigenständigen Datei gespeichert
und dann mit \verb+\lilypondfile+ eingebunden werden.

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

(Falls nötig kann @file{screech-and-boink.ly} durch eine beliebige andere
@file{.ly}-Datei im selben Verzeichnis wie diese Datei ersetzt werden.)

\end{document}

Verarbeitung

Speichern Sie den obigen LaTeX-Quellcode in eine Datei lilybook.lytex und führen Sie dann in der Kommandozeile folgende Befehle aus:

lilypond-book --output=out --pdf lilybook.lytex
lilypond-book (GNU LilyPond) 2.25.21 
Reading lilybook.lytex...
..(viele Ausgabezeilen entfernt)..
Compiling lilybook.tex...
cd out
pdflatex lilybook
..(viele Ausgabezeilen entfernt)..
xpdf lilybook
(Ersetzen Sie xpdf durch Ihren PDF-Betrachter)

Die Ausführung von lilypond-book und latex erzeugt zahlreiche temporäre Dateien, die das Arbeitsverzeichnis unnötig vollstopfen würden. Daher empfiehlt sich die Benutzung der --output=dir-Option, wodurch die Dateien im Unterverzeichnis dir erzeugt werden.

Das Endresultat des obigen LaTeX-Beispiels ist im nächsten Abschnitt zu sehen.³

Ausgabe

Dokumente für lilypond-book können Musik und Text nach Belieben kombinieren. Zum Beispiel:

Optionen für lilypond werden dabei in eckige Klammern gesetzt.

c'4 f16

Größere Beispiele können auch in einer eigenständigen Datei gespeichert und dann mit \lilypondfile eingebunden werden.

Wenn man eine tagline (die Zeile unten auf der Seite) braucht (in Standard oder angepasst), dann muss der ganze Schnipsel in eine \book { }-Umgebung.

\book{
  \header{
    title = "A scale in LilyPond"
  }

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

3.2 Noten in Text integrieren

In diesem Abschnitt soll die Integration von LilyPond mit den verschiedenen Dateiformaten detailliert erläutert werden.

\begin{lilypond}[Optionen,kommen,hierhin]
  IHR LILYPOND-QUELLCODE
\end{lilypond}

\lilypond[Optionen,kommen,hier]{ IHR LILYPOND-QUELLCODE }

\lilypondfile[Optionen,kommen,hier]{Dateiname}

\musicxmlfile[Optionen,kommen,hier]{Dateiname}

\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\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[Optionen,kommen,hier]
  IHR LILYPOND-QUELLCODE
@end lilypond

@lilypond[Optionen,kommen,hier]{ IHR LILYPOND-QUELLCODE }

@lilypondfile[Optionen,kommen,hier]{Dateiname}

@musicxmlfile[Optionen,kommen,hier]{Dateiname}

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

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

<lilypond Optionen hier>
  IHR LILYPOND-QUELLCODE
</lilypond>

<lilypond Optionen hier: IHR LILYPOND-QUELLCODE />

<lilypond-Datei Optionen hier>Dateiname</lilypondfile>

<musicxml-Datei Optionen hier>Dateiname</musicxmlfile>

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

Musik <lilypond relative=2: a b c/> in derselben Zeile.

<lilypondfile Option1 Option2 ...>Dateiname</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 Die Musikfragment-Optionen

Im Folgenden meint ‚LilyPond-Befehl‘ einen beliebigen in den vorgehenden Abschnitten beschriebenen Befehl, der ein LilyPond-Fragment in eine Datei einfügt und von lilypond-book verarbeitet wird. Der Einfachheit halber werden hier alle LilyPond-Befehle in der Syntax von LaTeX dargestellt.

Zu beachten ist, dass die Optionen eines LilyPond-Befehls von links nach rechts verarbeitet werden. Wenn eine Option also mehrfach angegeben wird, wird nur die letzte benutzt.

Die folgenden Optionen können für LilyPond-Befehle benutzt werden:

staffsize=ht

Setzt die Höhe einer Notenzeile auf ht, angegeben in Punkten.

ragged-right

Erzeugt Notenzeilen im Flattersatz mit natürlichem Abstand der Noten. In anderen Worten: ragged-right = ##t wird in das Musikfragment eingefügt. Einzeilige Fragmentschnipsel werden standardmäßig immer im Flattersatz gesetzt, außer noragged-right wird explizit angegeben.

noragged-right

Streckt Musikfragmente mit nur einer Notenzeile auf die volle Breite, es wird also ragged-right = ##f in das Musikfragment eingefügt.

line-width

line-width=Breite\Einheit

Setzt die Breite der Notenzeilen auf Breite, gemessen in Vielfachen der Einheit. Als Einheit können die folgenden Zeichenfolgen angegeben werden: cm, mm, in oder pt. Diese Option hat nur Einfluss auf die Breite von Notenzeilen und Text im Musikfragment, nicht jedoch auf den restlichen Text des Dokuments.

Wird diese Option ohne einen Wert angegeben, wird die Zeilenbreite auf einen Standardwert gesetzt, der durch einen heuristischen Algorithmus bestimmt wird.

Wenn die line-width-Option nicht angegeben wird, versucht lilypond-book einen geeigneten Standardwert für alle lilypond-Umgebungen zu finden, die die ragged-right-Option nicht benutzen.

papersize=Zeichenkette

Wobei Zeichenkette eine Papiergröße wie definiert in scm/paper.scm ist, beispielsweise a5, quarto, 11x17 usw.

Werte, die nicht in scm/paper.scm definiert sind, werden ignoriert, eine Warnung wird ausgegeben und das Schnipsel wird mit dem Standardwert a4 ausgegeben.

notime

Verhindert die Ausgabe der Taktangabe am Anfang des Fragments und schaltet Taktstriche und alle Taktangaben im Fragment ab.

fragment

Bewirkt, dass lilypond-book Standardcode um das Fragment herum einfügt, sodass z. B.

c'4

ohne \layout, \score, etc. eingegeben werden kann.

nofragment

Verhindert das Einfügen von Standardcode um das Fragment herum. Dies ist die Standardeinstellung, insofern ist diese Option im Normalfall unnötig.

indent=Einzug\Einheit

Setzt den Einzug des ersten Notensystems auf Einzug, gemessen in Vielfachen der Einheit. Als Einheit können die folgenden Zeichenfolgen angegeben werden: cm, mm, in oder pt. Diese Option hat nur Einfluss auf den Einzug von Notenzeilen und Text im Musikfragment, nicht jedoch auf den restlichen Text des Dokuments.

noindent

Setzt den Einzug des ersten Notensystems auf 0. Diese Option hat nur Einfluss auf den Einzug von Notenzeilen und Text im Musikfragment, nicht jedoch auf den restlichen Text des Dokuments. Dies ist die Standardeinstellung, insofern ist diese Option im Normalfall unnötig.

quote

Verringert die Zeilenlänge des Musikfragments um 2*0.4in und setzt das Fragment in einen Zitat-Block. Der Wert von ‚0.4in‘ kann durch die exampleindent Option angepasst werden.

exampleindent

Setzt den Betrag, um den das Fragment bei Benutzung der quote Option eingerückt wird.

relative

relative=n

Benutzt relative Oktavenbezeichnungen. Standardmäßig werden Noten relativ zum mittleren C angegeben. Das optionale ganzzahlige Argument gibt die Oktave der ersten Note an, wobei die Standardeinstellung von 1 das mittlere C bedeutet. Die relative Option macht nur Sinn in Verbindung mit der fragment Option, weshalb fragment automatisch durch die Angabe der relative Option impliziert wird. Eine explizite Angabe der (no)fragment Option hat keinen Effekt.

LilyPond benutzt zur Erzeugung seiner eigenen Dokumentation ebenfalls lilypond-book. Zu diesem Zweck stehen noch zahlreiche spezialisierte Optionen zur Verfügung:

verbatim

Der LilyPond-Code im LilyPond-Kommando wird zum einen benutzt, um das Musikfragment in eine Grafik mit schönem Notensatz zu konvertieren, andererseits aber auch wörtlich in das Dokument eingefügt. Dies geschieht in einem ‚verbatim‘-Block, gefolgt vom Text einer möglicherweise angegebenen intertext Option⁴ und der Grafik des tatsächlichen Notensatzes. Diese Option funktioniert nur fehlerhaft, wenn \lilypond{} im Fließtext benutzt wird.

Wird verbatim in Verbindung mit einem lilypondfile-Kommando benutzt, so ist es auch möglich, nur ein Teil der Datei wörtlich einfügen zu lassen: Wenn die eingebundene LilyPond-Datei ein Kommentar mit dem Inhalt ‘begin verbatim’ (ohne Anführungszeichen) enthält, wird nur der Dateiinhalt ab dieser Position eingefügt. Enthält die Datei mehrere solche Kommentare, wirkt nur das letzte. Analog wird nur der Dateiinhalt bis zu einem etwaigen Kommentar mit dem Inhalt ‘end verbatim’ eingefügt. Im folgenden Beispiel wird das gesamte Musik für die Erzeugung der Grafik im relativen Oktavenmodus interpretiert, der wörtlich in das Dokument kopierte LilyPond-Code zeigt den relative-Befehl jedoch nicht.

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

erzeugt ein Zitat der Form

  c4 e2 g4
  f2 e

Wenn Kommentare und Variablen im Zitat, aber nicht im Quelltext übersetzt werden sollen, kann die Umgebungsvariable LYDOC_LOCALEDIR auf einen Verzeichnispfad gesetzt werden. Das Verzeichnis sollte einen Baum an .mo-Nachrichtenkatalogen beinhalten mit lilypond-doc als Domain.

texidoc

(Nur innerhalb von Texinfo-Dateien.) Wird lilypond mit der Kommandozeilenoption --header=texidoc für eine Datei foo.ly und enthält die Datei ein texidoc-Feld im \header-Block, so wird dessen Inhalt in die Datei foo.texidoc ausgegeben. Die texidoc Option veranlasst lilypond-book, den Inhalt dieser .texidoc Dateien innerhalb eines Dokumentationsblocks direkt vor dem Musikfragment in das aktuelle Dokument einzufügen (aber außerhalb der example-Umgebung, die durch die Option quote hervorgerufen wird).

Enthält also die Datei foo.ly etwa den LilyPond-Code

\header {
  texidoc = "Dieses Beispiel zeigt eine einzelne Note."
}
{ c'4 }

und das Texinfo-Dokument text.texinfo

@lilypondfile[texidoc]{foo.ly}

so liefert der folgende Aufruf von lilypond-book das gewünschte Ergebnis:

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

Die meisten Test-Dateien (im input/ Verzeichnis von LilyPond) sind kleine .ly Dateien von genau dieser Form.

Auch die Übersetzung dieser zusätzlichen Kommentare ist möglich: Dazu muss das Texinfo-Dokument den Befehl @documentlanguage LANG und der \header Block in der Datei foo.ly die Übersetzung im Feld texidocLANG enthalten. Wird nun lilypond mit der Option --header=texidocLANG aufgerufen, so wird der Inhalt der Datei foo.texidocLANG anstelle von foo.texidoc eingefügt.

doctitle

(Nur innerhalb von Texinfo-Dateien.) Diese Option wirkt ähnlich wie die texidoc Option: Wenn lilypond mit der Option --header=doctitle aufgerufen wird und die Eingabedatei foo.ly ein Feld doctitle im \header-Block enthält, wird dessen Wert in die Datei foo.doctitle geschrieben. Wird die doctitle Option für ein Musikfragment benutzt, so wird der Inhalt dieser Datei, der eine einzelne Textzeile sein sollte, im Texinfo-Dokument als @lydoctitle Text eingefügt. @lydoctitle muss allerdings in Ihrem Texinfo-Dokument als Makro selbst definiert werden. Die Übersetzung funktioniert völlig analog zu texidoc.

nogettext

Nur für Texinfo-Ausgabe: Kommentare und Variablenbezeichnungen im zitierten Quelltext des Schnipsel werden nicht übersetzt.

printfilename

Wenn eine LilyPond-Datei mittels \lilypondfile und dieser Option eingebunden wird, wird der Dateiname (ohne die Pfadangabe) unmittelbar vor dem Musikfragment ausgegeben. In HTML-Dateien ist er außerdem ein Link auf die LilyPond-Datei. Nur der eigentliche Name der Datei wird ausgegeben, der Pfad wird also nicht mit angezeigt.

3.4 lilypond-book aufrufen

lilypond-book erzeugt abhängig vom Ausgabeformat eine Datei mit einer der folgenden Dateierweiterungen: .tex, .texi, .html oder .xml. Alle .tex, .texi und .xml Dateien müssen noch mit den entsprechenden Programmen (LaTeX, DocBook, etc.) weiter verarbeitet werden, um druckfähige Dateien zu erhalten.

Formatabhängige Anweisungen

LaTeX

Es existieren zwei Methoden, Ihr LaTeX-Dokument weiter zu verarbeiten, um zu einer druck- oder publikationsfähigen Datei zu gelangen: Zum einen die direkte Erzeugung einer PDF-Datei mit PDFLaTeX, zum anderen die Erzeugung einer DVI daraus einer PostScript-Datei mittels LaTeX und einem DVI-nach-PostScript Konverters wie dvips. Die erste Methode ist einfacher und daher empfehlenswert.⁵ Welche Methode auch immer benutzt wird, die Konvertierung zwischen PostScript und PDF kann leicht mit Hilfsprogrammen wie ps2pdf und pdf2ps (aus dem Ghostscript-Paket) erfolgen.

Um eine PDF-Datei mittels PDFLaTeX zu erzeugen, kann folgendermaßen vorgegangen werden:

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

Um eine PDF-Datei mittels LaTeX/dvips/ps2pdf zu erhalten, sind folgende Befehle nötig:

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

Die .dvi-Datei, die beim Aufruf von latex erzeugt wird, scheint keine Notenköpfe zu enthalten, was in Ordnung ist. Wenn Sie die Datei wie beschrieben weiter verarbeiten, erscheinen die Notenköpfe korrekt in den .ps und .pdf Dateien.

Der Aufruf von dvips kann einige Warnungen über fehlende Schriftarten ausgeben. Auch dies ist in Ordnung und kann ignoriert werden.

Wenn Sie in der LaTeX-Datei das Papierformat auf Querformat eingestellt haben, vergessen Sie nicht die -t landscape-Option beim Aufruf von dvips.

Bekannte Probleme und Warnungen

Der Befehl \pageBreak funktioniert nicht innerhalb einer \begin{lilypond} … \end{lilypond}-Umgebung.

Auch viele Variablen der \paper-Umgebung funktionieren nicht innerhalb einer \begin{lilypond} … \end{lilypond}-Umgebung. Benutzen Sie \newcommand mit \betweenLilyPondSystem:

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

Texinfo

Um ein von lilypond-book erzeugtes Texinfo-Dokument zu verarbeiten, gehen Sie wie für alle anderen Texinfo-Dokumente vor: Rufen Sie – abhängig vom gewünschten Ausgabeformat – eines der Programme texi2pdf, texi2dvi, texi2any oder texi2html auf.

Die Dokumentation von Texinfo liefert dazu nähere Informationen.

Optionen auf der Kommandozeile

lilypond-book unterstützt die folgenden Kommandozeilenoptionen:

-f Format

--format=Format

Gibt das Format des Eingabedokuments an: html, latex, texi (Standardeinstellung), texi-html oder docbook. Ist diese Option nicht angegeben, versucht lilypond-book das Format anhand des Dateinamens zu bestimmen. Im Moment bedeutet texi praktisch dasselbe wie texi-html.

-F Filter

--filter=Filter

Leitet die Musikfragmente durch das Programm filter anstatt sie mit LilyPond zu einer Grafik zu verarbeiten. --filter und --process kann nicht gleichzeitig benutzt werden. Beispielaufruf:

lilypond-book --filter='convert-ly --from=2.0.0 -' Mein-Buch.tely

-h

--help

Gibt eine kurze Hilfemeldung aus.

-I Pfad

--include=Pfad

Fügt Pfad zu den Include-Pfaden hinzu. lilypond-book sucht auch in allen Include-Pfaden nach bereits erstellten Grafiken für die Musikfragmente. Wird das aktuelle Fragment gefunden und hat sich seit der letzten Erstellung nicht geändert, wird es nicht erneut erzeugt. Bei manchen der Programme zur Weiterverarbeitung wie etwa texi2any oder latex muss dieselbe -I Pfad Option angegeben werden, damit das entsprechende Programm die Grafiken ebenso findet.

-l Logstufe

--loglevel=Logstufe

Passt die Ausführlichkeit der Ausgabe entsprechend Logstufe an. Mögliche Werte sind NONE, ERROR, WARN, PROGRESS (Standard) und DEBUG. Wenn diese Option nicht genutzt wird und die Umgebungsvariable LILYPOND_BOOK_LOGLEVEL definiert ist, wird ihr Wert als Logstufe eingesetzt.

-o Verzeichnis

--output=Verzeichnis

Erzeugt die Ausgabedateien in Verzeichnis. Der Aufruf von lilypond-book erzeugt zahlreiche kleine Dateien, die von LilyPond, latex, texi2any etc. dann weiter benützt werden. Um zu vermeiden, dass das Quellenverzeichnis durch diese Dateien unübersichtlich wird, kann die --output Option benutzt werden. Vor dem Aufruf von latex oder texi2any sollten Sie in dieses Verzeichnis wechseln.

lilypond-book --output=out IhreDatei.lytex
cd out
...

--skip-lily-check

Nicht mit einer Fehlermeldung abbrechen, wenn keine Ausgabe von LilyPond gefunden wird. Dies wird benutzt für Dokumentation ohne Grafiken.

--skip-png-check

Nicht mit einer Fehlermeldung abbrechen, wenn für die EPS-Dateien keine PNG-Grafiken gefunden werden. Dies wird benutzt für Dokumentation ohne Grafiken.

--lily-output-dir=Verzeichnis

Schreibt lily-XXX Dateien nach Verzeichnis und erzeugt im mit --output angegebenen Verzeichnis Verknüpfungen darauf. Diese Option ist nützlich, um Zeit zu sparen, wenn Dokumente in verschiedenen Verzeichnissen viele identische Musikfragmente enthalten.

--lily-loglevel=Logstufe

Passt die Ausführlichkeit der Ausgabe entsprechend Logstufe an. Mögliche Werte sind NONE, ERROR, WARN, PROGRESS (Standard) und DEBUG. Wenn diese Option nicht genutzt wird und die Umgebungsvariable LILYPOND_LOGLEVEL definiert ist, wird ihr Wert als Logstufe eingesetzt.

--info-images-dir=Verzeichnis

Formatiert die Texinfo-Ausgabe dergestalt, dass Info in Verzeichnis nach den Grafiken zu den Musikfragmenten sucht.

--latex-program=Programm

Führt Programm anstelle von latex aus. Dies ist nützlichen, wenn das Dokument mit einer anderen LaTeX-Variante wie etwa xelatex verarbeitet werden soll.

--left-padding=Einrückung

Fügt Einrückung als zusätzlichen Einzug in die EPS-Box ein. Einrückung wird in Millimetern angegeben, die Standardeinstellung ist 3.0 Millimeter. Diese Option kann benutzt werden, wenn die Notenzeilen über den Rand des Dokuments hinausstehen.

Die Breite eines eng ausgeschnittenen Notensystems kann variieren aufgrund von Notationselementen, die über den linken Rand hinausstehen, wie etwa Taktzahlen und Bezeichnungen der Instrumente. Diese Option verkürzt die Notenzeile und verschiebt sie um denselben Betrag nach rechts.

-P Befehl

--process=Befehl

Verarbeitet LilyPond-Fragmente mit Befehl anstelle des Standardbefehls lilypond. --filter und --process können mit lilypond-book nicht gleichzeitig benutzt werden.

--pdf

Erzeugt PDF-Dateien mit PDFLaTeX.

--redirect-lilypond-output

Standardmäßig wird die Ausgabe auf der Kommandozeile ausgegeben. Diese Option leitet die Ausgabe in eine Log-Datei im selben Verzeichnis wie die Quelldatei um.

--use-source-file-names

Schreibe Schnipsel-Ausgabedateien mit den gleichen Basisnamen wie die Quelldateien. Diese Option funktioniert mit Schnipseln, die mit lilypondfile eingfügt wurden und auch nur, wenn die Verzeichnisse --output-dir und --lily-output-dir unterschiedlich sind.

-V

--verbose

Gibt ausführliche informative Meldungen aus. Äquivalent zu --loglevel=DEBUG.

-v

--version

Gibt die Versionsnummer aus.

Bekannte Probleme und Warnungen

Der Texinfo-Befehl @pagesizes wird ignoriert. Ebenso werden LaTeX-Befehle ignoriert, die den Seitenrand oder die Zeilenlänge nach der Dokumentpräambel verändern.

Nur der erste \score-Block eines LilyPond-Fragments wird verarbeitet.

3.5 Dateiendungen

Für die Eingabedatei kann zwar jede beliebige Dateinamenserweiterung benutzt werden, allerdings muss bei Verwendung einer nicht bekannten Erweiterung das Ausgabeformat explizit an lilypond-book angegeben werden. Details dazu finden sich im Abschnitt lilypond-book aufrufen. Wird eine bekannte Erweiterung benutzt, wählt lilypond-book automatisch das richtige Ausgabeformat basierend auf der Erweiterung der Eingabedatei:

Erweiterung	Ausgabeformat
.html	HTML
.itely	Texinfo
.latex	LaTeX
.lytex	LaTeX
.lyxml	DocBook
.tely	Texinfo
.tex	LaTeX
.texi	Texinfo
.texinfo	Texinfo
.xml	HTML

Wird dieselbe Erweiterung für die Eingabedatei wie für die Ausgabedatei benutzt und befindet sich die Eingabedatei im aktuellen Arbeitsverzeichnis von lilypond-book, muss die --output Option für lilypond-book benutzt werden. Anderenfalls würde lilypond-book ja die Eingabedatei überschreiben, weshalb das Programm in diesem Fall mit einer Fehlermeldung wie „Fehler: Ausgabe würde Eingabedatei überschreiben; verwenden Sie –output.“ abbricht.

3.6 lilypond-book-Vorlagen

Diese Vorlagen sollen mit lilypond-book benutzt werden. Wenn Sie sich mit dem Programm nicht auskennen, lesen Sie bitte lilypond-book aufrufen.

LaTeX

Sie können LilyPond-Fragmente in ein LaTeX-Dokument einfügen:

\documentclass[]{article}

\begin{document}

Normaler LaTeX-Text.

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

Weiterer LaTeX-Text und Optionen in eckigen Klammern.

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

Texinfo

LilyPond-Fragmente können in Texinfo-Dokumente eingefügt werden: dieses gesamte Handbuch wurde in Texinfo geschrieben.

\input texinfo @node Top
@top

Texinfo-Text

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

Weiterer Texinfo-Text und Optionen in Klammern.

@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>
Dokumente für lilypond-book können Noten und Text frei kombinieren. Zum
Beispiel
<lilypond>
\relative {
  a'4 b c d
}
</lilypond>
</p>

<p>
Noch etwas LilyPond, mit Optionen:

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

</body>
</html>

xelatex

\documentclass{article}
\usepackage{ifxetex}
\ifxetex
%xetex specific stuff
\usepackage{xunicode,fontspec,xltxtra}
\setmainfont[Numbers=OldStyle]{Times New Roman}
\setsansfont{Arial}
\else
%This can be empty if you are not going to use pdftex
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{mathptmx}%Times
\usepackage{helvet}%Helvetica
\fi
%Here you can insert all packages that pdftex also understands
\usepackage[ngerman,finnish,english]{babel}
\usepackage{graphicx}

\begin{document}
\title{A short document with LilyPond and xelatex}
\maketitle

Normal \textbf{font} commands inside the \emph{text} work,
because they \textsf{are supported by \LaTeX{} and XeteX.}
If you want to use specific commands like \verb+\XeTeX+, you
should include them again in a \verb+\ifxetex+ environment.
You can use this to print the \ifxetex \XeTeX{} command \else
XeTeX command \fi which is not known to normal \LaTeX .

In normal text you can easily use LilyPond commands, like this:

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

\noindent
and so on.

The fonts of snippets set with LilyPond will have to be set from
inside
of the snippet. For this you should read the AU on how to use
lilypond-book.
\end{document}

3.7 Das Inhaltsverzeichnis flexibel einsetzen

Diese Funktionen existieren schon im OrchestralLily-Paket:

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

Um den Text flexibler behandeln zu können, bevorzugen manche Benutzer es, das Inhaltsverzeichnis aus LilyPond zu exportieren und dann mit LaTeX einzulesen.

Das Inhaltsverzeichnis (ToC) aus LilyPond exportieren

Hier wird angenommen, dass in Ihrer Partitur mehrere Sätze vorkommen, die sich alle in der selben LilyPond-Datei befinden.

#(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 (G_ "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))
}

Das Inhaltsverzeichnis in LaTeX importieren

In der LaTeX-Datei sollte folgendes enthalten:

\usepackage{pdfpages}
\includescore{nameofthescore}

wobei \includescore wiefolgt definiert ist:

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

% Read in the TOC entries for a PDF file from the corresponding .toc file.
% This requires some heave latex tweaking, since reading in things from a file
% and inserting it into the arguments of a macro is not (easily) possible

% Solution by Patrick Fimml on #latex on April 18, 2009:
% \readfile{filename}{\variable}
% reads in the contents of the file into \variable (undefined if file
% doesn't exist)
\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 Alternative Methoden Text und Musik zu kombinieren

Andere Methoden, Text und Noten miteinander zu kombinieren (ohne lilypond-book zu benutzen) werden beschrieben in LilyPond-Ausgabe in anderen Programmen.

4.1 Point and click

Poind and click fügt Verlinkung für bestimmte Notationselemente in die PDF-Dokumente ein.

urlCommand     "lilypond-invoke-editor %s"

emacsclient --no-wait +%(line)s:%(column)s %(file)s

\pointAndClickOff

\pointAndClickOn

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

4.2 Unterstützung von Texteditoren

Verschiedene Editoren unterstützen 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

4.3 Von anderen Formaten konvertieren

LilyPond kann auch Musik aus diversen anderen Formaten importieren. Dieses Kapitel beschreibt die dazu mit LilyPond mitgelieferten Hilfsprogramme. Daneben existieren natürlich auch noch weitere Programme, die Dateien für LilyPond erstellen können, wie etwa graphische Sequenzierprogramme und XML-Konverter. Näheres dazu findet sich auf der Homepage von LilyPond.

Die im Folgenden beschriebenen Programme sind eigenständige Hilfsprogramme und werden üblicherweise von der Kommandozeile aufgerufen. Siehe Benutzung auf der Kommandozeile für weitere Informationen.

Bekannte Probleme und Warnungen

Leider haben wir nicht ausreichend viele Entwickler, um all die folgenden Hilfsprogramme ständig zu warten. Wir stellen den aktuellen Stand zur Verfügung, können aber leider Fehlerberichte nur selten bearbeiten. Selbstverständlich sind Patches von Ihnen sehr willkommen!

midi2ly [Optionen]… MIDI-Datei

musicxml2ly [Optionen]… XML-Datei

abc2ly [Optionen]… ABC-Datei

%%LY voices \set autoBeaming = ##f

%%LY slyrics more words

%%LY slyrics more words

etf2ly [Optionen]… ETF-Datei

4.4 LilyPond-Ausgabe in anderen Programmen

Dieser Abschnitt stellt Methoden vor, wie Text und Musik auf andere Weise kombiniert werden können als dies durch lilypond-book automatisiert geschieht.

\paper{
  indent=0\mm
  line-width=120\mm
  oddFooterMarkup=##f
  oddHeaderMarkup=##f
  bookTitleMarkup = ##f
  scoreTitleMarkup = ##f
}

{ c1 }

EPS

lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts   Dateiname.ly

PNG

lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png Dateiname.ly

Ein transparentes PNG

lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
  -dpixmap-format=pngalpha --png myfile.ly

4.5 Unabhängige include-Abschnitte

Einige Leute haben große (und nützliche!) Code-Abschnitte geshrieben, die man in vielen Projekten verwenden kann. Dieser Code wird möglicherweise auch eines Tages in LilyPond selbst integriert werden, aber bis dahin müssen Sie ihn selber herunterladen und mit \include selber einfügen.

http://www.nicta.com.au/people/chubbp/articulate

5.1 Allgemeine Vorschläge

Hier einige Vorschläge, wie Sie Probleme vermeiden oder lösen können:

• Schreiben Sie immer mit \version die Versionsnummer in jede Datei. Beachten Sie, dass in allen Vorlagen die Versionsnummer \version "2.19.21" eingetragen ist. Es empfiehlt sich, in alle Dateien, unabhängig von ihrer Größe, den \version-Befehl einzufügen. Persönliche Erfahrung hat gezeigt, dass es ziemlich frustrierend sein kann zu erinnern, welche Programmversion man etwa vor einem Jahr verwendet hat. Auch convert-ly benötigt die Versionsnummer.
• Benutzen Sie Überprüfungen: Oktavenüberprüfung, und Takt- und Taktzahlüberprüfung. Wenn Sie hier und da diese Überprüfungen einfügen, finden Sie einen möglichen Fehler weit schneller. Wie oft aber ist „hier und da“? Das hängt von der Komplexität der Musik ab. ei einfachen Stücken reicht es vielleicht ein- oder zweimal, in sehr komplexer Musik sollte man sie vielleicht in jeden Takt einfügen.
• Ein Takt pro Textzeile. Wenn irgendetwas kompliziertes vorkommt, entweder in der Musik selber oder in der Anpassung der Ausgabe, empfiehlt es sich oft, nur einen Takt pro Zeile zu schreiben. Bildschirmplatz zu sparen, indem Sie acht Takte in eine Zeile zwängen, hilft nicht weiter, wenn Sie ihre Datei „debuggen“ müssen.
• Kommentieren Sie ihre Dateien. Benutzen Sie entweder Taktnummern (in regelmäßigen Abständen) oder Verweise auf musikalische Themen („Zweites Thema in den Geigen“, „vierte Variation“ usw.). Sie brauchen diese Kommentare vielleicht noch nicht, wenn Sie das Stück notieren, aber spätestens wenn Sie nach ein paar Jahren etwas verändern wollen oder Sie den Quelltext an einen Freund weitergeben wollen, ist es weitaus komplizierter, die Dateistruktur ohne Kommentare zu verstehen, als wenn Sie sie rechtzeitig eingefügt hätten.
• Schreiben Sie Klammern mit Einrückung. Viele Probleme entstehen durch ungerade Anzahl von { und }-Klammern.
• Schreiben Sie Tondauerangaben am Anfang von Abschnitten und Bezeichnern. Wenn Sie beispielsweise c4 d e am Anfang eines Abschnittes schreiben, ersparen Sie sich viele Probleme, wenn Sie ihre Musik eines Tages umarrangieren wollen.
• Trennen Sie Einstellungen von den eigentlichen Noten. Siehe auch Tipparbeit durch Variablen und Funktionen einsparen und Formatvorlagen.

5.2 Das Kopieren von bereits vorhandener Musik

Wenn Sie Musik aus einer fertigen Partitur kopieren (z. B. die LilyPond-Eingabe einer gedruckten Partitur):

• Schreiben Sie ein System ihrer Quelle nach dem anderen (aber trotzdem nur einen Takt pro Textzeile) und überprüfen Sie jedes System, nachdem Sie es fertig kopiert haben. Mit dem showLastLength- oder showFirstLength-Befehl können Sie den Übersetzungsprozess beschleunigen. Siehe auch Korrigierte Musik überspringen.
• Definieren Sie mBreak = { \break } und schreiben Sie \mBreak in der Quelldatei immer dann, wenn im Manuskript ein Zeilenumbruch vorkommt. Das macht es einfacher, die gesetzte Zeile mit den ursprünglichen Noten zu vergleichen. Wenn Sie die Partitur fertig gestellt haben, könne Sie mBreak = { }, also leer definieren, um diese manuellen Zeilenumbrüche zu entfernen. Damit kann dann LilyPond selber entscheiden, wohin es passende Zeilenumbrüche platziert.
• Wenn Sie eine Stimme für ein transponierendes Instrument als eine Variable notieren, wird empfohlen, dass die Noten von

  \transpose c klingende-Tonhöhe {...}
  

  eingefasst werden (wobei klingende-Tonhöhe die klingende Tonhöhe des Instruments ist), sodass die Noten innerhalb der Variable für klingendes C geschrieben sind. Sie können die Variable zurücktransponieren, wenn es nötig ist, aber Sie müssen es nicht tun. Fehler in Transpositionen sind treten seltener auf, wenn alle Noten in den Variablen für die gleiche Ausgangstonhöhe geschrieben werden.

  Denken Sie auch daran, dass Sie nur von/nach C transponieren. Das heißt, dass die einzigen anderen Tonhöhen, die Sie in Transpositionen benutzen, die Tonhöhen der Instrumente sind, für die Sie schreiben: bes für eine B-Trompete oder aes für eine As-Klarinette usw.

5.3 Große Projekte

Besonders wenn Sie an größeren Projekten arbeiten, ist es unumgänglich, dass Sie ihre LilyPond-Dateien klar strukturieren.

• Verwenden Sie Variablen für jede Stimme, innerhalb der Definition sollte so wenig Struktur wie möglich sein. Die Struktur des \score-Abschnittes verändert sich am ehesten, während die violine-Definition sich wahrscheinlich mit einer neuen Programmversion nicht verändern wird.

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

• Trennen Sie Einstellungen von den Noten. Diese Empfehlung wurde schon früher gegeben, aber für große Projekte ist es unumgänglich. Muss z. B. die Definition für fdannp verändert werden, so braucht man es nur einmal vorzunehmen und die Noten in der Geigenstimme, violin, bleiben unberührt.

  fdannp = _\markup{
    \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
  violin = \relative {
  g'4\fdannp c'8. e16
  }
  

5.4 Fehlersuche

Früher oder später werden Sie in die Lage kommen, dass LilyPond Ihre Datei nicht kompilieren will. Die Information, die LilyPond während der Übersetzung gibt, können Ihnen helfen, den Fehler zu finden, aber in vielen Fällen müssen Sie nach der Fehlerquelle auf die Suche gehen.

Die besten Hilfsmittel sind in diesem Fall das Zeilen- und Blockkommentar (angezeigt durch % bzw. %{ ... %}). Wenn Sie nicht bestimmen können, wo sich das Problem befindet, beginnen Sie damit, große Teile des Quelltextes auszukommentieren. Nachdem Sie einen Teil auskommentiert haben, versuchen Sie, die Datei erneut zu übersetzen. Wenn es jetzt funktioniert, muss sich das Problem innerhalb der Kommentare befinden. Wenn es nicht funktioniert, müssen Sie weitere Teile auskommentieren bis sie eine Version haben, die funktioniert.

In Extremfällen bleibt nur noch solch ein Beispiel übrig:

\score {
  <<
    % \melody
    % \harmony
    % \bass
  >>
  \layout{}
}

(also eine Datei ohne Noten).

Geben Sie nicht auf, wenn das vorkommen sollte. Nehmen Sie das Kommentarzeichen von einem Teil wieder weg, sagen wir der Bassstimme, und schauen Sie, ob es funktioniert. Wenn nicht, dann kommentieren Sie die gesamte Bassstimme aus, aber nicht den \bass-Befehl in dem \score-Abschnitt:

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

Jetzt beginnen Sie damit, langsam Stück für Stück der Bassstimme wieder hineinzunehmen, bis Sie die problematische Zeile finden.

Eine andere nützliche Technik zur Problemlösung ist es, Minimalbeispiele zu konstruieren.

5.5 Make und Makefiles

Fast alle Betriebssysteme, auf denen LilyPond benutzt werden kann, unterstützen ein Programm mit dem Namen make. Dieses Programm liest eine besondere Datei mit der Bezeichnung Makefile, die definiert, welche Dateien von welchen anderen Dateien abhängen und welche Befehle für das Betriebssystem nötig sind, um eine Datei aus einer anderen zu erstellen. Ein Makefile könnte etwa erklären, wie ballad.pdf und ballad.midi aus ballad.ly erstellt werden können, indem LilyPond aufgerufen wird.

Es gibt Fällen, wenn es sich sehr stark empfiehlt, ein Makefile für das aktuelle Projekt zu erstellen, entweder zur eigenen Bequemlichkeit, oder aber auch als Hilfe für andere, die vielleicht einmal die Quelldateien lesen und verstehen wollen. Insbesondere bei großen Projekten mit vielen eingefügten Dateien und unterschiedlichen Ausgabeoptionen (etwa Partitur, einzelne Stimmen, Dirigierpartitur, Klavierauszug usw.), aber auch bei Projekten, die komplizierte Programmaufrufe zur Verarbeitung erfordern (wenn man etwa mit lilypond-book arbeitet), lohnt sich die Erstellung einer Make-Datei. Diese Dateien können sehr unterschiedliche ausfallen, und ihre Komplexität und Flexibilität kann den Bedürfnissen aber auch Kenntnissen des Schreibers angepasst werden. Das Programm GNU Make ist auf GNU/Linux-Distributionen und MacOS X installiert, aber es ist auch für Windows erhältlich.

Das GNU Make Manual gibt eine vollständige Anleitung, wie make benutzt werden kann.  Hier sollen nur einige kleine Blicke auf die vielfältigen Möglichkeiten geworfen werden.

Die Befehle, um Regeln in einer Make-Datei zu erstellen, unterscheidet sich zwischen den Betriebssystemen. Die verschiedenen GNU/Linuxe und MacOS X benutzen bash, während unter Windows cmd eingesetzt wird. Unter MacOS X muss man das System so konfigurieren, dass die Kommandozeile benutzt wird. Hier einige Beispiele für Make-Dateien, mit einer Version für GNU/Linux und MacOS und einer für Windows.

Das erste Beispiel ist für ein Orchesterstück in vier Stätzen unt mit der folgenden Dateistruktur:

Symphony/
|-- MIDI/
|-- Makefile
|-- Notes/
|   |-- cello.ily
|   |-- figures.ily
|   |-- horn.ily
|   |-- oboe.ily
|   |-- trioString.ily
|   |-- viola.ily
|   |-- violinOne.ily
|   `-- violinTwo.ily
|-- PDF/
|-- Parts/
|   |-- symphony-cello.ly
|   |-- symphony-horn.ly
|   |-- symphony-oboes.ly
|   |-- symphony-viola.ly
|   |-- symphony-violinOne.ly
|   `-- symphony-violinTwo.ly
|-- Scores/
|   |-- symphony.ly
|   |-- symphonyI.ly
|   |-- symphonyII.ly
|   |-- symphonyIII.ly
|   `-- symphonyIV.ly
`-- symphonyDefs.ily

Die .ly-Dateien un den Verzeichnissen Scores und Parts erhalten ihrere Noten aus .ily-Dateien, die sich im Notes-Verzeichnis befinden:

%%% Kopfzeile der Datei "symphony-cello.ly"
\include ../symphonyDefs.ily
\include ../Notes/cello.ily

Die Make-Datei hat die Ziele score (das gesamte Stück als große Partitur), movements (die einzelnen Sätze als große Partitur) und parts (die einzelnen Stimmen für die Spieler). Es gibt auch das Ziel archive, welches ein Tar-Archiv der Quelldateien erstellt, etwa um die Quellen über das Internet oder per E-Mail zu verteilen. Hier die Make-Datei für GNU/Linux oder MacOS X. Sie sollte unter dem Namen Makefile im obersten Verzeichnis des Projektes gespeichert werden:

# Namensstamm der Ausgabedateien
piece = symphony
# finde heraus, wieviele Prozessoren vorhanden sind
CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
# Der Befehl, um lilypond aufzurufen
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click -djob-count=$(CPU_CORES)

# Die Endungen, die im Makefile benutzt werden
.SUFFIXES: .ly .ily .pdf .midi

# Eingabe- und Ausgabedateien werden in den Verzeichnissen durchsucht,
# die sich in der VPATH-Variable befinden.  Alle sind Unterverzeichnisse
# des aktuellen Verzeichnisses (angegeben durch die GNU make-Variable
# `CURDIR').
VPATH = \
  $(CURDIR)/Scores \
  $(CURDIR)/PDF \
  $(CURDIR)/Parts \
  $(CURDIR)/Notes

# Die Musterregel, um PDF und MIDI-Dateien aus der LY-Eingabedatei
# zu erstellen.  Die .pdf-Ausgabedateien werden in das
# `PDF'-Unterverzeichnis abgelegt, die .midi-Dateien in das
# `MIDI'-Unterverzeichnis.
%.pdf %.midi: %.ly
        $(LILY_CMD) $<; \           # this line begins with a tab
        if test -f "$*.pdf"; then \
            mv "$*.pdf" PDF/; \
        fi; \
        if test -f "$*.midi"; then \
            mv "$*.midi" MIDI/; \
        fi

notes = \
  cello.ily \
  horn.ily \
  oboe.ily \
  viola.ily \
  violinOne.ily \
  violinTwo.ily

# Abhängigkeiten der einzelnen Sätze.
$(piece)I.pdf: $(piece)I.ly $(notes)
$(piece)II.pdf: $(piece)II.ly $(notes)
$(piece)III.pdf: $(piece)III.ly $(notes)
$(piece)IV.pdf: $(piece)IV.ly $(notes)

# Abhängigkeiten der großen Partitur.
$(piece).pdf: $(piece).ly $(notes)

# Abhängigkeiten der Stimmen.
$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily

# `make score' eintippen, um die große Partitur mit allen vier
# Sätzen als eine Datei zu erstellen.
.PHONY: score
score: $(piece).pdf

# `make parts' tippen, um alle Stimmen zu erstellen.
# `make foo.pdf' tippen, um die Stimme für das Instrument `foo' zu erstellen.
# Beispiel: `make symphony-cello.pdf'.
.PHONY: parts
parts: $(piece)-cello.pdf \
       $(piece)-violinOne.pdf \
       $(piece)-violinTwo.pdf \
       $(piece)-viola.pdf \
       $(piece)-oboes.pdf \
       $(piece)-horn.pdf

# `make movements' tippen um Dateien für die vier Sätze einzeln zu erstellen.
.PHONY: movements
movements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parts movements

archive:
        tar -cvvf stamitz.tar \       # this line begins with a tab
        --exclude=*pdf --exclude=*~ \
        --exclude=*midi --exclude=*.tar \
        ../Stamitz/*

Unter Windows ergeben sich bestimmte Komplikationen. Nachdem man GNU Make für Windows heruntergeladen und installiert hat, muss man den richtigen Pfad in den Umgebungsvariablen des Systems setzen, damit die DOS-Kommandozeile das Make-Programm finden kann. Um das vorzunehmen, kann mit der rechten Maustaste auf "Arbeitsplatz" klicken, dann Eigenschaften und Erweitert geklickt werden. Hier wählt man Umgebungsvariablen. In der Liste Systemvariablen wählt man Path und mit einem Klick auf Bearbeiten kann man den Pfad zu der .exe-Datei von GNU Make hinzufügen, der etwa wie folgt aussieht:

C:\Program Files\GnuWin32\bin

Die Make-Datei selber muss auch angepasst werden, um unterschiedliche Shell-Befehle zu verwenden und mit Leerzeichen umgehen zu können, die sich in einigen Standardverzeichnissen unter Windows befinden. Das archive-Ziel wird entfernt, da Windows den tar-Befehl nicht kennt, und Windows benutzt auch eine andere Dateiendung für midi-Dateien.

## WINDOWS VERSION
##
piece = symphony
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click \
                    -djob-count=$(NUMBER_OF_PROCESSORS)

# 8.3 Bezeichnung für CURDIR erhalten (Workaround wg. Leerzeichen in PATH)
workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
          do @echo %%~sb)

.SUFFIXES: .ly .ily .pdf .mid

VPATH = \
  $(workdir)/Scores \
  $(workdir)/PDF \
  $(workdir)/Parts \
  $(workdir)/Notes

%.pdf %.mid: %.ly
        $(LILY_CMD) $<      # diese Zeile beginnt mit Tabulator
        if exist "$*.pdf"  move /Y "$*.pdf"  PDF/ # begin with tab
        if exist "$*.mid" move /Y "$*.mid" MIDI/  # begin with tab

notes = \
  cello.ily \
  figures.ily \
  horn.ily \
  oboe.ily \
  trioString.ily \
  viola.ily \
  violinOne.ily \
  violinTwo.ily

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

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

$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily

.PHONY: score
score: $(piece).pdf

.PHONY: parts
parts: $(piece)-cello.pdf \
       $(piece)-violinOne.pdf \
       $(piece)-violinTwo.pdf \
       $(piece)-viola.pdf \
       $(piece)-oboes.pdf \
       $(piece)-horn.pdf

.PHONY: movements
movements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parts movements

Die nächste Make-Datei ist für ein lilypond-book-Dokument, das in LaTeX gesetzt wird. Das Projekt hat einen Index, welcher erfordert, dass der Befehl latex zweimal aufgerufen wird, um die Verweise zu aktualisieren. Ausgabedateien werden in einem out-Verzeichnis für die .pdf-Dateien gespeichert und in htmlout für die html-Dateien.

SHELL=/bin/sh
FILE=myproject
OUTDIR=out
WEBDIR=htmlout
VIEWER=acroread
BROWSER=firefox
LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
PDF=cd $(OUTDIR) && pdflatex $(FILE)
HTML=cd $(WEBDIR) && latex2html $(FILE)
INDEX=cd $(OUTDIR) && makeindex $(FILE)
PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &

all: pdf web keep

pdf:
        $(LILYBOOK_PDF)  # begin with tab
        $(PDF)           # begin with tab
        $(INDEX)         # begin with tab
        $(PDF)           # begin with tab
        $(PREVIEW)       # begin with tab

web:
        $(LILYBOOK_HTML) # begin with tab
        $(HTML)          # begin with tab
        cp -R $(WEBDIR)/$(FILE)/ ./  # begin with tab
        $(BROWSER) $(FILE)/$(FILE).html &  # begin with tab

keep: pdf
        cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf  # begin with tab

clean:
        rm -rf $(OUTDIR) # begin with tab

web-clean:
        rm -rf $(WEBDIR) # begin with tab

archive:
        tar -cvvf myproject.tar \ # begin this line with tab
        --exclude=out/* \
        --exclude=htmlout/* \
        --exclude=myproject/* \
        --exclude=*midi \
        --exclude=*pdf \
        --exclude=*~ \
        ../MyProject/*

TODO: soll auch unter Windows funktionieren

Die vorige Make-Datei funktioniert nicht unter Windows. Als Alternative für Windows-Benutzer könnte man eine einfache batch-Datei erstellen, welche die erforderlichen Befehl enthält. Sie kümmert sich nicht um Abhängigkeiten, wie es eine Make-Datei kann, aber wenigstens wird die Kompilation auf einen einzigen Befehl beschränkt. Das folgende kann als Datei build.bat oder build.cmd gespeichert werden. Die Batch-Datei kann auf der Kommandozeile aufgerufen werden oder einfach doppelt angeklickt werden.

lilypond-book --output=out --pdf myproject.lytex
cd out
pdflatex myproject
makeindex myproject
pdflatex myproject
cd ..
copy out\myproject.pdf MyProject.pdf

Siehe auch

Programmbenutzung: Benutzung auf der Kommandozeile, lilypond-book aufrufen.