Docs: remove implicit relative from translations; issue 4731

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

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

@ignore
    Translation of GIT committish: e8fd54aac6821d27c14b911a00f009a150e5fa50

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

@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::
* Génération de fichiers 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 @{
@dots{}
@}
@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{%@{ @dots{} %@}} -- 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{@dots{}musique@dots{}}
@}
@end example

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

@example
\markup @{
  @var{@dots{}texte@dots{}}
@}
@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{@dots{}}
@}
\markup @{
  @var{@dots{}}
@}
\score @{
  @var{@dots{}}
@}
@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 @{
   @dots{}texte du second couplet@dots{}
@}
\markup @{
   @dots{}texte du troisième couplet@dots{}
@}
\score @{
  @dots{}
  \header @{ piece = "Menuet" @}
@}
@end example

@funindex \bookpart

Plusieurs pièces seront regroupées dans un même « chapitre » à l'aide
d'un bloc @code{\bookpart}.  Ces différents « 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{} @}
  \paper @{ @dots{} @}
@}
\book @{
  \score @{ @dots{} @}
  \paper @{ @dots{} @}
@}
\book @{
  \score @{ @dots{} @}
  \paper @{ @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{} @}
  \paper @{ @dots{} @}
@}
\book @{
  \bookOutputSuffix "Menuet"
  \score @{ @dots{} @}
  \paper @{ @dots{} @}
@}
\book @{
  \bookOutputSuffix "Nocturne"
  \score @{ @dots{} @}
  \paper @{ @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{} @}
  \paper @{ @dots{} @}
@}
\book @{
  \bookOutputName "Menuet"
  \score @{ @dots{} @}
  \paper @{ @dots{} @}
@}
\book @{
  \bookOutputName "Nocturne"
  \score @{ @dots{} @}
  \paper @{ @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 valide pour tout le
fichier.  Il comporte en général les valeurs par défaut des champs de
titrage, tels le titre ou l'auteur entre autres, communs à tous les
blocs @code{\book} inclus dans le fichier -- voir
@ref{Généralités en matière de titrages}.

@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.  Le gestionnaire
par défaut est défini dans le fichier d'initialisation
@file{../scm/lily.scm}.

@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.  Le gestionnaire par défaut est défini dans le fichier
d'initialisation @file{../scm/lily.scm}.

@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.  Le gestionnaire par
défaut est défini dans le fichier d'initialisation
@file{../scm/lily.scm}.

@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{%@{ @dots{} %@}}.

@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 ouvrante 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} -- avant et après les commandes
@code{\override} et @code{\set}.

@end itemize

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

Manuel de notation :
@ref{Généralités en matière de titrages},
@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 dispensent beaucoup plus
d'informations.

@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
* Généralités en matière de titrages::
* Mise en forme par défaut des titrages subalternes::
* Mise en forme par défaut des entête et pied de page::
@end menu


@node Généralités en matière de titrages
@unnumberedsubsubsec Généralités en matière de titrages
@translationof Titles explained

Chaque bloc @code{\book} apparaissant dans un même fichier source
résultera en un fichier indépendant, comme indiqué à la rubrique
@ref{Structure de fichier}. Chacun de ces fichiers résultants comporte
trois endroits où placer des titrages : le @strong{titrage de l'ouvrage}
au début de chaque recueil (@emph{book}), les @strong{titrages de
partie} au début de chaque partie (@emph{bookpart}) et les
@strong{titrages de morceau} avant chaque pièce (@emph{score}).

La valeur des champs de titrage @code{title} (le titre) et
@code{composer} (le compositeur) se définissent dans des blocs
@code{\header} -- la syntaxe appropriée et la liste des différents
champs disponibles par défaut sont à la section
@ref{Mise en forme par défaut des titrages subalternes}.
Les titrages d'un ouvrage, de ses parties ou des morceaux qu'il contient
peuvent tous comporter les même champs bien que, par défaut, le titrage
d'un morceau se limite à @code{piece} et @code{opus}.

Les blocs @code{\header} peuvent se placer à quatre endroits différents
qui formeront une hiérarchie descendante :

@itemize

@item
En tête du fichier source, avant même tout bloc @code{\book},
@code{\bookpart} ou @code{\score} ;

@item
Au sein d'un bloc @code{\book} et en dehors de tout bloc
@code{\bookpart} ou @code{\score} qu'il contient ;

@item
Au sein d'un bloc @code{\bookpart} et en dehors de tout bloc
@code{\score} qu'il contient ;

@item
Après l'expression musicale incluse dans un bloc @code{\score}.

@end itemize

La valeur des différents champs sera filtrée en respectant cette
hiérarchie ; les valeurs persisteront à moins d'être écrasées par une
autre valeur à un niveau inférieur.  Ainsi :

@itemize
@item
Le titre d'un ouvrage découle des champs définis en tête de fichier
source, modifiés par les champs définis au sein du bloc @code{\book}.
Les champs résultants serviront à affecter un titre de recueil à
l'ouvrage, si tant est que quoi que ce soit génère une page au début de
cet ouvrage, avant la première partie -- un simple saut de page forcé
(@code{\pageBreak}) suffit.

@item
Le titre d'une partie découle des champs définis en tête du fichier
source, modifiés par les champs définis au sein du bloc @code{\book}
puis par ceux définis au sein du bloc @code{\bookpart}.  Les valeurs qui
en résulteront permettront d'imprimer les titrages de partie pour cette
partie.

@item
Le titre d'un morceau découle des champs définis en tête du fichier
source, modifiés par les champs définis au sein du bloc @code{\book}
puis par ceux définis au sein du bloc @code{\bookpart}, et enfin par
ceux définis au sein du bloc @code{\score}.  Les valeurs qui en
résulteront permettront d'imprimer les titrages de morceau pour ce
morceau.  Notez toutefois que, pour un morceau, seuls les champs
@code{piece} et @code{opus} seront imprimés, à moins d'avoir valorisé
à @code{#t} la variable @code{print-all-headers} dans la section
@code{\paper}.

@end itemize

@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.}

Nul n'est besoin de fournir un bloc @code{\header} à chacun des quatre
niveaux ; on peut se passer aussi bien de l'un d'eux que de tous.  Dans
la même veine, un fichier source simpliste peut ne pas mentionner de
bloc @code{\book} ou @code{\bookpart} qui seront alors créés
implicitement.

Lorsque l'ouvrage ne comporte qu'un seul morceau, le bloc @code{\header}
devrait prendre place en tête de fichier, de telle sorte que soit produit
un titrage de partie qui met à disposition tous les champs de titrage.

Lorsque l'ouvrage comporte plusieurs morceaux, différents arrangements
du bloc @code{\header} permettent d'obtenir différents styles de
publication musicale.  Par exemple, si la publication comprend plusieurs
pièces du même compositeur, un bloc @code{\header} placé en tête de
fichier définira le titre de l'ouvrage et le compositeur, que l'on
complètera par un bloc @code{\header} dans chaque bloc @code{\score}
pour définir les champs @code{piece} et @code{opus}, comme ici :

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

\score {
  \new Staff \relative {
    \clef bass
    \key g \major
    \repeat unfold 2 { g,16( 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 {
    \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

Des agencements plus élaborés sont aussi réalisables.  Par exemple, les
champs appartenant au titrage principal d'un ouvrage peuvent se
reporter dans chaque bloc @code{\score}, certains étant modifiés voire
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 par défaut des titrages subalternes},
@ref{Mise en forme personnalisée des titrages}.


@node Mise en forme par défaut des titrages subalternes
@unnumberedsubsubsec Mise en forme par défaut des titrages subalternes
@translationof Default layout of bookpart and score titles

Voici les différentes variables attachées au bloc @code{\header} :

@c KEEP LY
@lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
\book {
  \header {
      % Les champs suivants sont centrés
    dedication = "Dédicace"
    title = "Titre"
    subtitle = "Sous-titre"
    subsubtitle = "Sous-sous-titre"
      % Les champs suivants sont répartis sur une même ligne, et
      % le champ "instrument" apparaîtra sur les pages suivantes
    instrument = \markup \with-color #green "Instrument"
    poet = "Librettiste"
    composer = "Compositeur"
      % Les champs suivants sont en opposition sur la même ligne
    meter = "Tempo"
    arranger = "Arrangeur"
      % Les champs suivants sont centrés en bas de page
    tagline = "« tagline » ou mention spéciale en pied de dernière page"
    copyright = "copyright en pied de première page"
  }
  \score {
    { s1 }
    \header {
       % Les champs suivants sont en opposition sur la même ligne
      piece = "Pièce 1"
      opus = "Opus 1"
    }
  }
  \score {
    { s1 }
    \header {
        % Les champs suivants sont en opposition sur la même ligne
      piece = "Pièce 2 sur la même page"
      opus = "Opus 2"
    }
  }
  \pageBreak
  \score {
    { s1 }
    \header {
        % Les champs suivants sont en opposition sur la même ligne
      piece = "Pièce 3 sur une nouvelle page"
      opus = "Opus 3"
    }
  }
}
@end lilypond

Quelques précisions :

@itemize
@item
Le nom de l'instrument sera répété en tête de chaque page.

@item
Seuls seront imprimés les champs @code{piece} et @code{opus} inclus dans
un bloc @code{\score} dès lors que la variable @code{print-all-headers}
reste désactivée (valeur à @code{##f}).

@item
@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.

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

@end itemize

Les possibilités de modifier la mise en forme par défaut sont abordées à
la rubrique @ref{Mise en forme personnalisée des titrages}.

@cindex breakbefore

Un bloc @code{\book} qui commencerait directement par un bloc
@code{\bookpart} ne verra pas ses titrages apparaître puisqu'il n'y a
aucune page où imprimer le titre.  Si toutefois le titre de l'ouvrage
est requis, le bloc @code{\book} devra commencer par un @emph{markup} ou
une commande @code{\pageBreak}.

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=c7landscape,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{Mise en forme personnalisée des titrages},
@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{header} et @emph{footer} -- 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

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'4 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 titles headers and footers

@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 titrages::
* 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 titrage
contenus dans un bloc @code{\header}.

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

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


@node Mise en forme personnalisée des titrages
@unnumberedsubsubsec Mise en forme personnalisée des titrages
@translationof Custom layout for titles

@cindex bookTitleMarkup
@cindex scoreTitleMarkup
@funindex bookTitleMarkup
@funindex scoreTitleMarkup

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

Le positionnement des titres, avec les valeurs par défaut de ces
variables @code{\markup}, est illustré à la rubrique
@ref{Mise en forme par défaut des titrages subalternes}.

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 redéfinir le @code{scoreTitleMarkup} de telle sorte que le
champ @code{piece}, dont nous modifions la taille et la graisse, se
place 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 absents du @code{\header} d'un bloc @code{\score}
seront toutefois imprimés 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
dévolus au titrage des parties devront être supprimés dans
chacun des blocs @code{\score} de votre fichier source -- voir
@ref{Généralités en matière de titrages}.

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 alors 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{Généralités en matière de titrages}.


@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 (à la volée)

@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} @{
  @dots{}
  @code{\on-the-fly} \@var{procédure} @var{markup}
  @dots{}
@}
@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é particulier 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  numéro de page = 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 les définitions 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 @dots{} \fromproperty #'header: @dots{} @}}
@end example

teste si la sortie tient sur une page unique.

@seealso
Manuel de notation :
@ref{Généralités en matière de titrages},
@ref{Mise en forme par défaut des titrages subalternes}.

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


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

@cindex bas de page, notes
@cindex footnotes

Les notes de bas de page sont utiles dans bien des situations.  Dans
tous les cas, un « appel de note » vient se placer en référence dans te
texte ou la musique, et le « texte de la note » est reporté en bas de la
page.

Selon qu'elle est référencée dans une expression musicale ou dans du
texte indépendant, une note de bas  de page sera créée suivant une
procédure différente.

@menu
* Notes de bas de page dans une expression musicale::
* Notes de bas de page dans du texte indépendant::
@end menu


@node Notes de bas de page dans une expression musicale
@unnumberedsubsubsec Notes de bas de page dans une expression musicale
@translationof Footnotes in music expressions

@cindex musique et note de bas de page
@funindex \footnote

@subsubsubheading Généralités sur l'annotation de musique
@c VO Music footnotes overview

Il existe deux catégories d'annotation concernant une expression
musicale :

@table @emph
@item Les annotations événementielles
se rattachent à des événements particuliers, comme une note individuelle,
un élément d'interprétation (doigté, accent ou nuance) ou des événements
postérieurs (liaison, ligature manuelle).  Une note de bas de page
événementielle se libelle généralement sous la forme :

@example
[@var{position}] \footnote [@var{marque}] @var{décalage} @var{annotation} @var{musique}
@end example

@item Les annotations temporelles
se rapportent à un point particulier du déroulement d'un contexte
musical.  Certaines commandes, telles @code{\time} et @code{\clef}, ne
reposent pas sur un événement pour la création de l'objet métrique ou
clef.  Il en va de même pour un accord : sa hampe ou ses crochets ne
sont créés qu'à la fin d'un moment (plus exactement au travers de l'un
des événements note qui le composent).  Il n'est pas possible de
connaître assurément lequel des événements note d'un accord est
plus particulièrement à l'origine de la hampe ou du crochet.  Il
est donc plus aisé, pour de tels éléments, d'utiliser des
annotations temporelles.

Une annotation temporelle permet d'annoter des objets de rendus
sans se référer à un événement.  Elle se libelle généralement sous
la forme :

@example
\footnote [@var{marque}] @var{décalage} @var{annotation} [@var{Contexte}.]@var{nom-grob}
@end example

@end table

Les arguments, quelle que soit la catégorie d'annotation, peuvent se
définir ainsi :

@table @var
@item position
Lorsque la commande @code{\footnote} s'applique à un élément
d'interprétation ou un événement rattaché, et uniquement dans ces cas,
elle doit être précédée d'un indicateur de positionnement (@code{-, _}
ou @code{^}) de façon à rattacher @var{musique} (avec sa marque) à
la note ou au silence qui précède.

@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 automatiquement le compteur.  Ce compteur est réinitialisé
à chaque page comportant une annotation.

@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.  Des valeurs positives décalent vers la droite ou le
haut, des valeurs négatives vers la gauche ou le bas ; des valeurs à
zéro centrent la marque sur le point de référence.  Le décalage
s'exprime en espace de portée.

@item Contexte
Le contexte auquel appartient l'objet à annoter.  Cet argument
peut être omis dès lors qu'il s'agit d'un contexte de bas niveau
tel que @code{Voice}.

@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
une expression musicale mais dans tout objet du type spécifié
intervenant à cet instant précis de la partition.

@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é.

@end table


@subsubsubheading Notes de bas de page événementielles
@c VO Event-based footnotes

@cindex événementielle, note de bas de page

Ce type de note de bas de page s'attache à un objet de rendu
généré directement par l'événement correspondant à @var{musique}.
Il répond à la syntaxe :

@example
\footnote [@var{décalage}] @var{décalage} @var{annotation} @var{musique}
@end example

@c KEEP LY
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(-1 . 3) "Une note" a4
    a4
    \footnote #'(2 . 2) "Un silence" r4
    a4
  }
}
@end lilypond

Un accord @emph{dans son intégralité} ne peut pas faire l'objet
d'une note de bas de page événementielle : un accord, même s'il ne
contient qu'une seule et unique note, ne génère aucun événement en
propre.  Une des notes @emph{au sein} de l'accord peut toutefois
se voir attribuer une annotation :

@c KEEP LY
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(2 . 3) "Résultat non probant" <a-3>2
    <\footnote #'(-2 . -3) "Résultat probant" a-3>4
    <a-3 \footnote #'(3 . 1/2) "Tout aussi probant" c-5>4
  }
}
@end lilypond

Lorsque l'annotation concerne un événement postérieur ou une
articulation, la commande @code{\footnote} @strong{doit} être
précédée d'un indicateur de position (@code{-, _} ou @code{^}) et
suivie de l'événement postérieur ou l'articulation comme argument
@var{musique}.  Dans ce cas, la commande @code{\footnote} peut se
considérer comme une copie de son dernier argument auquel on
attache une annotation.  La syntaxe consacrée est :

@example
@var{position} \footnote [@var{marque}] @var{décalage} @var{annotation} @var{musique}
@end example

@c KEEP LY
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
  \header { tagline = ##f }
  \relative {
    a'4_\footnote #'(0 . -1) "Une liaison arbitrairement en dessous" (
    b8^\footnote #'(1 . 0.5) "Une ligature manuelle forcée en haut" [
    b8 ]
    c4 )
    c-\footnote #'(1 . 1) "Tenuto" --
  }
}
@end lilypond

Les appels de note peuvent être personnalisés, et le trait reliant
l'objet à l'appel supprimé :


@subsubsubheading Notes de bas de page temporelles
@c VO Time-based footnotes

@cindex temporelle, note de bas de page

Lorsque la note de bas de page se réfère à un objet de rendu résultant
d'un événement -- @code{Accidental} ou @code{Stem} découlent d'un
@code{NoteHead} --, l'argument @var{nom-grob} de l'objet en question est
requis après le texte de l'annotation, en lieu et place de
@var{musique} :

@c KEEP LY
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
  \header { tagline = ##f }
  \relative c'' {
    \footnote #'(-1 . -3) "Un bémol" Accidental
    aes4 c
    \footnote #'(-1 . 0.5) "Un autre bémol" Accidental
    ees
    \footnote #'(1 . -2) "Une hampe" Stem
    aes
  }
}
@end lilypond

Notez bien que, lorsque @var{nom-grob} est spécifié, tous les objets de
ce type qui se trouvent à ce même instant se verront attacher une
annotation :

@c KEEP LY
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote #'(-1 . 3) "Un bémol" Accidental
    <ees ges bes>4
    \footnote #'(2 . 0.5) "Une articulation" Script
    c'->-.
  }
}
@end lilypond

Une note incluse dans un accord peut individuellement se voir attribuer
une annotation événementielle.  Une tête de note (@code{NoteHead}) est
le @emph{seul} objet directement généré par un constituant d'accord ;
elle peut donc être affectée d'une annotation événementielle.  Tous les
autres objets constituant un accord sont générés indirectement.  La
commande @code{\footnote} ne dispose pas d'une syntaxe permettant de
spécifier @emph{à la fois} un type d'objet @emph{et} un événement
particulier auquel s'attacher.  De tels objets pourront toutefois faire
l'objet d'une annotation temporelle, préfixée d'un @code{\single} afin
d'annoter l'événement directement consécutif :

@c KEEP LY
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
  \header { tagline = ##f }
  \relative c'' {
    < \footnote #'(1 . -2) "Un la" a
      \single \footnote #'(-1 . -1) "Un dièse" Accidental
      cis
      \single \footnote #'(0.5 . 0.5) "Un bémol" Accidental
      ees fis
    >2
  }
}
@end lilypond

@warning{Lorsque plusieurs notes de bas de page se rapportent à un même
empilement vertical comme ci-dessus, elles sont numérotées et
apparaîtront selon l'ordre vertical des éléments présentés, autrement dit
celui positionné le plus haut en premier, non dans leur ordre
d'apparition dans le fichier source.}

Les objets de rendu tels que changement de clef ou d'armure tirent leur
origine dans la modification d'une propriété plutôt que d'un véritable
événement.  D'autres, comme les barres ou numéros de mesure, dépendent
directement de la temporisation.  C'est la raison pour laquelle de tels
objets doivent s'annoter en fonction de leur survenance au fil de la
musique.  Les notes de bas de page temporelles sont la solution à
privilégier lorsqu'il s'agit d'annoter les hampes ou ligatures affectant
des accords : bien qu'une telle fonctionnalité puisse s'appliquer à l'un
des événements constituant l'accord, rien ne laisse présager lequel
serait le plus approprié.

En matière de note de bas de page temporelle, l'objet de rendu considéré
doit toujours être mentionné explicitement, ainsi que le contexte si
l'objet est créé dans un autre contexte que celui du plus bas niveau.

@c KEEP LY
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
  \header { tagline = ##f }
  \relative c'' {
    r1 |
    \footnote #'(-0.5 . -1) "Changement de métrique" Staff.TimeSignature
    \time 3/4
    \footnote #'(1 . -1) "Hampe de l'accord" Stem
    <c e g>4 q q
    \footnote #'(-0.5 . 1) "Barre de mesure" Staff.BarLine
    q q
    \footnote #'(0.5 . -1) "Changement d'armure" Staff.KeySignature
    \key c \minor
    q
  }
}
@end lilypond

Les appels de note peuvent être personnalisés, et le trait reliant
l'objet à l'appel supprimé :

@c KEEP LY
@lilypond[quote,verbatim,papersize=a8landscape]
\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote "*" #'(0.5 . -2) \markup { \italic "* La première note" }
    a'4 b8
    \footnote \markup { \super "$" } #'(0.5 . 1)
      \markup { \super "$" \italic " La deuxième note" }
    e c4
    \once \override Score.FootnoteItem #'annotation-line = ##f
    b-\footnote \markup \tiny "+" #'(0.1 . 0.1)
      \markup { \super "+" \italic " Éditorial" } \p
  }
}
@end lilypond

D'autres exemples de personnalisation des appels de note sont donnés à
la rubrique @ref{Notes de bas de page dans du texte indépendant}.


@node Notes de bas de page dans du texte indépendant
@unnumberedsubsubsec Notes de bas de page dans du texte indépendant
@translationof Footnotes in stand-alone text

@cindex texte indépendant et note de bas de page

De telles notes de bas de page affectent les @emph{markup} extérieurs
aux expressions musicales.  Il n'est pas nécessaire en pareil cas
d'indiquer un point de référence par un trait ; l'appel de note vient
juste s'accoler au @emph{markup} qui fait l'objet de l'annotation.  Les
appels de note peuvent être gérés automatiquement, auquel cas ils seront
numériques, ou bien manuellement en fournissant un indicateur
particulier.

Les notes de bas de page concernant du texte indépendant se gèrent
différemment selon qu'elles sont automatiques ou manuelles.


@subsubsubheading Notes de bas de page automatiques dans du texte
@c VO Footnotes in stand-alone text with automatic marks

La syntaxe consacrée dans le cas d'une gestion automatique des appels
de note est :

@example
\markup @{ @dots{} \auto-footnote @var{texte} @var{annotation} @dots{} @}
@end example

Ses les éléments sont :

@table @var

@item texte
le @emph{markup} ou la chaîne de caractères sur lequel porte
l'annotation ;

@item annotation
un @emph{markup} ou une chaîne de caractères constituant le texte de
l'annotation qui sera reportée en bas de page.

@end table

Par exemple :

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


@subsubsubheading Notes de bas de page personnalisées dans du texte
@c VO Footnotes in stand-alone text with custom marks

La syntaxe consacrée dans le cas d'une gestion personnalisée des appels
de note est :

@example
\markup @{ @dots{} \footnote @var{appel} @var{annotation} @dots{} @}
@end example

Ses les éléments sont :

@table @var

@item appel
un @emph{markup} ou une chaîne de caractères représentant l'appel de
note affecté à ce point de référence.  Notez bien que cette marque ne
sera @strong{pas} reproduite automatiquement avant le texte proprement
dit de l'annotation.

@item annotation
un @emph{markup} ou une chaîne de caractères constituant le texte de
l'annotation qui sera reportée en bas de page, précédé de l'@var{appel}.

@end table

N'importe quel caractère simple tel que @code{*} ou @code{+} peut
s'utiliser en tant qu'appel de note, comme nous l'avons vu à la rubrique
@ref{Notes de bas de page dans une expression musicale}.  D'autres
caractères particuliers sont accessibles sous forme de raccourci -- voir
la rubrique @ref{Équivalents ASCII} :

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \paper { #(include-special-characters) }
  \header { tagline = ##f }
  \markup {
    "A simple tune"
    \footnote "*" \italic "* By me"
    "is shown below.  It is a recent"
    \footnote \super &dagger; \concat {
      \super &dagger; \italic " Aug 2012"
    }
    "composition."
  }
  \relative {
    a'4 b8 e c4 d
  }
}
@end lilypond

Un appel de note peut aussi se libeller sous la forme d'un point de code
unicode -- voir la rubrique @ref{Unicode} :

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \markup {
    "A simple tune"
    \footnote \super \char##x00a7 \concat {
      \super \char##x00a7 \italic " By me"
    }
    "is shown below.  It is a recent"
    \footnote \super \char##x00b6 \concat {
      \super \char##x00b6 \italic " Aug 2012"
    }
    "composition."
  }
  \relative {
    a'4 b8 e c4 d
  }
}
@end lilypond

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

Manuel de notation :
@ref{Commentaires textuels},
@ref{Équivalents ASCII},
@ref{Indications textuelles},
@ref{Info-bulle},
@ref{Liste des caractères spéciaux},
@ref{Unicode}.

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

@knownissues
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.

Silences multimesures, ligatures automatiques et paroles ne peuvent se
voir affecter de note de bas de page.

Les notes de bas de page peuvent générer des chevauchements quand elles
sont trop nombreuses sur une même page.


@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,papersize=a8landscape]
\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  % @dots{}
    \tocItem \markup "Passage spécifique du premier mouvement"
    d'4  % @dots{}
  }
}

\tocItem \markup "Second mouvement"
\score {
  {
    e'4 % @dots{}
  }
}
@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 {
  %% Traduit le titre de la table des matières en français :
  tocTitleMarkup = \markup \huge \column {
    \fill-line { \null "Table des matières" \null }
    \hspace #1
  }
  %% des fontes un peu plus grandes
  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 (text) (markup?)
   (add-toc-item! 'tocActMarkup text))
@end verbatim

@lilypond[line-width=10.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 (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,line-width=10.0\cm]
\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 de manière globale à 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.

Lorsque @code{relative-include} est valorisé à @code{#t}, 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.

Selon l'endroit où @code{relative-includes} est valorisé à @code{#t} ou
@code{#f}, la commande @code{\include} permettra d'incorporer des
fichiers contenus dans l'arborescence du répertoire principal et des
fichiers situés ailleurs.  Si, par exemple, une biblothèque générale
libA a été créée pour utiliser des sous-fichiers à l'aide
d'inclusions dans un fichier catalogue, les clauses @code{\include}
devront être précédées d'un
@code{#(ly:set-option #relative-includes #t)}  de telle sorte
qu'elles soient interprétées correctement lorsque rapatriées dans
le fichier @file{.ly} principal.  Examinons cela dans les faits :

@example
libA/
  libA.ly
  A1.ly
  A2.ly
  @dots{}
@end example

@noindent
puis le fichier catalogue, @code{libA.ly}, qui contient

@example
#(ly:set-option 'relative-includes #t)
\include "A1.ly"
\include "A2.ly"
@dots{}
% retour au réglage par défaut
#(ly:set-option 'relative-includes #f)
@end example

Tout fichier @code{.ly} peut désormais consulter l'intégralité de cette
bibliothèque grâce à un simple

@example
\include "~/libA/libA.ly"
@end example

Un positionnement judicieux des commutateurs permet de gérer des
structures de fichiers plus complexes.

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 { a'4 b c b8( a) }
altoMusic = \relative { e'4 e e f }
tenorMusic = \relative { c'4 b e d8( c) }
bassMusic = \relative { 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
@cindex tag
@cindex balise
@cindex regroupement de balises

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}} ou
       @code{\keepWithTag #'(@var{nom1} @var{nom2}@dots{})}
@tab Musique non balisée et musique balisée par l'un des noms de
       balise fournis seront incluses ; la musique balisée
       autrement est exclue.

@item
Musique balisée précédée de @code{\removeWithTag #'@var{nom}} ou
       @code{\removeWithTag #'(@var{nom1} @var{nom2}@dots{})}
@tab Musique non balisée et fragments appelés autrement que par
       l'un des noms fournis seront inclus ; la musique balisée
       par autre chose que les noms mentionnés 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

L'argument des commandes @code{\tag}, @code{\keepWithTag} et
@code{\removeWithTag} doit être un symbole ou une liste de symboles
(tel que @code{#'conducteur} ou @code{#'(violonI violonII)}), suivi
d'une expression musicale.  Si, @emph{et seulement si} les symboles sont
des indentifiants LilyPond valides (caractères alphabétiques uniquement,
sans chiffre, souligné ou tiret) qui ne peuvent se confondre avec des
notes, le @code{#'} peut s'omettre et, pour raccourcir, une liste de
symbole peut utiliser le point en séparateur -- autrement dit,
@code{\tag #'(violinI violinII)} peut s'écrire @code{\tag
violinI.violinII}.  Ceci s'applique aussi bien pour @code{\keepWithTag}
que pour @code{\removeWithTag}.

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'8. 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'8. 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} ou bien en combinant plusieurs
balises dans une liste :

@lilypond[quote,verbatim]
music = \relative c'' {
  \tag #'a \tag #'both { a4 a a a }
  \tag #'(b 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.
Une liste fournie en argument à un unique @code{\removeWithTag}
produira le même effet :

@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 }
}
\new Voice {
  \removeWithTag #'B
  \removeWithTag #'C
  \music
  \removeWithTag #'(B 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.
L'utilisation d'une unique commande @code{\keepWithTag} avec une
liste de balises est en pareil cas des plus pertinente : seront
exclus tous les fragments non concernés par l'une quelconque des
balises mentionnées.

@cindex regroupements de balises
@cindex balises, regroupement
@funindex \tagGroup

Bien que @code{\keepWithTag} soit efficace pour gérer @emph{un} jeu
d'alternatives, le rejet de musique filtrée par des balises
@emph{étrangères} se révèle problématique lorsque les @code{\tag} sont
utilisés à plusieurs fins.  Des « groupements de balises » peuvent
alors être déclarés :

@example
\tagGroup #'(violinI violinII viola cello)
@end example

stipule que ces filtres respectifs appartiennent à un même groupe.

@example
\keepWithTag #'violinI @dots{}
@end example

ne sera donc concerné que par les balises @code{violinI} contenues dans
le groupe de filtres : tout élément de la musique incluse qui serait
balisé par un ou plusieurs des filtres de ce jeu mais @emph{pas} par
@code{violinI} sera rejeté.

Pour toute commande @code{\keepWithTag}, seules les balises du
regroupement mentionnées dans la commande seront visibles.

Une balise ne peut faire partie que d'un seul regroupement.

@funindex \pushToTag
@funindex \appendToTag
@cindex raccordement dans une balise

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.

@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}.

@knownissues
L'application d'un @code{\relative} à une expression musicale
obtenue par filtrage à l'aide de @code{\keepWithTag} ou
@code{\removeWithTag} peut générer des changements d'octave,
puisque seules les hauteurs récupérées dans ce filtre seront
prises en considération.  Une instruction @code{\relative} qui
précède les commandes @code{\keepWithTag} ou
@code{\removeWithTag} permet d'éviter ce risque, dans la mesure où
elle viendra « recaler » ces hauteurs récupérées.


@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'2 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''1 \mark \markup { \char ##x03EE }
    c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
  }
  \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
\markup { "Copyright 2008--2015" \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

@cindex fragments, extraction

@funindex clip-regions

LilyPond permet d'extraire des fragments d'une partition, une fois
definis explicitement le ou les emplacements de la musique concernés au
sein du bloc @code{\layout} du fichier source, grâce à la fonction
@code{clip-regions}, puis en lançant @command{lilypond} avec l'option
@w{@code{-dclip-systems}}.

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

@noindent
L'exemple ci-dessus permet d'extraire un seul fragment @emph{débutant}
après une blanche dans la cinquième mesure (@code{5 1 2}) et
@emph{finissant} après trois noires dans la septième
mesure (@code{7 3 4}).

D'autres fragments seront extraits dès lors que d'autres paires de
@w{@code{make-rhythmic-location}} auront été ajoutées à la liste de
@w{@code{clip-regions}} présente dans le bloc @code{\layout}.

Chaque fragment sera généré individuellement sous la forme d'un fichier
@code{EPS}, converti en @code{PDF} ou @code{PNG} selon le format que
vous aurez stipulé.  La musique extraite est rendue comme si elle avait
été littéralement « découpée » dans la partition.  Par voie de
conséquence, un fragment dépassant une ligne fera l'objet d'autant de
fichiers séparés que de lignes de la partition complète.

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

Manuel d'utilisation :
@rprogram{Utilisation en ligne de commande}.


@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

@example
showLastLength = R1*5
\score @{ @dots{} @}
@end example

@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,ragged-right,verbatim]
\relative {
  c''8 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,15cm,,}

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

@sourceimage{Gonville_before,15cm,,}


@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 Génération de fichiers MIDI
@section Génération de fichiers MIDI
@translationof Creating MIDI output

@cindex son
@cindex MIDI

LilyPond peut produire des fichiers conformes au standard MIDI (Musical
Instrument Digital Interface), ce qui permet de vérifier le rendu à
l'oreille grace à un logiciel ou un périphérique sachant interpréter le
MIDI.  L'écoute du rendu en MIDI permet de contrôler aisément ce que
vous avez saisi : octaves et altérations erronées heurteront votre
oreille avertie !

Les fichiers MIDI, contrairement aux fichiers AAC, MP3 ou Vorbis, ne
contiennent pas de son et nécessitent donc le recours à un logiciel
supplémentaire pour les écouter.

@menu
* Notation prise en compte dans le MIDI::
* Notation non prise en compte dans le MIDI::
* Le bloc MIDI::
* Gestion des nuances en MIDI::
* Gestion des instruments MIDI::
* Gestion des répétitions en MIDI::
* Affectation des canaux MIDI::
* Propriétés de contextes et effets MIDI::
* Amélioration du rendu MIDI::
@end menu

@node Notation prise en compte dans le MIDI
@subsection Notation prise en compte dans le MIDI
@translationof Supported notation for MIDI

@cindex MIDI, éléments pris en compte

LilyPond retranscrit par défaut dans un fichier MIDI les éléments de
notation suivant :

@itemize
@item les marques de respiration,
@item les accords nommés,
@item les crescendos et decrescendos s'étendant sur plusieurs notes --
le volume s'ajuste linéairement entre les deux extrêmes,
@item les indications de nuance, de @code{ppppp} à @code{fffff}, y compris
@code{mp}, @code{mf} et @code{sf},
@item les microtonalités mais @emph{pas} sous forme d'accord ; leur
rendu nécessite cependant un lecteur qui prenne en charge la
modulation,
@item les paroles,
@item les hauteurs,
@item le rythme sous forme de durée de note, y compris les n-olets,
@item les articulations « simples » comme staccato, staccatissimo,
accent, marcato et portato,
@item les changements de tempo indiqués par un @code{\tempo},
@item les liaisons de tenue,
@item les tremolos, excepté ceux utilisant la syntaxe
« @code{:}[@var{nombre}] ».
@end itemize

Spatialisation, balance, expression, réverbération et chorus peuvent se
contrôler à l'aide de propriétés de contexte -- voir
@ref{Propriétés de contextes et effets MIDI}.

En combinaison avec le script @file{articulate}, d'autres éléments
seront aussi reportés en MIDI :

@itemize
@item les appogiatures -- celles-ci prendront la moitié de la valeur,
dépourvue de point, de la note qui les suit --  par exemple,

@example
\appoggiatura c8 d2.
@end example

@noindent
le do (noté @code{c}) prendra la valeur d'une noire.

@item les ornements (mordants, trilles et groupettos, etc.),
@item rallentando, accelerando, ritardando et a tempo,
@item les liaisons y compris de phrasé,
@item les tenutos.
@end itemize

@noindent
Voir @ref{Amélioration du rendu MIDI}.


@node Notation non prise en compte dans le MIDI
@subsection Notation non prise en compte dans le MIDI
@translationof Unsupported notation for MIDI

@cindex MIDI, éléments non pris en comte

Certains éléments de notation ne peuvent être retranscrits dans un
fichier MIDI :

@itemize
@item les articulations autres que staccato, staccatissimo, accent, marcato
et portato,
@item les crescendos et decrescendos sur @emph{une seule} note,
@item les points d'orgue,
@item la basse chiffrée,
@item les glissandos,
@item les chutes ou sauts,
@item les accords en microtonalité,
@item le rythme indiqué sous forme d'annotation, comme « swing »,
@item les changements de tempo indiqués sous forme d'annotation (sans
@code{\tempo}),
@item les trémolos indiqués par la syntaxe « @code{:}[@var{nombre}] ».
@end itemize


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

@cindex MIDI, le bloc

LilyPond générera un fichier MIDI dès que vous ajouterez un bloc
@code{\midi}, même vide, au sein du bloc @code{\score} :

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

@warning{Lorsque le bloc @code{@bs{}score} contient uniquement un bloc
@code{@bs{}midi} (autrement dit pas de bloc @code{@bs{}layout}),
LilyPond produira uniquement la sortie MIDI -- aucun support visuel ne
sera généré.}

L'extension par défaut des fichiers MIDI générés (@code{.midi}) peut se
modifier en ligne de commande :

@example
lilypond -dmidi-extension=mid MonFichier.ly
@end example

Une autre manière de procéder consiste à placer la ligne suivante au
début de votre fichier source, avant l'ouverture de tout bloc
@code{\book}, @code{\bookpart} ou @code{\score} -- voir
@ref{Structure de fichier} :

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

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

Fichiers d'initialisation :
@file{scm/midi.scm}.

@knownissues
Le standard MIDI dispose de 15 canaux plus un (le numéro 10) affecté aux
percussions.  Les portées sont assignées l'une après l'autre à un canal.
Dans la mesure où une partition comporte plus de 15 portées, les portées
au-delà de la quinzième partageront un même canal MIDI, sans toutefois
l'écraser.  Ceci peut entraîner des conflits au niveau des canaux en
raison des propriétés MIDI, notamment l'instrument utilisé.

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

@cindex MIDI, gestion des nuances

Le volume général de la sortie MIDI peut se définir, ainsi que ses
modulations, en fonction des indications de nuance et les volumes
relatifs entre les différents instruments.

Les indications de nuance se traduisent automatiquement en niveau de
volume dans l'amplitude disponible en MIDI alors que crescendos et
diminuendos auront une progression linéaire entre les extrêmes.

@menu
* Indication des nuances en MIDI::
* Réglage du volume en MIDI::
* Réglage de propriétés dans le bloc MIDI::
@end menu


@node Indication des nuances en MIDI
@unnumberedsubsubsec Indication des nuances en MIDI
@translationof Dynamic marks in MIDI

@cindex MIDI, indications de nuance

Les indications de nuance, de @code{ppppp} à @code{fffff} -- y compris
@code{mp}, @code{mf} et @code{sf} -- ont des valeurs prédéfinies.  Ce
coefficient est alors appliqué pour corriger le volume général de façon
à obtenir le niveau sonore qui sera retranscrit dans le fichier de
sortie pour la nuance considérée.  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}.

@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{creating-custom-dynamics-in-midi-output.ly}

@seealso
Fichiers d'initialisation :
@file{ly/script-init.ly},
@file{scm/midi.scm}.

Morceaux choisis :
@rlsr{MIDI}.

Référence des propriétés internes :
@rinternals{Dynamic_performer}.

@node Réglage du volume en MIDI
@unnumberedsubsubsec Réglage du volume en MIDI
@translationof Setting MIDI volume

@cindex MIDI, réglage du 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 explicite 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 :

@example
\score @{
  <<
    \new Staff @{
      \set Staff.midiInstrument = #"flute"
      @var{@dots{} music @dots{}}
    @}
    \new Staff @{
      \set Staff.midiInstrument = #"clarinet"
      @var{@dots{} music @dots{}}
    @}
  >>
  \midi @{
    \context @{
      \Score
      midiMinimumVolume = #0.2
      midiMaximumVolume = #0.5
    @}
  @}
@}
@end example

La définition de l'amplitude du volume MIDI au niveau d'un contexte
@code{Staff} -- grace aux propriétés @code{midiMinimumVolume} et
@code{midiMaximumVolume} -- permet en quelque sorte d'égaliser un
instrument MIDI.

@example
\score @{
  \new Staff @{
    \set Staff.midiInstrument = #"flute"
    \set Staff.midiMinimumVolume = #0.7
    \set Staff.midiMaximumVolume = #0.9
    @var{@dots{} musique @dots{}}
  @}
  \midi @{ @}
@}
@end example

Dans le cas d'une partition à plusieurs portées et différents
instruments, les volumes relatifs entre les différents instruments se
gèrent individuellement :

@example
\score @{
  <<
    \new Staff @{
      \set Staff.midiInstrument = #"flute"
      \set Staff.midiMinimumVolume = #0.7
      \set Staff.midiMaximumVolume = #0.9
      @var{@dots{} music @dots{}}
    @}
    \new Staff @{
      \set Staff.midiInstrument = #"clarinet"
      \set Staff.midiMinimumVolume = #0.3
      \set Staff.midiMaximumVolume = #0.6
      @var{@dots{} music @dots{}}
    @}
  >>
  \midi @{ @}
@}
@end example

La clarinette de cet exemple jouera relativement moins fort que la
flûte.

En l'absence de tout réglage des propriétés de volume, LilyPond
appliquera cependant un léger degré d'égalisation pour certains
instruments -- voir @file{scm/midi.scm}.

@snippets
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{replacing-default-midi-instrument-equalization.ly}

@seealso
Fichiers d'initialisation :
@file{scm/midi.scm}.

Manuel de notation :
@ref{Mise en forme de la partition}.

Référence des propriétés internes :
@rinternals{Dynamic_performer}.

@knownissues
Les modifications apportées au volume MIDI n'interviennent que sur
l'attaque d'une note, en conséquence de quoi crescendos et decrescendos
n'affecteront pas le volume s'ils se produisent sur une même et unique
note.


@node Réglage de propriétés dans le bloc MIDI
@unnumberedsubsubsec Réglage de propriétés dans le bloc MIDI
@translationof Setting MIDI block properties

Le bloc @code{\midi}  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.

@example
\score @{
  @var{@dots{} music @dots{}}
  \midi @{
    \tempo 4 = 72
  @}
@}
@end example

Le tempo est ici réglé à 72 noires par minute. Une indication de tempo
inscrite dans le bloc @code{\midi} ne sera pas reportée sur la partition
imprimable.  Cependant, tout @code{\tempo} mentionné dans le bloc
@code{\score} sera répercuté dans la sortie MIDI.

Placée au sein d'un bloc @code{\midi}, la commande @code{\tempo}
détermine des propriétés lors de la phase d'interprétation de la musique
et dans le contexte de définition des sorties.  Elle est alors
considérée comme une modification de contexte.

@cindex MIDI, 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} :

@example
\score @{
  @var{@dots{} musique @dots{}}
  \midi @{
    \context @{
      \Voice
      \remove "Dynamic_performer"
    @}
  @}
@}
@end example

Ces quelques lignes ont pour effet de supprimer l'application des
nuances à la sortie MIDI.  Vous aurez noté que les modules de traduction
de LilyPond en matière de son s'appelent @emph{performers} -- des
« interprètes ».

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

Manuel de notation :
@ref{Signes d'interprétation},
@ref{Mise en forme de la partition}.

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

Morceaux choisis :
@rlsr{MIDI}.

Référence des propriétés internes :
@rinternals{Dynamic_performer}.

@knownissues
Certains lecteurs MIDI ne rendent pas correctement les changements de
tempo.

Les modifications de @code{midiInstrument} ou autres options MIDI en
début de portée peuvent se retrouver dédoublées dans la sortie MIDI.

@node Gestion des instruments MIDI
@subsection Gestion des instruments MIDI
@translationof Using MIDI Instruments

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

L'instrument MIDI est déterminé par la propriété @code{midiInstrument},
au sein d'un contexte @code{Staff}.

@example
\score @{
  \new Staff @{
    \set Staff.midiInstrument = #"glockenspiel"
    @var{@dots{} music @dots{}}
  @}
  \midi @{ @}
@}
@end example

ou

@example
\score @{
  \new Staff \with @{midiInstrument = #"cello"@} @{
    @var{@dots{} music @dots{}}
  @}
  \midi @{ @}
@}
@end example

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

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

Manuel de notation :
@ref{Instruments MIDI},
@ref{Mise en forme de la partition}.

Référence des propriétés internes :
@rinternals{Dynamic_performer}.

Fichiers d'initialisation :
@file{scm/midi.scm}.

@knownissues
Les percussions gérées par un contexte @code{DrumStaff} sont affectées
directement 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 « classiques » puisqu'ils sont capables
d'émettre des hauteurs différentes ; leur notation relève donc d'un
contexte @code{Staff} standard, et non d'un @code{DrumStaff} pour
pouvoir être rendus correctement en MIDI.  Une liste complète des
percussions affectées au canal 10 (@code{channel 10 drum-kits}) est
disponible dans le fichier @file{scm/midi.scm} -- voir
@rlearning{Autres sources de documentation}.


@node Gestion des répétitions en MIDI
@subsection Gestion des répétitions en MIDI
@translationof Using repeats with MIDI

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

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.

@example
\score @{
  \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' @}
    @}
  @}
  \midi @{ @}
@}
@end example

Lorsque l'on veut utiliser @code{\unfoldRepeats} seulement pour le rendu
MIDI, il faut établir @b{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{@dots{} musique @dots{}}
  \layout @{ @}
@}
\score @{
  \unfoldRepeats @var{@dots{} musique @dots{}}
  \midi @{ @}
@}
@end example

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.

@seealso
Manuel de notation :
@ref{Répétitions et reprises}.



@node Affectation des canaux MIDI
@subsection Affectation des canaux MIDI
@translationof MIDI channel mapping

@cindex MIDI, canaux
@cindex MIDI, pistes
@funindex midiChannelMapping

Lorsque LilyPond génère un fichier MIDI à partir d'une partition, chaque
note contenue dans cette partition sera automatiquement assignée à un
canal MIDI, celui sur lequel elle devrait être jouée quand elle est
transmise à un périphérique MIDI.  Chaque canal MIDI dispose d'un
certain nombre de contrôles pour, par exemple, sélectionner l'instrument
+qui jouera les notes de ce canal ou bien demander au périphérique MIDI
d'appliquer différents effets au son produit sur ce canal.  En tout état
de cause, chaque contrôle d'un canal MIDI ne peut se voir affecté que
d'une seule valeur à la fois -- celle-ci peut toutefois être modifiée
pour, par exemple, changer d'instrument au milieu du morceau.

Le standard MIDI ne dispose que de 16 canaux par périphérique MIDI.
Cette limite du nombre de canaux entraîne une limitation du nombre
d'instruments pouvant jouer de concert.

LilyPond crée une piste MIDI séparée pour chaque portée (ou chaque
instrument ou voix selon la valeur de @code{Score.midiChannelMapping})
ainsi que pour chaque contexte de paroles.  Il n'y a pas de limite au
nombre de pistes.

Afin de contourner la limitation du nombre de canaux MIDI, LilyPond
dispose de différents modes d'allocation d'un canal MIDI grâce à la
propriété de contexte @code{Score.midiChannelMapping}.  Dans tous les
cas, lorsque la limite au nombre de canaux est atteinte, LilyPond repart
du canal 0, ce qui peut affecter des notes au mauvais instrument.  Cette
propriété de contexte peut prendre les valeurs suivantes :

@table @var

@item @code{'staff}

Allocation d'un canal MIDI particulier à chacune des portées de la
partition (option par défaut).  Toutes les notes de toutes les voix
d'une même portée partageront le canal MIDI affecté à la portée qui les
englobe, et toutes seront encodées dans la même piste.

La limite des 16 canaux s'applique au nombre total de portées augmenté
des contextes de paroles même si les paroles MIDI n'occupent pas de
canal MIDI.

@item @code{'instrument}

Allocation d'un canal MIDI particulier à chaque instrument MIDI tel que
spécifié dans la partition.  En d'autre termes, des notes jouées par un
même instrument MIDI partageront le même canal MIDI (et la même piste),
même si elles proviennent de voix ou portées différentes.

Dans ce cas particulier, les contextes de paroles ne sont pas pris en
compte dans la limite des 16 canaux, puisqu'ils ne sont pas assignés à
un instrument MIDI, ce qui permet une meilleure allocation des canaux
MIDI lorsque le nombre de portées et de contextes de paroles dépasse 16.

@item @code{'voice}

Allocation d'un canal MIDI particulier à chaque voix de la partition
portant un nom unique parmi les voix de la portée considérée.  Des voix
appartenant à des portées différentes seront toujours affectées à des
canaux MIDI différents, mais deux voix partageant la même portée
partageront le même canal MIDI dès lors qu'elles porteront le même nom.
Dans la mesure où @code{midiInstrument} et les différents contrôles
d'effets MIDI sont des propriétés affectant le contexte de portée, ils
ne peuvent se déterminer individuellement pour une voix.  La première
voix adoptera l'instrument et les effets spécifiés pour cette portée, et
les voix dénommées différemment de la première se verront attribué
l'instrument et le effets par défaut.

Note : l'affectation d'instruments ou d'effets différents aux
differentes voix d'une même portée s'obtient dès lors que le
@code{Staff_performer} est déplacé du contexte @code{Staff} au contexte
@code{Voice} tout en maintenant le @code{midiChannelMapping} dans le
contexte @code{'staff} ou en le réglant sur @code{'instrument}.

@end table

Par exemple, l'affectation par défaut des canaux MIDI d'une partition
peut être réglée sur @code{'instrument} comme ceci :

@example
\score @{
  ...musique...
  \midi @{
    \context @{
      \Score
      midiChannelMapping = #'instrument
    @}
  @}
@}
@end example

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


@node Propriétés de contextes et effets MIDI
@subsection Propriétés de contextes et effets MIDI
@translationof Context properties for MIDI effects

@cindex effets MIDI
@cindex pan, MIDI
@cindex spatialisation (pan), MIDI
@cindex stéréo MIDI, balance
@cindex balance MIDI
@cindex expression MIDI
@cindex reverb MIDI
@cindex chorus MIDI
@funindex midiPanPosition
@funindex midiBalance
@funindex midiExpression
@funindex midiReverbLevel
@funindex midiChorusLevel

Les différentes propriétés de contexte qui suivent permettnt d'appliquer
différents effets MIDI aux notes contenues dans le canal MIDI associé à
la portée courante, à l'instrument ou à la voix, selon la valeur
affectée à la propriété de contexte @code{Score.midiChannelMapping} et
le contexte dans lequel le @code{Staff_performer} réside -- voir
@ref{Affectation des canaux MIDI}.

Une adaptation de ces propriétés de contexte affectera toutes les notes
jouées sur ce canal dès leur modification.  Certains effets pourront
même s'appliquer sur des notes déjà en cours, selon l'implémentation du
périphérique de sortie MIDI.

LilyPond dispose des propriétés de contexte suivantes :

@table @var

@item @code{Staff.midiPanPosition}

La spatialisation (@emph{pan position}) contrôle le positionnement d'un
canal MIDI entre les sorties stéréo droite et gauche.  Cette propriété
de contexte prend en argument une valeur entre -1.0 (@code{#LEFT})
et 1.0 (@code{#RIGHT}). Une valeur de -1.0 enverra toute la puissance
sonore sur le haut-parleur gauche (le droit sera silencieux), une
vaaleur de 0.0 (@code{#CENTER}) distribuera équitablement le son entre
les jaut-parleurs de gauche et de droite, et une valeur de 1.0 enverra
tout le son sur le haut-parleur de droite.  Des valeurs entre -1.0 et
1.0 permettent d'obtenir une répartition du son entre les sorties
gauche et droite d'un équipement stéréophonique.


@item @code{Staff.midiBalance}

La balance stéréo d'un canal MIDI.  Tout comme la spatialisation, cette
propriété de contexte prend en argument une valeur comprise entre -1.0
(@code{#LEFT}) et 1.0 (@code{#RIGHT}).  Elle permet de faire varier le
volume relatif envoyé aux deux haut-parleurs stéréo sans pour autant
affecter la distribution des signaux stéréo.

@item @code{Staff.midiExpression}

Le niveau d'expression, en tant que fraction du niveau maximum de volume
disponible, à appliquer à un canal MIDI.  Un périphérique MIDI combine
le niveau d'expression des canaux MIDI et le niveau de nuance de la voix
en cours (tel que défini par @code{\p} ou @code{\ff}) afin d'obtenir le
volume total de chacune des notes de la voix.  Un contrôle de
l'expression permet, par exemple, d'implémenter des effets de crescendo
ou decrescendo sur une note tenue, ce que LilyPond ne sait pas faire
automatiquement.

@c Issue 4059 contains an attached snippet which shows how this might
@c be done, but this is too large and complex for the NR, even as a
@c referenced snippet.  It could be added to the LSR.

Le niveau d'expression varie entre 0.0 (sans expression, autrement dit
volume à zéro) et 1.0 (volume au maximum).

@item @code{Staff.midiReverbLevel}

Le niveau de réverbération, en tant que fraction du niveau maximum
disponible, à appliquer à un canal MIDI.  Cette propriété prend en
argument une valeur entre 0.0 (pas d'écho) et 1.0 (effet maximal).

@item @code{Staff.midiChorusLevel}

Le niveau de chœur, en tant que fraction du niveau maximum disponible, à
appliquer à un canal MIDI.  Cette propriété prend en argument une valeur
entre 0.0 (pas de chorus) et 1.0 (effet maximal).

@end table

@knownissues

Dans la mesure où les fichiers MIDI ne comportent effectivement aucune
donnée audio, les modifications des propriétés de contexte ne se
traduisent qu'en requêtes de changement des contrôles du canal MIDI
lorsque ces fichiers MIDI sont joués.  La manière dont un périphérique
MIDI particulier, tel un synthétiseur MIDI logiciel, gérera ces
requêtes incluses dans un fichier MIDI dépend complètement de
l'implémentation du périphérique : certains d'entre eux pourront
simplement ignorer plusieurs, voire toutes ces requêtes.  Par ailleurs,
la manière dont un périphérique MIDI interprète les différentes valeurs
de ces contrôles (en règle générale, le standard MIDI ne fixe le
comportement qu'aux valeurs extrêmes de l'amplitude disponible pour
chacun des contrôles) et leur modification alors qu'une note sur un
canal est tenue, dépend de l'implémentation particulière à ce
périphérique.

Lors de la génération d'un fichier MIDI, LilyPond transforme simplement
les valeurs fractionnaires dans l'amplitude linéaire en valeurs entières
correspondantes (de 0 à 127 et sur 7 octets, ou de 0 à 32767 et sur 14
octets pour les contrôles MIDI supportant une résolution fine). Ces
valeurs entières converties sont  stockées telles quelles dans le
fichier MIDI généré.  Pour plus d'information sur la manière dont un
périphérique MIDI interprète ces valeurs, se reporter à sa
documentation.


@node Amélioration du rendu MIDI
@subsection Amélioration du rendu MIDI
@translationof Enhancing MIDI output

Le fichier MIDI généré par LilyPond est relativement brut.  Il peut
toutefois être amélioré en affectant des instruments MIDI, en réglant
des propriétés au sein du bloc @code{\midi} ou en utilisant le script
@file{articulate}.

@menu
* Le script articulate::
@end menu


@node Le script articulate
@unnumberedsubsubsec Le script @file{articulate}
@translationof The articulate script

@cindex MIDI, instruments
@cindex articulate, script
@funindex Staff.midiInstrument

L'utilisation du script @file{articulate} se fait après avoir ajouté en
tête de fichier la commande @code{\include} appropriée :

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

Le script créera une sortie MIDI dont les notes seront échelonées de
sorte à tenir compte de toute articulation ou changement de tempo.  La
sortie imprimable sera toutefois modifiée en profondeur, pour refléter
littéralement la sortie MIDI.

@example
\score @{
  \articulate <<
    @var{@dots{} musique @dots{}}
  >>
  \midi @{ @}
@}
@end example

Le script @file{articulate} tient compte des abréviations telles que les
trilles ou groupettos.  L'intégralité des éléments traités est
répertoriée dans le script lui-même -- voir @file{ly/articulate.ly}.

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

Manuel de notation :
@ref{Mise en forme de la partition}.

Fichiers d'initialisation :
@file{ly/articulate.ly}.

@warning{Dans la mesure où le script @file{articulate} tend à raccourcir
les accords, certaines musiques, notamment pour l'orgue, paraîtront de
moins bonne qualité.  Les notes dépourvues d'articulation peuvent aussi
se voir raccourcies ; pour pallier cet inconvénient, le recours à la
fonction @code{@bs{}articulate} devrait ne concerner que de courts
fragments, sauf à modifier les valeurs des variables contenues dans le
script @file{articulate}.}


@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 cis4 e4 fis4 g4 @}
@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{\displayLilyMusic}, 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{@dots{}paramètres@dots{}}
@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.