GNU LilyPond – Utilisation des programmes: 3.4 Utilisation de lilypond-book

## 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`.

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 alors 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 certains éléments comme `\linewidth`.

#### 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. 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) 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 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 `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.

#### LilyPond — Utilisation des programmes v2.22.2 (branche stable).