Documentation/de/user/running.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-
   2 @c This file is part of lilypond-program.tely
   3 @ignore
   4     Translation of GIT committish: 2c00bdbfaf62dd90863331c4713e6b29e32c9322
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c \version "2.11.61"
  11
  12 @c Translators: Reinhold Kainhofer, Till Rettig
  13
  14 @node Running LilyPond
  15 @chapter Running LilyPond
  16
  17 Dieses Kapitel behandelt die technischen Details, wie Lilypond ausgeführt werden kann.
  18
  19
  20 @menu
  21 * Normal usage::
  22 * Command-line usage::
  23 * Error messages::
  24 * Updating files with convert-ly::
  25 * Reporting bugs::
  26 @end menu
  27
  28 @node Normal usage
  29 @section Normal usage
  30
  31 Die meisten Benutzer führen LilyPond von einer graphischen Benutzeroberfläche
  32 aus. Siehe @rlearning{First steps}, falls Sie dies nicht bereits getan haben.
  33
  34
  35 @node Command-line usage
  36 @section Command-line usage
  37
  38 Dieser Abschnitt enthält zusätzliche Informationen, wie Sie LilyPond
  39 von der Kommandozeile ausführen können.  Dies kann erforderlich sein,
  40 um etwa zusätzliche Optionen an das Programm zu übergeben.  Außerdem
  41 sind einige Zusatzprogramme (wie etwa @code{midi2ly}) nur von der
  42 Kommandozeile verfügbar.
  43
  44 Unter @q{Kommandozeile} verstehen wir die Kommandozeile des jeweiligen
  45 Betriebssystems. Windows Benutzern ist sie vielleicht eher unter den
  46 englischen Begriffen @q{DOS shell} oder @q{command shell} bekannt.
  47 MacOS@tie{}X Benutzer kennen sie eher unter @q{Terminal} oder @q{Konsole}.
  48 Sie sollten auch den Abschnitt @ref{Setup for MacOS X} konsultieren.
  49
  50 Wie die Kommandozeile im jeweiligen Betriebssystem benutzt werden kann,
  51 soll in diesem Handbuch nicht näher beschrieben werden. Sehen Sie bitte
  52 im Handbuch Ihres Betriebssystems nach oder informieren Sie sich im
  53 Internet, wenn Sie mit der Kommandozeile nicht vertraut sind.
  54
  55
  56 @menu
  57 * Invoking lilypond::
  58 * Command line options for lilypond::
  59 * Environment variables::
  60 @end menu
  61
  62 @node Invoking lilypond
  63 @subsection Invoking @command{lilypond}
  64
  65 @cindex @command{lilypond} aufrufen
  66 @cindex Kommandozeilen-Optionen für @command{lilypond}
  67 @cindex Optionen an der Kommandozeile
  68
  69 Das @command{lilypond} Programm kann folgendermaßen von der Kommandozeile
  70 aufgerufen werden.
  71
  72 @example
  73 lilypond [@var{Option}]@dots{} @var{Dateiname}@dots{}
  74 @end example
  75
  76
  77 Wird ein @file{Dateiname} ohne Erweiterung angegeben, so wird @file{.ly} als
  78 Standarderweiterung für LilyPond-Dateien benutzt.  Um Daten von
  79 @code{stdin} einzulesen, benutzen Sie einfach einen Bindestrich (@code{-})
  80 als @var{Dateiname}.
  81
  82 Wenn Lilypond die Datei @file{Dateiname.ly} verarbeitet, werden daraus
  83 die Dateien @file{Dateiname.ps} und @file{Dateiname.pdf} erzeugt.
  84 Es können an @code{lilypond} auch mehrere @file{.ly} Dateien übergeben
  85 werden, die dann einzeln und voneinander unabhängig abgearbeitet
  86 werden.@footnote{Der Zustand von GUILE wird allerdings nicht nach
  87 jeder Datei zurückgesetzt, sodass Achtung geboten ist, wenn in einer
  88 Datei globale Änderungen von Scheme aus durchgeführt werden.}
  89
  90 Falls @file{Dateiname.ly} mehr als einen @code{\score}-Block enthält,
  91 werden die weiteren Stücke in durchnummerierte Dateien der Form
  92 @file{Dateiname-1.pdf} ausgegeben.  Zusätzlich wird der Wert der
  93 Variable @code{output-suffix} zwischen den ursprünglichen Dateienamen
  94 und der Zahl eingefügt.  Eine Lilypond-Datei @var{Dateiname.ly} mit dem Inhalt
  95
  96 @example
  97 #(define output-suffix "Geige")
  98 \book @{ @dots{} @}
  99 #(define output-suffix "Cello")
 100 \book @{ @dots{} @}
 101 @end example
 102
 103 @noindent
 104 erzeugt daher die Dateien @var{Dateiname}@file{-Geige.pdf} und
 105 @var{Dateiname}@file{-Cello-1.pdf}.
 106
 107
 108
 109 @node Command line options for lilypond
 110 @subsection Command line options for @command{lilypond}
 111
 112 Die folgenden Kommandozeilenoptionen werden von @command{lilypond} unterstützt:
 113
 114 @table @code
 115
 116 @item -e,--evaluate=@var{expr}
 117 Wertet den Scheme-Ausdruck @var{expr} aus, bevor die @file{.ly} Dateien
 118 gelesen und interpretiert werden.
 119 Die @code{-e} Option kann auch mehrfach angegeben werden, die Ausdrücke
 120 werden nacheinander ausgewertet.
 121
 122 Da der Ausdruck im @code{guile-user} Modul ausgewertet wird, ist bei der
 123 Definitionen innerhalb von @var{expr} folgendes Vorgehen nötig. An der
 124 Kommandozeile wird z.B. @code{a} im @code{guile-user} Modul definiert:
 125
 126 @example
 127 lilypond -e '(define-public a 42)'
 128 @end example
 129
 130 @noindent
 131 Am Beginn der @file{.ly}-Datei muss dann das @code{guile-user} Modul noch geladen werden, bevor die Definition von @var{a} verfügbar ist:
 132
 133 @example
 134 #(use-modules (guile-user))
 135 @end example
 136
 137
 138 @item -f,--format=@var{Format}
 139 Bestimmt das Ausgabeformat. Mögliche Werte von @var{Format} sind
 140 @code{svg}, @code{ps}, @code{pdf} und @code{png}.
 141
 142 Beispiel: @code{lilypond -fpng @var{Dateiname}.ly}
 143
 144
 145
 146 @item -d,--define-default=@var{Variable}=@var{Wert}
 147 Damit wird die interne Programmoption @var{Variable} auf den Scheme-Wert
 148 @var{Wert} gesetzt. Wird kein @var{Wert} angegeben, so wird @var{#t} benutzt.
 149 Um eine Option auszuschalten, kann der Präfix @code{no-} dem Namen
 150 @var{Variable} der Variable vorangestellt werden. So ist etwa
 151
 152 @cindex Point and Click, Kommandozeile
 153
 154 @example
 155 -dno-point-and-click
 156 @end example
 157
 158 @noindent
 159 dasselbe wie
 160 @example
 161 -dpoint-and-click='#f'
 162 @end example
 163
 164 Hier sind ein paar interessante Optionen:
 165
 166 @table @samp
 167 @item help
 168 Die Ausführung von @code{lilypond -dhelp} zeigt alle verfügbaren @code{-d}
 169 Optionen.
 170
 171 @item paper-size
 172 Setzt das Standard-Papierformat,
 173 @example
 174 -dpaper-size=\"letter\"
 175 @end example
 176
 177 @noindent
 178 Die Zeichenkette, die das Format angibt, muss in Anführungszeichen mit Backslash
 179 ( @code{\"} ) stehen.
 180
 181
 182 @item safe
 183 Vertraut der @code{.ly} Datei nicht.
 184
 185 Wenn LilyPond über einen Webserver verfügbar gemacht wird, @b{MUSS} unbedingt
 186 eine die Optionen @code{--safe} oder @code{--jail} angegeben werden.
 187 Die @code{--safe} Option verhindert, dass in der .ly-Datei angegebener
 188 Scheme-Code das System gefährden kann, wie etwa in folgendem Beispiel:
 189
 190 @quotation
 191 @verbatim
 192 #(system "rm -rf /")
 193 {
 194   c4^#(ly:export (ly:gulp-file "/etc/passwd"))
 195 }
 196 @end verbatim
 197 @end quotation
 198
 199 Mit der @code{-dsafe} Option werden alle Scheme-Ausdrücke einem speziellen
 200 sicheren Modus ausgewertet. Dieser Modus ist vom GUILE @file{safe-r5rs} Modul
 201 abgeleitet und fügt noch zahlreiche weitere erlaubte Funktionen der
 202 LilyPond Programm-Schnittstelle hinzu. Diese Funktionen sind in
 203 @file{scm/@/safe@/-lily@/.scm} angegeben.
 204
 205 Zusätzliche verbietet der sichere Modus auch @code{\include} Befehle.
 206
 207 Im sicheren Modus ist es nicht möglich, LilyPond-Variablen nach Scheme
 208 zu exportieren.
 209
 210 @code{-dsafe} erkennt jedoch @emph{KEINE} Überbeanspruchung der verfügbaren
 211 Ressourcen. In diesem Modus ist es also trotzdem möglich, dass LilyPond in einer
 212 Endlosschleife hängt, z.B. wenn zyklische Datenstrukturen an das Backend
 213 übergeben werden. Wenn LilyPond also auf einem öffentlich zugänglichen
 214 Webserver verfügbar gemacht wird, sollte der Prozess sowohl in der CPU-
 215 als auch in der Speichernutzung limitiert werden.
 216
 217 Der sichere Modus verhindert auch, dass zahlreiche nützliche
 218 Musikfragmente von LilyPond verarbeitet werden. Die @code{--jail} Option ist
 219 eine sicherere Alternative, benötigt allerdings auch mehr Aufwand zur
 220 Einrichtung.
 221
 222 @item backend
 223 Gibt an, welches Ausgabeformat das LilyPond Backend benutzt. Mögliche Werte
 224 für diese Option sind:
 225 @table @code
 226 @item ps
 227 PostScript-Ausgabeformat.
 228
 229 @cindex PostScript Ausgabeformat
 230
 231 Postscript-Dateien enthalten auch TTF-, Type1- und OTF-Schriften. Allerdings
 232 wird die gesamte Schriftart eingefügt und nicht nur die benötigten Zeichen.
 233 Vor allem wenn nicht-westliche Zeichensätze benutzt werden, kann dies zu sehr
 234 großen Dateien führen.
 235
 236 @item eps
 237 Erzeugt @q{encapsulated PostScript} (EPS). Jede Seite (oder jedes System) wird
 238 als eigene @file{EPS}-Datei ausgegeben, inklusive Schriftarten. Außerdem wird
 239 eine Datei mit allen Seiten (bzw. Systemen) und Schriftarten erzeugt.
 240
 241 Dies ist die Standardeinstellung von @command{lilypond-book}.
 242
 243 @item svg
 244 SVG-Ausgabe (Scalable Vector Graphics). Jede Seite wird als eigene
 245 @file{SVG}-Datei ausgegeben, inklusive eingebetteten Schriftarten.
 246 @cindex SVG (Scalable Vector Graphics)
 247 Sie benötigen einen SVG-Betrachter, der eingebettete Schriftarten unterstützt,
 248 oder einen SVG-Betrachter, der eingebettete Schriftarten durch OTF-Schriften
 249 ersetzen kann. In UNIX und Linux kann z.B. @uref{http://www.inkscape.org,Inkscape}
 250 (ab Version 0.42) benutzt werden, nachdem die OTF-Schriften aus dem
 251 LilyPond-Verzeichnis (typischerweise @file{/usr/share/lilypond/VERSION/fonts/otf/})
 252 in das Verzeichnis @file{~/.fonts/} kopiert wurden.
 253
 254 @item scm
 255 gibt die rohen Scheme-basierenden Zeichenbefehle aus, wie sie intern von
 256 LilyPond benutzt werden.
 257
 258 @cindex Scheme dump
 259 @end table
 260
 261 Beispiel: @code{lilypond -dbackend=svg @var{Dateiname}.ly}
 262
 263 @cindex Ausgabeformat
 264
 265 @item preview
 266 Erzeugt eine Ausgabedatei, die nur die Titelzeilen und das erste System
 267 enthält.
 268
 269 @item print-pages
 270 Erzeugt vollständige Seiten (Standardeinstellung).  @code{-dno-print-pages}
 271 ist in Verbindung mit @code{-dpreview} nützlich.
 272
 273 @end table
 274
 275
 276
 277 @item -h,--help
 278 Zeigt eine Zusammenfassung der Programmbenutzung und der Optionen.
 279
 280 @item -H,--header=@var{FELD}
 281 Gibt den Inhalt eines Feldes aus dem @code{\header}-Block in die Datei
 282 @file{Dateiname.@var{FELD}} aus.
 283
 284 @item --include, -I=@var{Verzeichnis}
 285 Fügt @var{Verzeichnis} zur Liste der Suchpfade hinzu.
 286 @cindex Dateisuche
 287 @cindex Suchpfad
 288
 289 @item -i,--init=@var{Initialisierungsdatei}
 290 Benutzt @var{Initialisierungsdatei} zur gesamten Programminitialisierung. Der
 291 Standardwert ist @file{init.ly}.
 292
 293 @item -o,--output=@var{DATEI}
 294 Schreibt das Ergebnis der Verarbeitung mit LilyPond in die Ausgabedatei
 295 @var{DATEI}. Die entsprechende Dateinamenserweiterung wird angehängt (z.B.
 296 @code{.pdf} für pdf).
 297
 298 @item --ps
 299 Erzeugt PostScript.
 300
 301 @item --png
 302 Erzeugt eine Grafik-Datei im PNG-Format von jeder Seite. Diese Option
 303 impliziert auch @code{--ps}. Die Auflösung in DPI der Grafik kann festgelegt
 304 werden durch
 305 @example
 306 -dresolution=110
 307 @end example
 308
 309 @item --pdf
 310 Erzeugt PDF-Dateien. Dies impliziert @code{--ps}.
 311
 312
 313
 314 @item -j,--jail=@var{Benutzer},@var{Gruppe},@var{Jail-Verzeichnis},@var{Arbeitsverzeichnis}
 315 Führt @command{lilypond} in einem chroot-Jail aus.
 316
 317 Die @code{--jail} Option ist eine flexiblere Alternative zu @code{--safe}, wenn
 318 LilyPond über das Internet verfügbar gemacht wird oder LilyPond-Quelldateien
 319 von Dritten automatisch vararbeitet werden.
 320
 321 Sie funktioniert dergestalt, dass das Wurzelverzeichnis von
 322 @command{lilypond} auf @var{Jail-Verzeichnis} gesetzt wird, bevor die
 323 tatsächliche Kompilierung der .ly-Datei beginnt. Der Benutzer und die Gruppe
 324 werden auf die angegebenen Werte gesetzt und das aktuelle Arbeitsverzeichnis
 325 wird ebenfalls auf den angegebenen Wert @var{Arbeitsverzeichnis} gesetzt.
 326 Diese Einstellungen garantieren (zumindest in der Theorie), dass es nicht
 327 möglich ist, aus dem Jail auszubrechen. Damit @code{--jail} funktioniert, muss
 328 @command{lilypond} allerdings als root ausgeführt werden, was normalerweise
 329 auf sichere Art mit dem Kommando @command{sudo} erreicht werden kann.
 330
 331 Das Jail-Verzeichnis zu erstellen ist etwas heikel, da LilyPond alle zur
 332 Ausführung nötigen Bibliotheken und Dateien @emph{innerhalb des
 333 Jail-Verzeichnisses} finden muss. Ein typisches Setup besteht aus folgenden
 334 Punkten:
 335
 336 @table @asis
 337 @item Erstellung eines getrennten Dateisystems
 338 Ein eigenes Dateisystem muss für LilyPond erstellt werden, sodass es mit
 339 sicheren Einstellungen wie @code{noexec}, @code{nodev} und @code{nosuid}
 340 eingebunden werden kann. Damit ist es unmöglich, Programme von diesem
 341 Dateisystem auszuführen oder direkt auf eine Hardware-Schnittstelle
 342 zuzugreifen. Wenn Sie keine eigene Partition erstellen möchten, können Sie
 343 auch eine Datei der entsprechenden Größe erstellen und sie als @q{loop}-Gerät
 344 einbinden. Ein getrenntes Dateisystem garantiert auch, dass LilyPond nicht
 345 mehr Festplattenspeicher benutzt als erlaubt.
 346
 347 @item Erstellung eines eigenen Benutzerkontos
 348 Es sollte ein eigener Benutzer und eine eigene Gruppe (z. B.
 349 @code{lily}/@code{lily}) mit geringen Rechten für die Ausführung von LilyPond
 350 innerhalb des Jails benutzt werden. Nur ein einziges Verzeichnis des Jails sollte
 351 für den Benutzer schreibbar sein und als @var{Arbeitsverzeichnis} an
 352 @code{lilypond} übergeben werden.
 353
 354 @item Einrichtung des Jails
 355 LilyPond muss zahlreiche Dateien für die Ausführung einlesen. All diese
 356 Dateien müssen in das Jail-Verzeichnis kopiert werden (mit denselben Pfaden
 357 wie im tatsächlichen Wurzel-Dateisystem). Die gesamte LilyPond-Installation
 358 (typischerweise @file{/usr/share/lilypond}) sollte kopiert werden.
 359
 360 Falls Probleme auftreten, ist es am einfachsten, Lilypond mittels
 361 @command{strace} zu starten, wodurch Sie relativ leicht feststellen können,
 362 welche Dateien im Jail noch fehlen.
 363
 364 @item Ausführung von LilyPond
 365 In einem mit @code{noexec} eingebundenen Jail ist es nicht möglich, externe
 366 Programme auszuführen. Daher muss LilyPond auf eine Art gestartet werden,
 367 die keine weitere Ausführung von Programmen benötigt. Wie bereits erwähnt
 368 muss LilyPond mit Administrator-Rechten gestartet werden (die es allerdings
 369 sofort wieder abgibt), beispielsweise mittels @command{sudo}. Außerdem
 370 ist es eine gute Idee, die LilyPond zur Verfügung stehende CPU-Zeit zu
 371 limitieren (z. B. mit @command{ulimit -t}) und -- falls das Betriebssystem
 372 dies unterstützt -- auch den zur Verfügung stehenden Hauptspeicher.
 373 @end table
 374
 375
 376 @item -v,--version
 377 Gibt die Versionsnummer aus.
 378
 379 @item -V,--verbose
 380 Gibt ausführliche informative Meldungen aus: Zeigt die vollen Dateipfade
 381 aller gelesenen Dateien sowie Informationen über die Laufzeit.
 382
 383 @item -w,--warranty
 384 Zeigt die Garantiebedingungen an, unter denen GNU LilyPond steht. (Es besteht
 385 @strong{KEINERLEI GARANTIE}!)
 386 @end table
 387
 388
 389 @node Environment variables
 390 @subsection Environment variables
 391
 392 @cindex LANG
 393 @cindex LILYPOND_DATADIR
 394
 395 @command{lilypond} erkennt und benützt die folgenden Umgebungsvariablen:
 396 @table @code
 397 @item LILYPOND_DATADIR
 398 Diese Variable gibt das Verzeichnis an, wo Lilypond seine eigenen Dateien,
 399 Meldungen und Übersetzungen finden kann.  Dieses Verzeichnis sollte
 400 Unterverzeichnisse @file{ly/}, @file{ps/}, @file{tex/}, etc. beinhalten.
 401
 402 @item LANG
 403 Gibt die Sprache an, in der Warnungen und Fehlermeldungen ausgegeben werden.
 404
 405 @item LILYPOND_GC_YIELD
 406 Mit dieser Variable (mit Werten zwischen 0 und 100) kann die Feinabstimmung
 407 zwischen dem Bedarf an Hauptspeicher und Rechenleistung bei der Ausführung
 408 von LilyPond durchgeführt werden.  Bei höheren Werten benutzt LilyPond
 409 mehr Hauptspeicher, benötigt aber weniger Prozessor-Leistung.  Bei
 410 niedrigeren Werten wird mehr Prozessor-Zeit, dafür weniger Hauptspeicher
 411 benötigt.  Voreinstellung ist ein Wert von @code{70}.
 412
 413 @end table
 414
 415
 416 @node Error messages
 417 @section Error messages
 418
 419 @cindex error messages
 420 Während der Verarbeitung einer Dateien können diverse Meldungen an der
 421 Kommandozeile auftreten:
 422
 423 @table @emph
 424
 425 @item Warnung
 426 @cindex Warnung
 427 Irgendetwas ist verdächtig.  Wenn Sie etwas Ungewöhnliches in Ihrer
 428 Datei durchführen, dann werden Sie die Meldung verstehen und können
 429 sie gegebenenfalls ignorieren.  Im Normalfall jedoch bedeutet eine
 430 Warnung, dass mit Ihrer Datei etwas nicht stimmt, LilyPond jedoch
 431 trotzdem versucht, die Datei soweit wie möglich korrekt zu übersetzen.
 432
 433 @item Fehler
 434 @cindex Fehler
 435 Irgendetwas stimmt definitiv nicht.  Der aktuelle Bearbeitungsschritt
 436 (Einlesen, Interpretieren oder Formatieren der Datei) wird noch fertig
 437 ausgeführt, danach bricht die Bearbeitung aber ab.
 438
 439 @item Fataler Fehler
 440 @cindex Fataler Fehler
 441 Irgendetwas stimmt definitiv nicht und LilyPond kann nicht weiter
 442 ausgeführt werden.  Dies ist nur sehr selten der Fall, meist sind
 443 die Schriftarten nicht korrekt installiert.
 444
 445 @item Scheme Fehler
 446 @cindex Fehlerprotokoll, Scheme
 447 @cindex Scheme Fehler
 448 Fehler, die während der Ausführung von Scheme-Code auftreten, werden
 449 vom Scheme-Interpreter aufgefangen und an der Kommandozeile ausgegeben.
 450 Wenn Sie LilyPond mit der @code{--verbose} Option (auch @code{-V})
 451 ausführen, wird der sogennante @q{Call trace} ausgegeben, der die
 452 aufgerufenen Funktionen zur Zeit des Fehlers angibt.
 453
 454 @item Programmierfehler
 455 @cindex Programmierfehler
 456 Eine interne Inkonsistenz ist aufgetreten.  Diese Fehlermeldungen
 457 sollen den Programmierern die Fehlersuche erleichtern und
 458 können meistens einfach ignoriert werden.  In manchen Fällen werden
 459 so viele Meldungen ausgegeben, dass die Lesbarkeit der restliche
 460 Ausgabe davon beeinträchtigt wird.
 461
 462 @item Abgebrochen (core dumped)
 463 Dies bezeichnet einen ernsten Programmierfehler, der das Programm
 464 zum Absturz gebracht hat.  Solche Fehler werden als kritisch angesehen.
 465 Falls daher einer auftritt, senden Sie bitte einen Bug-Report!
 466 @end table
 467
 468 @cindex Fehlermeldung, Format
 469 @cindex Form der Fehlermeldungen
 470 Wenn Warnungen oder Fehlermeldungen mit einer konkreten Stelle in der
 471 Eingabedatei verknüpft werden können, dann hat die Meldung die folgende
 472 Form:
 473
 474 @example
 475 @var{Dateiname}:@var{Zeile}:@var{Spalte}: @var{Meldung}
 476 @var{Fehlerhafte Eingabezeile}
 477 @end example
 478
 479 Ein Zeilenumbruch wird in der fehlerhaften Zeile an jener Stelle eingefügt,
 480 wo der Fehler aufgetreten ist.  Zum Beispiel
 481
 482 @example
 483 test.ly:2:19: Fehler: keine gültige Dauer: 5
 484   @{ c'4 e'
 485              5 g' @}
 486 @end example
 487
 488 Diese Stellen sind LilyPonds Vermutung, wo die Warnung oder der Fehler
 489 aufgetreten ist, allerdings treten Warnungen und Fehler ja gerade in
 490 unerwarteten Fällen auf.  Manchmal kann Lilypond auch eine fehlerhafte
 491 Stelle zwar noch problemlos verarbeiten, ein paar Zeilen später wirkt
 492 sich der Fehler aber dann doch noch aus.  In solchen Fällen, wo Sie in
 493 der angegebenen Zeile keinen Fehler erkennen, sollten Sie auch die Zeilen
 494 oberhalb der angegebenen Stelle genauer unter die Lupe nehmen.
 495
 496
 497 @node Updating files with convert-ly
 498 @section Updating files with @command{convert-ly}
 499
 500 @cindex Aktualisierung von LilyPond-Dateien
 501 @cindex Aktualisierung mit convert-ly
 502 @cindex convert-ly: Aktualisierung
 503
 504 Die Eingabesyntax von LilyPond ändert sich graduell um etwa die
 505 Eingabe zu erleichtern oder neue Funktionen zu ermöglichen.  Ein
 506 Nebeneffekt hiervon ist, dass das LilyPond-Übersetzerprogramm nicht
 507 mehr mit älteren Eingabedateien kompatibel sein kann.  Um dies
 508 zu umgehen, kann @command{convert-ly} benutzt werden, welches die
 509 meisten der Syntaxänderungen korrigieren kann.
 510
 511 Das Programm benötigt eine @code{\version}-Information in der
 512 Eingabedatei, um zu wissen, von welcher Version konvertiert werden
 513 soll.  In den meisten Fällen genügt es, den Befehl
 514
 515 @example
 516 convert-ly -e meineDatei.ly
 517 @end example
 518
 519 @noindent
 520 auszuführen.
 521 @c MacOS@tie{}X-Benutzer können diesen Befehl im Menu unter
 522 @c @code{Compile > Update syntax} finden.
 523 @c Does it work? TR
 524
 525 Wenn keine Veränderungen in @code{meineDatei.ly} vorgenommen wurden
 526 und eine Datei @code{meineDatei.ly.NEW} erstellt wird, it
 527 @code{meineDatei.ly} schon aktuell.
 528
 529
 530 @menu
 531 * Command line options for convert-ly::
 532 * Problems with convert-ly::
 533 @end menu
 534
 535 @node Command line options for convert-ly
 536 @subsection Command line options for @command{convert-ly}
 537
 538 @command{convert-ly} konvertiert immer bis zur letzten Syntaxänderung,
 539 die es beherrscht.  Das heißt, dass die neue @code{version}-Nummer
 540 in der Datei überlicherweise etwas niedriger ist als die
 541 Version von @command{convert-ly}.
 542
 543 Um LilyPond-Fragmente in texinfo-Dateien zu aktualisieren, gilt
 544 der Befehl:
 545
 546 @example
 547 convert-ly --from=... --to=... --no-version *.itely
 548 @end example
 549
 550 Um die Änderungen der LilyPond-Syntax zwischen bestimmten Versionen
 551 zu sehen, kann der Befehl
 552
 553 @example
 554 convert-ly --from=... --to=... -s
 555 @end example
 556
 557 @noindent
 558 benutzt werden.
 559
 560 Viele Dateien können auf einmal aktualisiert werden, indem
 561 @code{convert-ly} mit den üblichen UNIX-Befehlen kombiniert
 562 wird.  Das folgende Beispiel aktualisiert alle @code{.ly}-Dateien
 563 im aktuellen Verzeichnis:
 564
 565 @example
 566 for f in *.ly; do convert-ly -e $f; done;
 567 @end example
 568
 569 Die allgemeine Syntax des Programms lautet:
 570
 571 @example
 572 convert-ly [@var{option}]@dots{} @var{file}@dots{}
 573 @end example
 574
 575 Folgende Optionen sind möglich:
 576
 577 @table @code
 578 @item -e,--edit
 579 Verändere die entsprechende Zeile der Eingabedatei. Überschreibt
 580 @code{--output}.
 581
 582 @item -f,--from=@var{von-Versionsnummer}
 583 Setze die Version, ab welcher konvertiert werden soll.  Wenn diese
 584 Option nicht gesetzt ist, versucht @command{convert-ly}, die
 585 Version auf Grundlage von @code{\version} zu raten.
 586
 587 @item -n,--no-version
 588 Normalerweise fügt @command{convert-ly} eine @code{\version}-Zeile
 589 zur Ausgabe hinzu.  Mit dieser Option kann das unterdrückt werden.
 590
 591 @item -s, --show-rules
 592 Zeige alle bekannten Konversionsregeln und beende.
 593
 594 @item --to=@var{bis-Versionsnummer}
 595 Hiermit kann das Ziel der Konversion gesetzt werden.  Standard ist
 596 die neueste mögliche Version.
 597
 598 @item -h, --help
 599 Benutzerhilfe ausgeben.
 600 @end table
 601
 602
 603 @node Problems with convert-ly
 604 @subsection Problems with @code{convert-ly}
 605
 606 Nicht alle Änderungen der Syntax können konvertiert werden.  Nur
 607 eine Ausgabeoption kann angegeben werden.  Scheme- und
 608 LilyPond-Scheme-Code wird sehr unwahrscheinlich korrekt aktualisiert,
 609 hier ist meistens Nacharbeit erforderlich.
 610
 611 @verbatim
 612 Hier eine Liste einiger Befehle, die convert-ly nicht konvertieren kann.
 613
 614 Diese Liste ist in Form von Fehlermeldungen, denn convert-ly
 615 ist so strukturiert, dass nicht alle benötigten Änderungen
 616 implementiert werden können.  Es handelt sich also eher um eine
 617 Wunschliste zur Referenz.
 618
 619 1.6->2.0:
 620  Bezifferter Bass wird nicht immer korrekt konvertiert, besonders
 621  Befehle wie {< >}.  Mats Kommentar hierzu:
 622     Um convert-ly korrekt ausführen zu können, müssen alle Vorkommen
 623     von '{<' in etwas beliebiges wie '{#' und genauso '>}' in '&}'
 624     geändert werden.  Nach der Konversion können sie dann zurück
 625     in '{ <' und '> }' verwandelt werden
 626  Nicht alle Textbeschriftungen werden richtig konvertiert.  In der
 627  alten Syntax  konnten Beschriftungsbefehle mit Klammern gruppiert
 628  werden, etwa
 629    -#'((bold italic) "string")
 630    This will incorrectly be converted into
 631    -\markup{{\bold italic} "string"}
 632    instead of the correct
 633    -\markup{\bold \italic "string"}
 634 2.0->2.2:
 635  \partcombine wird nicht konvertiert
 636  \addlyrics => \lyricsto wird nicht konvertiert, dadurch kompilieren
 637  manche Dateien mit mehreren Strophen nicht.
 638 2.0->2.4:
 639  \magnify wird nicht nach \fontsize konvertiert.
 640     - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 641  remove-tag wird nicht verändert.
 642     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 643  first-page-number wird nicht geändert.
 644     - first-page-number no => print-first-page-number = ##f
 645  Zeilenumbrüche im \header-Feld werde nicht konvertiert.
 646     - \\\\  als Zeilenumbruch in \header{...} => \markup \center-align <
 647       "First Line" "Second Line" >
 648  Crescendo- und Decrescendo-Enden werden nicht konvertiert.
 649     - \rced => \!
 650     - \rc => \!
 651 2.2->2.4:
 652  \turnOff (in \set Staff.VoltaBracket = \turnOff eingesetzt) wird nicht korrekt behandelt.
 653 2.4.2->2.5.9
 654  \markup{ \center-align <{ ... }> } sollte umgewandelt werden in:
 655  \markup{ \center-align {\line { ... }} }
 656  aber im Moment fehlt \line.
 657 2.4->2.6
 658  Besondere LaTeX-Zeichen wie $~$ im Text werden nicht nach UTF(
 659  konvertiert.
 660 2.8
 661  \score{} muss jetzt mit einem musikalischen Ausdruck beginnen.
 662  Alles andere (insbesondere \header{}) darf erst nach den Noten
 663  kommen.
 664 @end verbatim
 665
 666
 667
 668 @node Reporting bugs
 669 @section Reporting bugs
 670
 671
 672 @cindex Fehler
 673 @cindex Fehler melden
 674
 675 Wenn Sie eine Datei haben, die zu einem Absturz von LilyPond oder zu einer
 676 fehlerhaften Ausgabe führt, so ist dies ein @q{Bug}.  Die List der aktuell
 677 bekannten derartigen Fehler findet sich in unserem @q{Google Bug Tracker}:
 678
 679 @uref{http://code.google.com/p/lilypond/issues/list}
 680
 681 Wenn Sie einen Fehler gefunden haben, der noch nicht aufgelistet ist, melden
 682 Sie dies bitte anhand der Anweisungen auf der Seite
 683
 684 @uref{http://lilypond.org/web/devel/participating/bugs}
 685
 686 Wenn Sie Beispieldateien für den Fehler erstellen, versuchen Sie bitte, die
 687 Datei möglichst minimal zu halten und nur jenen LilyPond Code aufzunehmen,
 688 der auch wirklich für den Fehler verantwortlich ist.  Meldungen mit
 689 Beispieldateien, die nicht minimal sind, können wir meist aus Zeitgründen
 690 nicht effektiv bearbeiten.
 691