Fix issue 1746 "v2.13.48 docball adds offline-root/ directory"

[lilypond.git] / Documentation / fr / notation / input.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
@ignore
    Translation of GIT committish: 40c0295431d0732747d0e37b7911f03fb9daca16

    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.15.39"

@c Translators: Jean-Charles Malahieude, Valentin Villenave

@node Généralités en matière d'entrée et sortie
@chapter Généralités en matière d'entrée et sortie
@translationof General input and output

Nous n'allons pas, dans ce chapitre, parler directement de notation,
mais plutôt du contenu des fichiers source et du résultat produit par
LilyPond.

@menu
* Agencement du code::
* Titres et entêtes::
* Travail sur des fichiers texte::
* Contrôle des sorties::
* Sortie MIDI::
* Extraction d'informations musicales::
@end menu


@node Agencement du code
@section Agencement du code
@translationof Input structure

LilyPond traite des fichiers textuels.  Ces fichiers portent par
convention une extension @code{.ly}.

@menu
* Structure d'une partition::
* Plusieurs partitions dans un même ouvrage::
* Plusieurs éditions pour une même source::
* Nom des fichiers de sortie::
* Structure de fichier::
@end menu


@node Structure d'une partition
@subsection Structure d'une partition
@translationof Structure of a score

@funindex \score

Un bloc @code{\score} contient obligatoirement une seule expression
musicale délimitée par des accolades :

@example
\score @{
...
@}
@end example

@warning{Il ne doit y avoir qu'@strong{une seule} expression musicale
globale dans un bloc @code{@bs{}score}, et elle @strong{doit} être
bornée par une paire d'accolades.}

Cette unique expression musicale peut être de n'importe quelle taille et
contenir d'autres expressions musicales aussi complexes soient elles.
Voici quelques exemples d'expression musicale :

@example
@{ c'4 c' c' c' @}
@end example

@lilypond[verbatim,quote]
{
  { c'4 c' c' c' }
  { d'4 d' d' d' }
}
@end lilypond

@lilypond[verbatim,quote]
<<
  \new Staff { c'4 c' c' c' }
  \new Staff { d'4 d' d' d' }
>>
@end lilypond

@example
@{
  \new GrandStaff <<
    \new StaffGroup <<
      \new Staff @{ \flute @}
      \new Staff @{ \hautbois @}
    >>
    \new StaffGroup <<
      \new Staff @{ \violonI @}
      \new Staff @{ \violonII @}
    >>
  >>
@}
@end example

Les commentaires constituent l'une des rares exceptions à cette règle
immuable -- voir @ref{Structure de fichier} pour les autres.  Qu'il
s'agisse d'une seule ligne ou de tout un bloc -- délimité par @code{%@{
.. %@}} -- un commentaire peut se placer n'importe où dans le fichier
source, aussi bien à l'intérieur qu'à l'extérieur du bloc @code{\score},
ou encore à l'intérieur ou à l'extérieur de l'expression musicale
contenue dans un bloc @code{\score}.

Lorsqu'un fichier ne comprend qu'un bloc @code{\score}, celui-ci est
implicitement inclus dans un bloc @code{\book}.  Le bloc @code{\book}
d'un fichier source permet la production d'au moins un fichier dont le
nom sera, par défaut, déduit du fichier source : le traitement de
@file{fandangopourelephants.ly} produira donc
@file{fandangopourelephants.pdf}.

Pour de plus amples informations à propos du bloc @code{\book}, lisez
@ref{Plusieurs partitions dans un même ouvrage},
@ref{Plusieurs éditions pour une même source} et
@ref{Structure de fichier}.

@seealso
Manuel d'initiation :
@rlearning{La partition est une (unique) expression musicale composée},
@rlearning{Les expressions musicales en clair},
@rlearning{Travail sur les fichiers d'entrée}.


@node Plusieurs partitions dans un même ouvrage
@subsection Plusieurs partitions dans un même ouvrage
@translationof Multiple scores in a book

@cindex mouvements, plusieurs
@cindex plusieurs mouvements

@funindex \book

Un ouvrage peut se composer de plusieurs morceaux et de texte.  C'est le
cas des cahiers d'exercices ou d'une partie d'orchestre avec ses
différents mouvements.  Chaque mouvement fait l'objet d'un bloc
@code{\score},

@example
\score @{
  @var{..musique..}
@}
@end example

et le texte est contenu dans un bloc @code{\markup},

@example
\markup @{
  @var{..texte..}
@}
@end example

@funindex \book

Les différents mouvements et textes qui apparaissent dans un même
fichier @file{.ly} ne composeront en principe qu'un seul fichier
résultant.

@example
\score @{
  @var{..}
@}
\markup @{
  @var{..}
@}
\score @{
  @var{..}
@}
@end example

Attention cependant si vous travaillez avec lilypond-book : il vous
faudra explicitement mentionner le bloc @code{\book}, en l'absence de
quoi seul le premier @code{\score} ou @code{\markup} apparaîtra après
traitement.

L'entête de chaque pièce peut se placer au sein du bloc @code{\score} ;
le contenu du champ @code{piece} viendra s'imprimer avant chaque
mouvement.  De même, le titre de l'ouvrage peut se placer au sein du
bloc @code{\book}.  Dans le cas contraire, le contenu du bloc
@code{\header} placé en début de fichier sera utilisé.

@example
\header @{
  title = "Huit miniatures"
  composer = "Igor Stravinsky"
@}
\score @{
  @dots{}
  \header @{ piece = "Romance" @}
@}
\markup @{
   ..texte du second couplet..
@}
\markup @{
   ..texte du troisième couplet..
@}
\score @{
  @dots{}
  \header @{ piece = "Menuet" @}
@}
@end example

@funindex \bookpart

Plusieurs pièces seront regroupées dans un même @qq{chapitre} à l'aide
d'un bloc @code{\bookpart}.  Ces différents @qq{chapitres} sont séparés
par un saut de page et peuvent comporter un titre à l'instar de
l'ouvrage dès lors que vous y insérez un bloc @code{\header}.

@example
\bookpart @{
  \header @{
    title = "Titre de l'ouvrage"
    subtitle = "Première partie"
  @}
  \score @{ @dots{} @}
  @dots{}
@}
\bookpart @{
  \header @{
    subtitle = "Deuxième partie"
  @}
  \score @{ @dots{} @}
  @dots{}
@}
@end example


@node Plusieurs éditions pour une même source
@subsection Plusieurs éditions pour une même source
@translationof Multiple output files from one input file

Dès lors que vous inscrivez plusieurs blocs @code{\book} dans un même
fichier @file{.ly}, chacun d'eux donnera lieu à un résultat indépendant.
Lorsqu'aucun bloc @code{\book} n'est spécifié dans le fichier source,
LilyPond considère que l'intégralité du fichier constitue un bloc
@code{\book} unique, comme indiqué à la rubrique
@ref{Structure de fichier}.

LilyPond fait en sorte, lorsque plusieurs fichiers sont produits à
partir d'une même source, qu'aucun résultat d'un bloc @code{\book}
n'écrase celui qui a été généré pour un bloc @code{\book} précédent.

Dans les faits, et si le nom du fichier produit est repris de sa source
-- comportement par défaut --, un suffixe lui sera ajouté pour chaque
@code{\book}.  Il s'agit en principe d'un pseudo numéro de version.
Ainsi, le fichier @file{huitminiatures.ly} qui contiendrait

@example
\book @{
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
@end example

générera

@itemize
@item
@file{huitminiatures.pdf},
@item
@file{huitminiatures-1.pdf} et
@item
@file{huitminiatures-2.pdf}.
@end itemize


@node Nom des fichiers de sortie
@subsection Nom des fichiers de sortie
@translationof Output file names

@funindex \bookOutputSuffix
@funindex \bookOutputName

LilyPond vous permet de prendre le contrôle dans la dénomination des
fichiers que vous voulez générer, quel que soit le moteur de rendu
utilisé.

Nous avons vu dans la rubrique précédente que LilyPond évite les
conflits de nom des fichiers qu'il génère à partir d'une même source.
Vous pouvez même définir vous-même le suffixe qui sera appliqué à chacun
des blocs @code{\book}.  Ainsi, en reprenant l'exemple ci-avant, vous
obtiendrez les fichiers @file{huitminiatures-Romance.pdf},
@file{huitminiatures-Menuet.pdf} et @file{huitminiatures-Nocturne.pdf}
en ajoutant simplement une déclaration @code{\bookOutputSuffix} au sein
de chaque bloc @code{\book}.

@example
\book @{
  \bookOutputSuffix "Romance"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \bookOutputSuffix "Menuet"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \bookOutputSuffix "Nocturne"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
@end example

La déclaration @code{\bookOutputName} vous permet de définir vous-même
le nom du fichier généré pour un bloc @code{\book} :

@example
\book @{
  \bookOutputName "Romance"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \bookOutputName "Menuet"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \bookOutputName "Nocturne"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
@end example

Le traitement de ce fichier produira :

@itemize
@item
@file{Romance.pdf},
@item
@file{Menuet.pdf} et
@item
@file{Nocturne.pdf}.
@end itemize


@node Structure de fichier
@subsection Structure de fichier
@translationof File structure

@funindex \paper
@funindex \midi
@funindex \layout
@funindex \header
@funindex \score
@funindex \book
@funindex \bookpart

Un fichier @code{.ly} peut contenir un certain nombre d'expressions de
haut niveau.  Les expressions de haut niveau sont les suivantes :

@itemize
@item
Une définition de sortie, comme @code{\paper}, @code{\midi} et
@code{\layout}.  Ces définitions, lorsqu'elles se trouvent à un niveau
supérieur, s'appliqueront à l'intégralité de l'ouvrage.  Si l'une de ces
expression apparaît à plusieurs reprises à un niveau supérieur, les
différents contenus seront combinés, à ceci près qu'en cas de
déclarations conflictuelles, la dernière aura préséance.  Des
informations complémentaires sont disponibles à la rubrique
@ref{Le bloc \layout}.

@item
Une expression Scheme pure, telle que
@w{@code{#(set-default-paper-size "a7" 'landscape)}} ou
@w{@code{#(ly:set-option 'point-and-click #f)}}.

@item
Un bloc @code{\header}, dont le contenu sera de portée globale -- ce qui
est le cas en général pour le titre ou l'auteur entre autres.

@item
Un bloc @code{\score} pour la partition.  Cette partition sera assemblée
avec les autres partitions se trouvant au même niveau pour composer le
@code{\book}.  Vous pouvez modifier ce comportement à l'aide de la
variable @code{toplevel-score-handler} placée en tête.
@ignore
@c FIXME - I cannot read "toplevel-score-handler" in scm/lily.scm -jcm
The default handler is defined in the init file @file{../scm/lily.scm}.
@end ignore

@item
Un bloc @code{\book} permet de regrouper naturellement plusieurs
mouvements -- autrement dit plusieurs blocs @code{\score} -- dans un
même document.  Lorsqu'il y a plusieurs @code{\score}, LilyPond génère
un seul fichier dans lequel les mouvements sont mis les uns à la suite
des autres, ce pour chacun des blocs @code{\book} rencontrés.  La seule
raison qui peut vous demander d'expliciter plusieurs blocs @code{\book}
dans un fichier @file{.ly} est lorsque vous avez besoin de générer
différents documents à partir d'une même source.  La présence explicite
d'un bloc @code{\book} est aussi nécessaire lorsque vous travaillez sur
un document lilypond-book qui reprendrait plusieurs @code{\score} ou
@code{\markup} dans un même extrait.  Vous pouvez modifier ce
comportement à l'aide de la variable @code{toplevel-book-handler}
placée en tête.
@ignore
@c FIXME - I cannot read "toplevel-book-handler" in scm/lily.scm -jcm
The default handler is defined in the init file @file{../scm/lily.scm}.
@end ignore

@item
Un bloc @code{\bookpart}.  Un ouvrage peut se découper en plusieurs
parties à l'aide de blocs @code{\bookpart}, aussi bien pour alléger le
travail de l'algorithme de calcul des sauts de page, que si les réglages
du bloc @code{\paper} diffèrent d'une partie à l'autre.

@item
Une expression musicale telle que
@example
@{ c'4 d' e'2 @}
@end example

Ce bout de code sera placé dans un @code{\score} et intégré à l'ouvrage
en même temps que tous les autres @code{\score} ou expressions
musicales.  En d'autres termes, un fichier qui ne contiendrait que cette
simple expression musicale sera traduit en

@example
\book @{
  \score @{
    \new Staff @{
      \new Voice @{
        @{ c'4 d' e'2 @}
      @}
    @}
    \layout @{ @}
  @}
  \paper @{ @}
  \header @{ @}
@}
@end example

Vous pouvez modifier ce comportement à l'aide de la variable
@code{toplevel-music-handler} placée en tête.
@ignore
@c FIXME - I cannot read "toplevel-music-handler" in scm/lily.scm -jcm
The default handler is defined in the init file @file{../scm/lily.scm}.
@end ignore

@item
Du texte sous forme de @emph{markup} comme les paroles d'un couplet
@example
\markup @{
   2.  Le première ligne du deuxième couplet.
@}
@end example

De tels @emph{markups} seront imprimés là où ils apparaissent,
avant, après ou entre les expressions musicales.

@cindex variables
@cindex identificateurs

@item
Une variable, ou identificateur, telle que
@example
toto = @{ c4 d e d @}
@end example

Vous pourrez la réutiliser plus loin dans votre fichier en saisissant
simplement @code{\toto}.  Le nom des identificateurs ne doit être
formés que de caractères alphabétiques -- sans chiffre ni caractère
souligné ou tiret.

@end itemize

Voici trois éléments que vous pouvez placer à un niveau supérieur :

@example
\layout @{
  % pas en pleine largeur
  ragged-right = ##t
@}

\header @{
   title = "Do-re-mi"
@}

@{ c'4 d' e2 @}
@end example

Vous pouvez placer, n'importe où dans votre fichier, les instructions
suivantes :

@itemize
@item @code{\version}
@item @code{\include}
@item @code{\sourcefilename}
@item @code{\sourcefileline}
@item
Une ligne de commentaire, introduite par le signe @code{%}.

@item
Un bloc de commentaire, délimité par @code{%@{ .. %@}}.

@end itemize

@cindex espace
@cindex blanc

Vous pouvez insérer des espaces dans votre fichier source afin de lui
apporter une meilleure lisibilité.  Les espaces superflus sont
normalement ignorés.  Notez cependant qu'il est des cas où l'espace est
requis pour éviter tout risque d'erreur :

@itemize
@item
Autour d'une accolade, qu'elle soit ouvrant ou fermante ;

@item
Après chaque commande ou variable, autrement dit tout élément qui
commence par un @code{\} ;

@item
Après tout élément qui sera interprété comme une expression Scheme,
autrement dit tout élément qui commence par un @code{#} ;

@item
Pour séparer les éléments d'une expression Scheme ;

@item
En mode parole -- @code{lyricmode} -- pour séparer les termes des
commandes @code{\override} et @code{\set}.  Précisons à ce sujet qu'en
plus d'ajouter une espace avant et après l'intégralité de la commande,
vous devrez encadrer d'espaces le point et le signe égal qu'elle peut
contenir, comme dans
@w{@code{\override Score . LyricText #'font-size = #5}}.

@end itemize

@seealso
Manuel d'initiation :
@rlearning{Organisation des fichiers LilyPond}.

Manuel de notation :
@ref{Le bloc \layout}.


@node Titres et entêtes
@section Titres et entêtes
@translationof Titles and headers

La plupart de la musique qui est éditée comporte un titre et le nom de
son compositeur ; certains ouvrages divulguent beaucoup plus
d'information.

@menu
* Création de titres et entête ou pied de page::
* Titrages personnalisés::
* Notes de bas de page::
* Référencement des numéros de page::
* Table des matières::
@end menu


@node Création de titres et entête ou pied de page
@subsection Création de titres et entête ou pied de page
@translationof Creating titles headers and footers

@menu
* Contenu des blocs de titrage::
* Mise en forme par défaut des titrages::
* Mise en forme par défaut des entête et pied de page::
@end menu


@node Contenu des blocs de titrage
@unnumberedsubsubsec Contenu des blocs de titrage
@translationof Title blocks explained

@c TODO: figure out how \bookpart titles work

Il existe en fait deux types de blocs de titrage : un bloc pour
contenir le titre principal qui doit apparaître avant le tout premier
@code{\score} d'un ouvrage, et un autre attaché à chacun des blocs
@code{\score} qui le composent.  Dans les deux cas, les champs qui
composent un bloc de titrage se saisissent dans un bloc @code{\header}.

Lorsque l'ouvrage ne comporte qu'un seul morceau, le bloc @code{\header}
peut se placer en dehors ou au sein même du bloc @code{\score}.

Dans le cas où le bloc @code{\header} est défini à l'intérieur du bloc
@code{\score}, seuls les champs @code{piece} et @code{opus} seront
imprimés.

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\score {
  { c'4 }
  \header {
    title = "title"  % not printed
    piece = "piece"
    opus = "opus"
  }
}
@end lilypond

@funindex print-all-headers
@noindent
Vous pouvez modifier ce comportement et imprimer tous les champs d'un
bloc @code{\header} défini dans un bloc @code{\score} en ajoutant

@example
\paper@{
  print-all-headers = ##t
@}
@end example

@warning{N'oubliez pas que lorsqu'il est placé à l'intérieur d'un bloc
@code{@bs{}score}, le bloc @code{@bs{}header} doit impérativement se
trouver @strong{à la suite} de l'expression musicale.}

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\header {
  title = "SUITE I."
  composer = "J. S. Bach."
}

\score {
  \new Staff \relative g, {
    \clef bass
    \key g \major
    \repeat unfold 2 { g16( d' b') a b d, b' d, } |
    \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
  }
  \header {
    piece = "Prélude."
  }
}

\score {
  \new Staff \relative b {
    \clef bass
    \key g \major
    \partial 16 b16 |
    <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
    d16( b g fis) g( e d c) b(c d e) fis( g a b) |
  }
  \header {
    piece = "Allemande."
  }
}
@end lilypond

Tous les champs appartenant au titrage principal d'un ouvrage peuvent se
reporter dans chaque bloc @code{\score} ou être supprimés manuellement :

@c KEEP LY
@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
  \paper {
    print-all-headers = ##t
  }
  \header {
    title = "DAS WOHLTEMPERIRTE CLAVIER"
    subtitle = "TEIL I"
    % Pas de mention spéciale pour cet ouvrage
    tagline = ##f
  }
  \markup { \vspace #1 }
  \score {
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
    \header {
      title = "PRAELUDIUM I"
      opus = "BWV 846"
      % Pas de sous-titre pour ce morceau
      subtitle = ##f
    }
  }
  \score {
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
    \header {
      title = "FUGA I"
      subsubtitle = "A 4 VOCI"
      opus = "BWV 846"
      % Pas de sous-titre pour ce morceau
      subtitle = ##f
    }
  }
}
@end lilypond

@seealso
Manuel de notation :
@ref{Structure de fichier},
@ref{Mise en forme personnalisée des blocs de titrage}.


@node Mise en forme par défaut des titrages
@unnumberedsubsubsec Mise en forme par défaut des titrages
@translationof Default layout of book and score title blocks

La mise en forme des blocs de titrage est contrôlée par deux variables
attachées au bloc @code{\paper} : @code{bookTitleMarkup} pour le bloc
@code{\header} principal, et @code{scoreTitleMarkup} pour les blocs
@code{\header} relevant des blocs @code{\score}.

@c KEEP LY
@lilypond[papersize=a6,quote,verbatim,noragged-right]
\header {
  % Les champs suivants sont centrés
  dedication = "Dédicace"
  title = "Titre"
  subtitle = "Sous-titre"
  subsubtitle = "Sous-sous-titre"
  instrument = "Instrument"

  % Les champs suivants sont alignés par la gauche
  poet = "Librettiste"
  meter = "Tempo"

  % Les champs suivants sont alignés par la droite
  composer = "Compositeur"
  arranger = "Arrangeur"
}

\score {
  { s1 }
  \header {
    % Les champs suivants sont en opposition sur la même ligne
    piece = "Pièce"
    opus = "Opus"
  }
}
@end lilypond

@c Is the bit about \null markups true? -mp

Les champs d'un bloc @code{\header} qui n'auront pas été alimentés
seront remplacés par un @emph{markup} @code{\null} de façon à ne pas
gaspiller d'espace.

Par défaut, @code{scoreTitleMarkup} place les champs @code{piece} et
@code{opus} de part et d'autre sur une même ligne.

@cindex breakbefore

La variable @code{breakbefore} activée dans un bloc @code{\header} situé
dans un bloc @code{\score} force le saut de page avant le morceau
contenu dans ce @code{\score}.  Vous pourrez ainsi séparer le titre
principal de la musique.

@lilypond[papersize=a8landscape,verbatim,noragged-right]
\book {
  \header {
    title = "This is my Title"
    subtitle = "This is my Subtitle"
    copyright = "This is the bottom of the first page"
  }
  \score {
    \repeat unfold 4 { e'' e'' e'' e'' }
    \header {
      piece = "This is the Music"
      breakbefore = ##t
    }
  }
}
@end lilypond

@seealso
Manuel d'initiation :
@rlearning{Organisation des fichiers LilyPond}.

Manuel de notation :
@ref{Structure de fichier}.

Fichiers d'initialisation :
@file{ly/titling-init.ly}.


@node Mise en forme par défaut des entête et pied de page
@unnumberedsubsubsec Mise en forme par défaut des entête et pied de page
@translationof Default layout of headers and footers

Les entête et pied -- @emph{headers} et @emph{footers} -- sont des
lignes de textes qui apparaissent en haut et en bas de chaque page,
indépendamment du texte de l'ouvrage.  Ils sont contrôlés par les
variables suivantes, attachées au bloc @code{\paper} :

@itemize
@item @code{oddHeaderMarkup} -- entête de page impaire
@item @code{evenHeaderMarkup} -- entête de page paire
@item @code{oddFooterMarkup} -- pied de page impaire
@item @code{evenFooterMarkup} -- pied de page paire
@end itemize

Ces variables @emph{markup} n'accèdent qu'au contenu des champs du bloc
@code{\header} principal, celui qui s'appliquera à tous les blocs
@code{\score} du document.  Ces variables sont définies dans le fichier
@file{ly/titling-init.ly}, et sont par défaut :

@itemize

@item
les numéros sont placés en haut à gauche (si pair) ou à droite (si
impair) de chaque page à compter de la deuxième ;

@item
le contenu du champ @code{instrument} est centré en haut de chaque page
à compter de la deuxième ;

@item
le texte du @code{copyright} est centré au bas de la première page ;

@item
le @code{tagline} -- mention spéciale -- se place au bas de la dernière
page, ou bien sous le @code{copyright} s'il n'y a qu'une seule page.

@end itemize

@lilypond[papersize=a8landscape]
\book {
  \score {
    \relative c' {
      c4 d e f
    }
  }
}
@end lilypond

La mention spéciale se modifie en alimentant le champ @code{tagline} au
niveau du bloc @code{\header} principal.

@lilypond[papersize=a8landscape,verbatim]
\book {
  \header {
    tagline = "... music notation for Everyone"
  }
  \score {
    \relative c' {
      c4 d e f
    }
  }
}
@end lilypond

Pour supprimer le @code{tagline}, il suffit de lui assigner la valeur
@code{##f}.


@node Titrages personnalisés
@subsection Titrages personnalisés
@translationof Custom headers footers and titles

@c TODO: somewhere put a link to header spacing info
@c       (you'll have to explain it more in NR 4).

@menu
* Mise en forme personnalisée des champs de titrage::
* Mise en forme personnalisée des blocs de titrage::
* Mise en forme personnalisée des entête et pied de page::
@end menu


@node Mise en forme personnalisée des champs de titrage
@unnumberedsubsubsec Mise en forme personnalisée des champs de titrage
@translationof Custom text formatting for title blocks

Toutes les commandes de mise en forme d'un @code{\markup} permettent de
personnaliser le texte des entête, pied de page et éléments de titre
contenus dans un bloc @code{\header}.

@lilypond[quote,verbatim,noragged-right]
\score {
  { s1 }
  \header {
    piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
    opus = \markup { \italic "(Excerpt)" }
  }
}
@end lilypond

@seealso
Manuel de notation :
@ref{Mise en forme du texte}.


@node Mise en forme personnalisée des blocs de titrage
@unnumberedsubsubsec Mise en forme personnalisée des blocs de titrage
@translationof Custom layout for title blocks

L'utilisation de commandes @code{\markup} au sein d'un bloc
@code{\header} permet de modifier aisément l'apparence du texte,
mais n'influence en rien le positionnement précis des éléments de
titrage.  L'accès au positionnement des champs de titrage est géré par
les deux variables suivantes, attachées au bloc @code{\paper} :

@itemize
@item @code{bookTitleMarkup}
@item @code{scoreTitleMarkup}
@end itemize

Ces variables sont abordées à la rubrique
@ref{Mise en forme par défaut des titrages}.

Voici les réglages par défaut de @code{scoreTitleMarkup}, tels que
définis dans le fichier @file{ly/titling-init.ly} :

@example
scoreTitleMarkup = \markup @{ \column @{
  \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
  \fill-line @{
    \fromproperty #'header:piece
    \fromproperty #'header:opus
  @}
@}
@}
@end example

Ceci aura donc pour effet de positionner les champs @code{piece} et
@code{opus} sur la même ligne, en opposition :

@lilypond[quote,verbatim,noragged-right]
\score {
  { s1 }
  \header {
    piece = "PRAELUDIUM I"
    opus = "BWV 846"
  }
}
@end lilypond

Voici comment positionner le champ @code{piece}, dont nous modifions
la taille et la graisse, au centre de cette ligne :

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
  \paper {
    indent = 0\mm
    scoreTitleMarkup = \markup {
      \fill-line {
        \null
        \fontsize #4 \bold \fromproperty #'header:piece
        \fromproperty #'header:opus
      }
    }
  }
  \header { tagline = ##f }
  \score {
    { s1 }
    \header {
      piece = "PRAELUDIUM I"
      opus = "BWV 846"
    }
  }
}
@end lilypond

Les champs normalement réservés au bloc de titrage principal seront
reportés au niveau inférieur dès lors que vous aurez activé
l'instruction @code{print-all-headers} au sein du bloc @code{\paper}.
Le principal inconvénient de cette fonction réside dans le fait que les
champs réservés au bloc @code{\header} principal devront être supprimés
dans chacun des blocs @code{\score} de votre fichier source -- voir
@ref{Contenu des blocs de titrage}.

Afin d'éviter ce désagrément, ajoutez le champ que vous désirez voir
apparaître à la définition de @code{scoreTitleMarkup}.  Nous allons,
dans l'exemple suivant, ajouter au @code{scoreTitleMarkup} le champ
@code{composer}, normalement associé au @code{bookTitleMarkup} ;
chaque @code{\score} pourra mentionner un compositeur différent.

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
  \paper {
    indent = 0\mm
    scoreTitleMarkup = \markup {
      \fill-line {
        \null
        \fontsize #4 \bold \fromproperty #'header:piece
        \fromproperty #'header:composer
      }
    }
  }
  \header { tagline = ##f }
  \score {
    { s1 }
    \header {
      piece = "MENUET"
      composer = "Christian Petzold"
    }
  }
  \score {
    { s1 }
    \header {
      piece = "RONDEAU"
      composer = "François Couperin"
    }
  }
}
@end lilypond

Rien ne vous empêche de créer votre propre champ personnalisé, puis d'y
faire référence dans la définition du @emph{markup}.

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
  \paper {
    indent = 0\mm
    scoreTitleMarkup = \markup {
      \fill-line {
        \null
        \override #`(direction . ,UP) {
          \dir-column {
            \center-align \fontsize #-1 \bold
              \fromproperty #'header:mycustomtext %% User-defined field
            \center-align \fontsize #4 \bold
              \fromproperty #'header:piece
          }
        }
        \fromproperty #'header:opus
      }
    }
  }
  \header { tagline = ##f }
  \score {
    { s1 }
    \header {
      piece = "FUGA I"
      mycustomtext = "A 4 VOCI" %% User-defined field
      opus = "BWV 846"
    }
  }
}
@end lilypond

@seealso
Manuel de notation :
@ref{Contenu des blocs de titrage}.


@node Mise en forme personnalisée des entête et pied de page
@unnumberedsubsubsec Mise en forme personnalisée des entête et pied de page
@translationof Custom layout for headers and footers

@c can make-header and make-footer be removed from
@c paper-defaults-init.ly? -mp

L'utilisation de commandes @code{\markup} au sein d'un bloc
@code{\header} permet de modifier aisément l'apparence du texte,
mais n'influence en rien le positionnement précis des entête et pied
de page.  L'accès au positionnement des champs concernés est géré par
les quatre variables suivantes, attachées au bloc @code{\paper} :

@itemize
@item @code{oddHeaderMarkup}
@item @code{evenHeaderMarkup}
@item @code{oddFooterMarkup}
@item @code{evenFooterMarkup}
@end itemize

@cindex markup conditionnel
@cindex condition et markup
@cindex on-the-fly
@funindex \on-the-fly

L'instruction @code{\on-the-fly} au sein d'un @code{\markup} permet
d'ajouter, lorsque certaines conditions sont respectées, des éléments
au texte des entête et pied de page définis dans le bloc @code{\paper}.
En voici la syntaxe :

@example
@code{variable} = @code{\markup} @{
  ...
  @code{\on-the-fly} #@var{procédure} @var{markup}
  ...
@}
@end example

La @var{procédure} est appelée à chaque fois que la commande
@code{\markup} où elle apparaît est évaluée.  La @var{procédure}
effectuera un test de conformité particulière et interprètera, autrement
dit imprimera l'argument @var{markup} si et seulement si cette
condition est remplie.

LilyPond dispose d'ores et déjà d'un certain nombre de procédures :

@quotation
@multitable {print-page-number-check-first-----} {ce n'est la première page du book--}

@headitem  Nom de la procédure      @tab  Condition testée

@item print-page-number-check-first @tab  il faut imprimer ce numéro de page.
@item create-page-number-stencil    @tab  'print-page-numbers est vrai.
@item print-all-headers             @tab  'print-all-headers est vrai.
@item first-page                    @tab  c'est la première page du @emph{book}.
@item (on-page nombre)              @tab  page number = nombre
@item last-page                     @tab  c'est la dernière page du @emph{book}.
@item not-first-page                @tab  ce n'est la première page du @emph{book}.
@item part-first-page               @tab  c'est la première page de la partie.
@item part-last-page                @tab  c'est la dernière page de la partie.
@item not-single-page               @tab  cette partie fait plus d'une page.

@end multitable
@end quotation

L'exemple suivant illustre  la manière de centrer son numéro au bas de
chaque page.  Il nous faut tout d'abord annuler la définition de
@code{oddHeaderMarkup} et @code{evenHeaderMarkup} à l'aide d'un
@emph{markup} @code{\null}. Nous redéfinissons ensuite
@code{oddFooterMarkup} pour qu'il contienne le numéro de page, centré.
Enfin, nous appliquons le même paramétrage au @code{\oddFooterMarkup}.

@lilypond[papersize=a8,quote,verbatim,noragged-right]
\book {
  \paper {
    print-page-number = ##t
    print-first-page-number = ##t
    oddHeaderMarkup = \markup \null
    evenHeaderMarkup = \markup \null
    oddFooterMarkup = \markup {
      \fill-line {
        \on-the-fly #print-page-number-check-first
        \fromproperty #'page:page-number-string
      }
    }
    evenFooterMarkup = \oddFooterMarkup
  }
  \score {
    \new Staff { s1 \break s1 \break s1 }
  }
}
@end lilypond

Plusieurs conditions @code{\on-the-fly} mentionnées l'une à la suite de
l'autre se cumulent.  Ainsi, par exemple,

@example
  @code{\on-the-fly #first-page}
  @code{\on-the-fly #last-page}
  @code{@{ \markup ... \fromproperty #'header: ... @}}
@end example

teste si la sortie tient sur une page unique.

@seealso
Manuel de notation :
@ref{Contenu des blocs de titrage},
@ref{Mise en forme par défaut des titrages}.

fichiers d'initialisation :
@file{../ly/titling-init.ly}.


@node Notes de bas de page
@subsection Notes de bas de page
@translationof Creating footnotes

LilyPond dispose de deux méthodes pour créer des notes de bas de page,
l'une automatisée, et l'autre manuelle.

@menu
* Considérations générales en matière de note de bas de page::
* Notes de bas de page automatiques::
* Notes de bas de page manuelles::
@end menu


@node Considérations générales en matière de note de bas de page
@unnumberedsubsubsec Considérations générales en matière de note de bas de page
@translationof Footnotes overview

Il est parfois judicieux, notamment lorsqu'une annotation ou un
commentaire gênerait la lecture de la partition, de les reporter en bas
de page.

Les notes de bas de page automatiques font appel à un compteur
numérique incrémenté automatiquement ; les notes de bas de page
manuelles vous laissent le libre choix de l'appel (l'indicateur).  Une
note de bas de page s'applique comme un @code{\tweak} ; elle peut donc
s'attacher directement à un objet graphique créé par la plupart des
éléments musicaux ou événements rattachés.  Lorsque ce n'est pas
possible, par exemple sur une barre de mesure ou un changement de
métrique -- l'objet étant alors le résultat d'une modification de
propriété --, les notes de bas de page peuvent être spécifiées en tant
qu'événement musical indépendant et affectant tous les objets d'un
type particulier à un instant particulier.

Examinons la forme développée d'une commande de note de bas de page :

@example
\footnote @var{marque} @var{décalage} @var{nom-grob} @var{annotation}
@var{musique}
@end example

Ses arguments peuvent se définir ainsi :

@table @var
@item marque
un @emph{markup} ou une chaîne de caractères identifiant l'annotation
tant au niveau de l'appel que de la note qui apparaîtra au bas de la
page.  L'absence de cet élément -- ou une valeur de @code{\default} --
incrémentera le compteur.

@item décalage
une paire de nombres -- @samp{#(2 . 1)} par exemple -- spécifiant le
décalage de la marque, en abscisse et en ordonnée, par rapport au point
de référence.

@item nom-grob
le type d'objet à annoter -- @samp{#'Flag} par exemple.  Lorsque cet
élément est spécifié, c'est l'objet en question qui servira de point de
référence, même s'il trouve son origine non pas directement dans
l'élément @var{musique} mais dans un objet en résultant.  Son absence ou
une valeur de @code{\default} ne permet d'annoter que des objets
directement créés.

@item annotation
un @emph{markup} ou une chaîne de caractères qui sera reporté au bas de
la page.

@item musique
l'élément qui fait l'objet du commentaire, qu'il s'agisse d'un
événement musical, de l'un des constituants d'un accord ou d'un
événement rattaché.  Bien qu'il ne puisse être omis, il peut être
remplacé par @code{\default}, auquel cas l'annotation ne sera pas
rattachée à une expression musicale particulière, mais plutôt à un
instant précis.  L'argument @var{nom-grob} est alors obligatoire pour
sélectionner le type d'objet affecté -- @samp{#'TimeSignature} par
exemple.
@end table

Tout comme pour la commande @code{\tweak}, lorsqu'un @code{\footnote}
s'applique à un événement rattaché ou à une articulation, il devra être
précédé d'un @code{-} de telle sorte que l'analyseur syntaxique en
attache le résultat à la note ou au silence précédant.


@node Notes de bas de page automatiques
@unnumberedsubsubsec Notes de bas de page automatiques
@translationof Automatic footnotes

@cindex note de bas de page automatique
@cindex bas de page, note automatique

@funindex \footnote
@funindex footnote

La commande @code{\footnote} permet de générer automatiquement des notes
de bas de page.  Elle requiert quatre arguments : la position
@samp{(x . y)} de l'appel de note, le @var{nom-grob} optionnel
spécifiant l'objet de rendu auquel s'applique le commentaire,
l'@var{annotation} qui apparaîtra au bas de la page, et enfin la
@var{musique} à laquelle se rapporte l'annotation.

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote #'(0.5 . -2)
      \markup { La première note }
    a'4 b8
    \footnote #'(0.5 . 1) #'Flag
      \markup { La troisième note }
    e\noBeam c4 d4
  }
}
@end lilypond

L'annotation d'un accord suit la même règle :

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    <
    \footnote #'(1 . -1.25) "Voici un do" c
    \footnote #'(2 . -0.25) \markup { \italic "Un mi bémol" } es
    \footnote #'(2 . 3) \markup { \bold "Ceci est un sol" } g
    >1
  }
}
@end lilypond

@warning{Lorsque plusieurs notes de bas de page se rapportent à un même
empilement vertical, les notes apparaîtront dans l'ordre vertical des
appels, autrement dit celui positionné le plus haut en premier, et ainsi
de suite.}

Voici quelques exemples d'objets annotés automatiquement.  Vous pouvez
constater l'agencement des annotations correspondantes avec le copyright
et le pied de page.

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { copyright = \markup { "Copyright 1970" } }
  \relative c' {
    a'4-\footnote #'(-3 . 0) \markup { \bold Forte } \f
    -\footnote #'(0 . 1.5) \markup { A slur } (
    b8)-\footnote #'(0 . -2) \markup { Beam } [ e]
    \footnote #'(1 . -1) #'Stem
      \markup  { \teeny { This is a stem } }
    c4
    \footnote #'(0 . 0.5) #'AccidentalCautionary
      \markup \italic { A cautionary accidental }
    \footnote #'(1 . 1) "The note itself"
    dis?4-\footnote #'(0.5 . -0.5) \markup \italic { Slow Down }
         _"rit."
  }
}
@end lilypond

Une note de bas de page affectant un @code{\markup} de haut niveau
s'introduit par la commande @code{\auto-footnote} : 

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \markup { \auto-footnote "A simple tune" \italic "By me" }
  \relative c' {
    a'4 b8 e c4 d
  }
}
@end lilypond


@node Notes de bas de page manuelles
@unnumberedsubsubsec Notes de bas de page manuelles
@translationof Manual footnotes

@cindex note de bas de page manuelle
@cindex bas de page, note manuelle

LilyPond permet aussi de créer des notes de bas de page manuelles :
la commande @code{\footnote} prend alors un argument supplémentaire :
la @var{marque}, qui contient l'appel qui s'attache à la note ou à
l'objet référencé.  Contrairement aux notes de bas de page automatiques,
l'annotation en bas de page ne sera pas précédée de la @var{marque} ;
l'indicateur  visuel est laissé à l'appréciation de l'utilisateur.
LilyPond ne s'attache ici qu'à faire apparaître l'annotation au bas de
la même page.

La commande @code{\footnote} s'utilise de la même manière que dans le
cas de notes automatiques.

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote
          "1" #'(0.5 . -2)
          \markup { \italic "1. The first note" }
    a'4
    b8
    \footnote
          \markup { \bold "2" } #'(0.5 . 1)
          "2. The second note"
    e
    c4
    d-\footnote "3" #'(0.5 . -1) "3. Piano" \p
  }
}
@end lilypond

L'annotation d'un accord suit la même règle :

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    <
    \footnote "1" #'(1 . -1.25) "1. C" c
    \footnote
       \markup { \bold "b" } #'(2 . -0.25) "b. E-flat" es
    \footnote "3" #'(2 . 3) \markup { \italic "iii. G" } g
    >1
  }
}
@end lilypond

@warning{Lorsque plusieurs notes de bas de page se rapportent à un même
empilement vertical, les notes apparaîtront dans l'ordre vertical des
appels, autrement dit celui positionné le plus haut en premier, et ainsi
de suite.}

Voici quelques exemples d'objets annotés manuellement.  Vous pouvez
constater l'agencement des annotations correspondantes avec le copyright
et le pied de page.

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    a'4-\footnote
      \markup { \teeny 1 } #'(-3 . 0)
      \markup { 1. \bold Forte } \f
    -\footnote
      \markup { \teeny b } #'(0 . 1.5)
      \markup { b. A slur } (
    b8)-\footnote
      \markup { \teeny 3 } #'(0 . -2)
      \markup { 3. Beam } [
    e]
    \footnote
      \markup { 4 } #'(1 . -1) #'Stem
      \markup  { \bold 4. { This is a stem } }
    c4
    \footnote
      \markup \concat \teeny { "sharp (v)" }
          #'(0 . 0.5) #'AccidentalCautionary
      \markup \italic { v. A cautionary accidental }
    dis?4-\footnote
      \markup \concat \teeny { "a" } #'(0.5 . -0.5)
      \markup \italic { a. Slow Down } _"rit."
    \footnote
      \markup { \teeny \musicglyph #"rests.4" }
          #'(1.5 . -0.25)
      \markup { \null } \breathe
  }
}
@end lilypond

L'annotation manuelle d'un @code{\markup} de haut niveau répond à la
syntaxe suivante :

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \markup { "A simple tune" \footnote "*" \italic "* By me" }
  \relative c' {
    a'4 b8 e c4 d4
  }
}
@end lilypond

@seealso
Manuel d'initiation :
@rlearning{Objets et interfaces}.

Manuel de notation :
@ref{Commentaires textuels},
@ref{Indications textuelles},
@ref{Info-bulle},
@ref{Mise en forme de la page},
@ref{Titres et entêtes}.

Référence des propriétés internes :
@rinternals{FootnoteEvent},
@rinternals{FootnoteItem},
@rinternals{FootnoteSpanner},
@rinternals{Footnote_engraver}.

@knownissues
Un silence multimesures ne peut se voir affecter une note de bas de
page.

Les notes de bas de page ne peuvent que s'empiler l'une au-dessus de
l'autre ; elles ne seront jamais présentées à la queue leu leu.
Les notes de bas de page peuvent générer des chevauchements quand elles
sont trop nombreuses sur une même page.

Dès lors que vous utilisez une commande de note de bas de page manuelle,
le bloc @code{\paper} doit contenir la mention
@w{@code{footnote-auto-number = ##f}}.


@node Référencement des numéros de page
@subsection Référencement des numéros de page
@translationof Reference to page numbers

LilyPond vous permet, à l'aide de la commande @code{\label}, d'insérer
des points de référence dans un ouvrage, aussi bien en dehors qu'au fil
de la musique.  Ce point de référence pourra être ensuite repris à
l'intérieur d'un @emph{markup} ; vous pourrez même y ajouter le
numéro de page grâce à la commande de @emph{markup} @code{\page-ref}.

@c KEEP LY
@lilypond[verbatim]
\header { tagline = ##f }
\book {
  \label #'firstScore
  \score {
    {
      c'1
      \pageBreak \mark A \label #'markA
      c'1
    }
  }

  \markup { Le premier mouvement débute à la page \page-ref #'firstScore "0" "?" }
  \markup { Le repère A est à la page \page-ref #'markA "0" "?" }
}
@end lilypond

L'instruction @code{\page-ref} prend trois arguments :
@enumerate
@item
le point de référence, sous la forme d'un symbole Scheme, comme par
exemple @code{#'firstScore},

@item
un @qq{emporte-pièce} afin d'estimer la longueur totale du
@emph{markup}, et

@item
un texte de remplacement au cas où la référence ne serait pas retrouvée.
@end enumerate

La présence de l'emporte-pièce est rendue nécessaire par le fait que les
@emph{markups} sont générés avant que les sauts de page ne soient
positionnés.  Bien que le numéro de page en question ne soit pas encore
déterminé, LilyPond doit connaître les dimensions de ce @emph{markup}.
Vous pouvez, lorsque l'ouvrage contiendra plus de dix pages, stipuler un
emporte-pièce sur deux caractères -- soit @code{"00"}.

@predefined
@funindex \label
@code{\label},
@funindex \page-ref
@code{\page-ref}.
@endpredefined


@node Table des matières
@subsection Table des matières
@translationof Table of contents

La commande @code{\markuplist \table-of-contents} vous permettra de
générer une table des matières.  Les éléments qui la composeront sont
créés par la commande @code{\tocItem}, insérée indépendamment ou au sein
d'une expression musicale.

@verbatim
\markuplist \table-of-contents
\pageBreak

\tocItem \markup "Premier mouvement"
\score {
  {
    c'4  % ...
    \tocItem \markup "Passage spécifique du premier mouvement"
    d'4  % ...
  }
}

\tocItem \markup "Second mouvement"
\score {
  {
    e'4 % ...
  }
}
@end verbatim

Les @emph{markups} dévolus à la mise en forme de la table des matières
se définissent dans le bloc @code{\paper}.  Il s'agit par défaut de
@code{tocTitleMarkup} pour le titre de la table, et de
@code{tocItemMarkup} pour ses éléments -- composés de leur libellé et
numéro de page.  Vous pouvez bien entendu personnaliser ces variables :

@verbatim
\paper {
  %% Translate the toc title into French:
  tocTitleMarkup = \markup \huge \column {
    \fill-line { \null "Table des matières" \null }
    \hspace #1
  }
  %% use larger font size
  tocItemMarkup = \markup \large \fill-line {
    \fromproperty #'toc:text \fromproperty #'toc:page
  }
}
@end verbatim

Notez bien la manière de référencer le libellé et le numéro de page dans
la définition de @code{tocItemMarkup}.

N'hésitez pas à définir vous-même d'autres commandes et @emph{markups}
afin de construire une table plus élaborée :
@itemize
@item 
commencez par définir une nouvelle variable de type @code{markup} au
sein du bloc @code{\paper},

@item
puis définissez une fonction musicale chargée d'insérer un élément de la
table à partir de cette variable.
@end itemize

Dans l'exemple qui suit, nous avons créé un nouveau style d'élément dans
le but de mentionner les actes dans la table des matières d'un opéra :

@verbatim
\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

tocAct =
#(define-music-function (parser location text) (markup?)
   (add-toc-item! 'tocActMarkup text))
@end verbatim

@lilypond[line-width=11.0\cm]
\header { tagline = ##f }
\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

tocAct =
#(define-music-function (parser location text) (markup?)
   (add-toc-item! 'tocActMarkup text))

\book {
  \markuplist \table-of-contents
  \tocAct \markup { Atto Primo }
  \tocItem \markup { Coro. Viva il nostro Alcide }
  \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
  \tocAct \markup { Atto Secondo }
  \tocItem \markup { Sinfonia }
  \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
  \markup \null
}
@end lilypond

L'élément et son numéro de page peuvent se rejoindre par une ligne
pointillée :

@lilypond[verbatim,quote]
\header { tagline = ##f }
\paper {
  tocItemMarkup = \tocItemWithDotsMarkup
}

\book {
  \markuplist \table-of-contents
  \tocItem \markup { Allegro }
  \tocItem \markup { Largo }
  \markup \null
}
@end lilypond

@predefined
@funindex \table-of-contents
@code{\table-of-contents},
@funindex \tocItem
@code{\tocItem}.
@endpredefined

@seealso
Fichiers d'initialisation :
@file{../ly/toc-init.ly}.


@node Travail sur des fichiers texte
@section Travail sur des fichiers texte
@translationof Working with input files

@menu
* Insertion de fichiers LilyPond::
* Différentes éditions à partir d'une même source::
* Caractères spéciaux::
@end menu


@node Insertion de fichiers LilyPond
@subsection Insertion de fichiers LilyPond
@translationof Including LilyPond files

@funindex \include
@cindex inclusion de fichiers

Lorsqu'un projet prend de l'importance en volume, il est judicieux de le
scinder en plusieurs fichiers, auxquels vous ferez référence avec un
simple

@example
\include "autrefichier.ly"
@end example

Une ligne @code{\include "autrefichier.ly"} dans un fichier revient à
recopier intégralement le contenu de @file{autrefichier.ly} à l'endroit
même ou est placée l'instruction @code{\include}.  Vous pouvez par
exemple écrire un fichier individuel par instrument, puis les regrouper
pour former le fichier @qq{conducteur}.  Les différentes variables
définies dans les fichiers séparés seront normalement reprises et
utilisables dans le fichier formant le conducteur.  Les sections
balisées dans les fichiers individuels peuvent être réutilisées en
différents endroit de la partition, comme expliqué à la rubrique
@ref{Différentes éditions à partir d'une même source}.

Lorsque le fichier auquel il est fait référence se trouve dans le même
répertoire, donner seulement son nom en argument à la commande
@code{\include} suffit.  S'il se trouve ailleurs, vous devrez indiquer
le chemin d'accès, absolu ou relatif, en respectant toutefois la syntaxe
UNIX -- autrement dit, le séparateur de répertoire est une oblique
normale @code{/} et non l'oblique inverse @code{\} de DOS ou Windows.
Par exemple, si le fichier @file{truc.ly} se trouve dans le répertoire
supérieur au répertoire de travail, la ligne devra être

@example
\include "../truc.ly"
@end example

@noindent
ou bien, si les fichiers correspondant aux parties d'orchestre se
trouvent dans le sous-répertoire @file{parties} relativement au
répertoire courant, vous devrez mentionner

@example
\include "parties/VI.ly"
\include "parties/VII.ly"
... etc.
@end example

Les fichiers à inclure peuvent eux-mêmes contenir des instructions
@code{\include}.  Ces instructions @code{\include} de second niveau ne
pourront, par défaut, être interprétées qu'une fois intégrées dans le
fichier principal ; leur argument doit donc comporter le chemin
relativement au fichier principal et non par rapport au fichier dans
lequel cette inclusion est mentionnée.  Vous pouvez toutefois influer
sur ce comportement à l'aide de l'option @w{@code{-drelative-includes}}
en ligne de commande ou en ajoutant une clause
@code{#(ly:set-option 'relative-includes #t)} en tête du fichier
principal.  Une fois @code{relative-include} activé, le chemin à suivre
pour chacune des commandes @code{\include} sera pris relativement au
fichier qui la contient.  Cette option est vouée à être activée par
défaut dans une future version de LilyPond.

Vous pouvez inclure des fichiers dont vous spécifierez le chemin d'accès
sur la ligne de commande au moment de lancer la compilation.  L'appel à
ces fichiers ne mentionnera alors que leur nom.  Par exemple, si vous
voulez compiler avec cette méthode le fichier @file{principal.ly} qui
inclut des fichiers situés dans le sous-répertoire @file{parties},
placez vous dans le répertoire contenant @file{principal.ly}, puis tapez

@example
lilypond --include=parties principal.ly
@end example

tout en ayant bien dans @file{principal.ly}

@example
\include "VI.ly"
\include "VII.ly"
... etc
@end example

Lorsqu'un fichier est voué à être inclus dans nombre de partitions, vous
pouvez le placer dans le répertoire de LilyPond @file{../ly}.
Attention : ce répertoire varie selon votre installation, comme
indiqué au chapitre @rlearning{Autres sources de documentation}.  Ce
fichier sera inclus dès lors que vous fournirez uniquement son nom en
argument à la fonction @code{\include}.  C'est par exemple le cas du
fichier de définition particulier @file{gregorian.ly}.

Au moment où vous lancez LilyPond, un certain nombre de fichiers se
retrouvent inclus par défaut ; il suffit d'activer le mode verbeux
en faisant @w{@code{lilypond --verbose}} pour s'en rendre compte.  Vous
verrez ainsi défiler, en plus de nombreuses informations, le nom d'un
certain nombre de fichiers et de chemins d'accès.  Les fichiers les plus
important sont mentionnés au chapitre
@rlearning{Autres sources de documentation}.  Si vous venez à les
modifier, rappelez-vous qu'ils seront écrasés à l'installation d'une
nouvelle version de LilyPond.

Vous trouverez quelques exemples simples d'utilisation de la commande
@code{\include} au chapitre @rlearning{Conducteurs et parties}.

@seealso
Manuel d'initiation :
@rlearning{Autres sources de documentation},
@rlearning{Conducteurs et parties}.

@knownissues
Lorsque vous incluez un fichier qui porte le même nom que l'un des
fichiers d'initialisation de LilyPond, le fichier de la distribution de
LilyPond aura préséance.


@node Différentes éditions à partir d'une même source
@subsection Différentes éditions à partir d'une même source
@translationof Different editions from one source

Plusieurs méthodes permettent de générer différentes versions d'une
partition à partir d'une même source.  Les variables -- ou
identificateurs -- sont sûrement le moyen le plus simple de combiner de
différente manière des passages relativement longs, alors que les
balises permettront de sélectionner de courts fragments selon leur
utilisation.

Quelle que soit la méthode utilisée, séparer la notation de la structure
de la partition vous donnera plus de liberté dans l'agencement de
l'ouvrage final, puisque vous ne reviendrez pas sur la musique qui le
compose.

@menu
* Utilisation de variables::
* Utilisation de balises::
* Globalisation des réglages::
@end menu


@node Utilisation de variables
@unnumberedsubsubsec Utilisation de variables
@translationof Using variables

@cindex variables, utilisation de

Un fragment musical identifié par une variable est réutilisable à divers
endroits de la partition, comme nous l'avons vu à la rubrique
@rlearning{Organisation du code source avec des variables}.  Par
exemple, une partition pour chœur @notation{a cappella} comporte souvent
une réduction pour piano reprenant toutes les voix ; il s'agit de
la même musique, et vous ne devrez donc la saisir qu'une seule fois.
D'autre part, la musique issue de deux variables peut se combiner sur
une seule portée, comme nous l'avons vu à la rubrique
@ref{Regroupement automatique de parties}.  Prenons l'exemple suivant :

@lilypond[verbatim,quote]
sopranoMusic = \relative c'' { a4 b c b8( a) }
altoMusic = \relative g' { e4 e e f }
tenorMusic = \relative c' { c4 b e d8( c) }
bassMusic = \relative c' { a4 gis a d, }
allLyrics = \lyricmode {King of glo -- ry }
<<
  \new Staff = "Soprano" \sopranoMusic
  \new Lyrics \allLyrics
  \new Staff = "Alto" \altoMusic
  \new Lyrics \allLyrics
  \new Staff = "Tenor" {
    \clef "treble_8"
    \tenorMusic
  }
  \new Lyrics \allLyrics
  \new Staff = "Bass" {
    \clef "bass"
    \bassMusic
  }
  \new Lyrics \allLyrics
  \new PianoStaff <<
    \new Staff = "RH" {
      \set Staff.printPartCombineTexts = ##f
      \partcombine
      \sopranoMusic
      \altoMusic
    }
    \new Staff = "LH" {
      \set Staff.printPartCombineTexts = ##f
      \clef "bass"
      \partcombine
      \tenorMusic
      \bassMusic
    }
  >>
>>
@end lilypond

Générer une partition chorale ou la réduction pour piano ne requiert que
de modifier la structure des éléments, sans aucunement toucher à la
musique.

Dans le cas d'une partition relativement longue, vous pouvez isoler la
définition des différentes variables dans des fichiers séparés que vous
rappellerez ensuite, comme indiqué à la rubrique
@ref{Insertion de fichiers LilyPond}.


@node Utilisation de balises
@unnumberedsubsubsec Utilisation de balises
@translationof Using tags

@funindex \tag
@funindex \keepWithTag
@funindex \removeWithTag
@funindex \pushToTag
@funindex \appendToTag
@cindex tag
@cindex balise

La commande @code{\tag #'@var{partieA}} affecte à une expression
musicale le nom @var{partieA}.  Les expressions ainsi balisées pourront
être filtrées par la suite, à l'aide de @code{\keepWithTag #'@var{nom}}
ou @code{\removeWithTag #'@var{nom}}.  Ces filtres fonctionnent de la
manière suivante :

@multitable @columnfractions .5 .5
@headitem Filtre
  @tab Résultat

@item
Musique balisée précédée de @code{\keepWithTag #'@var{nom}}
 @tab Musique non balisée et musique balisée par @var{nom} seront
 incluses ; la musique balisée autrement est exclue.

@item
Musique balisée précédée de @code{\removeWithTag #'@var{nom}}
 @tab Musique non balisée et fragments appelés autrement que @var{nom}
 seront inclus ; la musique balisée par @var{nom} est exclue.

@item
Musique balisée non précédée de @code{\keepWithTag} ou
@code{\removeWithTag}
 @tab Musique balisée et non balisée seront incluses.

@end multitable

Les arguments des commandes @code{\tag}, @code{\keepWithTag} et
@code{\removeWithTag} doivent être un symbole (tel que
@code{#'conducteur} ou @code{#'partie}), suivi d'une expression
musicale.

Dans l'exemple qui suit, nous obtenons deux versions du même extrait,
l'une pour le conducteur, l'autre pour l'instrumentiste qui, elle,
comportera les ornements développés.

@lilypond[verbatim,quote]
music = \relative g' {
  g8. c32 d
  \tag #'trills { d8.\trill }
  \tag #'expand { \repeat unfold 3 { e32 d } }
  c32 d
 }

\score {
  \keepWithTag #'trills \music
}
\score {
  \keepWithTag #'expand \music
}
@end lilypond

@noindent
Il est parfois plus aisé d'exclure des fragments :

@lilypond[verbatim,quote]
music = \relative g' {
  g8. c32 d
  \tag #'trills { d8.\trill }
  \tag #'expand {\repeat unfold 3 { e32 d } }
  c32 d
 }

\score {
  \removeWithTag #'expand
  \music
}
\score {
  \removeWithTag #'trills
  \music
}
@end lilypond

Ce principe de filtrage peut s'appliquer aux articulations, textes etc.
Il suffit de positionner

@example
-\tag #@var{ma-balise}
@end example

@noindent
avant l'articulation ou le texte, comme ici :

@example
c1-\tag #'doigt ^4
c1-\tag #'gaffe ^"Attention !"
@end example

@noindent
Ceci définira une note avec une indication conditionnelle de doigté ou
un texte.

Vous pouvez baliser différemment la même expression musicale en
saisissant plusieurs @code{\tag} :

@lilypond[quote,verbatim]
music = \relative c'' {
  \tag #'a \tag #'both { a4 a a a }
  \tag #'b \tag #'both { b4 b b b }
}
<<
\keepWithTag #'a \music
\keepWithTag #'b \music
\keepWithTag #'both \music
>>
@end lilypond

L'application concomitante de plusieurs filtres @code{\removeWithTag} à
la même expression musicale permet d'exclure plusieurs balisages :

@lilypond[verbatim,quote]
music = \relative c'' {
\tag #'A { a4 a a a }
\tag #'B { b4 b b b }
\tag #'C { c4 c c c }
\tag #'D { d4 d d d }
}
{
\removeWithTag #'B
\removeWithTag #'C
\music
}
@end lilypond

L'application de plus d'un filtre @code{\keepWithTag} à la même
expression musicale aboutit à l'exclusion de @b{tous} les balisages.
En effet, si le premier filtre exclut tous les autres balisages,
l'application du second exclura les effets du premier.

Il peut arriver que vous ayez besoin de raccorder quelque chose en un
point particulier d'une expression musicale.  Les commandes
@code{\pushToTag} et @code{\appendToTag} permettent d'insérer du
matériau, qu'il soit antérieur ou postérieur, à des @code{éléments}
d'une construction musicale existante.  La musique séquentielle ou
simultanée comporte assurément des @code{éléments} :

@lilypond[verbatim,quote]
test = { \tag #'here { \tag #'here <<c''>> } }

{
  \pushToTag #'here c'
  \pushToTag #'here e'
  \pushToTag #'here g' \test
  \appendToTag #'here c'
  \appendToTag #'here e'
  \appendToTag #'here g' \test
}
@end lilypond

Ces deux instructions sont affectées d'une balise, le matériau à
raccorder à chaque instance de la balise, et l'expression balisée.
Ces instructions prennent soin de recopier tout ce qui doit être
modifié, de telle sorte que l'expression @code{\test} originale conserve
tout son sens.
 
@seealso
Manuel d'initiation :
@rlearning{Organisation du code source avec des variables}.

Manuel de notation :
@ref{Regroupement automatique de parties},
@ref{Insertion de fichiers LilyPond}.


@ignore
@c This warning is more general than this placement implies.
@c Rests are not merged whether or not they come from tagged sections.
@c Should be deleted?  -td

@knownissues
Lorsqu'elles comportent des silences, ceux-ci ne seront pas fusionnés
si vous imprimez une partition avec les deux sections balisées.

@end ignore


@node Globalisation des réglages
@unnumberedsubsubsec Globalisation des réglages
@translationof Using global settings

@cindex include-settings

Vous pouvez regrouper dans un fichier indépendant vos réglages
personnels que vous inclurez au besoin :

@example
lilypond -dinclude-settings=MES_REGLAGES.ly MA_PARTITION.ly
@end example

Vous pouvez ainsi stocker dans un fichier séparé vos réglages en matière
de format de papier, de fontes utilisées ou vos définitions
particulières.  Selon le fichier de réglages que vous mentionnerez, vous
obtiendrez facilement différentes éditions à partir d'une même source
quelle qu'elle soit.

Cette technique peut s'utiliser en combinaison avec des feuilles de
styles, comme indiqué au chapitre @rlearning{Feuilles de style}.

@seealso
Manuel d'initiation :
@rlearning{Organisation du code source avec des variables},
@rlearning{Feuilles de style}.

Manuel de notation :
@ref{Insertion de fichiers LilyPond}.


@node Caractères spéciaux
@subsection Caractères spéciaux
@translationof Special characters

@cindex caractères spéciaux
@cindex non-ASCII, caractères

@menu
* Codage du texte::
* Unicode::
* Équivalents ASCII::
@end menu


@node Codage du texte
@unnumberedsubsubsec Codage du texte
@translationof Text encoding

@cindex UTF-8

LilyPond utilise le jeu de caractères défini par le consortium Unicode
et la norme ISO/CEI 10646.  Chaque caractère est identifié par un
nom unique et associé à un point de code, ce qui permet dans l'absolu de
couvrir tous les langages.  Unicode permet de coder tous les caractères
utilisés par toutes les langues écrites du monde.  LilyPond utilise le
codage UTF-8 (UTF pour @emph{Unicode Transformation Format}) qui permet
de représenter les caractères latins sur un octet et les autres sur une
longueur allant jusqu'à quatre octets.

L'apparence réelle des caractères est déterminée par les glyphes ou
graphèmes tels que définis dans les différentes polices disponibles.
Une police, ou une fonte, définit la mise en correspondance d'un
sous-ensemble de points de code unicode en glyphes.  LilyPond recourt à
la bibliothèque Pango pour assurer le rendu des textes multilingues.

LilyPond n'effectue aucune conversion d'encodage que ce soit.  Ceci
implique donc que tout texte -- un titre, des paroles ou même une
instruction musicale -- comportant des caractères non ASCII soit 
codé en UTF-8.  Le plus sûr moyen de saisir du texte de la sorte
consiste à utiliser un éditeur supportant l'unicode et à enregistrer vos
fichier en UTF-8.  C'est le cas pour la plupart des éditeurs actuels,
que ce soit vim, Emacs, jEdit et GEdit.  Tous les systèmes Windows
postérieurs à NT utilisent Unicode en natif ; même Notepad est
capable d'éditer et sauvegarder un fichier en UTF-8 -- sans parler de
l'excellente alternative qu'est BabelPad.

La compilation d'un fichier LilyPond comportant des caractères non ASCII
qui n'aurait pas été enregistré dans l'encodage UTF-8 vous renverra
l'erreur

@example
FT_Get_Glyph_Name () erreur : invalid argument
@end example

Voici un exemple utilisant du texte en cyrillique, en hébreux et en
portugais.

@lilypond[quote]
%c No verbatim here as the code does not display correctly in PDF
% Cyrillic
bulgarian = \lyricmode {
  Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
}

% Hebrew
hebrew = \lyricmode {
  זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
}

% Portuguese
portuguese = \lyricmode {
  à vo -- cê uma can -- ção legal
}

\relative c' {
  c2 d e f g f e
}
\addlyrics { \bulgarian }
\addlyrics { \hebrew }
\addlyrics { \portuguese }
@end lilypond


@node Unicode
@unnumberedsubsubsec Unicode
@translationof Unicode

@cindex Unicode

Lorsque vous avez besoin d'un caractère dont vous connaissez le point de
code mais que votre éditeur ne permet pas de saisir directement, vous
pouvez utiliser les instructions @code{\char ##xhhhh} ou
@code{\char #dddd} au sein d'un bloc @code{\markup} -- @code{hhhh}
et @code{dddd} correspondant respectivement à la valeur hexadécimale ou
décimale.  Même s'il est inutile de saisir les zéros superflus, il est
de bon ton de stipuler les quatre caractères formant la représentation
hexadécimale.  Évitez cependant l'encodage UTF-8 d'un point de code
après un @code{\char} ; les encodages UTF-8 comprennent un bit
supplémentaire indiquant le nombre d'octets.  Une table de
correspondance entre les codes Unicode et le nom des caractères ainsi
que leur code hexadécimal est disponible sur le site du consortium
Unicode, @uref{http://www.unicode.org/}.

Par exemple, @code{\char ##x03BE} et @code{\char #958} correspondent
tous deux au caractère unicode U+03BE, dénommé @qq{Greek Small Letter
Xi}.

Quel que soit le point de code spécifié de cette manière, il ne vous
sera alors pas nécessaire d'enregistrer votre fichier en UTF-8.  Vous
devrez toutefois disposer d'une fonte contenant ce caractère qui soit
accessible à LilyPond.

L'exemple suivant illustre la manière d'insérer un caractère sous sa
forme hexadécimale, à la fois dans un repère, dans une articulation,
dans des paroles et dans du texte indépendant.

@lilypond[quote,verbatim]
\score {
  \relative c'' {
    c1 \mark \markup { \char ##x03EE }
    c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
  }
  \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
\markup { "Copyright 2008--2012" \char ##x00A9 }
@end lilypond

@cindex copyright

Le signe @emph{copyright} dans le champ de titrage consacré s'inscrit de
la manière suivante :

@example
\header @{
  copyright = \markup @{ \char ##x00A9 "2008" @}
@}
@end example


@node Équivalents ASCII
@unnumberedsubsubsec Équivalents ASCII
@translationof ASCII aliases

Dès lors que vous aurez inclus la liste de leur équivalent ASCII,
LilyPond reconnaîtra un certain nombre de caractères spéciaux :

@lilypond[quote,verbatim]
\paper {
  #(include-special-characters)
}

\markup "&flqq; &ndash; &OE;uvre incomplète&hellip; &frqq;"

\score {
  \new Staff { \repeat unfold 9 a'4 }
  \addlyrics {
    This is al -- so wor -- kin'~in ly -- rics: &ndash;_&OE;&hellip;
  }
}

\markup \column {
  "The replacement can be disabled:"
  "&ndash; &OE; &hellip;"
  \override #'(replacement-alist . ()) "&ndash; &OE; &hellip;"
}
@end lilypond

L'extension de cette liste est possible aussi bien de manière globale :

@lilypond[quote,verbatim]
\paper {
  #(add-text-replacements!
    '(("100" . "hundred")
      ("dpi" . "dots per inch")))
}
\markup "A 100 dpi."
@end lilypond

qu'en un point particulier de votre source :

@lilypond[quote,verbatim]
\markup \replace #'(("100" . "hundred")
                    ("dpi" . "dots per inch")) "A 100 dpi."
@end lilypond

@seealso
Manuel de notation :
@ref{Liste des caractères spéciaux}.

Fichiers d'initialisation :
@file{ly/text-replacements.ly}.


@node Contrôle des sorties
@section Contrôle des sorties
@translationof Controlling output

@menu
* Extraction de fragments musicaux::
* Ignorer des passages de la partition::
* Formats de sortie alternatifs::
* Changement des fontes musicales::
@end menu


@node Extraction de fragments musicaux
@subsection Extraction de fragments musicaux
@translationof Extracting fragments of music

LilyPond permet d'extraire des fragments d'une partition à l'instar du
choriste amateur qui alimente son album avec des coupures de journaux.

Vous devrez pour cela définir les mesures à découper.  La définition
suivante, incluse dans votre fichier source,

@verbatim
\layout {
  clip-regions
  = #(list
      (cons
       (make-rhythmic-location 5 1 2)
       (make-rhythmic-location 7 3 4)))
}
@end verbatim

@noindent
vous permettra d'extraire un fragment compris entre le milieu de la
cinquième mesure et quelque part dans la septième.  Le triplet
@code{5 1 2} signifie : après la durée d'une blanche dans la mesure 5 ;
le @code{7 3 4} signifie quant à lui que l'on s'arrête à la mesure 7,
après la durée de trois noires.

Rien ne vous empêche d'extraire plusieurs fragments, dès lors que vous
définissez dans la liste d'autres paires d'emplacements rythmiques.

Cette fonctionnalité n'est toutefois effective que lorsque vous lancez
LilyPond avec l'option @w{@code{-dclip-systems}}.  Les @qq{coupures}
seront générées sous la forme de fichiers EPS, convertis en PDF ou PNG
selon le format que vous aurez stipulé.

Pour de plus amples informations quant au format des résultats,
consultez le chapitre @rprogram{Lancement de lilypond}.


@node Ignorer des passages de la partition
@subsection Ignorer des passages de la partition
@translationof Skipping corrected music

@funindex skipTypesetting
@funindex showFirstLength
@funindex showLastLength

Dans un travail de transcription ou de recopie de la musique, ce qui
vous intéresse plus particulièrement se situe à la fin, là même où vous
en êtes dans la notation.  Dans le but de gagner du temps dans le
processus de correction, vous pouvez @qq{escamoter} le reste et ne
générer que les dernières mesures en insérant

@verbatim
showLastLength = R1*5
\score { ... }
@end verbatim

@noindent
dans votre fichier source.  Ceci aura pour effet de ne générer que les
cinq dernières mesures -- si tant est que le morceau soit à 4/4 -- de
tous les @code{\score} de votre fichier.  Dans le cas d'un œuvre
conséquente, cette pratique s'avère fort utile puisqu'elle évite de tout
générer.  Vous pourriez aussi être amené à retravailler le début d'une
œuvre, pour y ajouter une partie par exemple, auquel cas c'est la
propriété @code{showFirstLength} que vous utiliserez.

Vous pouvez contrôler très finement les parties à escamoter, grâce au
commutateur @code{Score.skipTypesetting} : lorsqu'il est activé,
aucune gravure n'est réalisée.

Ce commutateur agit aussi sur la sortie MIDI.  Notez bien que tous les
événements seront escamotés, y compris les changements de tempo ou
d'instrument -- vous voilà prévenu !

@lilypond[quote,relative=2,ragged-right,verbatim]
c8 d
\set Score.skipTypesetting = ##t
e8 e e e e e e e
\set Score.skipTypesetting = ##f
c8 d b bes a g c2
@end lilypond

Dans le cadre de musique polyphonique, @code{Score.skipTypesetting}
s'applique à toutes les voix et portées.  Vous gagnerez donc encore plus
de temps.


@node Formats de sortie alternatifs
@subsection Formats de sortie alternatifs
@translationof Alternative output formats

@cindex scalable vector graphics
@cindex SVG, format de sortie
@cindex encapsulated postscript
@cindex EPS, format de sortie

En matière de partition imprimable, LilyPond génère par défaut des
documents au format PostScript (PS) et Portable Document Format (PDF).
Vous pouvez aussi obtenir des documents au format Scalable Vector
Graphics (SVG), Encapsulated PostScript (EPS) ou Portable Network
Graphics (PNG) dès lors que vous aurez lancé LilyPond en ligne de
commande avec l'option @i{ad hoc} -- voir
@rprogram{Utilisation en ligne de commande} à ce sujet.


@node Changement des fontes musicales
@subsection Changement des fontes musicales
@translationof Replacing the notation font

Gonville est une alternative à la fonte Feta que LilyPond utilise par
défaut.  Vous pouvez la télécharger à partir de
@example
@uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
@end example

Voici quelques mesures utilisant la police Gonville :

@c NOTE: these images are a bit big, but that's important
@c       for the font comparison.  -gp
@sourceimage{Gonville_after,,,}

Et ces même mesures avec la police de LilyPond, Feta :

@sourceimage{Gonville_before,,,}


@subsubheading Instructions d'installation pour MacOS
@translationof Installation Instructions for MacOS

Téléchargez puis décompressez l'archive zip.  Recopiez le répertoire
@code{lilyfonts} dans  @file{@var{SHARE_DIR}/lilypond/current} -- voir
@rlearning{Autres sources de documentation} à ce sujet.  Renommez le
répertoire @code{fonts} qui s'y trouve en @code{fonts_orig}, puis le
répertoire @code{lilyfonts} en @code{fonts}.  Il vous suffira, pour
retrouver la fonte Feta, de renommer @code{fonts_orig} en @code{fonts}.

@seealso
Manuel d'initiation :
@rlearning{Autres sources de documentation}.

@knownissues
Gonville ne permet pas de générer de la notation ancienne, et certains
glyphes ajoutés depuis lors aux jeux de caractères en soient absent.
Consultez le site de l'auteur pour de plus amples informations ainsi
qu'à propos des conditions d'utilisation.


@node Sortie MIDI
@section Sortie MIDI
@translationof MIDI output

@cindex son
@cindex MIDI

MIDI (Musical Instrument Digital Interface) constitue un standard en
matière de connexion et de contrôle des instruments électroniques.  Un
fichier MIDI contient une série de notes réparties dans différentes
pistes.  Il ne s'agit en rien d'un fichier sonore ; il vous faudra
un logiciel capable de traduire ces séries de notes en sons réels.

Vous pouvez convertir vos partition en fichier MIDI de manière à
entendre ce que vous avez saisi.  Ceci vous permet de contrôler aisément
ce que vous avez saisi : octaves et altérations erronées heurteront
votre oreille avertie grâce au MIDI.

Le fichier MIDI généré par LilyPond est relativement brut.  Vous pouvez
cependant obtenir un meilleur rendu avec @ref{Le script Articulate}.

Dans une sortie MIDI, LilyPond alloue un canal à chaque portée, tout en
réservant le canal 10 aux percussions. Dans la mesure ou un
périphérique MIDI ne comprend que 16 canaux, un fichier MIDI qui
comportera plus de quinze portées verra le même canal réutilisé.

@menu
* Création de fichiers MIDI::
* Le bloc MIDI::
* Contenu de la sortie MIDI::
* Répétitions et MIDI::
* Gestion des nuances en MIDI::
* MIDI et percussions::
* Le script Articulate::
@end menu


@node Création de fichiers MIDI
@subsection Création de fichiers MIDI
@translationof Creating MIDI files

LilyPond générera un fichier MIDI dès que vous ajouterez un bloc
@code{\midi} à la structure de votre partition, comme ici :

@example
\score @{
  @var{...musique...}
  \midi @{ @}
@}
@end example

Lorsque le bloc @code{\score} contient un bloc @code{\midi} mais pas de
bloc @code{\layout}, LilyPond ne produira qu'une sortie MIDI.  Si donc
vous avez besoin aussi d'un support visuel, vous devrez aussi mentionner
un bloc @code{\layout}.

@example
\score @{
  @var{...musique...}
  \midi @{ @}
  \layout @{ @}
@}
@end example

Hauteurs, durées, liaisons de prolongation, nuances et changements de
tempo seront interprétés et traduits en événements MIDI.  Les
indications de nuances, crescendos et decrescendos sont traduits en
niveau de volume ; les indications sous la forme d'une fraction
déterminée du volume disponible, et crescendos et decrescendos sous la
forme d'une progression linéaire entre les deux extrêmes.  Le rendu des
indications de nuance peut être désactivé pour le MIDI -- voir
@ref{Le bloc MIDI}.

Le tempo initial ainsi que ses changements sont normalement indiqués au
fil de la notation à l'aide de la commande @code{\tempo} ; ils seront
retranscrits dans le fichier MIDI.  La commande @code{\tempo} donne lieu
à l'impression d'une indication métronomique que vous pouvez toutefois
rendre invisible, comme indiqué à la rubrique
@ref{Indication métronomique}.  Une autre manière de spécifier le tempo
initial pour un fichier MIDI est indiquée plus avant -- voir
@ref{Le bloc MIDI}.

En raison de certaines limitations de Windows, les fichiers MIDI doivent
y porter l'extension @code{.mid}.  D'autres systèmes utilisent
l'extension @code{.midi}.  Si besoin est, placez la ligne suivante au
début de votre fichier source, avant l'ouverture de tout bloc
@code{\book}, @code{\bookpart} ou @code{\score} :

@example
#(ly:set-option 'midi-extension "midi")
@end example

Cette ligne déterminera @code{.midi} comme extension par défaut pour les
fichiers MIDI.

Vous pouvez aussi le faire en ligne de commande :

@example
lilypond … -dmidi-extension=midi fichierLily.ly
@end example


@unnumberedsubsubsec Noms d'instrument
@translationof Instrument names

@cindex instrument, nom d'
@funindex Staff.midiInstrument

L'instrument MIDI affecté à un canal particulier est déterminé par la
propriété @code{Staff.midiInstrument}.  Vous pouvez choisir l'un des
instruments répertoriés à l'annexe @ref{Instruments MIDI}.

@example
\new Staff @{
  \set Staff.midiInstrument = #"glockenspiel"
  @var{...notes...}
@}
@end example

@example
\new Staff \with @{midiInstrument = #"cello"@} @{
  @var{...notes...}
@}
@end example

Lorsque l'instrument choisi ne correspond pas exactement à l'une des
dénominations consacrées, LilyPond le replacera par un piano de concert
(@code{"acoustic grand"}).

@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{changing-midi-output-to-one-channel-per-voice.ly}

@knownissues
@c In 2.11 the following no longer seems to be a problem -td
@ignore
Un (de)crescendo non terminé ne sera pas correctement rendu en MIDI --
il y a nécessairement du silence.  Il vous faut donc lui donner une fin
explicite.  Par exemple,

@example
@{ a4\< b c d\f @}
@end example

@noindent
ne fonctionnera pas correctement, contrairement à

@example
@{ a4\< b c d\!\f @}
@end example
@end ignore

Un changement de volume ne peut intervenir que sur le démarrage d'une
note.  C'est la raison pour laquelle la succession d'un crescendo et
d'un diminuendo ne peut se produire sur une même note.

Certains lecteurs MIDI ne rendent pas correctement les changements de
tempo.  MS Windows Media Player et 
@uref{http://@/timidity@/.sourceforge@/.net/,timidity} le font sans
problème.


@node Le bloc MIDI
@subsection Le bloc MIDI
@translationof MIDI block

Dès lors que vous désirez obtenir une sortie MIDI, vous devrez inscrire
un bloc @code{\midi} au sein du bloc @code{\score}.  Son fonctionnement
est comparable à ce lui du bloc @code{\layout}, voire plus simple.  Si
le bloc @code{\midi} est la plupart du temps laissé vide, il peut
contenir des aménagements pour certains contextes, la définition de
contextes particuliers ou du code permettant de déterminer la valeur de
certaines propriétés.  L'exemple suivant détermine le tempo initial du
fichier MIDI tout en se passant de son indication sur la partition
imprimée.

@example
\score @{
  @var{...musique...}
  \midi @{
    \tempo 4 = 72
  @}
@}
@end example

Ici, le tempo est fixé à 72 noires à la minute.  Spécifier un tempo de
la sorte ne permet pas de donner une valeur pour une note pointée.  Vous
devrez, en pareil cas, subdiviser la note pointée en durée plus courte.
Par exemple, indiquer 90 à la noire pointée est équivalent à spécifier
270 croches à la minute :

@example
tempoWholesPerMinute = #(ly:make-moment 270 8)
@end example

@cindex MIDI et définition de contexte
@cindex contexte, définition en MIDI

La syntaxe permettant de définir un contexte pour le @code{\midi} est en
tout point identique à celle que vous utilisez dans le bloc
@code{\layout}, à ceci près que le @qq{graveur} est remplacé par un
@qq{interprète}.  Les différents contextes disponibles en matière de
MIDI sont répertoriés dans le fichier d'initialisation
@file{../ly/performer-init.ly} -- pour plus de détail, voir
@rlearning{Autres sources de documentation}.
Si vous voulez vous passer des nuances dans votre fichier MIDI, il vous
suffit d'insérer les lignes suivantes dans votre bloc
@code{\midi@{ @}}.

@example
\midi @{
  ...
  \context @{
    \Voice
    \remove "Dynamic_performer"
  @}
@}
@end example

LilyPond ne générera de sortie MIDI que si vous incluez un bloc
@code{\midi} dans la structure de la partition, initialisée par la
commande @code{\score}.

@example
\score @{
  @{ @dots{}notes@dots{} @}
  \midi @{ @}
@}
@end example


@node Contenu de la sortie MIDI
@subsection Contenu de la sortie MIDI
@translationof What goes into the MIDI output?

@c TODO Check grace notes - timing is suspect?


@unnumberedsubsubsec Éléments pris en compte dans le MIDI
@translationof Supported in MIDI

@cindex hauteurs en MIDI
@cindex MIDI, hauteurs
@cindex quart de ton en MIDI
@cindex MIDI, quart de ton
@cindex microtonalité en MIDI
@cindex MIDI, microtonalité
@cindex accords nommés en MIDI
@cindex MIDI, accords nommés
@cindex Rythme en MIDI
@cindex MIDI, Rythme
@cindex articulations et MIDI
@cindex MIDI et articulations
@cindex trilles et MIDI
@cindex MIDI et trilles
@c TODO etc

Un fichier MIDI généré par LilyPond comprendra les éléments de notation
suivants :

@itemize
@item
les hauteurs ;

@item
les microtonalités -- voir @ref{Altérations}.  Leur rendu nécessite
cependant un lecteur qui prenne en charge la modulation ;

@item
les accords nommés ;

@item
le rythme en tant que durée de note, y compris les nolets ;

@item
les trémolos, exceptés ceux utilisant la syntaxe
@qq{@code{:}[@var{nombre}]} ;

@item
les liaisons de prolongation ;

@item
les indications de nuance ;

@item
les crescendos et decrescendos s'étalant sur plusieurs notes ;

@item
les changements de tempo indiqués par un @code{\tempo} ;

@item
les paroles.
@end itemize

Si vous utilisez @ref{Le script Articulate}, d'autres éléments seront
alors inclus :

@itemize
@item articulations (lié, staccato, etc.),
@item trilles et groupettos,
@item rallentando et accelerando.
@end itemize


@unnumberedsubsubsec Éléments non pris en compte dans le MIDI
@translationof Unsupported in MIDI

@c TODO index as above

LilyPond ne peut générer d'événement MIDI pour les éléments
suivant, sauf à utiliser @ref{Le script Articulate} :

@itemize
@item
le rythme indiqué sous forme d'annotation (par ex. @emph{swing}) ;

@item
les changements de tempo indiqués sous forme d'annotation (sans
@code{\tempo}) ;

@item
les staccatos et autres articulations ou ornementations ;

@item
les liaisons d'articulation et de phrasé ;

@item
les crescendos ou decrescendos sur une seule note ;

@item
les trémolos indiqués par la syntaxe @qq{@code{:}[@var{nombre}]} ;

@item
la basse chiffrée ;

@item
les accords en microtonalité.
@end itemize


@node Répétitions et MIDI
@subsection Répétitions et MIDI
@translationof Repeats in MIDI

@cindex reprises développées
@cindex MIDI et reprises
@funindex \unfoldRepeats

Au prix de quelques réglages, les reprises de toutes sortes peuvent être
rendues dans le fichier MIDI.  Il suffit pour cela de recourir à la
fonction @code{\unfoldRepeats}, qui développe toutes les reprises.  En
d'autre termes, @code{\unfoldRepeats} transforme toutes les reprises
en reprises de type @code{unfold}.


@lilypond[quote,verbatim]
\unfoldRepeats {
  \repeat tremolo 8 {c'32 e' }
  \repeat percent 2 { c''8 d'' }
  \repeat volta 2 {c'4 d' e' f'}
  \alternative {
    { g' a' a' g' }
    {f' e' d' c' }
  }
}
\bar "|."
@end lilypond

Dans une partition comportant plusieurs voix, le développement des
reprises ne sera effectif en MIDI qu'à la condition que ces reprises
soient mentionnée correctement dans @strong{toutes} les voix.

Lorsque l'on veut utiliser @code{\unfoldRepeats} seulement pour le rendu
MIDI, il faut établir deux blocs @code{\score} : un pour le MIDI,
avec des reprises explicites, et l'autre pour la partition, avec des
reprises notées sous forme de barres de reprise, de trémolo ou de
symboles de pourcentage.  Par exemple

@example
\score @{
  @var{..musique..}
  \layout @{ ..  @}
@}
\score @{
  \unfoldRepeats @var{..musique..}
  \midi @{ .. @}
@}
@end example


@node Gestion des nuances en MIDI
@subsection Gestion des nuances en MIDI
@translationof Controlling MIDI dynamics

Les nuances MIDI sont générées par le @code{Dynamic_performer}, affecté
par défaut au contexte @code{Voice}.  Vous pouvez contrôler à la fois le
volume général, celui des indications de nuance ainsi que celui des
différents instruments.


@unnumberedsubsubsec Indications de nuance
@translationof Dynamic marks

Les indications de nuances sont transcrites en fraction du volume MIDI.
Nous allons, par défaut, de 0,25 pour un @notation{ppppp} à 0,95 pour un
@notation{fffff}.  Les correspondances entre nuance et fraction de
volume sont répertoriées dans le fichier @file{../scm/midi.scm} --
consultez la rubrique @rlearning{Autres sources de documentation} si
vous ne savez comment le localiser.  Vous pouvez modifier ou étendre ce
jeu grâce à une fonction qui prendra en argument une indication de
nuance et renverra la fraction désirée, puis en affectant cette fonction
à @code{Score.dynamicAbsoluteVolumeFunction}.

Prenons un exemple.  Votre partition comporte un  @notation{rinforzando}
que vous avez indiqué par @code{\rfz}.  Cette indication de nuance
n'étant pas répertoriée dans le jeu par défaut, elle ne produira aucun
effet en MIDI.  Il en sera d'ailleurs de même pour toute indication
créée de toute pièce à l'aide de l'instruction
@w{@code{make-dynamic-script}}.  Voici comment procéder pour ajuster le
volume MIDI de ce @notation{rinforzando} que le compositeur a indiqué.
La fonction Scheme définit une fraction de 0,9 en cas de @notation{rfz},
et demande d'utiliser la fonction par défaut dans les autre cas.

@lilypond[verbatim,quote]
#(define (myDynamics dynamic)
    (if (equal? dynamic "rfz")
      0.9
      (default-dynamic-absolute-volume dynamic)))

\score {
  \new Staff {
    \set Staff.midiInstrument = #"cello"
    \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
    \new Voice {
      \relative c'' {
        a4\pp b c-\rfz
      }
    }
  }
  \layout {}
  \midi {}
}
@end lilypond

Si vous étiez amené à devoir modifier l'intégralité du jeu des
correspondances, nous vous conseillons d'utiliser la procédure
@command{default-dynamic-absolute-volume} contenue dans le fichier
@file{../scm/midi.scm} ainsi que la table d'association comme base.
Le dernier exemple de cette partie illustre la manière de procéder.


@unnumberedsubsubsec Amplitude du volume en MIDI
@translationof Overall MIDI volume

Les valeurs extrêmes du volume MIDI des nuances se contrôlent à l'aide
des propriétés @code{midiMinimumVolume} et @code{midiMaximumVolume} qui
agissent au niveau @code{Score}.  Ces propriétés sont effectives dès
lors qu'une nuance est indiquée ; une nuance de départ est donc
requise pour que le volume soit ajusté dès le début de la partition.
Vous pouvez alors modifier la fraction correspondant à chaque nuance à
l'aide de la formule

@example
midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
@end example

Voici comment ajuster les nuances tout en limitant l'amplitude du volume
entre 0,2 et 0,5 :

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff {
      \key g \major
      \time 2/2
      \set Staff.midiInstrument = #"flute"
      \new Voice \relative c''' {
        r2 g\mp g fis~
        fis4 g8 fis e2~
        e4 d8 cis d2
      }
    }
    \new Staff {
      \key g \major
      \set Staff.midiInstrument = #"clarinet"
      \new Voice \relative c'' {
        b1\p a2. b8 a
        g2. fis8 e
        fis2 r
      }
    }
  >>
  \layout {}
  \midi {
    \context {
      \Score
      tempoWholesPerMinute = #(ly:make-moment 72 2)
      midiMinimumVolume = #0.2
      midiMaximumVolume = #0.5
    }
  }
}
@end lilypond


@unnumberedsubsubsec Égalisation de plusieurs instruments (i)
@translationof Equalizing different instruments (i)

La définition de l'amplitude du volume MIDI au niveau d'un contexte
@code{Staff} permet de gérer les volumes relatifs entre les différents
instruments.  Ceci constitue en quelque sorte un égaliseur, ce qui
permet d'améliorer notablement la qualité de la sortie MIDI.

La clarinette de l'exemple suivant jouera relativement moins fort que la
flûte.  Rappelez-vous que pour que cela fonctionne correctement, la
première note de chacun des instruments doit être affublée d'une
indication de nuance.

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff {
      \key g \major
      \time 2/2
      \set Staff.midiInstrument = #"flute"
      \set Staff.midiMinimumVolume = #0.7
      \set Staff.midiMaximumVolume = #0.9
      \new Voice \relative c''' {
        r2 g\mp g fis~
        fis4 g8 fis e2~
        e4 d8 cis d2
      }
    }
    \new Staff {
      \key g \major
      \set Staff.midiInstrument = #"clarinet"
      \set Staff.midiMinimumVolume = #0.3
      \set Staff.midiMaximumVolume = #0.6
      \new Voice \relative c'' {
        b1\p a2. b8 a
        g2. fis8 e
        fis2 r
      }
    }
  >>
  \layout {}
  \midi {
    \tempo 2 = 72
  }
}
@end lilypond


@unnumberedsubsubsec Égalisation de plusieurs instruments (ii)
@translationof Equalizing different instruments (ii)

Lorsque les propriétés volume minimum et maximum n'ont pas été définies,
LilyPond appliquera par défaut une légère égalisation pour quelques
instruments.  Les instrument concernés ainsi que le niveau d'égalisation
sont répertoriés dans une table @notation{instrument-equalizer-alist}
du fichier @file{../scm/midi.scm}.

Vous pouvez remplacer l'égaliseur basique en définissant une nouvelle
procédure Scheme @code{instrumentEqualizer} au sein du contexte
@code{Score}.  Cette procédure prend en unique argument le nom d'un
instrument MIDI et renverra une paire de fractions correspondant au
minimum et maximum de volume alloué à cet instrument.  Cette
substitution fonctionne selon le même principe que celui que nous avons
vu en début de chapitre avec @code{dynamicAbsoluteVolumeFunction}.
L'égaliseur par défaut, @notation{default-instrument-equalizer}, est
défini dans le fichier @file{../scm/midi.scm} ; son analyse vous
aidera à construire votre propre procédure.

Nous allons, dans l'exemple suivant, régler le volume relatif de la
flûte et de la clarinette -- au même niveau que dans le précédent.

@lilypond[verbatim,quote]
#(define my-instrument-equalizer-alist '())

#(set! my-instrument-equalizer-alist
  (append
    '(
      ("flute" . (0.7 . 0.9))
      ("clarinet" . (0.3 . 0.6)))
    my-instrument-equalizer-alist))

#(define (my-instrument-equalizer s)
  (let ((entry (assoc s my-instrument-equalizer-alist)))
    (if entry
      (cdr entry))))

\score {
  <<
    \new Staff {
      \key g \major
      \time 2/2
      \set Score.instrumentEqualizer = #my-instrument-equalizer
      \set Staff.midiInstrument = #"flute"
      \new Voice \relative c''' {
        r2 g\mp g fis~
        fis4 g8 fis e2~
        e4 d8 cis d2
      }
    }
    \new Staff {
      \key g \major
      \set Staff.midiInstrument = #"clarinet"
      \new Voice \relative c'' {
        b1\p a2. b8 a
        g2. fis8 e
        fis2 r
      }
    }
  >>
  \layout { }
  \midi {
    \tempo 2 = 72
  }
}
@end lilypond

@ignore
@c Delete when satisfied this is adequately covered elsewhere -td

@n ode Microtones in MIDI
@s ubsection Microtones in MIDI

@cindex microtones in MIDI

Microtones consisting of half sharps and half flats are exported
to the MIDI file and render correctly in MIDI players which support
pitch bending.  See @ref{Note names in other languages}.  Here is
an example showing all the half sharps and half flats.  It can be
copied out and compiled to test microtones in your MIDI player.

@lilypond[verbatim,quote]
\score {
  \relative c' {
    c4 cih cis cisih
    d4 dih ees eeh
    e4 eih f fih
    fis4 fisih g gih
    gis4 gisih a aih
    bes4 beh b bih
  }
  \layout {}
  \midi {}
}
@end lilypond
@end ignore


@node MIDI et percussions
@subsection MIDI et percussions
@translationof Percussion in MIDI

La notation pour percussions recourt généralement à un contexte
particulier -- le @code{DrumStaff} -- qui permet d'affecter directement
les instruments concernés au canal 10 qui leur est réservé.

Certains instruments, tels le xylophone, le marimba, le vibraphone ou
les timbales, se traitent cependant comme des instruments
@qq{classiques} puisqu'ils sont capables d'émettre des hauteurs
différentes ; leurs notation relève donc d'un contexte @code{Staff}
standard, et non d'un @code{DrumStaff} pour pouvoir être rendus
correctement en MIDI.

D'autres percussions, bien que n'émettant qu'un seul son et inclus dans
le standard @emph{general MIDI}, comme le tom mélodique ou le tambour
taiko, ne sont pas attachés au canal 10.  Ces instruments doivent
donc être saisi dans un contexte @code{Staff}, en utilisant la hauteur
appropriée.

De nombreux instruments de la famille des percussions, les castagnettes
par exemple,  n'existent pas dans le standard @emph{general MIDI}.
L'alternative, bien que peu satisfaisante, consiste à leur attribuer le
son le plus proche dans la banque standard.

@c TODO Expand with examples, and any other issues

@knownissues
Le standard @emph{general MIDI} ne dispose pas du @emph{rim shot} ;
LilyPond lui substitue un @emph{sidestick}.


@node Le script Articulate
@subsection Le script Articulate
@translationof The Articulate script

Vous obtiendrez un rendu MIDI plus @qq{réaliste} grâce au script
@code{articulate}.  Celui-ci va tout faire pour d'une part prendre en
compte les articulations (liaisons, staccato etc.) -- en ajoutant un
blanc aux notes raccourcies -- et, d'autre part, développer les trilles
ou groupettos ainsi que tenir compte des éventuels rallentando et
accelerando.

L'utilisation du script @code{articulate} se fait en deux temps.  Vous
devez dans un premier temps inclure son fichier d'initialisation en
ajoutant en tête de votre fichier la ligne

@example
\include "articulate.ly"
@end example

puis, dans le bloc @code{\score}, indiquer que toutes les répétitions
seront développées et appliquer la commande à votre musique :

@example
\unfoldRepeats \articulate <<
        tout le reste du bloc contenant la partition...
>>
@end example

Une fois votre fichier modifié de la sorte, vous constaterez que la
version imprimable aura été modifiée en profondeur.  Le bloc
@code{\midi} produira par contre un fichier MIDI de bien meilleure
qualité.

Bien que cela ne gène en rien le fonctionnement du script
@code{articulate}, lui adjoindre la commande @code{\unfoldRepeats} comme
illustré ci-dessus permettra le rendu d'un certain nombre
d'articulations tels les trilles.

@knownissues
Dans la mesure où le script @code{articulate} tend à raccourcir les
accords, certaines musiques, notamment pour l'orgue, paraîtront de moins
bonne qualité.


@node Extraction d'informations musicales
@section Extraction d'informations musicales
@translationof Extracting musical information

En plus de générer du graphisme et du MIDI, LilyPond peut présenter
l'information musicale sous forme textuelle.

@menu
* Affichage de notation au format LilyPond::
* Affichage de la musique sous forme d'expression Scheme::
* Enregistrement d'événements musicaux dans un fichier::
@end menu


@node Affichage de notation au format LilyPond
@subsection Affichage de notation au format LilyPond
@translationof Displaying LilyPond notation

@funindex \displayLilyMusic

La fonction musicale @code{\displayLilyMusic} permet d'afficher en
notation LilyPond une expression musicale.  Le résultat défilera dans le
terminal après avoir lancé LilyPond en ligne de commande.  Par exemple,

@example
@{
  \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
@}
@end example

affichera

@example
@{ a,4 cis e fis g @}
@end example

LilyPond affichera le résultat sous forme de message en console, au
milieu de toutes les informations de compilation.  Afin d'isoler ces
messages et enregistrer le résultat de la fonction
@code{\display@{MATÉRIAU@}}, pensez à rediriger la sortie vers un
fichier.

@example
lilypond fichier.ly > affichage.txt
@end example

@funindex \void

Vous noterez que LilyPond ne se contente pas de simplement afficher
l'expression musicale, mais procède aussi à son interprétation -- du
fait que @code{\displayLilyMusic} renvoie l'expression tout en
l'affichant.  S'il est bien pratique d'insérer un
@code{\displayLilyMusic} dans une expression musicale pour en obtenir
des informations, l'interprétation de cette expression peut toutefois
être évitée en ajoutant un @code{\void} avant l'instruction :

@example
@{
  \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
@}
@end example


@node Affichage de la musique sous forme d'expression Scheme
@subsection Affichage de la musique sous forme d'expression Scheme
@translationof Displaying scheme music expressions

Voir @rextend{Affichage d'expressions musicales}.


@node Enregistrement d'événements musicaux dans un fichier
@subsection Enregistrement d'événements musicaux dans un fichier
@translationof Saving music events to a file

LilyPond vous permet de sauvegarder dans un fichier séparé, sur la base
de la portée, les événements musicaux.  Vous devrez pour ce faire
inclure dans votre fichier maître un fichier d'initialisation
spécifique :

@example
\include "event-listener.ly"
@end example

Pour chaque portée que comporte votre partition, vous obtiendrez un
fichier @file{NOMFICHIER-PORTÉENOMMÉE.notes} ou
@file{NOMFICHIER-unnamed-staff.notes}.  Notez bien que si plusieurs
portées ne sont pas explicitement nommées, tous leurs événements seront
regroupés et mélangés dans le même fichier.  Le résultat ressemblera à
ceci :

@example
0.000   note     57       4   p-c 2 12
0.000   dynamic  f
0.250   note     62       4   p-c 7 12
0.500   note     66       8   p-c 9 12
0.625   note     69       8   p-c 14 12
0.750   rest     4
0.750   breathe
@end example

Il s'agit d'un tableau dont les colonnes sont délimitées par une
tabulation.  Chaque ligne comporte deux champs fixes suivis d'un certain
nombre de paramètres optionnels.

@example
@var{temps}  @var{type}  @var{...paramètres...}
@end example

Ces informations peuvent faire l'objet d'un retraitement par d'autres
programmes, comme des scripts python, aux fins de recherche en analyse
musicologique ou des expériences à partir du rendu de LilyPond.

@knownissues
Tous les événements ne sont pas pris en charge par
@file{event-listener.ly}.  Il s'agit en premier lieu d'une
démonstration, un @qq{proof of concept} du potentiel de LilyPond.  Si
certains des éléments que vous cherchez à obtenir n'apparaissent pas,
recopiez le fichier @file{event-listener.ly} dans votre répertoire et
modifiez-le de telle sorte qu'il travaille selon vos attentes.