3.4 Utilisation de lilypond-book

lilypond-book produit un fichier qui aura, selon le format de sortie spécifié, l’extension ‘.tex’, ‘.texi’, ‘.html’ ou ‘.xml’. Les fichiers ‘.tex’, ‘.texi’ et ‘.xml’ nécessitent un traitement complémentaire.

Instructions spécifiques à certains formats

LaTeX

Un document LaTeX destiné à l’impression ou à la publication peut se traiter de deux manières différentes : générer directement un PDF à l’aide de PDFLaTeX, ou bien générer un fichier avec LaTeX qui sera ensuite passé à un traducteur DVI-PostScript comme dvips. La première façon est de loin la plus simple et c’est celle que nous vous recommandons1 ; quelque soit votre préférence, sachez que vous pouvez aller du PostScript au PDF avec des outils tels que ps2pdf et pdf2ps – tous deux inclus dans la distribution de Ghostscript.

La production d’un PDF avec PDFLaTeX se fait en lançant les commandes

lilypond-book --pdf monfichier.lytex
pdflatex monfichier.tex

La séquence LaTeX/dvips/ps2pdf suivante permet de produire un PDF :

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

Le fichier ‘.dvi’ généré lors de ce traitement ne contient aucune tête de note, ce qui est tout à fait normal ; elles seront incluses lors de la génération du ‘.ps’ puis dans le ‘.pdf’.

La commande dvips peut déclencher certains messages concernant des fontes, que vous pouvez ignorer sans scrupule.
Si vous utilisez latex en mode colonnage, n’oubliez pas d’ajouter ‘-t landscape’ aux options de dvips.

Problèmes connus et avertissements

La commande \pageBreak est inopérante dans un environnement \begin{lilypond}…\end{lilypond}.

Il en va de même pour un certain nombre de variables appartenant au bloc \paper. Utilisez, entre autres, un \newcommand avec la macrocommande \betweenLilyPondSystem dans le préambule.

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

Texinfo

La génération d’un document Texinfo – quel que soit le format final – s’obtient grâce aux commandes Texinfo habituelles, c’est à dire texi2pdf, texi2dvi ou makeinfo selon le résultat que vous désirez obtenir. Pour plus de détails, consultez la documentation de Texinfo.

Options en ligne de commande

lilypond-book accepte les options suivantes :

-f format
--format=format

Spécifie le type de document à traiter : html, latex, texi (valeur par défaut) ou docbook. Lorsque cette option n’est pas mentionnée, lilypond-book tente de déterminer automatiquement le format – voir Extensions de nom de fichier. À l’heure actuelle, texi est équivalant à texi-html.

-F filtre
--filter=filtre

Passe les extrait au travers de filtre avant de traiter le fichier. Cette option permet de, par exemple, appliquer les mises à jour de LilyPond aux extraits avant de traiter le fichier :

lilypond-book --filter='convert-ly --from=2.0.0 -' mon-book.tely
-h
--help

Affiche un bref résumé des options.

-I dir
--include=répertoire

Ajoute répertoire au chemin des inclusions. Si des extraits ont déjà été compilés dans l’un des répertoires inclus, lilypond-book ne les réécrira pas dans le répertoire de sortie ; il sera donc nécessaire, dans la suite du traitement par makeinfo ou latex, de penser à utiliser cette même option -I répertoire.

-l loglevel
--loglevel=loglevel

Détermine le degré de verbosité à loglevel. Les différentes valeurs admises sont NONE, ERROR, WARNING, PROGRESS (par défaut) et DEBUG. Lorsque cette option n’est pas activée, c’est le niveau déterminé par la variable d’environnement LILYPOND_BOOK_LOGLEVEL qui sera utilisé.

-o dir
--output=répertoire

Regroupe les fichiers générés dans répertoire. lilypond-book crée un certain nombre de fichiers à l’usage de LilyPond. Afin d’éviter de polluer votre répertoire source, nous vous conseillons d’utiliser l’option ‘--output’, puis de vous rendre dans ce répertoire pour y lancer les commandes latex ou makeinfo.

lilypond-book --output=out monfichier.lytex
cd out
…
--skip-lily-check

Désactive la mise en échec en l’absence de sortie de lilypond.
Option utilisée pour la documentation au format Info sans images.

--skip-png-check

Désactive la mise en échec en l’absence d’images PNG correspondant aux fichiers EPS.
Option utilisée pour la documentation au format Info sans images.

--lily-output-dir=rép

Écrit les fichiers lily-XXX dans rép et crée un lien vers le répertoire spécifié par --output. Cette option permet d’économiser du temps lors de la génération de documents qui se trouvent dans différents répertoires et partagent un certain nombre d’extraits identiques.

--lily-loglevel=loglevel

Détermine le degré de verbosité lors des appels à lilypond. Les valeurs autorisée de loglevel sont : NONE, ERROR, WARNING, BASIC_PROGRESS, PROGRESS, INFO (par défaut) et DEBUG. Lorsque cette option n’est pas activée, c’est le niveau déterminé par la variable d’environnement LILYPOND_LOGLEVEL qui sera utilisé.

--info-images-dir=répertoire

Formate la sortie Texinfo de telle sorte que Info cherche les images de musique dans répertoire.

--latex-program=programme

Utilise l’exécutable programme en lieu et place de latex. C’est l’option que vous utiliserez si vous préférez xelatex par exemple.

--left-padding=distance

Décale les figures EPS de distance – exprimée en millimètres (3 par défaut). Cette option est utile lorsque les lignes de musique débordent sur la marge droite.

Rappelez-vous que la largeur d’un système dépend des élément contenus dans sa marge gauche, tels que numéro de mesure et nom d’instrument. Cette option permet de « raccourcir » les lignes et de les décaler vers la droite, de la distance donnée en argument.

-P commande
--process=commande

Traite les extraits LilyPond avec commande. Par défaut, il s’agit de lilypond.
Rappelez-vous que lilypond-book ne peut en même temps traiter l’option ‘--filter’ et l’option ‘--process’.

--pdf

Crée des fichiers PDF pour les retraiter avec PDFLaTeX.

--redirect-lilypond-output

Le résultat des commandes est habituellement affiché dans le terminal. Cette option permet de rediriger tout le verbiage dans un journal situé dans le même répertoire que le fichier source.

--use-source-file-names

Cette option permet d’affecter aux fichiers correspondant aux extraits de musique le même nom que leur source. Elle n’est fonctionnelle que dans le cas où la partition est incluse à l’aide de lilypondfile, et que les répertoires mentionnés par les options --output-dir et --lily-output-dir diffèrent.

-V
--verbose

lilypond-book sait être volubile ! Cette option est équivalente à --loglevel=DEBUG.

-v
--version

Affiche le numéro de version.

Problèmes connus et avertissements

lilypond-book ne sait pas interpréter la commande Texinfo @pagesize. Dans le même ordre d’idée, des commandes LaTeX modifiant les marges et longueur de ligne mentionnées après le préambule seront ignorées.

Lorsqu’une section LilyPond contient plusieurs \score, seul le premier sera traité.


Notes de bas de page

[1] Sachant que vous ne disposez pas forcément de PDFLaTeX et LaTeX pour compiler un document LaTeX, nous vous présentons les deux méthodes.


Autres langues : English, deutsch, español, italiano, 日本語.
About automatic language selection.

LilyPond — Utilisation des programmes v2.17.97 (branche de développement).