[ << Association musique-texte avec lilypond-book ]	[Top][Contents][Index]	[ Programmes externes >> ]
[ < DocBook ]	[ Up : Association musique-texte avec lilypond-book ]	[ Utilisation de lilypond-book > ]

---

3.3 Options applicables aux fragments de musique

Dans les lignes qui suivent, l’appellation « commande lilypond-book » fait référence à toutes celles vues plus haut et qui font appel à lilypond-book pour produire un extrait musical. Pour plus de simplicité, nous ne parlerons que de la syntaxe applicable à Texinfo (autrement dit, débutant par un ‘@’) afin qu’elles soient aisément distinguables des commandes LilyPond.

Nous attirons votre attention sur le fait que les différentes options sont lues de la gauche vers la droite. Si une option est transmise plusieurs fois, seule la dernière sera prise en compte.

Les commandes lilypond-book acceptent les options suivantes :

staffsize=hauteur

Définit la taille de portée à hauteur exprimée en points.

ragged-right

Produit des lignes en pleine largeur avec un espacement naturel. En d’autres termes, sera ajoutée la commande de mise en forme ragged-right = ##t. Il s’agit de l’option par défaut de la commande \lilypond{} en l’absence d’option line-width. C’est aussi l’option par défaut pour l’environnement lilypond lorsque l’option fragment est activée sans avoir défini explicitement de longueur de ligne.

noragged-right

Dans le cas où l’extrait tient sur une seule ligne, la portée sera étirée pour correspondre à la longueur de ligne du texte. Autrement dit, la commande de mise en forme ragged-right = ##f s’ajoute à l’extrait LilyPond.

line-width

line-width=taille\unité

Détermine la longueur de ligne à taille, exprimée en unité. unité peut prendre les valeurs cm, mm, in, pt ou bp. Cette option n’affectera que le résultat de LilyPond – la longueur de la portée – et en aucun cas la mise en forme du texte.

En l’absence d’argument ou lorsque l’option line-width n’est pas utilisée, lilypond-book tentera de déterminer une longueur de ligne par défaut pour les cas où les environnements lilypond ne font pas appel à ragged-right.

Voir aussi l’option papersize.

papersize=chaîne

Détermine le format du papier à chaîne (par exemple a5 ou letter) pour les fragments utilisant \book. Voir Formats de papier prédéfinis pour une liste des différentes tailles disponibles.

Cette option affecte le résultat de LilyPond – les dimensions de la feuille contenant le fragment musical – et en aucaun cas le texte. Une valeur non reconnue de chaîne sera rejetée. lilypond-book émettra un message d’avertissement et l’extrait utilisera le format par défaut, à savoir la taille de papier du documents pour LaTeX et Texinfo, et A4 pour le HTML et le DocBook.

Si l’option papersize est présente mais pas line-width (plus exactement une option line-width sans argument), LilyPond utilise sa propre estimation de la longueur de ligne par défaut de par l’extrait, ignorant aussi l’option quote – lilypond-book émettra toutefois un bloc de citation.

paper-width=taille\unité

Définit la largeur du papier à taille (exprimée en unité) pour les fragments musicaux utilisant \book. unité peut prendre les valeurs cm, mm, in, pt ou bp.

Cette option affecte le résultat de LilyPond – les dimensions de la feuille contenant le fragement musical – et en aucun cas le texte. Cette option, lorsqu’elle est présente, a préséance sur l’option papersize. En l’absence d’option paper-height, la hauteur de la feuille est déterminée à sa valeur par défaut de A4 (296mm).

paper-height=taille\unité

Définit la hauteur du papier à taille (exprimée en unité) pour les fragments musicaux utilisant \book. unité peut prendre les valeurs cm, mm, in, pt ou bp.

Cette option affecte le résultat de LilyPond – les dimensions de la feuille contenant le fragement musical – et en aucun cas le texte. Cette option, lorsqu’elle est présente, a préséance sur l’option papersize. En l’absence d’option paper-width, la largeur de la feuille est déterminée à celle du document pour LaTeX et Texinfo, et à la valeur par défaut de A4 (210mm) pour HTML et DocBook.

Exemple :

\lilypond[paper-width=10\cm, paper-height=57\mm]{
  \book {
    ...
  }
}

notime

Désactive l’impression des métriques et barres de mesure pour l’intégralité de la partition.

fragment

Laisse à lilypond-book le soin d’ajouter ce qui est indispensable, de telle sorte que vous pouvez vous contenter d’un

c'4

sans \layout, \score, etc.

nofragment

N’ajoute rien à ce qui se trouve dans l’environnement LilyPond. À noter qu’il s’agit de l’option par défaut.

inline

inline=vshift

Traite l’extrait pour une utilisation en ligne, autrement dit au fil du texte d’un paragraphe. L’extrait en lui-même est formaté avec un léger décalage à gauche (à peu près équivalent à celui sur la droite) tout en ignorant la valeur donnée à l’option en ligne de commande --left-padding.

En ce qui concerne LaTeX, l’image au fil du texte est décalée verticalement. vshift est un ratio de la hauteur de l’image. En l’absence d’argument est utilisée la valeur par défaut de -0.3, descendant ainsi l’image d’environ un tiers de sa hauteur. Cette valeur par défaut peut s’ajuster à l’aide de l’option en ligne de commande --inline-vshift.

Dans le cas d’une sortie Texinfo, ceci supprime l’insertion d’une ligne vide avant et après l’extrait. Dans le cas d’une sortie HTML, ceci supprime l’insertion des <p> et </p> encadrant l’extrait.

Afin que l’extrait apparaisse réellement au fil du texte dans les modes LaTeX et Texinfo, il est nécessaire de le positionner au sein même du paragraphe, autrement dit éviter toute ligne vide avant et après l’extrait. Par exemple, ce code LaTeX

Le motif
\lilypond[inline,staffsize=11]{
  { \time 2/4 r8 g'[ g' g'] | es'2 }
}
est bien connu.

devient

Le motif est bien connu.

indent=taille\unité

Définit l’indentation du premier système à taille, exprimée en unité – cm, mm, in, pt ou bp. Cette option n’affecte que LilyPond, et en aucun cas la mise en forme du texte.

noindent

Ramène l’indentation du premier système à zéro. Cette option n’affecte que LilyPond, et en aucun cas la mise en forme du texte. Dans la mesure où il s’agit du comportement par défaut, point n’est besoin de spécifier noindent.

quote

Réduit la longueur des lignes musicales de 2*0.4in (soit 2 * 10,16 mm) pour renvoyer l’extrait dans un bloc de citation. La valeur « 0,4 pouce » est contrôlée par l’option exampleindent.

exampleindent

Détermine la valeur de l’indentation qui sera utilisée par l’option quote.

Voir aussi l’option papersize.

relative

relative=n

Utilise le mode d’octave relative. Les notes sont donc par défaut positionnées relativement au do central. L’argument – un nombre entier – fourni à l’option relative spécifie l’octave de départ de l’extrait ; 1 correspond au do central. Cette option relative n’a d’effet que si elle est utilisée en combinaison avec l’option fragment ; autrement dit, l’option fragment est implicite dès lors que relative est explicité.

La documentation de LilyPond, comme nous l’avons déjà vu, use abondamment de lilypond-book. Elle utilise à cet effet quelques options particulières.

verbatim

L’argument de la commande lilypond-book est recopié textuellement dans le fichier généré, avant l’image de la partition. Cependant, cette option n’est pas pleinement opérationnelle lorsqu’un @lilypond{} se trouve au milieu d’un paragraphe.

L’utilisation conjointe d’un verbatim et de la commande lilypondfile permet de n’inclure textuellement qu’une seule partie du fichier source. lilypond-book reproduira alors textuellement la partie du fichier source comprise entre les commentaires begin verbatim et éventuellement end verbatim. Si l’on considère le fichier source suivant, la musique sera interprétée en mode relatif, mais la recopie du code ne comportera pas l’assertion du bloc relative :

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

donnera dans un bloc verbatim précédant la partition :

  c4 e2 g4
  f2 e

Si d’aventure vous désirez traduire les commentaires et noms de variable dans le rendu textuel plutôt que dans le fichier source, vous devrez définir la variable d’environnement LYDOC_LOCALEDIR qui pointera vers un répertoire contenant l’arborescence des catalogues de messages – fichiers d’extension .mo – du domaine lilypond-doc.

texidoc

Option disponible uniquement avec Texinfo, et pour @lilypondfile.
Dès lors qu’un fichier toto.ly contient dans sa section \header un champ texidoc, l’appel de lilypond avec l’option --header=texidoc créera le fichier toto.texidoc. C’est l’option texidoc de lilypond-book qui aura pour effet de reproduire le contenu de ce toto.texidoc en préambule de l’extrait de partition – soit avant l’environnement example créé par l’option quote.

Prenons par exemple le fichier toto.ly dont le contenu est

\header {
  texidoc = "This file demonstrates a single note."
}
{ c'4 }

et quelque part dans notre document Texinfo test.texinfo

@lilypondfile[texidoc]{toto.ly}

La ligne de commande suivante produira le résultat escompté.

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

Tous les extraits inclus dans la documentations de LilyPond (voir le répertoire Documentation/snippets de la distribution) sont des fichiers .ly contenant de tels champs texidoc dans leur bloc \header.

Cette option est fort utile dans le cadre de l’adaptation en langue étrangère. En effet, s’il est spécifié dans le document Texinfo une clause @documentlanguage XX, la présence d’une variable texidocXX dans le bloc \header du fichier toto.ly entraînera la reproduction – par l’appel lilypond --header=texidocXX – du contenu de toto.texidocXX en lieu et place de celui de toto.texidoc. XX est en réalité une chaîne de deux caractères telle que « de » pour l’allemand ou « ca » pour le catalan.

doctitle

Option disponible uniquement avec Texinfo, et seulement pour @lilypondfile.
Cette option fonctionne selon le même principe que l’option texidoc : lorsqu’un fichier toto.ly contient dans son \header une variable doctitle et que lilypond est appelé avec l’option doctitle, le contenu de cette variable – une simple ligne de texte – sera recopié dans un fichier toto.doctitle puis inséré dans le document Texinfo sous la forme @lydoctitle texte. @lydoctitle doit faire l’objet d’une macro, définie dans le document Texinfo.

Il en va de l’option doctitle comme de l’option texidoc en matière d’adaptation en langue étrangère.

nogettext

Option disponible uniquement pour Texinfo.
Commentaires et noms de variable ne seront pas traduits dans la recopie textuelle du code.

printfilename

Lorsqu’un fichier source LilyPond est inclus à l’aide de lilypondfile, le nom du fichier sera reproduit juste au dessus de l’extrait. Si le résultat est un fichier HTML, il s’agira alors d’un lien. Seul le nom du fichier est imprimé ; autrement dit, le chemin d’accès au fichier est tronqué.