Docs: run convert-ly for 2.14.0.

[lilypond.git] / Documentation / fr / usage / lilypond-book.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-

@ignore
    Translation of GIT committish: 8e1f0e01b3665bfd8e53ef646ad8fd627d09a41b

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore


@c \version "2.14.0"

@c Translators: Jean-Charles Malahieude
@c Translation checkers:

@c Note: keep this node named so that `info lilypond-book' brings you here.
@node lilypond-book
@chapter Association musique-texte avec @command{lilypond-book}
@translationof lilypond-book

Vous pouvez inclure des partitions dans un document tout comme vous
feriez pour n'importe quelle image.  Ces images sont générées séparément
-- que ce soit sous forme de description PostScript ou au format PNG --
puis incluses dans votre document @LaTeX{} ou HTML.

@command{lilypond-book} permet d'automatiser ces opérations@tie{}: le
programme extrait de votre document les fragments de musique, les
traite grâce à @command{lilypond} puis en restitue la partition dans
votre document.  Largeur de ligne et taille de la fonte sont adaptées
pour correspondre à la mise en forme de votre document.

@command{lilypond-book} est un script indépendant de @command{lilypond}
et se lance en ligne de commande -- pour plus de précisions, consultez
@ref{Utilisation en ligne de commande}.  Si vous utilisez MacOS 10.3 ou
10.4 et rencontrez quelque difficulté avec @code{lilypond-book},
référez-vous à @rwebnamed{MacOS X,cette page}.

@command{lilypond-book} s'applique aux documents @LaTeX{}, HTML, Texinfo
et DocBook.

@cindex texinfo
@cindex latex
@cindex texinfo
@cindex texi
@cindex html
@cindex docbook
@cindex documents, ajout de musique
@cindex HTML, musique et
@cindex Texinfo, musique et
@cindex DocBook, musique et
@cindex @LaTeX{}, musique et


@menu
* Exemple de document musicologique::
* Association musique-texte::
* Options applicables aux fragments de musique::
* Utilisation de lilypond-book::
* Extensions de nom de fichier::
* Modèles pour lilypond-book::
* Gestion de la table des matières::
* Autres méthodes d'association texte-musique::
@end menu


@node Exemple de document musicologique
@section Exemple de document musicologique
@translationof An example of a musicological document

@cindex musicologie

Un certain nombre d'ouvrages peuvent être illustrés par des extraits
musicaux, qu'il s'agisse d'un taité de musicologie, d'un carnet de chant
ou d'un manuel à l'exemple de celui que vous consultez actuellement.
Cet agencement peut se faire @qq{à la main} par importation d'un
graphique PostScript dans le traitement de texte.  Les développeurs de
LilyPond ont cependant créé un outil permettant d'automatiser ces
opérations pour ce qui concerne les documents HTML, @LaTeX{}, Texinfo et
DocBook.

Un script -- @code{lilypond-book} -- se charge d'extraire les fragments
de musique, puis de les mettre en forme avant de renvoyer la
@qq{partition} correspondante.  Voici un court exemple utilisable avec
@LaTeX{}.  Dans la mesure où il est suffisamment parlant, nous nous
abstiendrons de le commenter.


@subheading Fichier d'entrée
@translationof Input

@quotation
@verbatim
\documentclass[a4paper]{article}

\begin{document}

Un document destiné à être traité par \verb+lilypond-book+ peut tout à
fait mélanger de la musique et du texte.
Par exemple,

\begin{lilypond}
\relative c' {
  c2 e2 \times 2/3 { f8 a b } a2 e4
}
\end{lilypond}

Les options sont indiquées entre crochets.

\begin{lilypond}[fragment,quote,staffsize=26,verbatim]
  c'4 f16
\end{lilypond}

Des extraits plus conséquents peuvent faire l'objet d'un fichier
indépendant, alors inclus avec \verb+\lilypondfile+.

\lilypondfile[quote,noindent]{screech-boink.ly}

(Si besoin, remplacez @file{screech-boink.ly} par
n'importe quel fichier @file{.ly} qui se trouve dans
le même répertoire que le présent fichier.)

\end{document}
@end verbatim
@end quotation


@subheading Traitement
@translationof Processing

Enregistrez ces lignes dans un fichier nommé @file{lilybook.lytex} puis,
dans un terminal, lancez

@c keep space after @version{} so TeX doesn't choke
@example
lilypond-book --output=out --pdf lilybook.lytex
@emph{lilypond-book (GNU LilyPond) @version{} }
@emph{Lecture de lilybook.lytex...}
@emph{..nous vous épargnons le verbiage de la console..}
@emph{Compilation de lilybook.tex...}
cd out
pdflatex lilybook
@emph{..nous vous épargnons le verbiage de la console..}
xpdf lilybook
@emph{(remplacez @command{xpdf} par votre lecteur de PDF habituel)}
@end example

Le traitement par @command{lilypond-book} puis @command{latex} va
générer un certain nombre de fichiers temporaires susceptibles
d'encombrer inutilement votre répertoire de travail, aussi nous vous
recommandons d'utiliser l'option @code{--output=@var{répertoire}} afin
que les fichiers créés soient isolés dans le sous-répertoire
@file{répertoire}.

Pour terminer, voici le résultat de cet exemple pour
@LaTeX{}.@footnote{Ce manuel étant réalisé avec Texinfo, il se peut que
la mise en forme diverge quelque peu.}


@page

@subheading Résultat
@translationof Output

Un document destiné à être traité par @command{lilypond-book} peut tout à
fait mélanger de la musique et du texte.
Par exemple,

@lilypond
\relative c' {
  c2 e2 \times 2/3 { f8 a b } a2 e4
}
@end lilypond

Les options sont indiquées entre crochets.

@lilypond[fragment,quote,staffsize=26,verbatim]
c'4 f16
@end lilypond

Des extraits plus conséquents peuvent faire l'objet d'un fichier
indépendant, alors inclus avec @code{\lilypondfile}.

@lilypondfile[quote,noindent]{screech-boink.ly}


@page

@node Association musique-texte
@section Association musique-texte
@translationof Integrating music and text

Nous allons nous intéresser, dans les lignes qui suivent, à la manière
d'intégrer LilyPond selon différents types de format.

@menu
* LaTeX::
* Texinfo::
* HTML::
* DocBook::
@end menu


@node LaTeX
@subsection @LaTeX{}
@translationof LaTeX

@LaTeX{} peut être considéré comme le standard de publication dans le
domaine des sciences exactes.  Il repose sur le moteur typographique
@TeX{}, le @emph{nec plus ultra} en la matière.

Consultez
@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/french/,
@emph{The Not So Short Introduction to @LaTeX{}} en français} pour un
aperçu des possibilités de @LaTeX{}.

Il suffit, pour inclure de la musique, d'utiliser

@example
\begin@{lilypond@}[liste,des,options]
  VOTRE CODE LILYPOND
\end@{lilypond@}
@end example

@noindent
ou

@example
\lilypondfile[liste,des,options]@{@var{fichier}@}
@end example

@noindent
ou encore

@example
\lilypond[liste,des,options]@{ VOTRE CODE LILYPOND @}
@end example

Par ailleurs, la commande @code{\lilypondversion} vous permet d'afficher
le numéro de version de LilyPond.
Lancer @command{lilypond-book} produira un fichier qui sera ensuite
traité par @LaTeX{}.

Voici quelques exemples.  L'environnement @code{lilypond}

@example
\begin@{lilypond@}[quote,fragment,staffsize=26]
  c' d' e' f' g'2 g'2
\end@{lilypond@}
@end example

@noindent
produit

@lilypond[quote,fragment,staffsize=26]
c' d' e' f' g'2 g'2
@end lilypond

La version abrégée

@example
\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
@end example

@noindent
produit

@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}

@noindent
Dans l'état actuel des choses, il n'est pas possible d'inclure des
accolades -- @code{@{} ou @code{@}} -- dans un
@code{\lilypond@{@}}@tie{}; cette commande n'est donc pertinente que
lorsque conjuguée à l'option @code{fragment}.

La longueur par défaut des portées sera ajustée en fonction des
commandes contenues dans le préambule du document -- ce qui précède la
ligne @code{\begin@{document@}}.  La commande @code{lilypond-book} les
transmet à @LaTeX{} afin de connaître la largeur du texte, et par voie
de conséquence déterminer la longueur des portées.  Notez bien que cet
algorithme heuristique n'est pas infaillible@tie{}; vous devrez alors
recourir à l'option @code{line-width}.

@cindex titrage et lilypond-book
@cindex \header et documents @LaTeX{}

Dès lors qu'elles auront été définies dans votre document, les macros
suivantes seront appelées avant chaque extrait musical@tie{}:

@itemize @bullet
@item @code{\preLilyPondExample} avant la musique,

@item @code{\postLilyPondExample} après la musique,

@item @code{\betweenLilyPondSystem[1]} entre les systèmes, si tant est
que @code{lilypond-book} a découpé la partition en plusieurs fichiers
PostScript.  Elle requiert un paramètre et reçoit le nombre de fichiers
inclus dans l'extrait.  Par défaut, elle insert simplement un
@code{\linebreak}.
@end itemize

@ignore
Broken stuff.  :(

@cindex Latex, feta symbols
@cindex fetachar

To include feta symbols (such as flat, segno, etc) in a LaTeX
document, use @code{\input@{titledefs@}}

@example
\documentclass[a4paper]@{article@}

\input@{titledefs@}

\begin@{document@}

\fetachar\fetasharp

\end@{document@}
@end example

The font symbol names are defined in the file feta20.tex; to find
the location of this file, use the command

@example
kpsewhich feta20.tex
@end example

@end ignore

@snippets

Lorsque, pour les besoins de la démonstration, certains éléments
musicaux tels que des liaisons -- de phrasé ou de prolongation --
continuent après le fragment qui vous intéresse, il suffit d'insérer un
saut de ligne et de limiter le nombre de systèmes à inclure.

En ce qui concerne @LaTeX{}, vous devrez définir
@code{\betweenLilyPondSystem} de telle sorte que l'inclusion cesse dès
que le nombre de systèmes requis est atteint.  Dans la mesure où
@code{\betweenLilyPondSystem} n'est appelé qu'@strong{après} le premier
système, inclure un seul système est un jeu d'enfant@tie{}:

@example
\def\betweenLilyPondSystem#1@{\endinput@}

\begin@{lilypond@}[fragment]
  c'1\( e'( c'~ \break c' d) e f\)
\end@{lilypond@}
@end example

Pour un plus grand nombre de systèmes, il suffit d'insérer un test
conditionnel @TeX{} avant le @code{\endinput}.  À partir de l'exemple
qui suit, remplacez le @qq{2} par le nombre de systèmes dont vous aurez
besoin@tie{}:

@example
\def\betweenLilyPondSystem#1@{
    \ifnum##1<2\else\expandafter\endinput\fi
@}
@end example

@noindent
Étant donné que @code{\endinput} arrête immédiatement le traitement du
fichier source en cours, l'insertion du @code{\expandafter} permet de
repousser ce @code{\endinput} après le @code{\fi}@tie{}; la clause
@w{@code{\if-\fi}} sera alors respectée.

Gardez à l'esprit que @code{\betweenLilyPondSystem} est effectif tant
que @TeX{} n'est pas sorti du groupe en cours -- tel que
l'environnement @LaTeX{} -- ou écrasé par une nouvelle définition pour
la suite du document la plupart du temps.  Pour réinitialiser cette
définition, insérez

@example
\let\betweenLilyPondSystem\undefined
@end example

@noindent
dans votre document @LaTeX{}.

La création d'une macro @TeX{} permet de se simplifier la vie@tie{}:

@example
\def\onlyFirstNSystems#1@{
    \def\betweenLilyPondSystem##1@{%
      \ifnum##1<#1\else\expandafter\endinput\fi@}
@}
@end example

@noindent
Il suffit alors, avant chacun des fragments à inclure, de spécifier le
nombre de systèmes requis@tie{}:

@example
\onlyFirstNSystems@{3@}
\begin@{lilypond@}...\end@{lilypond@}
\onlyFirstNSystems@{1@}
\begin@{lilypond@}...\end@{lilypond@}
@end example


@seealso
@command{lilypond-book} dispose d'options en ligne de commande
particulières.  Elles sont consultables, ainsi que d'autres détails
spécifiques au traitement de documents @LaTeX{}, au chapitre
@ref{Utilisation de lilypond-book}.


@node Texinfo
@subsection Texinfo
@translationof Texinfo

Texinfo est le format standard pour toute la documentation du projet
GNU.  À titre d'exemple, toute la documentation de LilyPond -- qu'il
s'agisse des versions HTML, PDF ou info -- est générée à partir de
documents Texinfo.

Dans le fichier source, on spécifie qu'il s'agit de musique avec

@example
@@lilypond[liste,des,options]
  VOTRE CODE LILYPOND
@@end lilypond
@end example

@noindent
ou

@example
@@lilypond[liste,des,options]@{ VOTRE CODE LILYPOND @}
@end example

@noindent
ou bien encore

@example
@@lilypondfile[liste,des,options]@{@var{fichier}@}
@end example

Par ailleurs, l'utilisation d'un @code{@@lilypondversion} permet
d'afficher la version de LilyPond utilisée.

Le traitement du fichier source par @command{lilypond-book} génère un
fichier Texinfo (extension @file{.itexi}) qui contiendra les balises
@code{@@image} pour les formats HTML, Info ou imprimable.  Les images
générées par @command{lilypond-book} sont au format EPS et PDF en vue
d'une impression, et au format PNG pour leur utilisation en HTML ou
Info.

En voici deux exemples.  Un environnement @code{lilypond}

@example
@@lilypond[fragment]
c' d' e' f' g'2 g'
@@end lilypond
@end example

@noindent
produit

@lilypond[fragment]
c' d' e' f' g'2 g'
@end lilypond

La version abrégée

@example
@@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
@end example

@noindent
produit

@lilypond[fragment,staffsize=11]{<c' e' g'>}

Contrairement à @LaTeX{}, @code{@@lilypond@{@dots{}@}} ne va pas
intégrer d'image dans le document, mais générer un paragraphe.


@node HTML
@subsection HTML
@translationof HTML

Il suffit, pour inclure de la musique, d'utiliser

@example
<lilypond fragment relative=2>
\key c \minor c4 es g2
</lilypond>
@end example

@noindent
@command{lilypond-book} produira alors un fichier HTML contenant les
balises d'image pour les fragments de musique@tie{}:

@lilypond[fragment,relative=2]
\key c \minor c4 es g2
@end lilypond

Pour insérer l'image au fil du texte, il suffit d'utiliser
@code{<lilypond @dots{} />}, tout en séparant options et musique par un
caractère deux points, comme ici@tie{}:

@example
De la musique <lilypond relative=2: a b c/> au milieu d'une ligne de texte.
@end example

Lorsque l'inclusion  concerne des fichiers indépendants, utilisez

@example
<lilypondfile @var{option1} @var{option2} ...>@var{fichier}</lilypondfile>
@end example

Une liste des différentes options utilisables avec les balises
@code{lilypond} et @code{lilypondfile} est disponible, à la rubrique
@ref{Options applicables aux fragments de musique}.

Par ailleurs, la commande @code{\lilypondversion} vous permet d'afficher
le numéro de version de LilyPond.

@cindex titrage et HTML
@cindex prévisualisation d'image
@cindex thumbnail


@node DocBook
@subsection DocBook
@translationof DocBook

L'inclusion de documents LilyPond ne doit nuire en rien à la conformité
du document DocBooK@tie{}; l'utilisation d'éditeurs spécialisés ainsi
que d'outils de validation en sera ainsi préservée.  C'est la raison
pour laquelle nous ne définirons pas de balise spécifique@tie{}; nous
respecterons plutôt les conventions des éléments standards de DocBook.


@subheading Conventions communes
@translationof Common conventions

Quel que soit le type d'extrait à inclure, nous utiliserons les
éléments @code{mediaobject} et @code{inlinemediaobject}, de telle sorte
que ces inclusions soient incorporées directement ou non dans le
document final.  Les options de formatage des extraits en question sont
fournies par la propriété @code{role} de l'élément central -- voir les
paragraphes suivants.  Les balises sont déterminées de manière à ce que
les éditeurs DocBook prennent en charge du mieux possible leur contenu.
Les fichiers DocBook destinés à un traitement par
@command{lilypond-book} doivent avoir une extension @file{.lyxml}.


@subheading Inclusion d'un fichier LilyPond
@translationof Including a LilyPond file

Il s'agit en fait du cas le plus simple.  Le fichier à inclure doit
avoir une extension @file{.ly} et sera inséré comme n'importe quel
@code{imageobject}, en respectant la structure suivante@tie{}:

@example
<mediaobject>
  <imageobject>
    <imagedata fileref="music1.ly" role="printfilename" />
  </imageobject>
</mediaobject>
@end example

Vous pouvez utiliser, en tant que balise externe, aussi bien
@code{mediaobject} que @code{inlinemediaobject}.


@subheading Inclusion de code LilyPond
@translationof Including LilyPond code

L'inclusion de code LilyPond se réalise à l'aide d'un
@code{programlisting} auquel on associe le langage @code{lilypond}.  En
voici la syntaxe@tie{}:

@example
<inlinemediaobject>
  <textobject>
    <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
\context Staff \with @{
  \remove Time_signature_engraver
  \remove Clef_engraver@}
  @{ c4( fis) @}
    </programlisting>
  </textobject>
</inlinemediaobject>
@end example

Comme vous le remarquez, la balise externe -- qu'il s'agisse d'un
@code{mediaobject} ou d'un @code{inlinemediaobject} -- comporte un bloc
@code{textobject} qui contiendra le @code{programlisting}.


@subheading Génération du document DocBook
@translationof Processing the DocBook document

@command{lilypond-book} génère, à partir d'un fichier @file{.lyxml}, un
document DocBook tout à fait valide -- extension @file{.xml} -- que vous
pourrez ensuite traiter avec votre application habituelle.  Dans le cas
de @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, vous
obtiendrez alors automatiquement un fichier PDF.  Les feuilles de style
XSL@tie{}DocBook officielles permettent de générer du HTML (HTML Help,
JavaHelp etc.)@tie{}; vous pourriez néanmoins devoir y apporter quelques
adaptations.


@node Options applicables aux fragments de musique
@section Options applicables aux fragments de musique
@translationof Music fragment options

Dans les lignes qui suivent, l'appellation @qq{commande LilyPond} fait
référence à toutes celles vues plus haut et qui font appel à
@command{lilypond-book} pour produire un extrait musical.  Pour plus de
simplicité, nous ne parlerons que de la syntaxe applicable à @LaTeX{}.

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 acceptent les options suivantes@tie{}:

@table @code
@item staffsize=@var{hauteur}
Définit la taille de portée à @var{hauteur} exprimée en points.

@item 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
@w{@code{ragged-right = ##t}}.  Il s'agit de l'option par défaut de la
commande @code{\lilypond@{@}} en l'absence d'option @code{line-width}.
C'est aussi l'option par défaut pour l'environnement @code{lilypond}
lorsque l'option @code{fragment} est activée sans avoir défini
explicitement de longueur de ligne.

@item 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 @code{ragged-right = ##f} s'ajoute à
l'extrait LilyPond.

@item line-width
@itemx line-width=@var{taille}\@var{unité}
Détermine la longueur de ligne à @var{taille}, exprimée en @var{unité}.
@var{unité} peut prendre les valeurs @code{cm}, @code{mm}, @code{in} ou
@code{pt}.  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, la longueur de ligne sera définie à une valeur
par défaut telle que calculée par un algoritme heuristique.

Lorsque l'option @code{line-width} n'est pas utilisée,
@command{lilypond-book} tentera de déterminer des valeurs par défaut
pour les cas où les environnements @code{lilypond} ne font pas appel à
@code{ragged-right}.

@item notime
Désactive l'impression des métriques et barres de mesure pour
l'intégralité de la partition.

@item fragment
Laisse à @command{lilypond-book} le soin d'ajouter ce qui est
indispensable, de telle sorte que vous pouvez vous contenter d'un

@example
c'4
@end example

@noindent
sans @code{\layout}, @code{\score}, etc.

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

@item indent=@var{taille}\@var{unité}
Définit l'indentation du premier système à @var{taille}, exprimée en
@var{unité} -- @code{cm}, @code{mm}, @code{in} ou @code{pt}.  Cette
option n'affecte que LilyPond, et en aucun cas la mise en forme du
texte.

@item 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
@code{noindent}.

@item quote
Réduit la longueur des lignes musicales de @math{2*0.4}@dmn{in} (soit
@math{2 * 10,16}@tie{}@dmn{mm}) pour renvoyer l'extrait dans un bloc de
citation.  La valeur @qq{0,4@tie{}pouce} est contrôlée par l'option
@code{exampleindent}.

@item exampleindent
Détermine la valeur de l'indentation qui sera utilisée par l'option
@code{quote}.

@item relative
@itemx relative=@var{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 @code{relative} spécifie l'octave de départ de
l'extrait@tie{}; @code{1} correspond au do central.  Cette option
@code{relative} n'a d'effet que si elle est utilisée en combinaison avec
l'option @code{fragment}@tie{}; autrement dit, l'option @code{fragment}
est implicite dès lors que @code{relative} est explicité.
@end table


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

@table @code
@item verbatim
L'argument de la commande LilyPond 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 @code{\lilypond@{@}} se
trouve au milieu d'un paragraphe.

L'utilisation conjointe d'un @code{verbatim} et de la commande
@code{lilypondfile} permet de n'inclure textuellement qu'une seule
partie du fichier source.  @code{lilypond-book} reproduira alors
textuellement la partie du fichier source comprise entre les
commentaires @code{begin@tie{}verbatim} et éventuellement
@code{end@tie{}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 @code{relative}@tie{}:

@example
\relative c' @{ % begin verbatim
  c4 e2 g4
  f2 e % end verbatim
@}
@end example

@noindent
donnera dans un bloc @emph{verbatim} précédant la partition@tie{}:

@example
  c4 e2 g4
  f2 e
@end example

@noindent
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 @code{LYDOC_LOCALEDIR} qui
pointera vers un répertoire contenant l'arborescence des catalogues de
messages -- fichiers d'extension @code{.mo} -- du domaine
@code{lilypond-doc}.

@item addversion
Cette option, effective uniquement pour Texinfo, permet d'ajouter une
ligne @code{\version @@w@{"@@version@{@}"@}} au @code{verbatim}.

@item texidoc
Option disponible uniquement pour Texinfo.@*
Dès lors qu'un fichier @file{toto.ly} contient dans sa section
@code{\header} la variable @code{texidoc}, l'appel de @command{lilypond}
avec l'option @option{--header=@/texidoc} créera le fichier
@file{toto.texidoc}.  Par ailleurs, c'est le contenu de ce
@file{toto.texidoc} qui sera ensuite recopié par
@command{lilypond-book} en préambule de l'extrait de partition.

Prenons par exemple le fichier @file{toto.ly} dont le contenu est

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

@noindent
et quelque part dans notre document Texinfo @file{test.texinfo}

@example
@@lilypondfile[texidoc]@{toto.ly@}
@end example

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

@example
lilypond-book --pdf --process="lilypond \
  -dbackend=eps --header=texidoc" test.texinfo
@end example

La plupart des fichiers de test contenus dans le répertoire @file{input}
de la distribution est constituée de la sorte.

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 @code{@@documentlanguage@tie{}@var{LANGUE}}, la présence d'une
variable @code{texidoc@var{LANGUE}} dans l'entête du fichier
@file{foo.ly} entraînera la reproduction -- par l'appel
@code{lilypond}@tie{}@option{--header=@/texidoc@var{LANGUE}} -- du
contenu de @file{toto.texidoc@var{LANGUE}} en lieu et place de celui de
@file{toto.texidoc}.

@item lilyquote
Option disponible uniquement pour Texinfo.@*
Cette option est équivalente à l'option @code{quote} à ceci près que
seule l'image de la partition -- ainsi que les éventuels blocs
@emph{verbatim} si vous la couplez à l'option @code{verbatim} -- fera
l'objet d'une citation.  Cette option permet l'inclusion de la partition
en omettant les commentaires contenus dans le bloc @code{texidoc} du
fichier source.

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

Il en va de l'option @code{doctitle} comme de l'option @code{texidoc} en
matière d'adaptation en langue étrangère.

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

@item printfilename
Lorsqu'un fichier source LilyPond est inclus à l'aide de
@code{\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é@tie{}; autrement dit, le
chemin d'accès au fichier est tronqué.

@end table


@node Utilisation de lilypond-book
@section Utilisation de @command{lilypond-book}
@translationof Invoking lilypond-book

@command{lilypond-book} produit un fichier qui aura, selon le format de
sortie spécifié, l'extension @file{.tex}, @file{.texi}, @file{.html} ou
@file{.xml}.  Les fichiers @file{.tex}, @file{.texi} et @file{.xml}
nécessitent un traitement complémentaire.


@subheading Instructions spécifiques à certains formats
@translationof Format-specific instructions


@subsubheading @LaTeX{}
@translationof @LaTeX{}

Un document @LaTeX{} destiné à l'impression ou à la publication peut se
traiter de deux manières différentes@tie{}:  générer directement un PDF
à l'aide de PDF@LaTeX{}, ou bien générer un fichier avec @LaTeX{}
qui sera ensuite passé à un traducteur DVI-PostScript comme
@command{dvips}.  La première façon est de loin la plus simple et c'est
celle que nous vous recommandons@footnote{Sachant que vous ne disposez
pas forcément de PDF@LaTeX{} et @LaTeX{} pour compiler un document
@LaTeX{}, nous vous présentons les deux méthodes.}@tie{}; quelque soit
votre préférence, sachez que vous pouvez aller du PostScript au PDF avec
des outils tels que @command{ps2pdf} et @command{pdf2ps} -- tous deux
inclus dans la distribution de Ghostscript.

La production d'un PDF avec PDF@LaTeX{} se fait en lançant les commandes

@example
lilypond-book --pdf monfichier.lytex
pdflatex monfichier.tex
@end example

@cindex type1, polices
@cindex dvips
@cindex utilisation de dvips

La séquence @LaTeX{}/@command{dvips}/@command{ps2pdf} suivante permet de
produire un PDF@tie{}:

@example
lilypond-book monfichier.lytex
latex monfichier.tex
dvips -Ppdf monfichier.dvi
ps2pdf monfichier.ps
@end example

@noindent
Le fichier @file{.dvi} généré lors de ce traitement ne contient aucune
tête de note, ce qui est tout à fait normal@tie{}; elles seront incluses
lors de la génération du @file{.ps} puis dans le @file{.pdf}.

La commande @command{dvips} peut déclencher certains messages concernant
des fontes, que vous pouvez ignorer sans scrupule.@*
Si vous utilisez @command{latex} en mode colonnage, n'oubliez pas
d'ajouter @option{-t landscape} aux options de @command{dvips}.


@subsubheading Texinfo
@translationof Texinfo

La génération d'un document Texinfo -- quel que soit le format final --
s'obtient grâce aux commandes Texinfo habituelles, c'est à dire
@command{texi2pdf}, @command{texi2dvi} ou @command{makeinfo} selon le
résultat que vous désirez obtenir.
@ifinfo
@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, et @ref{Creating
an Info File, , , texinfo, GNU Texinfo}.
@end ifinfo
@ifnotinfo
Pour plus de détails, consultez la documentation de Texinfo.
@end ifnotinfo


@subheading Options en ligne de commande
@translationof Command line options

@command{lilypond-book} accepte les options suivantes@tie{}:

@table @code
@item -f @var{format}
@itemx --format=@var{format}
Spécifie le type de document à traiter@tie{}: @code{html}, @code{latex},
@code{texi} (valeur par défaut) ou @code{docbook}.  Lorsque cette
option n'est pas mentionnée, @command{lilypond-book} tente de déterminer
automatiquement le format -- voir @ref{Extensions de nom de fichier}.  À
l'heure actuelle, @code{texi} est équivalant à @code{texi-html}.

@c This complicated detail is not implemented, comment it out -jm
@ignore
The @code{texi} document type produces a Texinfo file with music
fragments in the printed output only.  For getting images in the HTML
version, the format @code{texi-html} must be used instead.
@end ignore

@item -F @var{filtre}
@itemx --filter=@var{filtre}
Passe les extrait au travers de @var{filtre} avant de traiter le
fichier.  Cette option permet de, par exemple, appliquer les mises à
jour de LilyPond aux extraits avant de traiter le fichier@tie{}:

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

@item -h
@itemx --help
Affiche un bref résumé des options.

@item -I @var{dir}
@itemx --include=@var{répertoire}
Ajoute @var{répertoire} au chemin des inclusions.  Si des extraits ont
déjà été compilés dans l'un des répertoires inclus,
@command{lilypond-book}  ne les rééecria pas dans le répertoire de
sortie@tie{}; il sera donc nécessaire, dans la suite du traitement par
@command{makeinfo} ou @command{latex}, de penser à utiliser cette même
option @code{-I @var{répertoire}}.

@item -o @var{dir}
@itemx --output=@var{répertoire}
Regroupe les fichiers générés dans @var{répetoire}.
@command{lilypond-book} crée un certain nombre de fichiers à l'usage de
LilyPond.  Afin d'éviter de polluer votre répertoire source, nous vous
conseillons d'utiliser l'option @option{--output}, puis de vous rendre
dans ce répertoire pour y lancer les commandes @command{latex} ou
@command{makeinfo}.

@example
lilypond-book --output=out monfichier.lytex
cd out
@dots{}
@end example

@itemx --skip-lily-check
Désactive la mise en échec en l'absence de sortie de lilypond.@*
Option utilisée pour la documentation au format Info sans images.

@itemx --skip-png-check
Désactive la mise en échec en l'absence d'images PNG correspondant aux
fichiers EPS.@*
Option utilisée pour la documentation au format Info sans images.

@itemx --lily-output-dir=@var{rép}
Écrit les fichiers lily-XXX dans @var{rép} et crée un lien vers le
répertoire spécifié par @code{--output}.  Cette option permet
d'économiser du temps lors de la génération de documents qui se trouvent
dans différents répertoires et partagent un certain nombre d'extraits
identiques.

@itemx --info-images-dir=@var{répertoire}
Formate la sortie Texinfo de telle sorte que Info cherche les images
de musique dans @var{répertoire}.

@itemx --latex-program=@var{programme}
Utilise l'exécutable @command{programme} en lieu et place de
@command{latex}.  C'est l'option que vous utiliserez si vous préférez
@command{xelatex} par exemple.

@itemx --left-padding=@var{distance}
Décale les figures EPS de @var{distance} -- exprimée en milimètres (3
par défaut).  Cette option est utile lorsque les lignes de musique
débordent sur la marge droite.

Rappelez-vous que la largeur d'un système dépend des élément contenus
dans sa marge gauche, tels que numéro de mesure et nom d'instrument.
Cette option permet de @qq{raccourcir} les lignes et de les décaler vers
la droite, de la distance donnée en argument.

@item -P @var{commande}
@itemx --process=@var{commande}
Traite les extraits LilyPond avec @var{commande}.  Par défaut, il s'agit
de @code{lilypond}.@*
Rappelez-vous que @code{lilypond-book} ne peut en même temps traiter
l'option @code{--filter} et l'option @code{--process}.

@item --pdf
Crée des fichiers PDF pour les retraiter avec PDF@LaTeX{}.

@itemx --use-source-file-names
Cette option permet d'affecter aux fichiers correspondant aux extraits
de musique le même nom que leur source.  Elle n'est fonctionnelle que
dans le cas où la partition est incluse à l'aide de @code{lilypondfile},
et que les répertoires mentionnés par les options @code{--output-dir} et
@code{--lily-output-dir} diffèrent.

@item -V
@itemx --verbose
@command{lilypond-book} sait être volubile@tie{}!

@item -v
@itemx --version
Affiche le numéro de version.
@end table


@knownissues

@code{lilypond-book} ne sait pas interpréter la commande Texinfo
@code{@@pagesize}.  Dans le même ordre d'idée, des commandes @LaTeX{}
modifiant les marges et longueur de ligne mentionnées après le préambule
seront ignorées.

Lorsqu'une section LilyPond contient plusieurs @code{\score}, seul le
premier sera traité.


@node Extensions de nom de fichier
@section Extensions de nom de fichier
@translationof Filename extensions

Vous pouvez affecter à votre fichier source n'importe quelle extension.
Nous vous recommandons cependant un certain nombre d'extensions selon le
format de sortie désiré.  Une extension hors du commun vous obligera à
spécifier le format de sortie, alors que @code{lilpond-book} est en
mesure de déterminer le format de sortie en fonction de l'extension du
fichier source.

@quotation
@multitable @columnfractions .2 .5
@item @strong{extension} @tab @strong{format résultant}
@item
@item @file{.html} @tab HTML
@item @file{.htmly} @tab HTML
@item @file{.itely} @tab Texinfo
@item @file{.latex} @tab @LaTeX{}
@item @file{.lytex} @tab @LaTeX{}
@item @file{.lyxml} @tab DocBook
@item @file{.tely} @tab Texinfo
@item @file{.tex} @tab @LaTeX{}
@item @file{.texi} @tab Texinfo
@item @file{.texinfo} @tab Texinfo
@item @file{.xml} @tab HTML
@end multitable
@end quotation

Lorsque le fichier source a la même extension que celle que
@code{lilypond-book} affectera au fichier résultant et que vous
lancez @code{lilypond-book} à partir du répertoire le contenant, vous
verrez assurément un message du type @qq{La sortie va écraser le fichier
d'entrée}.  Aussi ne saurions-nous trop vous conseiller d'utiliser
l'option @code{--output}.


@node  Modèles pour lilypond-book
@section Modèles pour lilypond-book
@translationof lilypond-book templates

Voici quelques canevas dédiés à @code{lilypond-book}.  Si vous ne savez
pas de quoi il retourne, lisez le chapitre @ref{lilypond-book}.


@subsection LaTeX
@translationof LaTeX

Vous pouvez inclure des partitions LilyPond dans un document LaTeX.

@example
\documentclass[]@{article@}

\begin@{document@}

Des bananes alitées sur du LaTeX.

\begin@{lilypond@}
\relative c'' @{
  a4 b c d
@}
\end@{lilypond@}

Encore des banalités LaTeX, puis quelques options entre crochets.

\begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim]
d4 c b a
\end@{lilypond@}
\end@{document@}
@end example


@subsection Texinfo
@translationof Texinfo

Un document Texinfo est tout à fait capable de comporter des fragments
de partition LilyPond.  Si vous ne le savez pas encore, sachez que
l'intégralité de ce manuel est rédigée en Texinfo.

@example
\input texinfo @c -*-texinfo-*-
@@node Top
@@top

Du verbiage en mode Texinfo

@@lilypond
\relative c' @{
  a4 b c d
@}
@@end lilypond

Toujours plus de texte Texinfo, puis des options entre crochets.

@@lilypond[verbatim,fragment,ragged-right]
d4 c b a
@@end lilypond

@@bye
@end example


@subsection html
@translationof html

@example
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<HTML>
<body>

<p>
Un document pour lilypond-book peut absolument mélanger musique et
texte.  Par exemple,
<lilypond>
\relative c'' @{
  a4 b c d
@}
</lilypond>
</p>

<p>
Pourquoi pas un peu plus de lilypond, avec des options pour changer :

<lilypond fragment quote staffsize=26 verbatim>
a4 b c d
</lilypond>
</p>

</body>
</html>


@end example


@subsection xelatex
@translationof xelatex

@verbatim
\documentclass{article}
\usepackage{ifxetex}
\ifxetex
%pour ce qui est de xetex
\usepackage{xunicode,fontspec,xltxtra}
\setmainfont[Numbers=OldStyle]{Times New Roman}
\setsansfont{Arial}
\else
%inutile en l'absence de pdftex
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{mathptmx}%Times
\usepackage{helvet}%Helvetica
\fi
%ici les paquetages que pdftex sait interpréter
\usepackage[ngerman,finnish,english]{babel}
\usepackage{graphicx}

\begin{document}
\title{Un petit document avec LilyPond et xelatex}
\maketitle

Les commandes habituelles de \textbf{fontes} sont fonctionnelles y
compris au fil du texte, étant donné qu'\textsf{elles sont prises en
charge par \LaTeX{} and XeteX.} Lorsque vous avez besoin de commandes
particulières du style \verb+\XeTeX+, pensez à les inclure dans un
environnement \verb+\ifxetex+. Vous pourrez ainsi utiliser la \ifxetex
commande \XeTeX{} \else commande XeTeX \fi qui, elle, n'est pas reconnue
par le \LaTeX traditionnel.

Vous pouvez inclure des commandes LilyPond directement dans votre texte,
comme ici~:

\begin{lilypond}
{a2 b c'8 c' c' c'}
\end{lilypond}

\noindent
puis reprendre le fil de votre discours.

Les fontes utilisées dans les extraits LilyPond  devront être définies
au sein de l'extrait. Lisez le manuel d'ustilisation si vous ne
maîtrisez pas lilypond-book.

\selectlanguage{ngerman}
Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle anderen
seltsamen Zeichen: ß, æ, ł, ã, č, wenn sie von der Schriftart unterstützt
werden.

\end{document}
@end verbatim


@node Gestion de la table des matières
@section Gestion de la table des matières
@translationof Sharing the table of contents

Les fonctions qui sint ici mentionnées sont incluses dans le paquetage
OrchestralLily, disponible sur

@example
@url{http://repo.or.cz/w/orchestrallily.git}
@end example

Certains utilisateurs privilégient la flexibilité dans la gestion du
texte@tie{}; ils génèrent la table des matières à partir de LilyPond et
la récupèrent dans @LaTeX{}.


@subsubheading Export de la table à partir de LilyPond
@translationof Exporting the ToC from LilyPond

Nous partons du principe que LilyPond a généré un seul fichier
comportant tous les mouvement de la partition.

@smallexample
#(define (oly:create-toc-file layout pages)
  (let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
    (if (not (null? label-table))
      (let* ((format-line (lambda (toc-item)
             (let* ((label (car toc-item))
                    (text  (caddr toc-item))
                    (label-page (and (list? label-table)
                                     (assoc label label-table)))
                    (page (and label-page (cdr label-page))))
               (format #f "~a, section, 1, @{~a@}, ~a" page text label))))
             (formatted-toc-items (map format-line (toc-items)))
             (whole-string (string-join formatted-toc-items ",\n"))
             (output-name (ly:parser-output-name parser))
             (outfilename (format "~a.toc" output-name))
             (outfile (open-output-file outfilename)))
        (if (output-port? outfile)
            (display whole-string outfile)
            (ly:warning (_ "Impossible d'ouvrir le fichier ~a contenant les informations de TdM") outfilename))
        (close-output-port outfile)))))

\paper @{
  #(define (page-post-process layout pages) (oly:create-toc-file layout pages))
@}
@end smallexample


@subsubheading Import de la table dans LaTeX
@translationof Importing the ToC into LaTeX

L'entête de votre fichier @LaTeX{} doit comporter les lignes

@c no, this doesn't require the smallexample, but since the other
@c two blocks on this page use it, I figured I might as well
@c user it here as well, for consistency. -gp
@smallexample
\usepackage@{pdfpages@}
\includescore@{nomdelapartition@}
@end smallexample

@noindent
où @code{\includescore} est défini ainsi@tie{}:

@smallexample
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \includescore@{PossibleExtension@}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Read in the TOC entries for a PDF file from the corresponding .toc file.
% This requires some heave latex tweaking, since reading in things from a file
% and inserting it into the arguments of a macro is not (easily) possible

% Solution by Patrick Fimml on #latex on April 18, 2009:
% \readfile@{filename@}@{\variable@}
% reads in the contents of the file into \variable (undefined if file
% doesn't exist)
\newread\readfile@@f
\def\readfile@@line#1@{%
@{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}%
\edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do%
\ifeof\readfile@@f\else%
\readfile@@line@{#1@}%
\fi%
@}
\def\readfile#1#2@{%
\openin\readfile@@f=#1 %
\ifeof\readfile@@f%
\typeout@{No TOC file #1 available!@}%
\else%
\gdef#2@{@}%
\readfile@@line@{#2@}%
\fi
\closein\readfile@@f%
@}%


\newcommand@{\includescore@}[1]@{
\def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@}
\let\oly@@addtotoc\undefined
\readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@}
\ifx\oly@@addtotoc\undefined
\includepdf[pages=-]@{\oly@@fname@}
\else
\edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}]
@{\oly@@fname@}@}\includeit
\fi
@}
@end smallexample


@node Autres méthodes d'association texte-musique
@section Autres méthodes d'association texte-musique
@translationof Alternative methods of mixing text and music

D'autres moyens de mélanger musique et texte sans recourir à
@command{lilypond-book} sont abordés au chapitre
@ref{Inclusion de partition LilyPond dans d'autres programmes}.