1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 0f93dd92ffa0319328e58148458d22c5448b3d58
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
93 \documentclass[a4paper]{article}
97 Un document destiné à être traité par \verb+lilypond-book+ peut tout à
98 fait mélanger de la musique et du texte.
103 c2 e2 \times 2/3 { f8 a b } a2 e4
107 Les options sont indiquées entre crochets.
109 \begin{lilypond}[fragment,quote,staffsize=26,verbatim]
113 Des extraits plus conséquents peuvent faire l'objet d'un fichier
114 indépendant, alors inclus avec \verb+\lilypondfile+.
116 \lilypondfile[quote,noindent]{screech-and-boink.ly}
118 (Si besoin, remplacez @file{screech-and-boink.ly} par
119 n'importe quel fichier @file{.ly} qui se trouve dans
120 le même répertoire que le présent fichier.)
127 @subheading Traitement
129 Enregistrez ces lignes dans un fichier nommé @file{lilybook.lytex} puis,
130 dans un terminal, lancez
132 @c keep space after @version{} so TeX doesn't choke
134 lilypond-book --output=out --pdf lilybook.lytex
135 @emph{lilypond-book (GNU LilyPond) @version{} }
136 @emph{Lecture de lilybook.lytex...}
137 @emph{..nous vous épargnons le verbiage de la console..}
138 @emph{Compilation de lilybook.tex...}
141 @emph{..nous vous épargnons le verbiage de la console..}
143 @emph{(remplacez @command{xpdf} par votre lecteur de PDF habituel)}
146 Le traitement par @command{lilypond-book} puis @command{latex} va
147 générer un certain nombre de fichiers temporaires susceptibles
148 d'encombrer inutilement votre répertoire de travail, aussi nous vous
149 recommandons d'utiliser l'option @option{--output=@var{répertoire}} afin
150 que les fichiers créés soient isolés dans le sous-répertoire
153 Pour terminer, voici le résultat de cet exemple pour
154 @LaTeX{}.@footnote{Ce manuel étant réalisé avec Texinfo, il se peut que
155 la mise en forme diverge quelque peu.}
162 Un document destiné à être traité par @command{lilypond-book} peut tout à
163 fait mélanger de la musique et du texte.
168 c2 e2 \times 2/3 { f8 a b } a2 e4
172 Les options sont indiquées entre crochets.
174 @lilypond[fragment,quote,staffsize=26,verbatim]
178 Des extraits plus conséquents peuvent faire l'objet d'un fichier
179 indépendant, alors inclus avec @code{\lilypondfile}.
181 @lilypondfile[quote,noindent]{screech-and-boink.ly}
183 Lorsque vous désirez y inclure un @code{tagline}, personnalisé ou non,
184 l'intégralité de l'extrait devra apparaître dans une construction de
185 type @code{\book @{ @}}.
187 @lilypond[papersize=a8,verbatim]
190 title = "LilyPond fait ses gammes"
201 @node Association musique-texte
202 @section Association musique-texte
203 @translationof Integrating music and text
205 Nous allons nous intéresser, dans les lignes qui suivent, à la manière
206 d'intégrer LilyPond selon différents types de format.
220 @LaTeX{} peut être considéré comme le standard de publication dans le
221 domaine des sciences exactes. Il repose sur le moteur typographique
222 @TeX{}, le @emph{nec plus ultra} en la matière.
225 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/french/,
226 @emph{The Not So Short Introduction to @LaTeX{}} en français} pour un
227 aperçu des possibilités de @LaTeX{}.
229 Afin d'insérer de la musique dans vos fichiers @LaTeX{},
230 @code{lilypond-book} dispose des environnements et commandes
236 la commande @code{\lilypond@{...@}} qui permet de directement saisir du
237 code LilyPond simple@tie{};
240 l'environnement @code{\begin@{lilypond@}...\end@{lilypond@}} qui permet
241 de saisir directement du code LilyPond plus élaboré@tie{};
244 la commande @code{\lilypondfile@{...@}} qui permet d'insérer un fichier
248 la commande @code{\musicxmlfile@{...@}} qui permet d'insérer un fichier
249 MusicXML qui sera alors traité par @code{musicxml2ly} puis @code{lilypond}.
254 Il suffit, pour inclure de la musique, d'utiliser l'une des instructions
258 \begin@{lilypond@}[liste,des,options]
262 \lilypond[liste,des,options]@{ VOTRE CODE LILYPOND @}
264 \lilypondfile[liste,des,options]@{@var{fichier}@}
266 \musicxmlfile[liste,des,options]@{@var{fichier}@}
271 Par ailleurs, la commande @code{\lilypondversion} vous permet d'afficher
272 le numéro de version de LilyPond.
273 Lancer @command{lilypond-book} produira un fichier qui sera ensuite
276 Voici quelques exemples. L'environnement @code{lilypond}
279 \begin@{lilypond@}[quote,fragment,staffsize=26]
287 @lilypond[quote,fragment,staffsize=26]
294 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
300 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
303 Dans l'état actuel des choses, il n'est pas possible d'inclure des
304 accolades -- @code{@{} ou @code{@}} -- dans un
305 @code{\lilypond@{@}}@tie{}; cette commande n'est donc pertinente que
306 lorsque conjuguée à l'option @option{fragment}.
308 La longueur par défaut des portées sera ajustée en fonction des
309 commandes contenues dans le préambule du document -- ce qui précède la
310 ligne @code{\begin@{document@}}. La commande @code{lilypond-book} les
311 transmet à @LaTeX{} afin de connaître la largeur du texte, et par voie
312 de conséquence déterminer la longueur des portées. Notez bien que cet
313 algorithme heuristique n'est pas infaillible@tie{}; vous devrez alors
314 recourir à l'option @code{line-width}.
316 @cindex titrage et lilypond-book
317 @cindex \header et document @LaTeX{}
319 Dès lors qu'elles auront été définies dans votre document, les macros
320 suivantes seront appelées avant chaque extrait musical@tie{}:
323 @item @code{\preLilyPondExample} avant la musique,
325 @item @code{\postLilyPondExample} après la musique,
327 @item @code{\betweenLilyPondSystem[1]} entre les systèmes, si tant est
328 que @code{lilypond-book} a découpé la partition en plusieurs fichiers
329 PostScript. Elle requiert un paramètre et reçoit le nombre de fichiers
330 inclus dans l'extrait. Par défaut, elle insère simplement un
337 @cindex Latex, feta symbols
340 To include feta symbols (such as flat, segno, etc) in a LaTeX
341 document, use @code{\input@{titledefs@}}
344 \documentclass[a4paper]@{article@}
355 The font symbol names are defined in the file feta20.tex; to find
356 the location of this file, use the command
366 Lorsque, pour les besoins de la démonstration, certains éléments
367 musicaux tels que des liaisons -- de phrasé ou de prolongation --
368 continuent après le fragment qui vous intéresse, il suffit d'insérer un
369 saut de ligne et de limiter le nombre de systèmes à inclure.
371 En ce qui concerne @LaTeX{}, vous devrez définir
372 @code{\betweenLilyPondSystem} de telle sorte que l'inclusion cesse dès
373 que le nombre de systèmes requis est atteint. Dans la mesure où
374 @code{\betweenLilyPondSystem} n'est appelé qu'@strong{après} le premier
375 système, inclure un seul système est un jeu d'enfant@tie{}:
378 \def\betweenLilyPondSystem#1@{\endinput@}
380 \begin@{lilypond@}[fragment]
381 c'1\( e'( c'~ \break c' d) e f\)
385 Pour un plus grand nombre de systèmes, il suffit d'insérer un test
386 conditionnel @TeX{} avant le @code{\endinput}. À partir de l'exemple
387 qui suit, remplacez le @qq{2} par le nombre de systèmes dont vous aurez
391 \def\betweenLilyPondSystem#1@{
392 \ifnum##1<2\else\expandafter\endinput\fi
397 Étant donné que @code{\endinput} arrête immédiatement le traitement du
398 fichier source en cours, l'insertion du @code{\expandafter} permet de
399 repousser ce @code{\endinput} après le @code{\fi}@tie{}; la clause
400 @w{@code{\if-\fi}} sera alors respectée.
402 Gardez à l'esprit que @code{\betweenLilyPondSystem} est effectif tant
403 que @TeX{} n'est pas sorti du groupe en cours -- tel que
404 l'environnement @LaTeX{} -- ou écrasé par une nouvelle définition pour
405 la suite du document la plupart du temps. Pour réinitialiser cette
409 \let\betweenLilyPondSystem\undefined
413 dans votre document @LaTeX{}.
415 La création d'une macro @TeX{} permet de se simplifier la vie@tie{}:
418 \def\onlyFirstNSystems#1@{
419 \def\betweenLilyPondSystem##1@{%
420 \ifnum##1<#1\else\expandafter\endinput\fi@}
425 Il suffit alors, avant chacun des fragments à inclure, de spécifier le
426 nombre de systèmes requis@tie{}:
429 \onlyFirstNSystems@{3@}
430 \begin@{lilypond@}...\end@{lilypond@}
431 \onlyFirstNSystems@{1@}
432 \begin@{lilypond@}...\end@{lilypond@}
437 @command{lilypond-book} dispose d'options en ligne de commande
438 particulières. Elles sont consultables, ainsi que d'autres détails
439 spécifiques au traitement de documents @LaTeX{}, au chapitre
440 @ref{Utilisation de lilypond-book}.
445 @translationof Texinfo
447 Texinfo est le format standard pour toute la documentation du projet
448 GNU. À titre d'exemple, toute la documentation de LilyPond -- qu'il
449 s'agisse des versions HTML, PDF ou info -- est générée à partir de
452 Afin d'insérer de la musique dans vos fichiers Texinfo,
453 @code{lilypond-book} dispose des environnements et commandes
459 la commande @code{@@lilypond@{...@}} qui permet de directement saisir du
460 code LilyPond simple@tie{};
463 l'environnement @code{@@lilypond...@@endlilypond} qui permet
464 de saisir directement du code LilyPond plus élaboré@tie{};
467 la commande @code{@@lilypondfile@{...@}} qui permet d'insérer un fichier
471 la commande @code{@@musicxmlfile@{...@}} qui permet d'insérer un fichier
472 MusicXML qui sera alors traité par @code{musicxml2ly} puis @code{lilypond}.
477 Il suffit, pour inclure de la musique, d'utiliser l'une des instructions
478 suivantes dans votre fichier source@tie{}:
481 @@lilypond[liste,des,options]
485 @@lilypond[liste,des,options]@{ VOTRE CODE LILYPOND @}
487 @@lilypondfile[liste,des,options]@{@var{fichier}@}
489 @@musicxmlfile[liste,des,options]@{@var{fichier}@}
492 Par ailleurs, l'utilisation d'un @code{@@lilypondversion} permet
493 d'afficher la version de LilyPond utilisée.
495 Le traitement du fichier source par @command{lilypond-book} génère un
496 fichier Texinfo (extension @file{.itexi}) qui contiendra les balises
497 @code{@@image} pour les formats HTML, Info ou imprimable. Les images
498 générées par @command{lilypond-book} sont au format EPS et PDF en vue
499 d'une impression, et au format PNG pour leur utilisation en HTML ou
502 En voici deux exemples. Un environnement @code{lilypond}
520 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
526 @lilypond[fragment,staffsize=11]{<c' e' g'>}
528 Contrairement à @LaTeX{}, @code{@@lilypond@{@dots{}@}} ne va pas
529 intégrer d'image dans le document, mais générer un paragraphe.
536 Afin d'insérer de la musique dans vos fichiers Texinfo,
537 @code{lilypond-book} dispose des environnements et commandes
543 la commande @code{<lilypond ... />} qui permet de directement saisir du
544 code LilyPond simple@tie{};
547 l'environnement @code{<lilyond>...</lilypond>} qui permet de saisir
548 directement du code LilyPond plus élaboré@tie{};
551 la commande @code{<lilypondfile>...</lilypondfile>} qui permet d'insérer
552 un fichier LilyPond@tie{};
555 la commande @code{<musicxmlfile>...</musicxmlfile>} qui permet d'insérer
556 un fichier MusicXML qui sera alors traité par @code{musicxml2ly} puis
562 Il suffit, pour inclure de la musique, d'utiliser l'une des instructions
563 suivantes dans votre fichier source@tie{}:
566 <lilypond liste des options>
570 <lilypond liste des options: VOTRE CODE LILYPOND />
572 <lilypondfile liste des options>@var{fichier}</lilypondfile>
574 <musicxmlfile liste des options>@var{fichier}</musicxmlfile>
577 Il suffit, pour inclure de la musique, d'utiliser
580 <lilypond fragment relative=2>
581 \key c \minor c4 es g2
586 @command{lilypond-book} produira alors un fichier HTML contenant les
587 balises d'image pour les fragments de musique@tie{}:
589 @lilypond[fragment,relative=2]
590 \key c \minor c4 es g2
593 Pour insérer l'image au fil du texte, il suffit d'utiliser
594 @code{<lilypond @dots{} />}, tout en séparant options et musique par un
595 caractère deux points, comme ici@tie{}:
598 De la musique <lilypond relative=2: a b c/> au milieu d'une ligne de texte.
601 Lorsque l'inclusion concerne des fichiers indépendants, utilisez
604 <lilypondfile @var{option1} @var{option2} ...>@var{fichier}</lilypondfile>
607 La syntaxe pour @code{>musicXmlfile>} est identique à celle de
608 @code{<lilypondfile>}, à ceci près qu'elle fait référence à un fichier
609 MusicXML plutôt qu'à un fichier LilyPond.
611 Une liste des différentes options utilisables avec les balises
612 @code{lilypond} et @code{lilypondfile} est disponible, à la rubrique
613 @ref{Options applicables aux fragments de musique}.
615 Par ailleurs, la commande @code{<lilypondversion/>} vous permet
616 d'afficher le numéro de version de LilyPond.
618 @cindex titrage et HTML
619 @cindex prévisualisation d'image
625 @translationof DocBook
627 L'inclusion de documents LilyPond ne doit nuire en rien à la conformité
628 du document DocBooK@tie{}; l'utilisation d'éditeurs spécialisés ainsi
629 que d'outils de validation en sera ainsi préservée. C'est la raison
630 pour laquelle nous ne définirons pas de balise spécifique@tie{}; nous
631 respecterons plutôt les conventions des éléments standards de DocBook.
634 @subheading Conventions communes
636 Quel que soit le type d'extrait à inclure, nous utiliserons les
637 éléments @code{mediaobject} et @code{inlinemediaobject}, de telle sorte
638 que ces inclusions soient incorporées directement ou non dans le
639 document final. Les options de formatage des extraits en question sont
640 fournies par la propriété @code{role} de l'élément central -- voir les
641 paragraphes suivants. Les balises sont déterminées de manière à ce que
642 les éditeurs DocBook prennent en charge du mieux possible leur contenu.
643 Les fichiers DocBook destinés à un traitement par
644 @command{lilypond-book} doivent avoir une extension @file{.lyxml}.
647 @subheading Inclusion d'un fichier LilyPond
649 Il s'agit en fait du cas le plus simple. Le fichier à inclure doit
650 avoir une extension @file{.ly} et sera inséré comme n'importe quel
651 @code{imageobject}, en respectant la structure suivante@tie{}:
656 <imagedata fileref="music1.ly" role="printfilename" />
661 Vous pouvez utiliser, en tant que balise externe, aussi bien
662 @code{mediaobject} que @code{inlinemediaobject}.
665 @subheading Inclusion de code LilyPond
667 L'inclusion de code LilyPond se réalise à l'aide d'un
668 @code{programlisting} auquel on associe le langage @code{lilypond}. En
669 voici la syntaxe@tie{}:
674 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
675 \context Staff \with @{
676 \remove Time_signature_engraver
677 \remove Clef_engraver@}
684 Comme vous le remarquez, la balise externe -- qu'il s'agisse d'un
685 @code{mediaobject} ou d'un @code{inlinemediaobject} -- comporte un bloc
686 @code{textobject} qui contiendra le @code{programlisting}.
689 @subheading Génération du document DocBook
691 @command{lilypond-book} génère, à partir d'un fichier @file{.lyxml}, un
692 document DocBook tout à fait valide -- extension @file{.xml} -- que vous
693 pourrez ensuite traiter avec votre application habituelle. Dans le cas
694 de @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, vous
695 obtiendrez alors automatiquement un fichier PDF. Les feuilles de style
696 XSL@tie{}DocBook officielles permettent de générer du HTML (HTML Help,
697 JavaHelp etc.)@tie{}; vous pourriez néanmoins devoir y apporter quelques
701 @node Options applicables aux fragments de musique
702 @section Options applicables aux fragments de musique
703 @translationof Music fragment options
705 Dans les lignes qui suivent, l'appellation @qq{commande LilyPond} fait
706 référence à toutes celles vues plus haut et qui font appel à
707 @command{lilypond-book} pour produire un extrait musical. Pour plus de
708 simplicité, nous ne parlerons que de la syntaxe applicable à @LaTeX{}.
710 Nous attirons votre attention sur le fait que les différentes options
711 sont lues de la gauche vers la droite. Si une option est transmise
712 plusieurs fois, seule la dernière sera prise en compte.
714 Les commandes LilyPond acceptent les options suivantes@tie{}:
717 @item staffsize=@var{hauteur}
718 Définit la taille de portée à @var{hauteur} exprimée en points.
721 Produit des lignes en pleine largeur avec un espacement naturel. En
722 d'autres termes, sera ajoutée la commande de mise en forme
723 @w{@code{ragged-right = ##t}}. Il s'agit de l'option par défaut de la
724 commande @code{\lilypond@{@}} en l'absence d'option @code{line-width}.
725 C'est aussi l'option par défaut pour l'environnement @code{lilypond}
726 lorsque l'option @option{fragment} est activée sans avoir défini
727 explicitement de longueur de ligne.
730 Dans le cas où l'extrait tient sur une seule ligne, la portée sera
731 étirée pour correspondre à la longueur de ligne du texte. Autrement
732 dit, la commande de mise en forme @code{ragged-right = ##f} s'ajoute à
736 @itemx line-width=@var{taille}\@var{unité}
737 Détermine la longueur de ligne à @var{taille}, exprimée en @var{unité}.
738 @var{unité} peut prendre les valeurs @code{cm}, @code{mm}, @code{in} ou
739 @code{pt}. Cette option n'affectera que le résultat de LilyPond -- la
740 longueur de la portée -- et en aucun cas la mise en forme du texte.
742 En l'absence d'argument, la longueur de ligne sera définie à une valeur
743 par défaut telle que calculée par un algoritme heuristique.
745 Lorsque l'option @code{line-width} n'est pas utilisée,
746 @command{lilypond-book} tentera de déterminer des valeurs par défaut
747 pour les cas où les environnements @code{lilypond} ne font pas appel à
748 @option{ragged-right}.
750 @item papersize=@var{chaîne}
751 Détermine le format du papier à @var{chaîne} tel que défini dans le
752 fichier @file{scm/paper.scm} -- @code{a5}, @code{quarto}, @code{11x17},
755 Toute valeur non mentionnée dans @file{scm/paper.scm} sera rejetée.
756 @code{lilypond-book} émettra un message d'avertissement et l'extrait
757 utilisera le format par défaut, à savoir @code{a4}.
760 Désactive l'impression des métriques et barres de mesure pour
761 l'intégralité de la partition.
764 Laisse à @command{lilypond-book} le soin d'ajouter ce qui est
765 indispensable, de telle sorte que vous pouvez vous contenter d'un
772 sans @code{\layout}, @code{\score}, etc.
775 N'ajoute rien à ce qui se trouve dans l'environnement LilyPond. À noter
776 qu'il s'agit de l'option par défaut.
778 @item indent=@var{taille}\@var{unité}
779 Définit l'indentation du premier système à @var{taille}, exprimée en
780 @var{unité} -- @code{cm}, @code{mm}, @code{in} ou @code{pt}. Cette
781 option n'affecte que LilyPond, et en aucun cas la mise en forme du
785 Ramène l'indentation du premier système à zéro. Cette option n'affecte
786 que LilyPond, et en aucun cas la mise en forme du texte. Dans la mesure
787 où il s'agit du comportement par défaut, point n'est besoin de spécifier
791 Réduit la longueur des lignes musicales de @math{2*0.4}@dmn{in} (soit
792 @math{2 * 10,16}@tie{}@dmn{mm}) pour renvoyer l'extrait dans un bloc de
793 citation. La valeur @qq{0,4@tie{}pouce} est contrôlée par l'option
794 @option{exampleindent}.
797 Détermine la valeur de l'indentation qui sera utilisée par l'option
801 @itemx relative=@var{n}
802 Utilise le mode d'octave relative. Les notes sont donc par défaut
803 positionnées relativement au do central. L'argument -- un nombre entier
804 -- fourni à l'option @code{relative} spécifie l'octave de départ de
805 l'extrait@tie{}; @code{1} correspond au do central. Cette option
806 @option{relative} n'a d'effet que si elle est utilisée en combinaison
807 avec l'option @option{fragment}@tie{}; autrement dit, l'option
808 @option{fragment} est implicite dès lors que @code{relative} est
813 La documentation de LilyPond, comme nous l'avons déjà vu, use
814 abondamment de @command{lilypond-book}. Elle utilise à cet effet
815 quelques options particulières.
819 L'argument de la commande LilyPond est recopié textuellement dans le
820 fichier généré, avant l'image de la partition. Cependant, cette option
821 n'est pas pleinement opérationnelle lorsqu'un @code{\lilypond@{@}} se
822 trouve au milieu d'un paragraphe.
824 L'utilisation conjointe d'un @option{verbatim} et de la commande
825 @code{lilypondfile} permet de n'inclure textuellement qu'une seule
826 partie du fichier source. @code{lilypond-book} reproduira alors
827 textuellement la partie du fichier source comprise entre les
828 commentaires @code{begin@tie{}verbatim} et éventuellement
829 @code{end@tie{}verbatim}. Si l'on considère le fichier source suivant,
830 la musique sera interprétée en mode relatif, mais la recopie du code ne
831 comportera pas l'assertion du bloc @code{relative}@tie{}:
834 \relative c' @{ % begin verbatim
841 donnera dans un bloc @emph{verbatim} précédant la partition@tie{}:
849 Si d'aventure vous désirez traduire les commentaires et noms de
850 variable dans le rendu textuel plutôt que dans le fichier source, vous
851 devrez définir la variable d'environnement @code{LYDOC_LOCALEDIR} qui
852 pointera vers un répertoire contenant l'arborescence des catalogues de
853 messages -- fichiers d'extension @code{.mo} -- du domaine
857 Cette option, effective uniquement avec Texinfo, permet d'ajouter une
858 ligne @code{\version @@w@{"@@version@{@}"@}} au @code{verbatim}.
861 Option disponible uniquement avec Texinfo.@*
862 Dès lors qu'un fichier @file{toto.ly} contient dans sa section
863 @code{\header} un champ @code{texidoc}, l'appel de @command{lilypond}
864 avec l'option @option{--header=@/texidoc} créera le fichier
865 @file{toto.texidoc}. Par ailleurs, c'est le contenu de ce
866 @file{toto.texidoc} qui sera ensuite recopié par
867 @command{lilypond-book} en préambule de l'extrait de partition -- soit
868 avant l'environnement @code{example} créé par un @code{quote}.
870 Prenons par exemple le fichier @file{toto.ly} dont le contenu est
874 texidoc = "This file demonstrates a single note."
880 et quelque part dans notre document Texinfo @file{test.texinfo}
883 @@lilypondfile[texidoc]@{toto.ly@}
887 La ligne de commande suivante produira le résultat escompté.
890 lilypond-book --pdf --process="lilypond \
891 -dbackend=eps --header=texidoc" test.texinfo
894 La plupart des fichiers de test contenus dans le répertoire @file{input}
895 de la distribution est constituée de la sorte.
897 Cette option est fort utile dans le cadre de l'adaptation en langue
898 étrangère. En effet, s'il est spécifié dans le document Texinfo une
899 clause @code{@@documentlanguage@tie{}@var{LANGUE}}, la présence d'une
900 variable @code{texidoc@var{LANGUE}} dans l'entête du fichier
901 @file{toto.ly} entraînera la reproduction -- par l'appel
902 @code{lilypond}@tie{}@option{--header=@/texidoc@var{LANGUE}} -- du
903 contenu de @file{toto.texidoc@var{LANGUE}} en lieu et place de celui de
907 Option disponible uniquement avec Texinfo.@*
908 Cette option fonctionne selon le même principe que l'option
909 @code{texidoc}@tie{}: lorsqu'un fichier @file{toto.ly} contient dans
910 son @code{\header} une variable @code{doctitle} et que @code{lilypond}
911 est appelé avec l'option @code{doctitle}, le contenu de cette variable
912 -- une simple ligne de @var{texte} -- sera recopié dans un fichier
913 @file{toto.doctitle} puis inséré dans le document Texinfo sous la
914 forme @code{@@lydoctitle@tie{}@var{texte}}. @code{@@lydoctitle} doit
915 faire l'objet d'une macro, définie dans le document Texinfo.
917 Il en va de l'option @code{doctitle} comme de l'option @code{texidoc} en
918 matière d'adaptation en langue étrangère.
921 Option disponible uniquement pour Texinfo.@*
922 Commentaires et noms de variable ne seront pas traduits dans la recopie
926 Lorsqu'un fichier source LilyPond est inclus à l'aide de
927 @code{\lilypondfile}, le nom du fichier sera reproduit juste au dessus
928 de l'extrait. Si le résultat est un fichier HTML, il s'agira alors d'un
929 lien. Seul le nom du fichier est imprimé@tie{}; autrement dit, le
930 chemin d'accès au fichier est tronqué.
935 @node Utilisation de lilypond-book
936 @section Utilisation de @command{lilypond-book}
937 @translationof Invoking lilypond-book
939 @command{lilypond-book} produit un fichier qui aura, selon le format de
940 sortie spécifié, l'extension @file{.tex}, @file{.texi}, @file{.html} ou
941 @file{.xml}. Les fichiers @file{.tex}, @file{.texi} et @file{.xml}
942 nécessitent un traitement complémentaire.
945 @subheading Instructions spécifiques à certains formats
948 @subsubheading @LaTeX{}
950 Un document @LaTeX{} destiné à l'impression ou à la publication peut se
951 traiter de deux manières différentes@tie{}: générer directement un PDF
952 à l'aide de PDF@LaTeX{}, ou bien générer un fichier avec @LaTeX{}
953 qui sera ensuite passé à un traducteur DVI-PostScript comme
954 @command{dvips}. La première façon est de loin la plus simple et c'est
955 celle que nous vous recommandons@footnote{Sachant que vous ne disposez
956 pas forcément de PDF@LaTeX{} et @LaTeX{} pour compiler un document
957 @LaTeX{}, nous vous présentons les deux méthodes.}@tie{}; quelque soit
958 votre préférence, sachez que vous pouvez aller du PostScript au PDF avec
959 des outils tels que @command{ps2pdf} et @command{pdf2ps} -- tous deux
960 inclus dans la distribution de Ghostscript.
962 La production d'un PDF avec PDF@LaTeX{} se fait en lançant les commandes
965 lilypond-book --pdf monfichier.lytex
966 pdflatex monfichier.tex
969 @cindex type1, polices
971 @cindex utilisation de dvips
973 La séquence @LaTeX{}/@command{dvips}/@command{ps2pdf} suivante permet de
974 produire un PDF@tie{}:
977 lilypond-book monfichier.lytex
979 dvips -Ppdf monfichier.dvi
984 Le fichier @file{.dvi} généré lors de ce traitement ne contient aucune
985 tête de note, ce qui est tout à fait normal@tie{}; elles seront incluses
986 lors de la génération du @file{.ps} puis dans le @file{.pdf}.
988 La commande @command{dvips} peut déclencher certains messages concernant
989 des fontes, que vous pouvez ignorer sans scrupule.@*
990 Si vous utilisez @command{latex} en mode colonnage, n'oubliez pas
991 d'ajouter @option{-t@tie{}landscape} aux options de @command{dvips}.
994 La commande @code{\pageBreak} est inopérante dans un environnement
995 @code{\begin@{lilypond@} @dots{} \end@{lilypond@}}.
997 Il en va de même pour un certain nombre de variables appartenant au bloc
998 @code{\paper}. Utilisez, entre autres, un @code{\newcommand} avec la
999 macrocommande @code{\betweenLilyPondSystem} dans le préambule.
1002 \newcommand@{\betweenLilyPondSystem@}[1]@{\vspace@{36mm@}\linebreak@}
1006 @subsubheading Texinfo
1008 La génération d'un document Texinfo -- quel que soit le format final --
1009 s'obtient grâce aux commandes Texinfo habituelles, c'est à dire
1010 @command{texi2pdf}, @command{texi2dvi} ou @command{makeinfo} selon le
1011 résultat que vous désirez obtenir.
1013 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, et
1014 @ref{Creating an Info File, , , texinfo, GNU Texinfo}.
1017 Pour plus de détails, consultez la documentation de Texinfo.
1021 @subheading Options en ligne de commande
1023 @command{lilypond-book} accepte les options suivantes@tie{}:
1026 @item -f @var{format}
1027 @itemx --format=@var{format}
1028 Spécifie le type de document à traiter@tie{}: @code{html}, @code{latex},
1029 @code{texi} (valeur par défaut) ou @code{docbook}. Lorsque cette
1030 option n'est pas mentionnée, @command{lilypond-book} tente de déterminer
1031 automatiquement le format -- voir @ref{Extensions de nom de fichier}. À
1032 l'heure actuelle, @code{texi} est équivalant à @code{texi-html}.
1034 @c This complicated detail is not implemented, comment it out -jm
1036 The @code{texi} document type produces a Texinfo file with music
1037 fragments in the printed output only. For getting images in the HTML
1038 version, the format @code{texi-html} must be used instead.
1041 @item -F @var{filtre}
1042 @itemx --filter=@var{filtre}
1043 Passe les extrait au travers de @var{filtre} avant de traiter le
1044 fichier. Cette option permet de, par exemple, appliquer les mises à
1045 jour de LilyPond aux extraits avant de traiter le fichier@tie{}:
1048 lilypond-book --filter='convert-ly --from=2.0.0 -' mon-book.tely
1053 Affiche un bref résumé des options.
1056 @itemx --include=@var{répertoire}
1057 Ajoute @var{répertoire} au chemin des inclusions. Si des extraits ont
1058 déjà été compilés dans l'un des répertoires inclus,
1059 @command{lilypond-book} ne les rééecria pas dans le répertoire de
1060 sortie@tie{}; il sera donc nécessaire, dans la suite du traitement par
1061 @command{makeinfo} ou @command{latex}, de penser à utiliser cette même
1062 option @code{-I@tie{}@var{répertoire}}.
1064 @item -l @var{loglevel}
1065 @itemx --loglevel=@var{loglevel}
1066 Détermine le degré de verbosité à @var{loglevel}. Les différentes
1067 valeurs admises sont @code{NONE}, @code{ERROR}, @code{WARNING},
1068 @code{PROGRESS} (par défaut) et @code{DEBUG}. Lorsque cette option n'est
1069 pas activée, c'est le niveau déterminé par la variable d'environnement
1070 @code{LILYPOND_BOOK_LOGLEVEL} qui sera utilisé.
1073 @itemx --output=@var{répertoire}
1074 Regroupe les fichiers générés dans @var{répetoire}.
1075 @command{lilypond-book} crée un certain nombre de fichiers à l'usage de
1076 LilyPond. Afin d'éviter de polluer votre répertoire source, nous vous
1077 conseillons d'utiliser l'option @option{--output}, puis de vous rendre
1078 dans ce répertoire pour y lancer les commandes @command{latex} ou
1082 lilypond-book --output=out monfichier.lytex
1087 @itemx --skip-lily-check
1088 Désactive la mise en échec en l'absence de sortie de lilypond.@*
1089 Option utilisée pour la documentation au format Info sans images.
1091 @itemx --skip-png-check
1092 Désactive la mise en échec en l'absence d'images PNG correspondant aux
1094 Option utilisée pour la documentation au format Info sans images.
1096 @itemx --lily-output-dir=@var{rép}
1097 Écrit les fichiers lily-XXX dans @var{rép} et crée un lien vers le
1098 répertoire spécifié par @code{--output}. Cette option permet
1099 d'économiser du temps lors de la génération de documents qui se trouvent
1100 dans différents répertoires et partagent un certain nombre d'extraits
1103 @itemx --lily-loglevel=@var{loglevel}
1104 Détermine le degré de verbosité lors des appels à @command{lilypond}.
1105 Les valeurs autorisée de @var{loglevel} sont@tie{}: @code{NONE},
1106 @code{ERROR}, @code{WARNING}, @code{BASIC_PROGRESS}, @code{PROGRESS},
1107 @code{INFO} (par défaut) et @code{DEBUG}. Lorsque cette option n'est
1108 pas activée, c'est le niveau déterminé par la variable d'environnement
1109 @code{LILYPOND_LOGLEVEL} qui sera utilisé.
1111 @itemx --info-images-dir=@var{répertoire}
1112 Formate la sortie Texinfo de telle sorte que Info cherche les images
1113 de musique dans @var{répertoire}.
1115 @itemx --latex-program=@var{programme}
1116 Utilise l'exécutable @command{programme} en lieu et place de
1117 @command{latex}. C'est l'option que vous utiliserez si vous préférez
1118 @command{xelatex} par exemple.
1120 @itemx --left-padding=@var{distance}
1121 Décale les figures EPS de @var{distance} -- exprimée en milimètres (3
1122 par défaut). Cette option est utile lorsque les lignes de musique
1123 débordent sur la marge droite.
1125 Rappelez-vous que la largeur d'un système dépend des élément contenus
1126 dans sa marge gauche, tels que numéro de mesure et nom d'instrument.
1127 Cette option permet de @qq{raccourcir} les lignes et de les décaler vers
1128 la droite, de la distance donnée en argument.
1130 @item -P @var{commande}
1131 @itemx --process=@var{commande}
1132 Traite les extraits LilyPond avec @var{commande}. Par défaut, il s'agit
1133 de @code{lilypond}.@*
1134 Rappelez-vous que @code{lilypond-book} ne peut en même temps traiter
1135 l'option @option{--filter} et l'option @option{--process}.
1138 Crée des fichiers PDF pour les retraiter avec PDF@LaTeX{}.
1140 @item --redirect-lilypond-output
1141 Le résultat des commandes est habituellement affiché dans le terminal.
1142 Cette option permet de rediriger tout le verbiage dans un journal situé
1143 dans le même répertoire que le fichier source.
1145 @itemx --use-source-file-names
1146 Cette option permet d'affecter aux fichiers correspondant aux extraits
1147 de musique le même nom que leur source. Elle n'est fonctionnelle que
1148 dans le cas où la partition est incluse à l'aide de @code{lilypondfile},
1149 et que les répertoires mentionnés par les options @code{--output-dir} et
1150 @code{--lily-output-dir} diffèrent.
1154 @command{lilypond-book} sait être volubile@tie{}! Cette option est
1155 éqivalente à @code{--loglevel=DEBUG}.
1159 Affiche le numéro de version.
1165 @code{lilypond-book} ne sait pas interpréter la commande Texinfo
1166 @code{@@pagesize}. Dans le même ordre d'idée, des commandes @LaTeX{}
1167 modifiant les marges et longueur de ligne mentionnées après le préambule
1170 Lorsqu'une section LilyPond contient plusieurs @code{\score}, seul le
1171 premier sera traité.
1174 @node Extensions de nom de fichier
1175 @section Extensions de nom de fichier
1176 @translationof Filename extensions
1178 Vous pouvez affecter à votre fichier source n'importe quelle extension.
1179 Nous vous recommandons cependant un certain nombre d'extensions selon le
1180 format de sortie désiré -- voir @ref{Utilisation de lilypond-book}. Une
1181 extension hors du commun vous obligera à spécifier le format de sortie,
1182 alors que @code{lilpond-book} est en mesure de déterminer le format de
1183 sortie en fonction de l'extension du fichier source.
1186 @multitable @columnfractions .2 .5
1187 @item @strong{extension} @tab @strong{format résultant}
1189 @item @file{.html} @tab HTML
1190 @item @file{.htmly} @tab HTML
1191 @item @file{.itely} @tab Texinfo
1192 @item @file{.latex} @tab @LaTeX{}
1193 @item @file{.lytex} @tab @LaTeX{}
1194 @item @file{.lyxml} @tab DocBook
1195 @item @file{.tely} @tab Texinfo
1196 @item @file{.tex} @tab @LaTeX{}
1197 @item @file{.texi} @tab Texinfo
1198 @item @file{.texinfo} @tab Texinfo
1199 @item @file{.xml} @tab HTML
1203 Lorsque le fichier source a la même extension que celle que
1204 @code{lilypond-book} affectera au fichier résultant et que vous
1205 lancez @code{lilypond-book} à partir du répertoire le contenant, vous
1206 verrez assurément un message du type @qq{La sortie va écraser le fichier
1207 d'entrée}. Aussi ne saurions-nous trop vous conseiller d'utiliser
1208 l'option @option{--output}.
1211 @node Modèles pour lilypond-book
1212 @section Modèles pour lilypond-book
1213 @translationof lilypond-book templates
1215 Voici quelques canevas dédiés à @code{lilypond-book}. Si vous ne savez
1216 pas de quoi il retourne, lisez le chapitre @ref{lilypond-book}.
1219 @subsection @LaTeX{}
1221 Vous pouvez inclure des partitions LilyPond dans un document LaTeX.
1224 \documentclass[]@{article@}
1228 Des bananes alitées sur du LaTeX.
1236 Encore des banalités LaTeX, puis quelques options entre crochets.
1238 \begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
1247 Un document Texinfo est tout à fait capable de comporter des fragments
1248 de partition LilyPond. Si vous ne le savez pas encore, sachez que
1249 l'intégralité de ce manuel est rédigée en Texinfo.
1252 \input texinfo @c -*-texinfo-*-
1256 Du verbiage à la mode Texinfo
1264 Toujours plus de texte Texinfo, puis des options entre crochets.
1266 @@lilypond[verbatim,fragment,ragged-right]
1277 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1283 Un document pour lilypond-book peut absolument mélanger musique et
1293 Pourquoi pas un peu plus de lilypond, avec des options pour changer :
1295 <lilypond fragment quote staffsize=26 verbatim>
1310 \documentclass{article}
1311 \usepackage{ifxetex}
1313 %pour ce qui est de xetex
1314 \usepackage{xunicode,fontspec,xltxtra}
1315 \setmainfont[Numbers=OldStyle]{Times New Roman}
1318 %inutile en l'absence de pdftex
1319 \usepackage[T1]{fontenc}
1320 \usepackage[utf8]{inputenc}
1321 \usepackage{mathptmx}%Times
1322 \usepackage{helvet}%Helvetica
1324 %ici les paquetages que pdftex sait interpréter
1325 \usepackage[ngerman,finnish,english]{babel}
1326 \usepackage{graphicx}
1329 \title{Un petit document avec LilyPond et xelatex}
1332 Les commandes habituelles de \textbf{fontes} sont fonctionnelles y
1333 compris au fil du texte, étant donné qu'\textsf{elles sont prises en
1334 charge par \LaTeX{} and XeteX.} Lorsque vous avez besoin de commandes
1335 particulières du style \verb+\XeTeX+, pensez à les inclure dans un
1336 environnement \verb+\ifxetex+. Vous pourrez ainsi utiliser la \ifxetex
1337 commande \XeTeX{} \else commande XeTeX \fi qui, elle, n'est pas reconnue
1338 par le \LaTeX traditionnel.
1340 Vous pouvez inclure des commandes LilyPond directement dans votre texte,
1348 puis reprendre le fil de votre discours.
1350 Les fontes utilisées dans les extraits LilyPond devront être définies
1351 au sein de l'extrait. Lisez le manuel d'ustilisation si vous ne
1352 maîtrisez pas lilypond-book.
1354 \selectlanguage{ngerman}
1355 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle anderen
1356 seltsamen Zeichen: ß, æ, ł, ã, č, wenn sie von der Schriftart unterstützt
1363 @node Gestion de la table des matières
1364 @section Gestion de la table des matières
1365 @translationof Sharing the table of contents
1367 Les fonctions ici mentionnées sont incluses dans le paquetage
1368 OrchestralLily, disponible sur
1371 @url{http://repo.or.cz/w/orchestrallily.git}
1374 Certains utilisateurs privilégient la flexibilité dans la gestion du
1375 texte@tie{}; ils génèrent la table des matières à partir de LilyPond et
1376 la récupèrent dans @LaTeX{}.
1379 @subsubheading Export de la table à partir de LilyPond
1381 Nous partons du principe que LilyPond a généré un seul fichier
1382 comportant tous les mouvement de la partition.
1385 #(define (oly:create-toc-file layout pages)
1386 (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
1387 (if (not (null? label-table))
1388 (let* ((format-line (lambda (toc-item)
1389 (let* ((label (car toc-item))
1390 (text (caddr toc-item))
1391 (label-page (and (list? label-table)
1392 (assoc label label-table)))
1393 (page (and label-page (cdr label-page))))
1394 (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
1395 (formatted-toc-items (map format-line (toc-items)))
1396 (whole-string (string-join formatted-toc-items ",\n"))
1397 (output-name (ly:parser-output-name parser))
1398 (outfilename (format "~a.toc" output-name))
1399 (outfile (open-output-file outfilename)))
1400 (if (output-port? outfile)
1401 (display whole-string outfile)
1402 (ly:warning (_ "Impossible d'ouvrir le fichier ~a contenant les informations de TdM") outfilename))
1403 (close-output-port outfile)))))
1406 #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
1411 @subsubheading Import de la table dans @LaTeX{}
1413 L'entête de votre fichier @LaTeX{} doit comporter les lignes
1415 @c no, this doesn't require the smallexample, but since the other
1416 @c two blocks on this page use it, I figured I might as well
1417 @c user it here as well, for consistency. -gp
1419 \usepackage@{pdfpages@}
1420 \includescore@{nomdelapartition@}
1424 où @code{\includescore} est défini ainsi@tie{}:
1427 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1428 % \includescore@{PossibleExtension@}
1429 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1431 % Read in the TOC entries for a PDF file from the corresponding .toc file.
1432 % This requires some heave latex tweaking, since reading in things from a file
1433 % and inserting it into the arguments of a macro is not (easily) possible
1435 % Solution by Patrick Fimml on #latex on April 18, 2009:
1436 % \readfile@{filename@}@{\variable@}
1437 % reads in the contents of the file into \variable (undefined if file
1439 \newread\readfile@@f
1440 \def\readfile@@line#1@{%
1441 @{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
1442 \edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
1443 \ifeof\readfile@@f\else%
1444 \readfile@@line@{#1@}%
1447 \def\readfile#1#2@{%
1448 \openin\readfile@@f=#1 %
1450 \typeout@{No TOC file #1 available!@}%
1453 \readfile@@line@{#2@}%
1455 \closein\readfile@@f%
1459 \newcommand@{\includescore@}[1]@{
1460 \def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
1461 \let\oly@@addtotoc\undefined
1462 \readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
1463 \ifx\oly@@addtotoc\undefined
1464 \includepdf[pages=-]@{\oly@@fname@}
1466 \edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
1467 @{\oly@@fname@}@}\includeit
1473 @node Autres méthodes d'association texte-musique
1474 @section Autres méthodes d'association texte-musique
1475 @translationof Alternate methods of mixing text and music
1477 D'autres moyens de mélanger musique et texte sans recourir à
1478 @command{lilypond-book} sont abordés au chapitre
1479 @ref{Inclusion de partition LilyPond dans d'autres programmes}.