1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 0fcca9bfd579bbda8ef0842baa5cd57b8ba718e2
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
14 @c Translators: Jean-Charles Malahieude
15 @c Translation checkers:
17 @c Note: keep this node named so that `info lilypond-book' brings you here.
19 @chapter Association musique-texte avec @command{lilypond-book}
20 @translationof lilypond-book
22 Vous pouvez inclure des partitions dans un document tout comme vous
23 feriez pour n'importe quelle image. Ces images sont générées séparément
24 -- que ce soit sous forme de description PostScript ou au format PNG --
25 puis incluses dans votre document @LaTeX{} ou HTML.
27 @command{lilypond-book} permet d'automatiser ces opérations@tie{}: le
28 programme extrait de votre document les fragments de musique, les
29 traite grâce à @command{lilypond} puis en restitue la partition dans
30 votre document. Largeur de ligne et taille de la fonte sont adaptées
31 pour correspondre à la mise en forme de votre document.
33 @command{lilypond-book} est un script indépendant de @command{lilypond}
34 et se lance en ligne de commande -- pour plus de précisions, consultez
35 @ref{Utilisation en ligne de commande}. Si vous utilisez MacOS ou
36 Windows et rencontrez quelque difficulté avec @code{lilypond-book},
37 référez-vous à @rweb{MacOS X} ou @rweb{Windows}.
39 @command{lilypond-book} s'applique aux documents @LaTeX{}, HTML, Texinfo
48 @cindex documents, ajout de musique
49 @cindex HTML, musique et
50 @cindex Texinfo, musique et
51 @cindex DocBook, musique et
52 @cindex LaTeX, musique et
56 * Exemple de document musicologique::
57 * Association musique-texte::
58 * Options applicables aux fragments de musique::
59 * Utilisation de lilypond-book::
60 * Extensions de nom de fichier::
61 * Modèles pour lilypond-book::
62 * Gestion de la table des matières::
63 * Autres méthodes d'association texte-musique::
67 @node Exemple de document musicologique
68 @section Exemple de document musicologique
69 @translationof An example of a musicological document
73 Un certain nombre d'ouvrages peuvent être illustrés par des extraits
74 musicaux, qu'il s'agisse d'un taité de musicologie, d'un carnet de chant
75 ou d'un manuel à l'exemple de celui que vous consultez actuellement.
76 Cet agencement peut se faire @qq{à la main} par importation d'un
77 graphique PostScript dans le traitement de texte. Les développeurs de
78 LilyPond ont cependant créé un outil permettant d'automatiser ces
79 opérations pour ce qui concerne les documents HTML, @LaTeX{}, Texinfo et
82 Un script -- @code{lilypond-book} -- se charge d'extraire les fragments
83 de musique, puis de les mettre en forme avant de renvoyer la
84 @qq{partition} correspondante. Voici un court exemple utilisable avec
85 @LaTeX{}. Dans la mesure où il est suffisamment parlant, nous nous
86 abstiendrons de le commenter.
89 @subheading Fichier d'entrée
94 \documentclass[a4paper]{article}
98 Un document destiné à être traité par \verb+lilypond-book+ peut tout à
99 fait mélanger de la musique et du texte.
104 c2 e2 \times 2/3 { f8 a b } a2 e4
108 Les options sont indiquées entre crochets.
110 \begin{lilypond}[fragment,quote,staffsize=26,verbatim]
114 Des extraits plus conséquents peuvent faire l'objet d'un fichier
115 indépendant, alors inclus avec \verb+\lilypondfile+.
117 \lilypondfile[quote,noindent]{screech-boink.ly}
119 (Si besoin, remplacez @file{screech-boink.ly} par
120 n'importe quel fichier @file{.ly} qui se trouve dans
121 le même répertoire que le présent fichier.)
128 @subheading Traitement
129 @translationof Processing
131 Enregistrez ces lignes dans un fichier nommé @file{lilybook.lytex} puis,
132 dans un terminal, lancez
134 @c keep space after @version{} so TeX doesn't choke
136 lilypond-book --output=out --pdf lilybook.lytex
137 @emph{lilypond-book (GNU LilyPond) @version{} }
138 @emph{Lecture de lilybook.lytex...}
139 @emph{..nous vous épargnons le verbiage de la console..}
140 @emph{Compilation de lilybook.tex...}
143 @emph{..nous vous épargnons le verbiage de la console..}
145 @emph{(remplacez @command{xpdf} par votre lecteur de PDF habituel)}
148 Le traitement par @command{lilypond-book} puis @command{latex} va
149 générer un certain nombre de fichiers temporaires susceptibles
150 d'encombrer inutilement votre répertoire de travail, aussi nous vous
151 recommandons d'utiliser l'option @option{--output=@var{répertoire}} afin
152 que les fichiers créés soient isolés dans le sous-répertoire
155 Pour terminer, voici le résultat de cet exemple pour
156 @LaTeX{}.@footnote{Ce manuel étant réalisé avec Texinfo, il se peut que
157 la mise en forme diverge quelque peu.}
163 @translationof Output
165 Un document destiné à être traité par @command{lilypond-book} peut tout à
166 fait mélanger de la musique et du texte.
171 c2 e2 \times 2/3 { f8 a b } a2 e4
175 Les options sont indiquées entre crochets.
177 @lilypond[fragment,quote,staffsize=26,verbatim]
181 Des extraits plus conséquents peuvent faire l'objet d'un fichier
182 indépendant, alors inclus avec @code{\lilypondfile}.
184 @lilypondfile[quote,noindent]{screech-boink.ly}
186 Lorsque vous désirez y inclure un @code{tagline}, personnalisé ou non,
187 l'intégralité de l'extrait devra apparaître dans une construction de
188 type @code{\book @{ @}}.
190 @lilypond[papersize=a8,verbatim]
193 title = "LilyPond fait ses gammes"
204 @node Association musique-texte
205 @section Association musique-texte
206 @translationof Integrating music and text
208 Nous allons nous intéresser, dans les lignes qui suivent, à la manière
209 d'intégrer LilyPond selon différents types de format.
223 @LaTeX{} peut être considéré comme le standard de publication dans le
224 domaine des sciences exactes. Il repose sur le moteur typographique
225 @TeX{}, le @emph{nec plus ultra} en la matière.
228 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/french/,
229 @emph{The Not So Short Introduction to @LaTeX{}} en français} pour un
230 aperçu des possibilités de @LaTeX{}.
232 Afin d'insérer de la musique dans vos fichiers @LaTeX{},
233 @code{lilypond-book} dispose des environnements et commandes
239 la commande @code{\lilypond@{...@}} qui permet de directement saisir du
240 code LilyPond simple@tie{};
243 l'environnement @code{\begin@{lilypond@}...\end@{lilypond@}} qui permet
244 de saisir directement du code LilyPond plus élaboré@tie{};
247 la commande @code{\lilypondfile@{...@}} qui permet d'insérer un fichier
251 la commande @code{\musicxmlfile@{...@}} qui permet d'insérer un fichier
252 MusicXML qui sera alors traité par @code{musicxml2ly} puis @code{lilypond}.
257 Il suffit, pour inclure de la musique, d'utiliser l'une des instructions
261 \begin@{lilypond@}[liste,des,options]
265 \lilypond[liste,des,options]@{ VOTRE CODE LILYPOND @}
267 \lilypondfile[liste,des,options]@{@var{fichier}@}
269 \musicxmlfile[liste,des,options]@{@var{fichier}@}
274 Par ailleurs, la commande @code{\lilypondversion} vous permet d'afficher
275 le numéro de version de LilyPond.
276 Lancer @command{lilypond-book} produira un fichier qui sera ensuite
279 Voici quelques exemples. L'environnement @code{lilypond}
282 \begin@{lilypond@}[quote,fragment,staffsize=26]
290 @lilypond[quote,fragment,staffsize=26]
297 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
303 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
306 Dans l'état actuel des choses, il n'est pas possible d'inclure des
307 accolades -- @code{@{} ou @code{@}} -- dans un
308 @code{\lilypond@{@}}@tie{}; cette commande n'est donc pertinente que
309 lorsque conjuguée à l'option @option{fragment}.
311 La longueur par défaut des portées sera ajustée en fonction des
312 commandes contenues dans le préambule du document -- ce qui précède la
313 ligne @code{\begin@{document@}}. La commande @code{lilypond-book} les
314 transmet à @LaTeX{} afin de connaître la largeur du texte, et par voie
315 de conséquence déterminer la longueur des portées. Notez bien que cet
316 algorithme heuristique n'est pas infaillible@tie{}; vous devrez alors
317 recourir à l'option @code{line-width}.
319 @cindex titrage et lilypond-book
320 @cindex \header et document @LaTeX{}
322 Dès lors qu'elles auront été définies dans votre document, les macros
323 suivantes seront appelées avant chaque extrait musical@tie{}:
326 @item @code{\preLilyPondExample} avant la musique,
328 @item @code{\postLilyPondExample} après la musique,
330 @item @code{\betweenLilyPondSystem[1]} entre les systèmes, si tant est
331 que @code{lilypond-book} a découpé la partition en plusieurs fichiers
332 PostScript. Elle requiert un paramètre et reçoit le nombre de fichiers
333 inclus dans l'extrait. Par défaut, elle insère simplement un
340 @cindex Latex, feta symbols
343 To include feta symbols (such as flat, segno, etc) in a LaTeX
344 document, use @code{\input@{titledefs@}}
347 \documentclass[a4paper]@{article@}
358 The font symbol names are defined in the file feta20.tex; to find
359 the location of this file, use the command
369 Lorsque, pour les besoins de la démonstration, certains éléments
370 musicaux tels que des liaisons -- de phrasé ou de prolongation --
371 continuent après le fragment qui vous intéresse, il suffit d'insérer un
372 saut de ligne et de limiter le nombre de systèmes à inclure.
374 En ce qui concerne @LaTeX{}, vous devrez définir
375 @code{\betweenLilyPondSystem} de telle sorte que l'inclusion cesse dès
376 que le nombre de systèmes requis est atteint. Dans la mesure où
377 @code{\betweenLilyPondSystem} n'est appelé qu'@strong{après} le premier
378 système, inclure un seul système est un jeu d'enfant@tie{}:
381 \def\betweenLilyPondSystem#1@{\endinput@}
383 \begin@{lilypond@}[fragment]
384 c'1\( e'( c'~ \break c' d) e f\)
388 Pour un plus grand nombre de systèmes, il suffit d'insérer un test
389 conditionnel @TeX{} avant le @code{\endinput}. À partir de l'exemple
390 qui suit, remplacez le @qq{2} par le nombre de systèmes dont vous aurez
394 \def\betweenLilyPondSystem#1@{
395 \ifnum##1<2\else\expandafter\endinput\fi
400 Étant donné que @code{\endinput} arrête immédiatement le traitement du
401 fichier source en cours, l'insertion du @code{\expandafter} permet de
402 repousser ce @code{\endinput} après le @code{\fi}@tie{}; la clause
403 @w{@code{\if-\fi}} sera alors respectée.
405 Gardez à l'esprit que @code{\betweenLilyPondSystem} est effectif tant
406 que @TeX{} n'est pas sorti du groupe en cours -- tel que
407 l'environnement @LaTeX{} -- ou écrasé par une nouvelle définition pour
408 la suite du document la plupart du temps. Pour réinitialiser cette
412 \let\betweenLilyPondSystem\undefined
416 dans votre document @LaTeX{}.
418 La création d'une macro @TeX{} permet de se simplifier la vie@tie{}:
421 \def\onlyFirstNSystems#1@{
422 \def\betweenLilyPondSystem##1@{%
423 \ifnum##1<#1\else\expandafter\endinput\fi@}
428 Il suffit alors, avant chacun des fragments à inclure, de spécifier le
429 nombre de systèmes requis@tie{}:
432 \onlyFirstNSystems@{3@}
433 \begin@{lilypond@}...\end@{lilypond@}
434 \onlyFirstNSystems@{1@}
435 \begin@{lilypond@}...\end@{lilypond@}
440 @command{lilypond-book} dispose d'options en ligne de commande
441 particulières. Elles sont consultables, ainsi que d'autres détails
442 spécifiques au traitement de documents @LaTeX{}, au chapitre
443 @ref{Utilisation de lilypond-book}.
448 @translationof Texinfo
450 Texinfo est le format standard pour toute la documentation du projet
451 GNU. À titre d'exemple, toute la documentation de LilyPond -- qu'il
452 s'agisse des versions HTML, PDF ou info -- est générée à partir de
455 Afin d'insérer de la musique dans vos fichiers Texinfo,
456 @code{lilypond-book} dispose des environnements et commandes
462 la commande @code{@@lilypond@{...@}} qui permet de directement saisir du
463 code LilyPond simple@tie{};
466 l'environnement @code{@@lilypond...@@endlilypond} qui permet
467 de saisir directement du code LilyPond plus élaboré@tie{};
470 la commande @code{@@lilypondfile@{...@}} qui permet d'insérer un fichier
474 la commande @code{@@musicxmlfile@{...@}} qui permet d'insérer un fichier
475 MusicXML qui sera alors traité par @code{musicxml2ly} puis @code{lilypond}.
480 Il suffit, pour inclure de la musique, d'utiliser l'une des instructions
481 suivantes dans votre fichier source@tie{}:
484 @@lilypond[liste,des,options]
488 @@lilypond[liste,des,options]@{ VOTRE CODE LILYPOND @}
490 @@lilypondfile[liste,des,options]@{@var{fichier}@}
492 @@musicxmlfile[liste,des,options]@{@var{fichier}@}
495 Par ailleurs, l'utilisation d'un @code{@@lilypondversion} permet
496 d'afficher la version de LilyPond utilisée.
498 Le traitement du fichier source par @command{lilypond-book} génère un
499 fichier Texinfo (extension @file{.itexi}) qui contiendra les balises
500 @code{@@image} pour les formats HTML, Info ou imprimable. Les images
501 générées par @command{lilypond-book} sont au format EPS et PDF en vue
502 d'une impression, et au format PNG pour leur utilisation en HTML ou
505 En voici deux exemples. Un environnement @code{lilypond}
523 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
529 @lilypond[fragment,staffsize=11]{<c' e' g'>}
531 Contrairement à @LaTeX{}, @code{@@lilypond@{@dots{}@}} ne va pas
532 intégrer d'image dans le document, mais générer un paragraphe.
539 Afin d'insérer de la musique dans vos fichiers Texinfo,
540 @code{lilypond-book} dispose des environnements et commandes
546 la commande @code{<lilypond ... />} qui permet de directement saisir du
547 code LilyPond simple@tie{};
550 l'environnement @code{<lilyond>...</lilypond>} qui permet de saisir
551 directement du code LilyPond plus élaboré@tie{};
554 la commande @code{<lilypondfile>...</lilypondfile>} qui permet d'insérer
555 un fichier LilyPond@tie{};
558 la commande @code{<musicxmlfile>...</musicxmlfile>} qui permet d'insérer
559 un fichier MusicXML qui sera alors traité par @code{musicxml2ly} puis
565 Il suffit, pour inclure de la musique, d'utiliser l'une des instructions
566 suivantes dans votre fichier source@tie{}:
569 <lilypond liste des options>
573 <lilypond liste des options: VOTRE CODE LILYPOND />
575 <lilypondfile liste des options>@var{fichier}</lilypondfile>
577 <musicxmlfile liste des options>@var{fichier}</musicxmlfile>
580 Il suffit, pour inclure de la musique, d'utiliser
583 <lilypond fragment relative=2>
584 \key c \minor c4 es g2
589 @command{lilypond-book} produira alors un fichier HTML contenant les
590 balises d'image pour les fragments de musique@tie{}:
592 @lilypond[fragment,relative=2]
593 \key c \minor c4 es g2
596 Pour insérer l'image au fil du texte, il suffit d'utiliser
597 @code{<lilypond @dots{} />}, tout en séparant options et musique par un
598 caractère deux points, comme ici@tie{}:
601 De la musique <lilypond relative=2: a b c/> au milieu d'une ligne de texte.
604 Lorsque l'inclusion concerne des fichiers indépendants, utilisez
607 <lilypondfile @var{option1} @var{option2} ...>@var{fichier}</lilypondfile>
610 La syntaxe pour @code{>musicXmlfile>} est identique à celle de
611 @code{<lilypondfile>}, à ceci près qu'elle fait référence à un fichier
612 MusicXML plutôt qu'à un fichier LilyPond.
614 Une liste des différentes options utilisables avec les balises
615 @code{lilypond} et @code{lilypondfile} est disponible, à la rubrique
616 @ref{Options applicables aux fragments de musique}.
618 Par ailleurs, la commande @code{<lilypondversion/>} vous permet
619 d'afficher le numéro de version de LilyPond.
621 @cindex titrage et HTML
622 @cindex prévisualisation d'image
628 @translationof DocBook
630 L'inclusion de documents LilyPond ne doit nuire en rien à la conformité
631 du document DocBooK@tie{}; l'utilisation d'éditeurs spécialisés ainsi
632 que d'outils de validation en sera ainsi préservée. C'est la raison
633 pour laquelle nous ne définirons pas de balise spécifique@tie{}; nous
634 respecterons plutôt les conventions des éléments standards de DocBook.
637 @subheading Conventions communes
638 @translationof Common conventions
640 Quel que soit le type d'extrait à inclure, nous utiliserons les
641 éléments @code{mediaobject} et @code{inlinemediaobject}, de telle sorte
642 que ces inclusions soient incorporées directement ou non dans le
643 document final. Les options de formatage des extraits en question sont
644 fournies par la propriété @code{role} de l'élément central -- voir les
645 paragraphes suivants. Les balises sont déterminées de manière à ce que
646 les éditeurs DocBook prennent en charge du mieux possible leur contenu.
647 Les fichiers DocBook destinés à un traitement par
648 @command{lilypond-book} doivent avoir une extension @file{.lyxml}.
651 @subheading Inclusion d'un fichier LilyPond
652 @translationof Including a LilyPond file
654 Il s'agit en fait du cas le plus simple. Le fichier à inclure doit
655 avoir une extension @file{.ly} et sera inséré comme n'importe quel
656 @code{imageobject}, en respectant la structure suivante@tie{}:
661 <imagedata fileref="music1.ly" role="printfilename" />
666 Vous pouvez utiliser, en tant que balise externe, aussi bien
667 @code{mediaobject} que @code{inlinemediaobject}.
670 @subheading Inclusion de code LilyPond
671 @translationof Including LilyPond code
673 L'inclusion de code LilyPond se réalise à l'aide d'un
674 @code{programlisting} auquel on associe le langage @code{lilypond}. En
675 voici la syntaxe@tie{}:
680 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
681 \context Staff \with @{
682 \remove Time_signature_engraver
683 \remove Clef_engraver@}
690 Comme vous le remarquez, la balise externe -- qu'il s'agisse d'un
691 @code{mediaobject} ou d'un @code{inlinemediaobject} -- comporte un bloc
692 @code{textobject} qui contiendra le @code{programlisting}.
695 @subheading Génération du document DocBook
696 @translationof Processing the DocBook document
698 @command{lilypond-book} génère, à partir d'un fichier @file{.lyxml}, un
699 document DocBook tout à fait valide -- extension @file{.xml} -- que vous
700 pourrez ensuite traiter avec votre application habituelle. Dans le cas
701 de @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, vous
702 obtiendrez alors automatiquement un fichier PDF. Les feuilles de style
703 XSL@tie{}DocBook officielles permettent de générer du HTML (HTML Help,
704 JavaHelp etc.)@tie{}; vous pourriez néanmoins devoir y apporter quelques
708 @node Options applicables aux fragments de musique
709 @section Options applicables aux fragments de musique
710 @translationof Music fragment options
712 Dans les lignes qui suivent, l'appellation @qq{commande LilyPond} fait
713 référence à toutes celles vues plus haut et qui font appel à
714 @command{lilypond-book} pour produire un extrait musical. Pour plus de
715 simplicité, nous ne parlerons que de la syntaxe applicable à @LaTeX{}.
717 Nous attirons votre attention sur le fait que les différentes options
718 sont lues de la gauche vers la droite. Si une option est transmise
719 plusieurs fois, seule la dernière sera prise en compte.
721 Les commandes LilyPond acceptent les options suivantes@tie{}:
724 @item staffsize=@var{hauteur}
725 Définit la taille de portée à @var{hauteur} exprimée en points.
728 Produit des lignes en pleine largeur avec un espacement naturel. En
729 d'autres termes, sera ajoutée la commande de mise en forme
730 @w{@code{ragged-right = ##t}}. Il s'agit de l'option par défaut de la
731 commande @code{\lilypond@{@}} en l'absence d'option @code{line-width}.
732 C'est aussi l'option par défaut pour l'environnement @code{lilypond}
733 lorsque l'option @option{fragment} est activée sans avoir défini
734 explicitement de longueur de ligne.
737 Dans le cas où l'extrait tient sur une seule ligne, la portée sera
738 étirée pour correspondre à la longueur de ligne du texte. Autrement
739 dit, la commande de mise en forme @code{ragged-right = ##f} s'ajoute à
743 @itemx line-width=@var{taille}\@var{unité}
744 Détermine la longueur de ligne à @var{taille}, exprimée en @var{unité}.
745 @var{unité} peut prendre les valeurs @code{cm}, @code{mm}, @code{in} ou
746 @code{pt}. Cette option n'affectera que le résultat de LilyPond -- la
747 longueur de la portée -- et en aucun cas la mise en forme du texte.
749 En l'absence d'argument, la longueur de ligne sera définie à une valeur
750 par défaut telle que calculée par un algoritme heuristique.
752 Lorsque l'option @code{line-width} n'est pas utilisée,
753 @command{lilypond-book} tentera de déterminer des valeurs par défaut
754 pour les cas où les environnements @code{lilypond} ne font pas appel à
755 @option{ragged-right}.
757 @item papersize=@var{chaîne}
758 Détermine le format du papier à @var{chaîne} tel que défini dans le
759 fichier @file{scm/paper.scm} -- @code{a5}, @code{quarto}, @code{11x17},
762 Toute valeur non mentionnée dans @file{scm/paper.scm} sera rejetée.
763 @code{lilypond-book} émettra un message d'avertissement et l'extrait
764 utilisera le format par défaut, à savoir @code{a4}.
767 Désactive l'impression des métriques et barres de mesure pour
768 l'intégralité de la partition.
771 Laisse à @command{lilypond-book} le soin d'ajouter ce qui est
772 indispensable, de telle sorte que vous pouvez vous contenter d'un
779 sans @code{\layout}, @code{\score}, etc.
782 N'ajoute rien à ce qui se trouve dans l'environnement LilyPond. À noter
783 qu'il s'agit de l'option par défaut.
785 @item indent=@var{taille}\@var{unité}
786 Définit l'indentation du premier système à @var{taille}, exprimée en
787 @var{unité} -- @code{cm}, @code{mm}, @code{in} ou @code{pt}. Cette
788 option n'affecte que LilyPond, et en aucun cas la mise en forme du
792 Ramène l'indentation du premier système à zéro. Cette option n'affecte
793 que LilyPond, et en aucun cas la mise en forme du texte. Dans la mesure
794 où il s'agit du comportement par défaut, point n'est besoin de spécifier
798 Réduit la longueur des lignes musicales de @math{2*0.4}@dmn{in} (soit
799 @math{2 * 10,16}@tie{}@dmn{mm}) pour renvoyer l'extrait dans un bloc de
800 citation. La valeur @qq{0,4@tie{}pouce} est contrôlée par l'option
801 @option{exampleindent}.
804 Détermine la valeur de l'indentation qui sera utilisée par l'option
808 @itemx relative=@var{n}
809 Utilise le mode d'octave relative. Les notes sont donc par défaut
810 positionnées relativement au do central. L'argument -- un nombre entier
811 -- fourni à l'option @code{relative} spécifie l'octave de départ de
812 l'extrait@tie{}; @code{1} correspond au do central. Cette option
813 @option{relative} n'a d'effet que si elle est utilisée en combinaison
814 avec l'option @option{fragment}@tie{}; autrement dit, l'option
815 @option{fragment} est implicite dès lors que @code{relative} est
820 La documentation de LilyPond, comme nous l'avons déjà vu, use
821 abondamment de @command{lilypond-book}. Elle utilise à cet effet
822 quelques options particulières.
826 L'argument de la commande LilyPond est recopié textuellement dans le
827 fichier généré, avant l'image de la partition. Cependant, cette option
828 n'est pas pleinement opérationnelle lorsqu'un @code{\lilypond@{@}} se
829 trouve au milieu d'un paragraphe.
831 L'utilisation conjointe d'un @option{verbatim} et de la commande
832 @code{lilypondfile} permet de n'inclure textuellement qu'une seule
833 partie du fichier source. @code{lilypond-book} reproduira alors
834 textuellement la partie du fichier source comprise entre les
835 commentaires @code{begin@tie{}verbatim} et éventuellement
836 @code{end@tie{}verbatim}. Si l'on considère le fichier source suivant,
837 la musique sera interprétée en mode relatif, mais la recopie du code ne
838 comportera pas l'assertion du bloc @code{relative}@tie{}:
841 \relative c' @{ % begin verbatim
848 donnera dans un bloc @emph{verbatim} précédant la partition@tie{}:
856 Si d'aventure vous désirez traduire les commentaires et noms de
857 variable dans le rendu textuel plutôt que dans le fichier source, vous
858 devrez définir la variable d'environnement @code{LYDOC_LOCALEDIR} qui
859 pointera vers un répertoire contenant l'arborescence des catalogues de
860 messages -- fichiers d'extension @code{.mo} -- du domaine
864 Cette option, effective uniquement avec Texinfo, permet d'ajouter une
865 ligne @code{\version @@w@{"@@version@{@}"@}} au @code{verbatim}.
868 Option disponible uniquement avec Texinfo.@*
869 Dès lors qu'un fichier @file{toto.ly} contient dans sa section
870 @code{\header} un champ @code{texidoc}, l'appel de @command{lilypond}
871 avec l'option @option{--header=@/texidoc} créera le fichier
872 @file{toto.texidoc}. Par ailleurs, c'est le contenu de ce
873 @file{toto.texidoc} qui sera ensuite recopié par
874 @command{lilypond-book} en préambule de l'extrait de partition -- soit
875 avant l'environnement @code{example} créé par un @code{quote}.
877 Prenons par exemple le fichier @file{toto.ly} dont le contenu est
881 texidoc = "This file demonstrates a single note."
887 et quelque part dans notre document Texinfo @file{test.texinfo}
890 @@lilypondfile[texidoc]@{toto.ly@}
894 La ligne de commande suivante produira le résultat escompté.
897 lilypond-book --pdf --process="lilypond \
898 -dbackend=eps --header=texidoc" test.texinfo
901 La plupart des fichiers de test contenus dans le répertoire @file{input}
902 de la distribution est constituée de la sorte.
904 Cette option est fort utile dans le cadre de l'adaptation en langue
905 étrangère. En effet, s'il est spécifié dans le document Texinfo une
906 clause @code{@@documentlanguage@tie{}@var{LANGUE}}, la présence d'une
907 variable @code{texidoc@var{LANGUE}} dans l'entête du fichier
908 @file{toto.ly} entraînera la reproduction -- par l'appel
909 @code{lilypond}@tie{}@option{--header=@/texidoc@var{LANGUE}} -- du
910 contenu de @file{toto.texidoc@var{LANGUE}} en lieu et place de celui de
914 Option disponible uniquement avec Texinfo.@*
915 Cette option fonctionne selon le même principe que l'option
916 @code{texidoc}@tie{}: lorsqu'un fichier @file{toto.ly} contient dans
917 son @code{\header} une variable @code{doctitle} et que @code{lilypond}
918 est appelé avec l'option @code{doctitle}, le contenu de cette variable
919 -- une simple ligne de @var{texte} -- sera recopié dans un fichier
920 @file{toto.doctitle} puis inséré dans le document Texinfo sous la
921 forme @code{@@lydoctitle@tie{}@var{texte}}. @code{@@lydoctitle} doit
922 faire l'objet d'une macro, définie dans le document Texinfo.
924 Il en va de l'option @code{doctitle} comme de l'option @code{texidoc} en
925 matière d'adaptation en langue étrangère.
928 Option disponible uniquement pour Texinfo.@*
929 Commentaires et noms de variable ne seront pas traduits dans la recopie
933 Lorsqu'un fichier source LilyPond est inclus à l'aide de
934 @code{\lilypondfile}, le nom du fichier sera reproduit juste au dessus
935 de l'extrait. Si le résultat est un fichier HTML, il s'agira alors d'un
936 lien. Seul le nom du fichier est imprimé@tie{}; autrement dit, le
937 chemin d'accès au fichier est tronqué.
942 @node Utilisation de lilypond-book
943 @section Utilisation de @command{lilypond-book}
944 @translationof Invoking lilypond-book
946 @command{lilypond-book} produit un fichier qui aura, selon le format de
947 sortie spécifié, l'extension @file{.tex}, @file{.texi}, @file{.html} ou
948 @file{.xml}. Les fichiers @file{.tex}, @file{.texi} et @file{.xml}
949 nécessitent un traitement complémentaire.
952 @subheading Instructions spécifiques à certains formats
953 @translationof Format-specific instructions
956 @subsubheading @LaTeX{}
957 @translationof @LaTeX{}
959 Un document @LaTeX{} destiné à l'impression ou à la publication peut se
960 traiter de deux manières différentes@tie{}: générer directement un PDF
961 à l'aide de PDF@LaTeX{}, ou bien générer un fichier avec @LaTeX{}
962 qui sera ensuite passé à un traducteur DVI-PostScript comme
963 @command{dvips}. La première façon est de loin la plus simple et c'est
964 celle que nous vous recommandons@footnote{Sachant que vous ne disposez
965 pas forcément de PDF@LaTeX{} et @LaTeX{} pour compiler un document
966 @LaTeX{}, nous vous présentons les deux méthodes.}@tie{}; quelque soit
967 votre préférence, sachez que vous pouvez aller du PostScript au PDF avec
968 des outils tels que @command{ps2pdf} et @command{pdf2ps} -- tous deux
969 inclus dans la distribution de Ghostscript.
971 La production d'un PDF avec PDF@LaTeX{} se fait en lançant les commandes
974 lilypond-book --pdf monfichier.lytex
975 pdflatex monfichier.tex
978 @cindex type1, polices
980 @cindex utilisation de dvips
982 La séquence @LaTeX{}/@command{dvips}/@command{ps2pdf} suivante permet de
983 produire un PDF@tie{}:
986 lilypond-book monfichier.lytex
988 dvips -Ppdf monfichier.dvi
993 Le fichier @file{.dvi} généré lors de ce traitement ne contient aucune
994 tête de note, ce qui est tout à fait normal@tie{}; elles seront incluses
995 lors de la génération du @file{.ps} puis dans le @file{.pdf}.
997 La commande @command{dvips} peut déclencher certains messages concernant
998 des fontes, que vous pouvez ignorer sans scrupule.@*
999 Si vous utilisez @command{latex} en mode colonnage, n'oubliez pas
1000 d'ajouter @option{-t@tie{}landscape} aux options de @command{dvips}.
1003 La commande @code{\pageBreak} est inopérante dans un environnement
1004 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}}.
1006 Il en va de même pour un certain nombre de variables appartenant au bloc
1007 @code{\paper}. Utilisez, entre autres, un @code{\newcommand} avec la
1008 macrocommande @code{\betweenLilyPondSystem} dans le préambule.
1011 \newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
1015 @subsubheading Texinfo
1016 @translationof Texinfo
1018 La génération d'un document Texinfo -- quel que soit le format final --
1019 s'obtient grâce aux commandes Texinfo habituelles, c'est à dire
1020 @command{texi2pdf}, @command{texi2dvi} ou @command{makeinfo} selon le
1021 résultat que vous désirez obtenir.
1023 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, et
1024 @ref{Creating an Info File, , , texinfo, GNU Texinfo}.
1027 Pour plus de détails, consultez la documentation de Texinfo.
1031 @subheading Options en ligne de commande
1032 @translationof Command line options
1034 @command{lilypond-book} accepte les options suivantes@tie{}:
1037 @item -f @var{format}
1038 @itemx --format=@var{format}
1039 Spécifie le type de document à traiter@tie{}: @code{html}, @code{latex},
1040 @code{texi} (valeur par défaut) ou @code{docbook}. Lorsque cette
1041 option n'est pas mentionnée, @command{lilypond-book} tente de déterminer
1042 automatiquement le format -- voir @ref{Extensions de nom de fichier}. À
1043 l'heure actuelle, @code{texi} est équivalant à @code{texi-html}.
1045 @c This complicated detail is not implemented, comment it out -jm
1047 The @code{texi} document type produces a Texinfo file with music
1048 fragments in the printed output only. For getting images in the HTML
1049 version, the format @code{texi-html} must be used instead.
1052 @item -F @var{filtre}
1053 @itemx --filter=@var{filtre}
1054 Passe les extrait au travers de @var{filtre} avant de traiter le
1055 fichier. Cette option permet de, par exemple, appliquer les mises à
1056 jour de LilyPond aux extraits avant de traiter le fichier@tie{}:
1059 lilypond-book --filter='convert-ly --from=2.0.0 -' mon-book.tely
1064 Affiche un bref résumé des options.
1067 @itemx --include=@var{répertoire}
1068 Ajoute @var{répertoire} au chemin des inclusions. Si des extraits ont
1069 déjà été compilés dans l'un des répertoires inclus,
1070 @command{lilypond-book} ne les rééecria pas dans le répertoire de
1071 sortie@tie{}; il sera donc nécessaire, dans la suite du traitement par
1072 @command{makeinfo} ou @command{latex}, de penser à utiliser cette même
1073 option @code{-I@tie{}@var{répertoire}}.
1075 @item -l @var{loglevel}
1076 @itemx --loglevel=@var{loglevel}
1077 Détermine le degré de verbosité à @var{loglevel}. Les différentes
1078 valeurs admises sont @code{NONE}, @code{ERROR}, @code{WARNING},
1079 @code{PROGRESS} (par défaut) et @code{DEBUG}. Lorsque cette option n'est
1080 pas activée, c'est le niveau déterminé par la variable d'environnement
1081 @code{LILYPOND_BOOK_LOGLEVEL} qui sera utilisé.
1084 @itemx --output=@var{répertoire}
1085 Regroupe les fichiers générés dans @var{répetoire}.
1086 @command{lilypond-book} crée un certain nombre de fichiers à l'usage de
1087 LilyPond. Afin d'éviter de polluer votre répertoire source, nous vous
1088 conseillons d'utiliser l'option @option{--output}, puis de vous rendre
1089 dans ce répertoire pour y lancer les commandes @command{latex} ou
1093 lilypond-book --output=out monfichier.lytex
1098 @itemx --skip-lily-check
1099 Désactive la mise en échec en l'absence de sortie de lilypond.@*
1100 Option utilisée pour la documentation au format Info sans images.
1102 @itemx --skip-png-check
1103 Désactive la mise en échec en l'absence d'images PNG correspondant aux
1105 Option utilisée pour la documentation au format Info sans images.
1107 @itemx --lily-output-dir=@var{rép}
1108 Écrit les fichiers lily-XXX dans @var{rép} et crée un lien vers le
1109 répertoire spécifié par @code{--output}. Cette option permet
1110 d'économiser du temps lors de la génération de documents qui se trouvent
1111 dans différents répertoires et partagent un certain nombre d'extraits
1114 @itemx --lily-loglevel=@var{loglevel}
1115 Détermine le degré de verbosité lors des appels à @command{lilypond}.
1116 Les valeurs autorisée de @var{loglevel} sont@tie{}: @code{NONE},
1117 @code{ERROR}, @code{WARNING}, @code{BASIC_PROGRESS}, @code{PROGRESS},
1118 @code{INFO} (par défaut) et @code{DEBUG}. Lorsque cette option n'est
1119 pas activée, c'est le niveau déterminé par la variable d'environnement
1120 @code{LILYPOND_LOGLEVEL} qui sera utilisé.
1122 @itemx --info-images-dir=@var{répertoire}
1123 Formate la sortie Texinfo de telle sorte que Info cherche les images
1124 de musique dans @var{répertoire}.
1126 @itemx --latex-program=@var{programme}
1127 Utilise l'exécutable @command{programme} en lieu et place de
1128 @command{latex}. C'est l'option que vous utiliserez si vous préférez
1129 @command{xelatex} par exemple.
1131 @itemx --left-padding=@var{distance}
1132 Décale les figures EPS de @var{distance} -- exprimée en milimètres (3
1133 par défaut). Cette option est utile lorsque les lignes de musique
1134 débordent sur la marge droite.
1136 Rappelez-vous que la largeur d'un système dépend des élément contenus
1137 dans sa marge gauche, tels que numéro de mesure et nom d'instrument.
1138 Cette option permet de @qq{raccourcir} les lignes et de les décaler vers
1139 la droite, de la distance donnée en argument.
1141 @item -P @var{commande}
1142 @itemx --process=@var{commande}
1143 Traite les extraits LilyPond avec @var{commande}. Par défaut, il s'agit
1144 de @code{lilypond}.@*
1145 Rappelez-vous que @code{lilypond-book} ne peut en même temps traiter
1146 l'option @option{--filter} et l'option @option{--process}.
1149 Crée des fichiers PDF pour les retraiter avec PDF@LaTeX{}.
1151 @item --redirect-lilypond-output
1152 Le résultat des commandes est habituellement affiché dans le terminal.
1153 Cette option permet de rediriger tout le verbiage dans un journal situé
1154 dans le même répertoire que le fichier source.
1156 @itemx --use-source-file-names
1157 Cette option permet d'affecter aux fichiers correspondant aux extraits
1158 de musique le même nom que leur source. Elle n'est fonctionnelle que
1159 dans le cas où la partition est incluse à l'aide de @code{lilypondfile},
1160 et que les répertoires mentionnés par les options @code{--output-dir} et
1161 @code{--lily-output-dir} diffèrent.
1165 @command{lilypond-book} sait être volubile@tie{}! Cette option est
1166 éqivalente à @code{--loglevel=DEBUG}.
1170 Affiche le numéro de version.
1176 @code{lilypond-book} ne sait pas interpréter la commande Texinfo
1177 @code{@@pagesize}. Dans le même ordre d'idée, des commandes @LaTeX{}
1178 modifiant les marges et longueur de ligne mentionnées après le préambule
1181 Lorsqu'une section LilyPond contient plusieurs @code{\score}, seul le
1182 premier sera traité.
1185 @node Extensions de nom de fichier
1186 @section Extensions de nom de fichier
1187 @translationof Filename extensions
1189 Vous pouvez affecter à votre fichier source n'importe quelle extension.
1190 Nous vous recommandons cependant un certain nombre d'extensions selon le
1191 format de sortie désiré -- voir @ref{Utilisation de lilypond-book}. Une
1192 extension hors du commun vous obligera à spécifier le format de sortie,
1193 alors que @code{lilpond-book} est en mesure de déterminer le format de
1194 sortie en fonction de l'extension du fichier source.
1197 @multitable @columnfractions .2 .5
1198 @item @strong{extension} @tab @strong{format résultant}
1200 @item @file{.html} @tab HTML
1201 @item @file{.htmly} @tab HTML
1202 @item @file{.itely} @tab Texinfo
1203 @item @file{.latex} @tab @LaTeX{}
1204 @item @file{.lytex} @tab @LaTeX{}
1205 @item @file{.lyxml} @tab DocBook
1206 @item @file{.tely} @tab Texinfo
1207 @item @file{.tex} @tab @LaTeX{}
1208 @item @file{.texi} @tab Texinfo
1209 @item @file{.texinfo} @tab Texinfo
1210 @item @file{.xml} @tab HTML
1214 Lorsque le fichier source a la même extension que celle que
1215 @code{lilypond-book} affectera au fichier résultant et que vous
1216 lancez @code{lilypond-book} à partir du répertoire le contenant, vous
1217 verrez assurément un message du type @qq{La sortie va écraser le fichier
1218 d'entrée}. Aussi ne saurions-nous trop vous conseiller d'utiliser
1219 l'option @option{--output}.
1222 @node Modèles pour lilypond-book
1223 @section Modèles pour lilypond-book
1224 @translationof lilypond-book templates
1226 Voici quelques canevas dédiés à @code{lilypond-book}. Si vous ne savez
1227 pas de quoi il retourne, lisez le chapitre @ref{lilypond-book}.
1231 @translationof LaTeX
1233 Vous pouvez inclure des partitions LilyPond dans un document LaTeX.
1236 \documentclass[]@{article@}
1240 Des bananes alitées sur du LaTeX.
1248 Encore des banalités LaTeX, puis quelques options entre crochets.
1250 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1258 @translationof Texinfo
1260 Un document Texinfo est tout à fait capable de comporter des fragments
1261 de partition LilyPond. Si vous ne le savez pas encore, sachez que
1262 l'intégralité de ce manuel est rédigée en Texinfo.
1265 \input texinfo @c -*-texinfo-*-
1269 Du verbiage à la mode Texinfo
1277 Toujours plus de texte Texinfo, puis des options entre crochets.
1279 @@lilypond[verbatim,fragment,ragged-right]
1291 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1297 Un document pour lilypond-book peut absolument mélanger musique et
1307 Pourquoi pas un peu plus de lilypond, avec des options pour changer :
1309 <lilypond fragment quote staffsize=26 verbatim>
1322 @translationof xelatex
1325 \documentclass{article}
1326 \usepackage{ifxetex}
1328 %pour ce qui est de xetex
1329 \usepackage{xunicode,fontspec,xltxtra}
1330 \setmainfont[Numbers=OldStyle]{Times New Roman}
1333 %inutile en l'absence de pdftex
1334 \usepackage[T1]{fontenc}
1335 \usepackage[utf8]{inputenc}
1336 \usepackage{mathptmx}%Times
1337 \usepackage{helvet}%Helvetica
1339 %ici les paquetages que pdftex sait interpréter
1340 \usepackage[ngerman,finnish,english]{babel}
1341 \usepackage{graphicx}
1344 \title{Un petit document avec LilyPond et xelatex}
1347 Les commandes habituelles de \textbf{fontes} sont fonctionnelles y
1348 compris au fil du texte, étant donné qu'\textsf{elles sont prises en
1349 charge par \LaTeX{} and XeteX.} Lorsque vous avez besoin de commandes
1350 particulières du style \verb+\XeTeX+, pensez à les inclure dans un
1351 environnement \verb+\ifxetex+. Vous pourrez ainsi utiliser la \ifxetex
1352 commande \XeTeX{} \else commande XeTeX \fi qui, elle, n'est pas reconnue
1353 par le \LaTeX traditionnel.
1355 Vous pouvez inclure des commandes LilyPond directement dans votre texte,
1363 puis reprendre le fil de votre discours.
1365 Les fontes utilisées dans les extraits LilyPond devront être définies
1366 au sein de l'extrait. Lisez le manuel d'ustilisation si vous ne
1367 maîtrisez pas lilypond-book.
1369 \selectlanguage{ngerman}
1370 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle anderen
1371 seltsamen Zeichen: ß, æ, ł, ã, č, wenn sie von der Schriftart unterstützt
1378 @node Gestion de la table des matières
1379 @section Gestion de la table des matières
1380 @translationof Sharing the table of contents
1382 Les fonctions ici mentionnées sont incluses dans le paquetage
1383 OrchestralLily, disponible sur
1386 @url{http://repo.or.cz/w/orchestrallily.git}
1389 Certains utilisateurs privilégient la flexibilité dans la gestion du
1390 texte@tie{}; ils génèrent la table des matières à partir de LilyPond et
1391 la récupèrent dans @LaTeX{}.
1394 @subsubheading Export de la table à partir de LilyPond
1395 @translationof Exporting the ToC from LilyPond
1397 Nous partons du principe que LilyPond a généré un seul fichier
1398 comportant tous les mouvement de la partition.
1401 #(define (oly:create-toc-file layout pages)
1402 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1403 (if (not (null? label-table))
1404 (let* ((format-line (lambda (toc-item)
1405 (let* ((label (car toc-item))
1406 (text (caddr toc-item))
1407 (label-page (and (list? label-table)
1408 (assoc label label-table)))
1409 (page (and label-page (cdr label-page))))
1410 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1411 (formatted-toc-items (map format-line (toc-items)))
1412 (whole-string (string-join formatted-toc-items ",\n"))
1413 (output-name (ly:parser-output-name parser))
1414 (outfilename (format "~a.toc" output-name))
1415 (outfile (open-output-file outfilename)))
1416 (if (output-port? outfile)
1417 (display whole-string outfile)
1418 (ly:warning (_ "Impossible d'ouvrir le fichier ~a contenant les informations de TdM") outfilename))
1419 (close-output-port outfile)))))
1422 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1427 @subsubheading Import de la table dans LaTeX
1428 @translationof Importing the ToC into LaTeX
1430 L'entête de votre fichier @LaTeX{} doit comporter les lignes
1432 @c no, this doesn't require the smallexample, but since the other
1433 @c two blocks on this page use it, I figured I might as well
1434 @c user it here as well, for consistency. -gp
1436 \usepackage@{pdfpages@}
1437 \includescore@{nomdelapartition@}
1441 où @code{\includescore} est défini ainsi@tie{}:
1444 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1445 % \includescore@{PossibleExtension@}
1446 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1448 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1449 % This requires some heave latex tweaking, since reading in things from a file
1450 % and inserting it into the arguments of a macro is not (easily) possible
1452 % Solution by Patrick Fimml on #latex on April 18, 2009:
1453 % \readfile@{filename@}@{\variable@}
1454 % reads in the contents of the file into \variable (undefined if file
1456 \newread\readfile@@f
1457 \def\readfile@@line#1@{%
1458 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1459 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1460 \ifeof\readfile@@f\else%
1461 \readfile@@line@{#1@}%
1464 \def\readfile#1#2@{%
1465 \openin\readfile@@f=#1 %
1467 \typeout@{No TOC file #1 available!@}%
1470 \readfile@@line@{#2@}%
1472 \closein\readfile@@f%
1476 \newcommand@{\includescore@}[1]@{
1477 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1478 \let\oly@@addtotoc\undefined
1479 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1480 \ifx\oly@@addtotoc\undefined
1481 \includepdf[pages=-]@{\oly@@fname@}
1483 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1484 @{\oly@@fname@}@}\includeit
1490 @node Autres méthodes d'association texte-musique
1491 @section Autres méthodes d'association texte-musique
1492 @translationof Alternate methods of mixing text and music
1494 D'autres moyens de mélanger musique et texte sans recourir à
1495 @command{lilypond-book} sont abordés au chapitre
1496 @ref{Inclusion de partition LilyPond dans d'autres programmes}.