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 (XeLaTeX, luaLaTeX), ou bien générer un fichier PostScript 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 recommandons⁶ ; 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.

Les environnements tels que

\begin{lilypond} … \end{lilypond}

ne sont pas interprétés par LaTeX. En fait, lilypond-book extrait ces « environnements » dans des fichiers accessoires et les traite par LilyPond. Il récupère ensuite les graphiques résultants et crée un fichier .tex dans lequel les macros \begin{lilypond}…\end{lilypond} sont remplacées par des commandes « d’inclusion de graphique ». C’est seulement à ce moment là que LaTeX est lancé – bien que LaTeX aura préalablement tourné, cela aura été en fait sur un document « vide » et pour calculer les dimensions du papier et la longueur de ligne pour l’extrait LilyPond.

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 texi2any selon le résultat que vous désirez obtenir. Par défaut, texi2pdf recourt à pdftex pour son traitement, ce que l’on peut constater à l’affichage en console. En pareil cas, lancer lilypond-book avec l’option --pdf générera des bribes de .pdf plutôt que des fichiers .eps. pdftex est incapable d’inclure ces derniers et émettra un message d’erreur dans le cas contraire.

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), texi-html 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-html est équivalant à texi.

-F filtre

--filter=filtre

Passe les extrait au travers de filtre avant de traiter le fichier. Cette option ne génèrera pas de partition, mais permet d’appliquer les mises à jour de LilyPond aux extraits avant de traiter le fichier par un nouvel appel à lilypond-book, cette fois-ci sans l’option --filter. Exemple :

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

lilypond-book n’autorise pas l’utilisation conjointe des options --filter et --process.

-h

--help

Affiche un bref résumé des options.

-I dir

--include=répertoire

Ajoute répertoire au chemin des inclusions. Lorsque 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 texi2any 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, WARN, 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 rép

--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 texi2any.

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 générer la documentation de LilyPond 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 générer la documentation de LilyPond 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, WARN, BASIC, 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.

--inline-vshift=vshift

En ce qui concerne le traitement par LaTeX, utiliser vshift aura pour effet de déplacer verticalement toutes les images au fil du texte. vshift est un ratio de la hauteur de l’image ; sa valeur par défaut est de -0.3, ce qui descendra donc les images d’environ un tiers de leur hauteur respective. Ce facteur peut s’adapter localement en fournissant un argument à l’option inline de l’extrait.

--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

Insère du blanc à gauche de l’extrait LilyPond. distance est exprimée en millimètres relativement au début de la portée. Sa valeur est par défaut de 3,0mm.

Rappelez-vous que la largeur d’un système dépend des élément positionnés à sa gauche, tels que numéro de mesure et noms d’instrument. Le décalage détermine la distance minimale entre le bord de l’image et le début de la portée (non indentée), ce qui permet d’obtenir un alignement vertical correct des extraits dans le document maître.

Cette option permet de « raccourcir » les lignes de portée et de les décaler vers la droite, de la distance donnée en argument.

Notez bien que distance, lorsqu’utilsée pour décaler, est arrondie à une valeur entière en big point (bp), unité pour les sorties PostScript et PDF – le bp correspond à 1/72 pouce, soit environ 0,353 mm. Ce n’est toutefois pas LilyPond qui raccourcira la longueur de la portée. Il se pourrait donc, si distance ne correspondait pas à un entier multiple de bp, que la longueur de portée paraisse modifiée.

-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. Si cette option n’est pas définie, seuls seront générés des fichiers PNG et EPS. Cette option permet d’intégrer directement du PDF dans des fichiers LaTeX ou Texinfo.

--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é.