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

@ignore
   Translation of GIT committish: 606ac3c3b22c41d84aa5fa938d42da5125ac572a

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

@c Translators: Jean-Charles Malahieude, Valentin Villenave
@c Translation checkers: Jean Abou Samra


@part Généralités en matière d'entrée et sortie


@anchor{General input and output}
@node Input modes
@chapter Modes de saisie

La manière dont sera interprétée la notation contenue dans un fichier
source dépend du mode affecté à la saisie. Il existe, en règle générale,
deux façons de spécifier le mode : une forme développée -- par exemple
@code{\chordmode} -- et une forme abrégée -- par exemple @code{\chords}.
La forme développée s'utilise particulièrement lorsque la saisie fait
l'objet d'une variable ou se trouve dans un contexte explicitement créé.
La forme abrégée crée implicitement un contexte du type adéquate à la
saisie et la lui transmet directement. Cette forme abrégée est tout à
fait indiquée aux situations simples pour lesquelles nul n'est besoin de
créer explicitement le contexte qui prendra en charge la saisie.


@subsubheading Mode accords

@funindex \chordmode
@funindex \chords

Ce mode, activé par la commande @code{\chordmode}, permet d'interpréter
les saisies comme étant des accords, qui seront imprimés sous forme de
notes sur une portée -- voir @ref{Chord notation}. La musique entrée en
mode accords est rendue soit sous forme d'accords sur une portée pour un
contexte @code{Staff}, soit sous forme de noms d'accord pour un contexte
@code{ChordNames} ou sous forme de diagrammes pour un contexte
@code{FretBoards}.

Le mode accords s'active aussi par la commande @code{\chords}, qui
créera implicitement un nouveau contexte @code{ChordNames}. Le code
saisi selon la syntaxe dévolue aux accords, sera interprété comme étant
des accords nommés et sera alors rendu sous forme nominale dans ce
contexte @code{ChordNames} -- voir @ref{Printing chord names}.


@subsubheading Mode percussions

@funindex \drummode
@funindex \drums

Ce mode, activé par la commande @code{\drummode}, permet d'interpréter
les saisies comme étant de la notation pour percussions -- voir
@ref{Basic percussion notation}. Lorsqu'elle est entrée en mode
percussions, la musique est rendue dans un contexte @code{DrumStaff}.

Le mode percussions s'active aussi par la commande @code{\drums}, qui
créera implicitement un nouveau contexte @code{DrumStaff}. Le code saisi
selon la syntaxe dévolue aux percussions, sera interprété comme étant de
la notation pour percussions et alors rendu sous forme symbolique sur
une portée de percussions -- voir @ref{Basic percussion notation}.


@subsubheading Mode figures

@funindex \figuremode
@funindex \figures

Ce mode, activé par la commande @code{\figuremode}, permet d'interpréter
les saisies comme étant de la basse chiffrée (ou figurée) -- voir
@ref{Entering figured bass}. Lorsqu'elle est entrée en mode figures, la
musique est rendue sous forme de basse figurée dans un contexte
@code{FiguredBass} ou dans un contexte @code{Staff}.

Le mode figures s'active aussi par la commande @code{\figures}, qui
créera implicitement un nouveau contexte @code{FiguredBass}. Le code,
saisi selon la syntaxe dévolue à la basse chiffrée, sera interprété
comme étant des indication de basse chiffrée et sera alors rendu sous
forme symbolique dans le contexte @code{FiguredBass} -- voir
@ref{Introduction to figured bass}.


@subsubheading Modes frets et tablatures

Il n'existe pas de mode spécifique pour saisir des symboles de fret ou
de tablature.

Notes ou accords saisis en mode note puis affectés à un contexte
@code{TabStaff} seront rendus sous forme de diagramme de tablature --
voir @ref{Default tablatures}.

Des diagrammes de fret viendront se positionner en surplomb d'une portée
dès lors que les notes ou accords auront été saisis en mode note ou
accord puis rendus dans un contexte @code{FretBoards} -- voir
@ref{Automatic fret diagrams}. Ils peuvent aussi se gérer sous forme de
@emph{markups} créés par la commande @code{\fret-diagram} -- voir
@ref{Fret diagram markups}.


@subsubheading Mode paroles

@funindex \lyricmode
@funindex \lyrics

Ce mode, activé par la commande @code{\lyricmode}, permet d'interpréter
les saisies comme étant des syllabes, ayant éventuellement une durée, et
des indications habituelles aux paroles -- voir @ref{Vocal music}.
Lorsqu'il est entré en mode paroles, le texte est rendu sous forme de
syllabes dans un contexte @code{Lyrics}.

Le mode paroles s'active aussi par la commande @code{\lyrics}, qui
créera implicitement un nouveau contexte @code{Lyrics}. Le code saisi
sera interprété comme étant des paroles et sera alors rendu sous forme
de syllabes dans le contexte @code{Lyrics}.

Le mode paroles s'active aussi par la commande @code{\addlyrics}, qui
créera un contexte @code{Lyrics} et ajoutera implicitement une commande
@code{\lyricsto} afin d'associer les paroles qui suivent à la musique
précédemment saisie -- voir @ref{Automatic syllable durations}.


@subsubheading Mode @emph{markup}

@funindex \markup

Ce mode, activé par la commande @code{\markup}, permet d'interpréter les
saisies comme étant des @emph{markups} (annotations ou étiquettes) --
voir @ref{Text markup commands}.


@subsubheading Mode notes

@funindex \notemode

Le mode notes est le mode par défaut dans LilyPond. Il peut aussi
s'activer par la commande @code{\notemode}. Les saisies seront
interprétées comme étant des hauteurs, durées, @emph{markups}, etc. qui
seront rendues sous forme de notation musicale sur une portée.

Nul n'est besoin de spécifier le mode notes de manière explicite, hormis
dans certaines situations particulières, notamment lorsque vous êtes en
mode paroles, accords, ou tout autre mode, et que vous deviez insérer un
élément qui ne serait disponible que grâce à la syntaxe du mode notes.

@lilypond[verbatim,quote]
% Ceci...

<<
  \chords { g1:m }
  { f'1 }
  \lyrics { foo1 }
  \drums { sn1 }
  \figures { <6 4>1 }
>>

% ...est équivalent à

<<
  \new ChordNames \chordmode { g1:m }
  \new Voice \notemode { f'1 }
  \new Lyrics \lyricmode { foo1 }
  \new DrumStaff \drummode { sn1 }
  \new FiguredBass \figuremode { <6 4>1 }
>>
@end lilypond


@node Input structure
@chapter Agencement du code

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


@node Structure of a score
@section Structure d'une partition

@funindex \score

Un bloc @code{\score} contient obligatoirement une seule expression
musicale délimitée par des accolades@footnote{Il existe aussi une
commande de @emph{markup} @code{\score} -- @pxref{Scores within
markup}.} :

@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

@funindexpre %
@funindex %@{ @dots{} %@}
@cindex commentaire
@cindex ligne de commentaire
@cindex bloc de commentaire

Les commentaires constituent l'une des rares exceptions à cette règle
immuable -- voir @ref{File structure} 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{Multiple scores in a book}, @ref{Multiple output files from one
input file} et @ref{File structure}.

@morerefs
Manuel d'initiation :
@rlearningnamed{A score is a (single) compound musical expression,
La partition est une (unique) expression musicale composée},
@rlearningnamed{Music expressions explained,
Les expressions musicales en clair},
@rlearningnamed{Working on input files, Travail sur les fichiers d'entrée}.
@endmorerefs


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

@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

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

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

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

@cindex variable et @code{\book}
@cindex variable et @code{\bookpart}
@cindex @code{\book} et variables
@cindex @code{\bookpart} et variables

De par leur conception, il n'est pas possible de définir des variables
au sein d'un bloc @code{\book} ou @code{\bookpart} -- c'est d'ailleurs
aussi le cas pour les blocs @code{\score}. Ceci s'avère particulièrement
important lorsque l'on veut répartir la musique dans de multiples
fichiers à l'aide de variables « locales ». On peut toutefois adopter la
structure suivante en pareil cas :

@example
% mouvement1.ly
variableI = @{ ... @}
bookpartI = \bookpart @{ \score @{ ... utilise \variableI ... @} @}

% mouvement2.ly
variableII = @{ ... @}
bookpartII = \bookpart @{ \score @{ ... utilise \variableII ... @} @}

% principal.ly
\include "mouvement1.ly"
\include "mouvement2.ly"
\book @{
  \bookpart @{ \bookpartI @}
  \bookpart @{ \bookpartII @}
@}
@end example

@cindex @code{\book} et @code{\layout}
@cindex @code{\bookpart} et @code{\layout}
@cindex @code{\layout} et @code{\book}
@cindex @code{\layout} et @code{\bookpart}

De la même manière, un bloc @code{\layout} ne peut se trouver au sein
d'un bloc @code{\book} ou @code{\bookpart}. Il doit se trouver au sein
d'un bloc @code{\score} qui, lui, peut être inclus dans un bloc
@code{\book} ou @code{\bookpart}.


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

LilyPond produit un fichier par bloc @code{\book}. 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{File structure}.

Par défaut, LilyPond nomme le fichier produit à partir du nom du fichier
source et, si nécessaire afin d'éviter les conflits, lui ajoute un
suffixe -- 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

@noindent
générera

@example
@file{huitminiatures.pdf},
@file{huitminiatures-1.pdf}
@file{huitminiatures-2.pdf}.
@end example


@node Output file names
@section Nom des fichiers de sortie

@funindex output-filename
@funindex output-suffix

@funindex \bookOutputSuffix
@funindex \bookOutputName

LilyPond vous permet de prendre le contrôle dans la dénomination des
fichiers à générer, ainsi que de l'éventuel suffixe, à partir du bloc
@code{\paper}.

@example
\paper @{
  output-filename = "mon_fichier_perso"
@}

\book @{
  \paper @{
    output-suffix = "menuetto"
  @}
  ...
@}
\book @{
  \paper @{
    output-suffix = "scherzo"
  @}
  ...
@}
@end example

@noindent
Ceci résultera en deux fichiers dénommés
@file{mon_fichier_perso-menuetto.pdf} et
@file{mon_fichier_perso-scherzo.pdf}. Une attention particulière doit
être portée aux valeurs de @code{output-filename} et
@code{output-suffix} qui doivent être valides pour votre système
d'exploitation.

Dès lors que le nom du fichier existe déjà, ce qui peut arriver, par
exemple, lorsque @code{output-filename} et @code{output-suffix} sont
définis dans un bloc @code{\paper} global et no au sein de blocs
@code{\book}, LilyPond lui adjoindra un suffixe numérique.

Notez bien que les variables prédéfinies de @code{\paper} (@pxref{The
paper block}) doivent se placer avant les réglages de
@code{output-filename} et @code{output-suffix}, comme ici :

@example
bigMargin = \paper @{ top-margin = 10\cm @}

\book @{
  \paper @{
    \bigMargin % doit intervenir en premier
    output-filename = "toto"
  @}
@}
@end example


@node File structure
@section Structure de fichier

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

@itemize
@item
@funindex \paper
@funindex \midi
@funindex \layout
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{The
layout block}.

@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
@funindex \header
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{Titles
explained}.

@item
@funindex \score
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}, et les réglages par défaut dans le fichier
@file{../ly/declarations-init.ly}.

@item
@funindex \book
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 @command{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
@funindex \bookpart
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.  La 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.

@item
@cindex variable
@cindex identificateur
@cindex identifiant
Une variable ou identifiant, ou bien une structure Scheme sous forme
de liste associative imbriquée (alist).

@example
toto = @{ c4 d e d @}       % variable normale
"Cor 3" = @{ c4 d e d @}    % variable entre guillemets
couplet.1 = @{ c4 d e d @}  % liste associative imbriquée
@end example

@noindent
Ces variables peuvent se réutiliser plus loin dans votre fichier
en les faisant précéder d'une oblique inverse.

@example
\toto
\"Cor 3"
\couplet.1
@end example

Le nom des identifiants ne doit pas comporter de chiffre (ASCII), de
succession de caractères souligné (@code{_}) ou de tiret ni aucune
espace. Tous les autres caractères Unicode sont permis, aussi bien
latins, grecs, chinois que cyrilliques. Les souligné ou tiret isolés
sont autorisés. Autrement dit, les variables @code{CorIII} ou
@code{Скрипка-II} sont valides.

Toute combinaison de caractères est permise dès lors que le nom de la
variable est borné par des guillemets informatiques. En pareil cas, les
@emph{antislashes} et guillemets doivent être « échappés » par un
@emph{antislash}. Sont donc valides : @code{"toto tutu"}, @code{"a-b-c"}
et @code{"Cor 3"}.

Les listes associatives imbriquées permettent de contourner les
limitation vues ci-dessus à propos du nommage des variables qui ne
devraient comporter de nombre. Une liste associative imbriquée est un
nom d'identifiant valide suivi d'un ou plusieurs jeux de point et clé.
Dans @code{mus.violon.1 = @{ a1 +@}}, nous avons un identifiant appelé
@code{mus} qui comporte une liste associative @code{violon} qui à son
tour comporte une clé @code{1}, et auquel est finalement attribué la
valeur @code{@{ a1 @}}. Pour @code{"1.2"."3.4".5} le nom de variable est
@code{"1.2"} et les clés sont @code{"3.4"} et @code{5} -- une telle
construction, tout à fait valide, peut permettre de générer de manière
automatique des noms de variable.

Aucun nom de variable ou de clé dans une liste associative ne doit
correspondre à un nom de note. Si cela se révélait nécessaire, il
faudrait l'entourer de guillemets informatiques ou, encore mieux, opter
pour un autre nom ou une autre clé.

Pour des raisons techniques, accéder à des listes associatives
imbriquées peut échouer dans certaines circonstances. En particulier, on
ne peut y accéder aux niveaux de premier rang -- autrement dit en dehors
d'un bloc de musique. Si @command{lilypond} venait à à avorter avec un
message d'erreur « mauvais type d'expression », il faudrait remplacer la
liste associative imbriquée par une variable entre guillemets.

@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}
@funindex \version

@item @code{\include}
@funindex \include

@item @code{\sourcefilename}
@funindex \sourcefilename

@item @code{\sourcefileline}
@funindex \sourcefileline

@item
@funindexpre %
@cindex commentaire, ligne
@cindex ligne de commentaire
Une ligne de commentaire, introduite par le signe @code{%}.

@item
@funindex %@{ @dots{} %@}
@cindex commentaire, bloc
@cindex bloc de commentaire
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 @samp{#} ;

@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

@morerefs
Manuel d'initiation :
@rlearningnamed{How LilyPond input files work,
Organisation des fichiers LilyPond}.

Manuel de notation :
@ref{Titles explained},
@ref{The layout block}.
@endmorerefs


@node Titles and headers
@chapter Titres et entêtes

@cindex titre
@cindex entête
@cindex pied de page

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.


@need 800
@node Creating titles headers and footers
@section Création de titres et entête ou pied de page


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

Chaque bloc @code{\book} apparaissant dans un même fichier source
résultera en un fichier indépendant, comme indiqué à la rubrique
@ref{File structure}. 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{Default layout of
bookpart and score titles}. 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
Au sein d'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.

@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

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,line-width=14.5\cm,quote,verbatim,noragged-right]
\header {
  title = "SUITE I."
  composer = "J. S. Bach."
}

\score {
  \header {
    piece = "Prélude."
  }
  \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, } |
  }
}

\score {
  \header {
    piece = "Allemande."
  }
  \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) |
  }
}
@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,line-width=14.5\cm,quote,verbatim,noragged-right]
\book {
  \paper {
    print-all-headers = ##t
  }
  \header {
    title = "DAS WOHLTEMPERIRTE CLAVIER"
    subtitle = "TEIL I"
    % Pas de mention spéciale par défaut pour cet ouvrage
    tagline = ##f
  }
  \markup { \vspace #1 }
  \score {
    \header {
      title = "PRAELUDIUM I"
      opus = "BWV 846"
      % Pas de sous-titre pour ce morceau
      subtitle = ##f
    }
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
  }
  \score {
    \header {
      title = "FUGA I"
      subsubtitle = "A 4 VOCI"
      opus = "BWV 846"
      % Pas de sous-titre pour ce morceau
      subtitle = ##f
    }
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
  }
}
@end lilypond

@morerefs
Manuel de notation :
@ref{Default layout of bookpart and score titles},
@ref{Custom layout for titles},
@ref{File structure}.
@endmorerefs


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

@funindex arranger
@funindex composer
@funindex copyright
@funindex dedication
@funindex instrument
@funindex meter
@funindex opus
@funindex piece
@funindex poet
@funindex subsubtitle
@funindex subtitle
@funindex tagline
@funindex title

L'exemple suivant recense les différentes variables imprimables
attachées au bloc @code{\header}. Notez bien que l'espacement vertical
par défaut entre les différentes composantes des entêtes est optimisé
pour des entrées d'une seule ligne. Si l'un des éléments devait
comprendre plusieurs lignes, par exemple un compositeur sur deux lignes,
l'ajout d'un @code{\vspace} au champ en question sera peut-être
nécessaire pour ajuster l'espacement vertical. Une alternative consiste
à se définir sa propre mise en forme personnalisée -- @pxref{Custom
layout for titles}.

@c KEEP LY
@lilypond[papersize=a6landscape,line-width=14.5\cm,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 = "Le « tagline » ou mention spéciale va en pied de dernière page"
    copyright = "Le copyright va 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 {
    \header {
    % Les champs suivants sont en opposition sur la même ligne
      piece = "Pièce 2 sur la même page"
      opus = "Opus 2"
    }
    { s1 }
  }
  \pageBreak
  \score {
    \header {
    % Les champs suivants sont en opposition sur la même ligne
      piece = "Pièce 3 sur une nouvelle page"
      opus = "Opus 3"
    }
    { s1 }
  }
}
@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
Les champs d'un bloc @code{\header} qui n'auront pas été alimentés
seront absents, 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{Custom layout for titles}.

@funindex 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 {
    \header {
      piece = "This is the Music"
      breakbefore = ##t
    }
    \repeat unfold 4 { e'' e'' e'' e'' }
  }
}
@end lilypond

@morerefs
Manuel d'initiation :
@rlearningnamed{How LilyPond input files work,
Organisation des fichiers LilyPond}.

Manuel de notation :
@ref{Custom layout for titles},
@ref{File structure}.

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


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

@cindex entête de page
@cindex pied de page
@cindex page, entête
@cindex page, pied

Les entête et pied -- @dfn{header} et @dfn{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} sont définies dans le fichier
@file{ly/titling-init.ly}, et de manière suivante 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 contenu du champ @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

Le texte de la mention spéciale par défaut se modifie en alimentant le
champ @code{tagline} au niveau du bloc @code{\header} principal.

@lilypond[papersize=a8landscape,verbatim]
\book {
  \header {
    tagline = "... la notation musicale pour Tous"
  }
  \score {
    \relative {
      c'4 d e f
    }
  }
}
@end lilypond

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

@morerefs
Manuel de notation :
@ref{Custom layout for headers and footers}.
@endmorerefs


@need 800
@node Custom titles headers and footers
@section Titrages personnalisés

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


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

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

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

@morerefs
Manuel de notation :
@ref{Formatting text}.
@endmorerefs


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

@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{Default layout
of bookpart and score titles}.

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 @{
  \if \should-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 {
  \header {
    piece = "PRAELUDIUM I"
    opus = "BWV 846"
  }
  { s1 }
}
@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,line-width=14.5\cm,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 {
    \header {
      piece = "PRAELUDIUM I"
      opus = "BWV 846"
    }
    { s1 }
  }
}
@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 -- @pxref{Titles explained}.

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,line-width=14.5\cm,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 {
    \header {
      piece = "MENUET"
      composer = "Christian Petzold"
    }
    { s1 }
  }
  \score {
    \header {
      piece = "RONDEAU"
      composer = "François Couperin"
    }
    { s1 }
  }
}
@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,line-width=14.5\cm,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 {
    \header {
      piece = "FUGA I"
      mycustomtext = "A 4 VOCI" %% User-defined field
      opus = "BWV 846"
    }
    { s1 }
  }
}
@end lilypond

@morerefs
Manuel de notation :
@ref{Titles explained}.
@endmorerefs


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

@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 \if
@funindex \unless

L'instruction @code{\if} au sein d'un @code{\markup} permet d'ajouter
des éléments au texte des entêtes et pieds de page définis dans le bloc
@code{\paper}, et ce uniquement lorsque certaines conditions sont
vérifiées. En voici la syntaxe :

@example
\if \@var{condition} @var{argument}
@end example

@noindent
La @var{condition} est testée à chaque fois que le @emph{markup} où elle
apparaît est évalué. Le @emph{markup} @var{argument} sera imprimé si et
seulement si cette condition est remplie.

LilyPond dispose d'ores et déjà d'un certain nombre de conditions
relatives à la numérotation des pages (la première, la dernière, une
page spécifique, etc.). Le test renversant la condition s'obtient en
remplaçant le @code{\if} par un @code{\unless}.

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} en les désactivant par
un @code{#f}. 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{\evenFooterMarkup}.

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

Voici une liste des procédures prédéfinies utilisables avec @code{\if}
ou @code{\unless}.

@indentedblock
@multitable {@code{\should-print-page-numbers-global}} {ce n'est pas la première page du book--}

@headitem  Syntaxe                      @tab  Condition testée
@item @code{\on-first-page}             @tab  c'est la première page du @emph{book}.
@item @code{\on-last-page}              @tab  c'est la dernière page du @emph{book}.
@item @code{\on-first-page-of-part}     @tab  c'est la première page de la partie.
@item @code{\on-last-page-of-part}      @tab  c'est la dernière page de la partie.
@item @code{\on-page @var{nombre}}      @tab  ceci est la page @var{nombre}
@item @code{\single-page}               @tab  ce @emph{book} tient sur une page.
@item @code{\should-print-page-numbers-global} @tab  il faut imprimer les numéros de page.
   @footnote{@code{\should-@/print-@/page-@/numbers-@/global} peut être
   différent de @code{\should-@/print-@/page-@/number} pour la première
   page de l'ouvrage, selon le réglage affecté à
   @code{print-@/first-@/page-@/number} dans le bloc @code{\paper}.}
@item @code{\should-print-page-number}  @tab  il faut imprimer le numéro de cette page.
@item @code{\should-print-all-headers}  @tab  @code{print-all-headers} est vrai.

@end multitable
@end indentedblock

@morerefs
Manuel de notation :
@ref{Conditional markup,Conditions},
@ref{Titles explained},
@ref{Default layout of bookpart and score titles}.

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


@node Creating output file metadata
@section Création des métadonnées des fichiers de sortie

@cindex PDF, métadonnées
@cindex MIDI, métadonnées
@cindex métadonnées PDF
@cindex métadonnées MIDI

En plus de s'imprimer sur la partition, les variables du bloc
@code{\header} permettent de générer les métadonnées des fichiers de
sortie. Dans le cas d'un fichier PDF, ces métadonnées pourront être
affichées par le lecteur en tant que propriétés du document. Quel que
soit le type de fichier de sortie, seules seront analysées les variables
déterminées dans le @code{\header} du bloc définissant le fichier à
générer, ainsi que celles des blocs hiérarchiquement supérieurs. Pour
les fichiers PDF, seules les définitions du @code{\header} en dehors ou
au niveau d'un bloc @code{\book} affecteront les métadonnées des
documents PDF ; pour les fichiers MIDI seront utilisées les définitions
jusqu'au niveau @code{\score}.

Par exemple, affecter « Symphony I » à la propriété @code{title} dans le
bloc @code{\header} donnera aussi ce titre au document PDF et à la
séquence MIDI.

@example
\header @{
  title = "Symphony I"
@}
@end example

Lorsque le titre imprimé diffère de celui affiché en tant que propriété
du PDF, devra être renseignée la propriété @code{pdftitle}.

@example
\header @{
  title = "Symphony I"
  pdftitle = "Symphony I by Beethoven"
@}
@end example

Les variables @code{title}, @code{subject}, @code{keywords},
@code{subtitle}, @code{composer}, @code{arranger}, @code{poet},
@code{author} et @code{copyright} initialisent toutes les propriétés
PDF, qu'il suffit de préfixer d'un « pdf » pour affecter aux propriétés
PDF une valeur divergente de la sortie imprimable.

La propriété PDF @code{Creator} prend automatiquement la valeur
« LilyPond » additionnée du numéro de version ; les valeurs de
@code{CreationDate} et @code{ModDate} sont définies à la date et l'heure
courantes -- @code{ModDate} peut être écrasé par la variable de
@code{\header} @code{moddate} (ou @code{pdfmoddate}) pour un horodatage
PDF valide.

La variable @code{title} détermine aussi le nom de la séquence MIDI.
L'utilisation de la variable @code{midititle} permet d'attribuer à la
séquence MIDI un nom différent de celui attribué au fichier imprimable.


@node Creating footnotes
@section Notes de bas de page

@cindex bas de page, note de
@cindex @emph{footnote}, note de bas de page

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 le texte
ou la musique, et le « texte de la note » est reporté au bas de la page,
isolé de la musique par un trait horizontal. L'apparence de ce
séparateur peut se modifier à l'aide de la variable de papier
@code{footnote-separator-markup} -- @pxref{paper variables concerning
headers and markups}.

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.


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

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

@subsubheading 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 rendu 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 (@samp{-},
@samp{_} ou @samp{^}) de façon à rattacher @var{musique} (avec sa
marque) à la note ou au silence qui précède.

@item marque
@funindex \default
@funindexpost \default
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 par défaut
réinitialisé à chaque page comportant une annotation. La numérotation
peut être continue sur l'ouvrage en désactivant la variable
@code{reset-@/footnotes-@/on-@/new-@/page} -- @pxref{paper variables
concerning headers and markups}.

@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


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

@cindex @'evé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{marque}] @var{décalage} @var{annotation} @var{musique}
@end example

@c In this and the following footnote examples we use `\markup`
@c commands to ensure enough vertical space so that footnotes are
@c not clipped.  This is issue #6128.

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

Lorsqu'un accord fait l'objet d'une note de bas de page événementielle,
chacune des hauteurs qui le composent se voit individuellement affublée
de cette même annotation, ce qui n'est pas ce à quoi on pourrait
s'attendre. 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 }
  \markup "Notes de bas de page événementielles"
  \markup \null
  \relative c'' {
    \footnote #'(1 . 3) "Un accord." <a-3 c-5>2
    <a-3 \footnote #'(3 . 0.5) "Une note dans un accord." 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 (@samp{-}, @samp{_} ou @samp{^}) 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 }
  \markup "Notes de bas de page événementielles"
  \markup \null
  \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


@subsubheading 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 }
  \markup "Notes de bas de page temporelles"
  \markup \null
  \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 }
  \markup "Notes de bas de page temporelles"
  \markup \null
  \relative c' {
    \footnote #'(-1 . 3) "Un bémol." Accidental
    <ees ges bes>4
    \footnote #'(2 . 0.5) "Une articulation." Script
    c'->-.
  }
}
@end lilypond

@funindex \single

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 }
  \markup "Notes de bas de page temporelles"
  \markup \null
  \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 }
  \markup "Notes de bas de page temporelles"
  \markup \null
  \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 }
  \markup "Appels de note personnalisés"
  \markup \null
  \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.Footnote.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{Footnotes in stand-alone text}.


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

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


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


@subsubheading 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 @samp{*} ou @samp{+} peut
s'utiliser en tant qu'appel de note, comme nous l'avons vu à la rubrique
@ref{Footnotes in music expressions}. D'autres caractères particuliers
sont accessibles sous forme de raccourci -- @pxref{ASCII aliases} :

@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 -- @pxref{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

@morerefs
Manuel d'initiation :
@rlearningnamed{Objects and interfaces, Objets et interfaces}.

Manuel de notation :
@ref{Text scripts},
@ref{ASCII aliases},
@ref{Text marks},
@ref{Balloon help},
@ref{List of special characters},
@ref{Unicode}.

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

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

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


@node Creating in-notes
@section Notes en ligne

@cindex in-note

Les notes en ligne fonctionnent comme les notes de bas de page en ceci
qu'elles servent à annoter la musique, mais sont différents puisqu'elles
apparaissent au-dessus ou au-dessous du système dans lequel se trouve
l'objet auquel elles se rattachent.

@funindex in-note-padding
@funindex in-note-system-padding
@funindex in-note-direction

Avant de créer une note en ligne, la propriété @code{footnote} de
l'objet @code{Footnote} doit être affectée d'un @code{#f}. La distance
entre deux notes en ligne est gérée par la variable de papier
@code{in-note-padding}, et l'écartement par rapport au système associé
par la variable @code{in-note-system-padding}. Le positionnement des
notes en ligne au-dessous du système concerné s'obtient en réglant la
variable @code{in-note-direction} sur @code{DOWN}.

@lilypond[verbatim,quote,papersize=a6]
music = { a4 b8 e c4 d }

\book {
  \relative c'' {
    \override Score.Footnote.footnote = ##f

    \repeat unfold 5 \music
    \footnote #'(1 . 1) "An in-note." NoteHead
    <>-> \repeat unfold 4 \music
    \footnote "" #'(0 . 0) "An in-note without number." NoteHead
    <>-> \repeat unfold 2 \music
    \footnote "" #'(0 . 0) "Another numberless in-note." NoteHead
    <>-> \music
  }

  \paper {
    in-note-system-padding = 5
    in-note-padding = 2
    tagline = ##f
  }
}
@end lilypond


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

@cindex page, référencement du numéro
@cindex numéro de page, référencement
@cindex signet

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 « 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"}.

Lorsque la taille du texte final diffère de l'emporte-pièce, il peut
s'avérer utile de configurer son alignement horizontal par rapport à
l'espace réservé, à l'aide de la propriété @code{x-align}. Le réglage
par défaut est un alignement sur la droite.

@lilypond[quote,verbatim]
\markup {
  \box
    \page-ref #'foo "???" "?" " right-aligned (default)"
}
\markup {
  \box
    \override #`(x-align . ,LEFT)
    \page-ref #'foo "???" "?" " left-aligned"
}
\markup {
  \box
    \override #'(x-align . -2.5)
    \page-ref #'foo "???" "?" " left outside"
}
@end lilypond

Dans cet exemple, l'emporte-pièce @samp{???} est plus large que le texte
de remplacement @samp{?}. Le texte de remplacement est utilisé parce que
le label @code{#'foo} n'existe pas.

La propriété @code{x-align} peut prendre n'importe quel nombre. Les
symboles prédéfinis @code{LEFT}, @code{CENTER} et @code{RIGHT}
permettent d'aligner respectivement sur la gauche, au centre, et sur la
droite de l'emporte-pièce.

@predefined
@funindex \label
@funindex \page-ref

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


@node Table of contents
@section Table des matières

@cindex signets

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 "Première partie"
\score {
  {
    c'4  % ...
    \tocItem \markup "Passage spécifique de la première partie"
    d'4  % ...
  }
}

\tocItem \markup "Seconde partie"
\score {
  {
    e'4 % ...
    \tocItem actI \markup "Acte I"
    f'4 % ...
    \tocItem actI.sceneI \markup "Scène 1"
    g'4 % ...
    \tocItem actI.sceneI.recitativo \markup "Récit."
    a'4 % ...
  }
}
@end verbatim

Un libellé peut, facultativement, être associé à un élément particulier
ou de façon hiérarchique dans une liste de libellés existants, terminant
alors par le libellé de cet élément. Ce dernier cas permet de marquer
l'élément comme « enfant » d'éléments précédemment libellés et ainsi
laisser transparaître la structure de la partition dans la table des
matières.

Les @emph{markups} dévolus à la mise en forme de la table des matières
se définissent dans le bloc @code{\paper}. LilyPond dispose de trois
@emph{markups} prédéfinis :

@itemize

@item
@code{tocTitleMarkup}

@noindent
Utilisé pour mettre en forme le titre de la table des matières.

@verbatim
tocTitleMarkup = \markup \huge \column {
  \fill-line { \null "Table of Contents" \null }
  \null
}
@end verbatim

@item
@code{tocItemMarkup}

@noindent
Utilisé pour mettre en forme les éléments au sein de la table des
matières.

@verbatim
tocItemMarkup = \markup \fill-line {
  \fromproperty #'toc:text \fromproperty #'toc:page
}
@end verbatim

@item
@code{tocFormatMarkup}

@noindent
Utilisé pour mettre en forme les entrées de premier niveau dans la table
des matières si tant est qu'existent plusieurs niveaux hiérarchiques. Il
s'agit ici d'une procédure, comme abordé dans @rextendnamed{Markup
construction in Scheme, Construction d'un markup en Scheme}.

@verbatim
tocFormatMarkup = #make-bold-markup
@end verbatim

@item
@code{tocIndentMarkup}

@noindent
Utilisé pour définir comment sera mise en évidence la hiérarchie. Ce
@emph{markup} sera imprimé zéro, une ou plusieurs fois selon le niveau
de chacune des entrées.

@verbatim
tocIndentMarkup = \markup \hspace #4
@end verbatim

@end itemize

@noindent
Toutes ces variables sont adaptables.

Voici comment, par exemple, franciser le titre :

@verbatim
\paper {
  tocTitleMarkup = \markup \huge \column {
    \fill-line { \null "Table des matières" \null }
    \hspace #1
  }
@end verbatim

L'exemple suivant illustre la manière de modifier la taille des éléments
de la table des matières :

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

@funindex \tocItemWithDotsMarkup

Grâce à la commande @code{\tocItemWithDotsMarkup}, 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

@funindex add-toc-item!
@cindex table des matières, personnalisation

Au-delà de ces mécanismes de mise en forme, il est possible de définir
d'autres commandes et @emph{markups} afin de construire une table plus
élaborée. Dans l'exemple qui suit, nous créons un nouveau style
d'élément dans le but de mentionner les actes et scènes dans la table
des matières d'un opéra :

@noindent
Commençons par définir une nouvelle variable de type @code{markup} --
appelée @code{tocActMarkup} -- au sein du bloc @code{\paper}.

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

@noindent
Créons ensuite une fonction musicale (@code{tocAct}) utilisant la
nouvelle définition de @emph{markup} @code{tocActMarkup}, tout en lui
autorisant de définir un libellé pour chaque acte.

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

@noindent
Dans un fichier LilyPond, l'utilisation de cette définition
personnalisée, avec quelques adaptations aux réglages par défaut,
pourrait ressembler à ceci :

@funindex \fill-with-pattern

@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
  }
  tocItemMarkup = \markup \fill-line {
    \fill-with-pattern #1.5 #CENTER .
    \line {
      \hspace #-4 %% Cancelling the first level's tocIndentMarkup
      \fromproperty #'toc:indent \fromproperty #'toc:text
      \hspace #2
    }
    \fromproperty #'toc:page
  }
}

tocAct =
  #(define-music-function (label text) (symbol-list-or-symbol? markup?)
     (add-toc-item! 'tocActMarkup text label))

\book {
  \markuplist \table-of-contents
  \tocAct actI \markup { Atto Primo }
  \tocItem actI.sceneI \markup { Coro. Viva il nostro Alcide }
  \tocItem actI.sceneII \markup { Cesare. Presti omai l'Egizia terra }
  \tocItem actI.sceneII.recitativo \markup { \italic Recit. Curio, Cesare venne,e vide, e vinse. }
  \tocAct actII \markup { Atto Secondo }
  \tocItem actII.sceneI \markup { Sinfonia }
  \tocItem actII.sceneII \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
  \markup \null
}
@end lilypond

Cet exemple illustre par ailleurs l'utilisation de la commande
@code{\fill-with-pattern} dans le cadre d'une table des matières.

@predefined
@funindex \table-of-contents
@funindex \tocItem
@funindex tocItemMarkup
@funindex tocTitleMarkup
@funindex tocFormatMarkup
@funindex tocIndentMarkup

@code{\table-of-contents},
@code{\tocItem},
@code{tocItemMarkup},
@code{tocTitleMarkup},
@code{tocFormatMarkup},
@code{tocIndentMarkup}.
@endpredefined

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


@need 1500
@node Working with input files
@chapter Travail sur des fichiers texte


@node Including LilyPond files
@section Insertion de fichiers LilyPond

@funindex \include
@cindex inclusion de fichier

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 « 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
endroits de la partition, comme expliqué à la rubrique @ref{Different
editions from one 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
seront, par défaut, interprétées par rapport à leur situation dans
l'arborescence. Tel sera, par exemple, le cas d'une bibliothèque
générale « libA » créée pour utiliser des sous-fichiers à l'aide
d'inclusions dans un fichier catalogue, comme ici :

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

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

@example
\include "A1.ly"
\include "A2.ly"
@dots{}
@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

Vous pouvez toutefois influer sur ce comportement de manière globale à
l'aide de l'option @w{@option{-drelative-includes=#f}} en ligne de
commande ou en ajoutant une clause
@code{#(ly:set-option 'relative-includes #f)} en tête du fichier
principal. En pareil cas, le chemin à suivre pour chacune des commandes
@code{\include} sera pris relativement au fichier principal. 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.

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

@noindent
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 @rlearningnamed{Other sources of information, 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 @rlearningnamed{Other sources of
information, 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 @rlearningnamed{Scores and parts,
Conducteurs et parties}.

@morerefs
Manuel d'initiation :
@rlearningnamed{Other sources of information,
Autres sources de documentation},
@rlearningnamed{Scores and parts, Conducteurs et parties}.
@endmorerefs

@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 Different editions from one source
@section Différentes éditions à partir d'une même source

Plusieurs méthodes permettent de générer différentes versions d'une
partition à partir d'une même source. Les variables -- ou identifiants
-- sont sûrement le moyen le plus simple de combiner de différentes
manières 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.


@node Using variables
@subsection Utilisation de 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
@rlearningnamed{Organizing pieces with variables, 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{Automatic part combining}. 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{Including LilyPond
files}.


@node Using tags
@subsection Utilisation de balises

@funindex \tag
@cindex tag
@cindex balise

La commande @code{\tag} affecte un nom à une expression musicale.

@example
\tag #'toto @{ ... @}
@end example

@noindent
Les expressions ainsi balisées peuvent aisément se manipuler comme un
tout.

@subsubheading Conserver et exclure de la musique balisée
@c VO Keeping and removing tagged music

@funindex \keepWithTag
@funindex \removeWithTag
@cindex balises, garder
@cindex balises, exclure

Si la commande @code{\keepWithTag} permet de conserver une expression
musicale balisée, la commande @code{\removeWithTag} exclura la musique
balisée.

@indentedblock
@multitable @columnfractions .55 .45
@headitem Filtre
  @tab Résultat

@item
Musique balisée précédée de

@example
\keepWithTag #'@var{nom}
@end example

@noindent
ou

@example
\keepWithTag #'(@var{nom1} @var{nom2}@dots{})
@end example

  @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

@example
\removeWithTag #'@var{nom}
@end example

@noindent
ou

@example
\removeWithTag #'(@var{nom1} @var{nom2}@dots{})
@end example

  @tab Musique non balisée et fragments appelés autrement que par l'un
       des noms fournis seront inclus ; la musique balisée par l'un des
       noms mentionnés est exclue.

@item
Musique balisée non précédée de

@example
\keepWithTag
@end example

@noindent
ou

@example
\removeWithTag
@end example

  @tab Musique balisée et non balisée seront incluses.

@end multitable
@end indentedblock

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
identifiants LilyPond valides (caractères alphabétiques uniquement,
sans chiffre, souligné ou tiret) qui ne peuvent se confondre avec des
notes, le préfixe @code{#'} peut s'omettre et, pour raccourcir, une
liste de symboles peut utiliser la virgule 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}.

Les commandes de balisage sont des fonctions musicales ; elles ne
peuvent donc s'utiliser pour filtrer des éléments qui ne sont pas des
expressions musicales tels que des blocs @code{\book} ou @code{\score}.

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

@cindex @code{\cueDuring} et balise
@cindex @code{\quoteDuring} et balise
@cindex @code{\tag} et citation de musique

Lorsque des balises concernent des alternatives de durée non nulle, ces
alternatives sont souvent conceptuellement simultanées. Il vaut alors
mieux mettre ces alternatives dans des expressions musicales simultanées
de telle sorte que l'expression musicale ait la même durée quelle que
soit la balise retenue. Ceci est tout particulièrement important lorsque
les balises sont utilisées conjointement avec des commandes telles que
@code{\cueDuring}.

@lilypond[verbatim,quote]
outputTypeTag = "isScore"

firstInstrument = \relative c' {
  <<
    \tag #'isPart {
      \cueDuring "quoteSecondInstrument" #UP { r2 } }
    \tag #'isScore { r2 }
  >>
  e4 f |
  g4 a b c |
}

secondInstrument= \relative c'' {
  c4 c r2 |
  \cueDuring "quoteFirstInstrument" #DOWN { r2 }
  c4 c |
}

\addQuote quoteFirstInstrument \firstInstrument
\addQuote quoteSecondInstrument \secondInstrument

\new Staff {
  \keepWithTag \outputTypeTag \firstInstrument
}

\new Staff {
  \keepWithTag \outputTypeTag \secondInstrument
}
@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 AA \tag AB { a4 a a a }
  \tag BB,both { b4 b b b }
}

<<
  \keepWithTag AA \music
  \keepWithTag BB \music
  \keepWithTag AB \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 AA { a4 a a a }
  \tag BB { b4 b b b }
  \tag CC { c4 c c c }
  \tag DD { d4 d d d }
}

\new Voice {
  \removeWithTag BB \removeWithTag CC \music
  \removeWithTag BB,CC \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, ce
qui n'est certainement pas l'effet attendu : 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 pertinentes : seront
exclus tous les fragments non concernés par l'une quelconque des balises
mentionnées. Le code suivant, à titre d'exemple, imprimera les
@code{\tag}s @var{violinI} et @var{violinII}, mais ni @var{viola} ni
@var{cello}.

@lilypond[verbatim,quote]
music = \relative c'' {
  \tag violinI { a4 a a a }
  \tag violinII { b4 b b b }
  \tag viola { c4 c c c }
  \tag cello { d4 d d d }
}

\new Staff {
  \keepWithTag violinI,violinII \music
}
@end lilypond


@subsubsubheading Utilisation de regroupements de balises
@c VO Using tag groups

@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 é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 à l'aide de @code{\tagGroup}. Un code tel que

@example
\tagGroup violinI,violinII,viola,cello
@end example

@noindent
met les quatre balises dans un seul regroupement. Par conséquent, taper

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

@noindent
ne prendra désormais en compte que la musique concernée par la balise
@code{violinI} du groupe de filtres : tout élément de la musique qui
serait balisé par l'un des autres filtres de ce jeu sera rejeté, comme
le montre l'exemple suivant.

@lilypond[verbatim,quote]
\tagGroup violinI,violinII
\tagGroup original,arranged

music = \relative {
  \tag violinI { c''4^"violinI" c c c }
  \tag violinII { a2 a }
  \tag original { e8 e e2. }
  \tag arranged { d'2 d4 d }
  \tag other { f^"other" f f f }
  R1^"untagged"
}

\new Voice {
  \keepWithTag violinI \music
}
@end lilypond

Il est à noter que les balises ne peuvent être incluses que dans un seul
regroupement.

@funindex \tagGroupRef

Il est possible de modifier des regroupements de balises. Une autre
manière de les définir consiste à utiliser @code{\tagGroupRef} dans le
but de références le groupement pour modification ultérieure. Libeller

@example
tg = \tagGroupRef violinI,violinII
@end example

@noindent
revient à mentionner

@example
tg = #'(violinI violinII)
\tagGroup \tg
@end example

Diverses possibilités permettent de modifier des regroupements de
balises existant.

@itemize
@funindex \resetTagGroups

@item
L'annulation de tous les effets induits de tous les @code{\tagGroup} ou
@code{\tagGroupRef} s'obtient simplement par un @code{\resetTagGroups}.

@lilypond[verbatim,quote]
\tagGroup tagI,tagII

music = \relative {
  \tag tagI { c''4^"tagI" c c c }
  \tag tagII { a2^"tagII" a }
  \tag otherI { d4^"otherI" d d d }
  \tag otherII { f,4^"otherII" g a c }
}

\new Voice {
  \keepWithTag tagI \music
}

\resetTagGroups

\new Voice {
  \keepWithTag tagI \music
}
@end lilypond

@funindex \resetTagGroup

@item
L'annulation des effets d'un regroupement particulier s'obtient à l'aide
d'un @code{\resetTagGroup} auquel est fourni le regroupement considéré,
donc toutes ses balises. @code{\tagGroupRef} se révèle très pratique
pour définir le regroupement de balises.

@lilypond[verbatim,quote]
tgI = \tagGroupRef tagI,tagII
tgII = \tagGroupRef otherI,otherII

music = \relative {
  \tag tagI { c''4^"tagI" c c c }
  \tag tagII { a2^"tagII" a }
  \tag otherI { d4^"otherI" d d d }
  \tag otherII { f,4^"otherII" g a c }
  \tag test { c8^"test" a g f e2 }
}

% 'otherI', 'otherII' and 'test' are not in the same group
% as 'tagI' so they stay untouched.
\new Voice {
  \keepWithTag tagI \music
}

\resetTagGroup \tgI

% now only 'otherI' and 'otherII' are in a tag group,
% so '\keepWithTag tagI' filters 'tagII' and 'test'.
\new Voice {
  \keepWithTag tagI \music
}
@end lilypond

@funindex \addToTagGroup
@funindex \removeFromTagGroup

@item
L'ajout ou le retrait d'une balise à un regroupement à l'aide de
@code{\addToTagGroup} et @code{\removeFromTagGroup} constituent d'autres
moyens de modifier des regroupements.

@lilypond[verbatim,quote]
tgI = \tagGroupRef tagI,tagII
tgII = \tagGroupRef otherI,otherII

music = \relative {
  \tag tagI { c''4^"tagI" c c c }
  \tag tagII { a2^"tagII" a }
  \tag otherI { d4^"otherI" d d d }
  \tag otherII { f,4^"otherII" g a c }
  \tag test { c8^"test" a g f e2 }
}

% 'otherI', 'otherII' and 'test' are not in the same group
% as 'tagI' so they stay untouched.
\new Voice {
  \keepWithTag tagI \music
}

\addToTagGroup \tgI test

% now 'tagI', 'tagII' and 'test' are in the same group
% so 'tagII' and 'test' are removed.
\new Voice {
  \keepWithTag tagI \music
}

\removeFromTagGroup \tgII otherII
\addToTagGroup \tgI otherII

% now 'otherII' is removed from 'tgII' and
% added to 'tgI' so only 'otherI' is in its
% own tag group and is not filtered.
\new Voice {
  \keepWithTag tagI \music
}
@end lilypond

@end itemize


@subsubheading Préposition et apposition a de la musique balisée
@c VO Prepending and appending to tagged music

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

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 constructions
musicales existantes. Les différentes possibilités sont les suivantes :

@indentedblock
@table @asis
@item Musique séquentielle ou simultanée
Lorsqu'a été balisée l'intégralité d'une construction @code{@{@dots{}@}}
ou @code{<<@dots{}>>}, peuvent venir s'insérer, avant ou après, des
expression musicales.

@item Accords
Lorsqu'a été balisé un accord @code{<@dots{}>}, peuvent venir s'y
ajouter, avant ou après, d'autres notes ou des articulations, ces
dernières pour l'accord dans sa globalité.

@item Notes et silences
Lorsque la musique balisée est une note (y compris à l'intérieur d'un
accord), ou un silence, peuvent venir s'y ajouter, avant ou après,
d'autres articulations.

Afin d'ajouter d'autres @emph{notes}, il est préférable de les placer
dans une construction d'accord et baliser @emph{l'accord}. Notez bien
qu'il n'est pas possible de baliser une simple @emph{articulation} et y
ajouter quelque chose, puisqu'il ne s'agit pas d'une liste ; il vaut
alors mieux baliser la note.
@end table
@end indentedblock

Ces deux instructions sont affectées d'une balise, le matériau à
raccorder à chaque instance de la balise, et l'expression balisée.

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

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


@subsubheading Remplacement de musique balisée
@c VO Replace tagged music

@funindex \replaceWithTag

Il est possible de remplacer de la musique balisée par une autre
musique.

@lilypond[verbatim,quote]
music = { c' \tag #'ici { d' } e' }

{
  \music
  \replaceWithTag #'ici c' \music
}
@end lilypond

Il faut bien garder à l'esprit que la balise disparaît avec son
remplacement ; elle ne peut donc être remplacée qu'une seule fois. Le
filtrage aussi n'est plus possible à la suite du remplacement.

@lilypond[verbatim,quote]
music = { c' \tag #'ici { d' } e' }

{
  \removeWithTag #'ici % sans effet à cause du remplacement de balise
  \replaceWithTag #'ici c'
  \music
}
@end lilypond


@subsubheading Balise et @emph{markup}
@c VO Tagging within markups

@cindex @emph{markup} et balise

@funindex \keep-with-tag
@funindex \remove-with-tag
@funindex \push-to-tag
@funindex \append-to-tag
@funindex \replace-with-tag

La commande @code{\tag} peut s'utiliser aussi dans des @code{\markup}.
LilyPond fournit les commandes @code{\keep-with-tag},
@code{\remove-with-tag}, @code{\push-to-tag}, @code{\append-to-tag} et
@code{\replace-with-tag} qui se comportent comme celles utilisées pour
les expressions musicales.

@lilypond[verbatim,quote]
test = \markup {
  \tag #'AA a
  \tag #'BB b
  \tag #'CC c
}

\markup { \keep-with-tag #'BB \test }
\markup { \remove-with-tag #'BB \test }
\markup { \push-to-tag #'CC pre \test }
\markup { \append-to-tag #'CC post \test }
\markup { \replace-with-tag #'CC sub \test }
@end lilypond

Les commandes musicales @code{\keepWithTag} et @code{\removeWithTag}
filtrent aussi les balises des portions @code{\markup} incluses dans la
musique.

@lilypond[verbatim,quote]
music = \relative {
  c'4^\markup { \tag #'one first \tag #'two second part } c c c
}

{
  \keepWithTag #'one \music
  \removeWithTag #'one \music
}
@end lilypond

@funindex \pushToTagMarkup
@funindex \appendToTagMarkup
@funindex \replaceWithTagMarkup

Il est aussi possible d'insérer ou ajouter quelque chose à un
@code{\markup} attaché aux objets musicaux. On ne peut toutefois
utiliser @code{\pushToTag}, @code{\appendToTag} ou
@code{\replaceWithTag} puisqu'ils ne traitent que de la musique ;
cependant, @code{\pushToTagMarkup}, @code{\appendToTagMarkup} et
@code{\replaceWithTagMarkup} sont conçus pour rajouter un @emph{markup}.

@lilypond[verbatim,quote]
music = \relative {
  c'4^\markup { \tag #'part part } c c c
}

{
  \pushToTagMarkup #'part "great" \music
  \appendToTagMarkup #'part \markup { is also great } \music
  \replaceWithTagMarkup #'part \markup { cool substitution } \music
}
@end lilypond

Le filtrage des balises fonctionne aussi lorsque de la musique comprise
dans un bloc @code{\score} est membre d'une commande de @emph{markup}.

@lilypond[verbatim,quote]
music = \relative {
  c'2^\markup { \tag #'first first \tag #'second second } c
  \tag #'first { d d }
  \tag #'second { f f }
}

\markup {
  \keep-with-tag #'first \score { \music }
  \remove-with-tag #'first \score { \music }
}
@end lilypond

@funindex \tag-list

Une attention particulière doit toutefois être portée lors de
l'utilisation de balises avec des listes de @emph{markups}. Les
fonctions de filtrage fonctionnent comme prévu, mais les commandes
telles que @code{\push-to-tag}, @code{\append-to-tag} et
@code{\replace-with-tag} posent problème.

@lilypond[verbatim,quote]
\markup {
  \remove-with-tag #'test { a \tag #'test { b c } d }
}
\markup {
  \push-to-tag #'test "twice" { a \tag #'test { b c } d }
}
\markup {
  \replace-with-tag #'test "twice" { a \tag #'test { b c } d }
}
@end lilypond

La raison de ce comportemenet tient au fait que LilyPond transforme

@example
\tag #'test @{ b c @}
@end example

@noindent
de manière interne en

@example
\tag #'test b
\tag #'test c
@end example

@noindent
et donc insère deux fois le texte donné. Le balisage d'une liste à
laquelle doit s'insérer ou s'ajouter quelque chose s'obtient en
utilisant la commande @code{\tag-list}.

@lilypond[verbatim,quote]
\markup {
  \push-to-tag #'test "once" { a \tag-list #'test { b c } d }
}
@end lilypond

@morerefs
Manuel d'initiation :
@rlearningnamed{Organizing pieces with variables,
Organisation du code source avec des variables}.

Manuel de notation :
@ref{Including LilyPond files},
@ref{Automatic part combining}.
@endmorerefs

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

Même lors de l'utilisation de regroupements de balises, les commandes
telles que @code{\keepWithTag} ne sont pas cumulatives. du code comme

@example
\keepWithTag violonI,original \laMusique
@end example

@noindent
ne produira pas le même résultat que

@example
\keepWithTag violonI \keepWithTag original \laMusique
@end example


@node Using global settings
@subsection Globalisation des réglages

@cindex réglages, globalisation

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, que vous pourrez charger par des options
@code{-dinclude-settings}. 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 @rlearningnamed{Style sheets, Feuilles
de style}.

@morerefs
Manuel d'initiation :
@rlearningnamed{Style sheets, Feuilles de style},
@rlearningnamed{Organizing pieces with variables,
Organisation du code source avec des variables}.

Manuel de notation :
@ref{Including LilyPond files}.
@endmorerefs


@node Using music functions
@section Utilisation de fonctions musicales

@c TODO -- add @morerefs, etc. to these subsections

Une adaptation ou un affinage qui devient récurrent parce que doit
s'appliquer à différentes expressions musicales peut faire l'objet d'une
@emph{fonction musicale}. Nous ne traiterons ici que des fonctions de
@emph{substitution}, dont le but est de substituer une variable en un
bout de code LilyPond. D'autres fonctions, plus complexes, sont abordées
au chapitre @rextendnamed{Music functions, Fonctions musicales}.


@node Substitution function syntax
@subsection Syntaxe d'une fonction de substitution

La rédaction d'une fonction chargée de substituer du code LilyPond à une
variable est chose relativement aisée. Une telle fonction est de la
forme

@example
fonction =
#(define-music-function
     (@var{arg1} @var{arg2}@dots{})
     (@var{type1?} @var{type2?}@dots{})
   #@{
     @var{@dots{}musique@dots{}}
   #@})
@end example

@noindent
où

@indentedblock
@multitable @columnfractions .2 .7
@item @code{@var{argN}}
@tab Le @var{n}ième argument.

@item @code{@var{typeN?}}
@tab Un @emph{type de prédicat} Scheme pour lequel @code{@var{argN}}
doit renvoyer @code{#t}.

@item @code{@var{@dots{}musique@dots{}}}
@tab Du code LilyPond tout ce qu'il y a de plus ordinaire, avec des
@samp{$} (là où seule une construction LilyPond est autorisée) et des
@samp{#} (lorsqu'il s'agit d'une valeur en Scheme, d'un argument de
fonction musicale ou de musique faisant partie d'une liste) pour
référencer les arguments (par ex. @samp{#arg1}).
@end multitable
@end indentedblock

La liste des types de prédicat est aussi obligatoire. Voici quelques uns
des types de prédicat les plus utilisés dans les fonctions musicales :

@itemize @w{}
@item boolean?
@item cheap-list?  @emph{(au lieu de }« list? »@emph{, pour accélérer le traitement)}
@item ly:duration?
@item ly:music?
@item ly:pitch?
@item markup?
@item number?
@item pair?
@item string?
@item symbol?
@end itemize

@noindent
Une liste plus fournie est disponible à l'annexe @ref{Predefined type
predicates}. Vous pouvez par ailleurs définir vos propres types de
prédicat.

@morerefs
Manuel de notation :
@ref{Predefined type predicates}.

Manuel d'extension :
@rextendnamed{Music functions, Fonctions musicales}.

Fichiers d'initialisation :
@file{lily/music-scheme.cc},
@file{scm/c++.scm},
@file{scm/lily.scm}.
@endmorerefs


@node Substitution function examples
@subsection Exemples de fonction de substitution

@cindex substitution, fonction

La présente rubrique regroupe quelques exemples de fonction
substitutive. Le propos est ici d'illustrer les possibilités qu'offrent
les fonctions de substitution simple.

Dans ce premier exemple, nous définissons une fonction dans le but de
simplifier le réglage du décalage d'une annotation (un
@code{TextScript}).

@lilypond[quote,verbatim,ragged-right]
padText =
#(define-music-function
     (padding)
     (number?)
   #{
     \once \override TextScript.padding = #padding
   #})

\relative {
  c''4^"piu mosso" b a b
  \padText 1.8
  c4^"piu mosso" b a b
  \padText 2.6
  c4^"piu mosso" b a b
}
@end lilypond

Nous pouvons utiliser autre chose que des nombres au sein d'une
fonction, y compris une expression musicale :

@lilypond[quote,verbatim,ragged-right]
custosNote =
#(define-music-function
     (note)
     (ly:music?)
   #{
     \tweak NoteHead.stencil #ly:text-interface::print
     \tweak NoteHead.text
        \markup \musicglyph "custodes.mensural.u0"
     \tweak Stem.stencil ##f
     #note
   #})

\relative { c'4 d e f \custosNote g }
@end lilypond

@funindex \etc

Ces fonctions sont toutes deux des expressions uniques simples dans
lesquelles seul le dernier élément d'un appel à une fonction ou une
dérogation est absent. Dans ce cas particulier de définition d'une
fonction, une syntaxe alternative et plus simple autorise à se cantonner
à écrire la partie constante de l'expression et remplacer son dernier
élément, absent, par @code{\etc} :

@lilypond[quote,verbatim,ragged-right]
padText =
  \once \override TextScript.padding = \etc

\relative {
  c''4^"piu mosso" b a b
  \padText 1.8
  c4^"piu mosso" b a b
  \padText 2.6
  c4^"piu mosso" b a b
}
@end lilypond

@lilypond[quote,verbatim,ragged-right]
custosNote =
  \tweak NoteHead.stencil #ly:text-interface::print
  \tweak NoteHead.text
     \markup \musicglyph "custodes.mensural.u0"
  \tweak Stem.stencil ##f
  \etc

\relative { c'4 d e f \custosNote g }
@end lilypond

Une fonction de substitution peut traiter plusieurs arguments :

@lilypond[quote,verbatim,ragged-right]
tempoPadded =
#(define-music-function
     (padding tempotext)
     (number? markup?)
   #{
     \once \override Score.MetronomeMark.padding = #padding
     \tempo \markup { \bold #tempotext }
   #})

\relative {
  \tempo \markup { "Low tempo" }
  c''4 d e f g1
  \tempoPadded 4.0 "High tempo"
  g4 f e d c1
}
@end lilypond

@c TODO: add appropriate @@ref's here.


@node How to prevent sharing of music expressions
@subsection Comment éviter le partage d'expressions musicales

@cindex expression musicale, partage
@cindex expression musicale, copie

Lors de l'écriture de fonctions musicales, il est important de respecter
la règle suivante : une même expression musicale de doit pas se
retrouver à plusieurs endroits. Voici, à titre d'exemple, une fonction
problématique :

@lilypond[verbatim,quote]
simpleAccompaniment =
#(define-music-function
   (bass-1 bass-2 chord) (ly:music? ly:music? ly:music?)
   #{
     #bass-1 #chord #bass-2 #chord
   #})

{
  \clef bass
  \simpleAccompaniment c g, <e g>
  \simpleAccompaniment d g, <f g>
}
@end lilypond

Le problème avec cette fonction est évident si le résultat est
transposé :

@lilypond[verbatim,quote]
simpleAccompaniment =
#(define-music-function
   (bass-1 bass-2 chord) (ly:music? ly:music? ly:music?)
   #{
     #bass-1 #chord #bass-2 #chord
   #})

\transpose c e {
  \clef bass
  \simpleAccompaniment c g, <e g>
  \simpleAccompaniment d g, <f g>
}
@end lilypond

Alors que les notes de basse sont correctes, l'accord n'est pas
transposé comme il faut -- il est en fait transposé deux fois. La raison
tient au fait que l'expression musicale @var{chord} est utilisé deux
fois dans le résultat de la fonction sans le recopier. Les fonctions
telles que @code{\transpose} modifient directement l'objet musical --
dans le cas de @code{\transpose}, les hauteurs sont changées. Lorsqu'un
même objet musical est réutilisé, les modifications appliquées à l'un
des endroits où il est utilisé affectent les deux puisqu'ils concernent
le même objet. Dans le cas présent, @code{\transpose} rencontre l'objet
deux fois, donc le transpose deux fois.

L'un des moyens de corriger cette fonction consiste à utiliser @samp{$}
au lieu de @samp{#} pour référencer les variables, ce qui en réalise une
copie. La différence entre @samp{#} et @samp{$} est abordée dans
@rextendnamed{LilyPond Scheme syntax,Syntaxe Scheme dans LilyPond}.

@lilypond[verbatim,quote]
simpleAccompaniment =
#(define-music-function
   (bass-1 bass-2 chord) (ly:music? ly:music? ly:music?)
   #{
     $bass-1 $chord $bass-2 $chord
   #})

\transpose c e {
  \clef bass
  \simpleAccompaniment c g, <e g>
  \simpleAccompaniment d g, <f g>
}
@end lilypond


@node Substitution functions and relative octave entry
@subsection Fonctions de subsitution et octave relative

@cindex octave relative et fonction de substitution
@funindex \relative
@funindex make-relative

Lorsque @code{\relative} s'applique à une expression musicale, celle-ci
est parcourue à la recherche de notes, et les hauteurs sont modifiées
dans leur ordre d'apparition, l'octave de chaque hauteur étant changée
selon sa marque d'octaviation (@samp{'} et @samp{,}) et la hauteur qui
précède. Dans le cadre d'une fonction substitutive, ceci peut mener à
des situations où la musique est « relativisée » de manière surprenante
parce que le résultat de la fonction utilise les paramètres plusieurs
fois ou dans un ordre différent. Examinons la fonction suivante et
comment son résultat réagit au @code{\relative}.

@lilypond[verbatim,quote]
simpleAccompaniment =
#(define-music-function
   (bass-1 bass-2 chord) (ly:music? ly:music? ly:music?)
   #{
     $bass-1 $chord $bass-2 $chord
   #})

\relative {
  \clef bass
  \simpleAccompaniment c g <e' g>
  \simpleAccompaniment d g, <f' g>
}
@end lilypond

Dans cet exemple, le résultat est identique à

@lilypond[verbatim,quote]
\relative {
  \clef bass
  c <e' g> g <e' g>
  d <f' g>  g, <f' g>
}
@end lilypond

Ce n'est toutefois pas le résultat auquel on s'attendrait à
l'utilisation la fonction @code{\simpleAccompaniment}. La hauteur
@code{g,} est relative à la première hauteur de l'accord qui précède,
@code{<e' g>}, bien qu'il soit libellé après le @code{c} de la source.
De toute évidence, les hauteurs devraient être relatives selon l'ordre
dans lequel elles sont transmises à la fonction, non pas selon leur
ordre d'apparition en sortie de la fonction. Le moyen d'y parvenir est
un recours à la fonction Scheme @code{make-relative}. Ses arguments
sont : une liste de variables, une expression de référence, et une
expression musicale principale. L'expression de référence est réputée
être une représentation de la façon dont les variables auront été
saisies. Il s'agit la plupart du temps d'une simple expression de la
forme @code{#@{ @dots{} #@}} contenant les variables dans l'ordre.
Attention à ne pas réaliser de copie dans l'expression de référence --
en particulier, il faut y utiliser @samp{#}, pas @samp{$}. L'exemple
précédent peut se corriger à l'aide de @code{make-relative} de la
manière suivante :

@lilypond[verbatim,quote]
simpleAccompaniment =
#(define-music-function
   (bass-1 bass-2 chord) (ly:music? ly:music? ly:music?)
   (make-relative
    (bass-1 bass-2 chord)
    #{ #bass-1 #bass-2 #chord #}
    #{ $bass-1 $chord $bass-2 $chord #}))

\relative {
  \clef bass
  \simpleAccompaniment c g <e' g>
  \simpleAccompaniment d g, <f' g>
}
@end lilypond


@need 1500
@node Special characters
@section Caractères spéciaux

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


@node Text encoding
@subsection Codage du texte

@cindex UTF-8
@cindex texte, codage

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.

@c NOTE: No verbatim in the following example as the code does not
@c display correctly in PDF Font settings for Cyrillic and Hebrew

@lilypond[quote]
% Linux Libertine fonts contain Cyrillic and Hebrew glyphs.
\paper {
  property-defaults.fonts.serif = "Linux Libertine O,serif"
  property-defaults.fonts.sans = "Linux Biolinum O,sans-serif"
  property-defaults.fonts.typewriter = "Linux Libertine Mono O,monospace"
}

% 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
@subsection 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{https://www.unicode.org/}.

Par exemple, @code{\char ##x03BE} et @code{\char #958} correspondent
tous deux au caractère unicode U+03BE, dénommé « 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 textuel, dans une
articulation, dans des paroles et dans du texte indépendant.

@lilypond[quote,verbatim]
\score {
  \relative {
    c''1
    \textMark \markup { \char ##x03A8 }
    c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
  }
  \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
\markup { "Copyright 2008--2026" \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 ASCII aliases
@subsection Équivalents ASCII

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

@noindent
qu'en un point particulier de votre source :

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

Le remplacement n'affectera pas nécessairement une chaîne ; il peut
s'agir d'un @emph{markup} quelconque. Au niveau de la syntaxe, ceci
requiert d'utiliser la syntaxe de quasi-citation de Scheme, à savoir une
apostrophe inversée @samp{`} au lieu d'une apostrophe normale @samp{'}
pour écrire la liste associative.

@lilypond[quote,verbatim]
\markup \replace
  #`(("2nd" . ,#{ \markup \concat { 2 \super nd } #})) "2nd time"
@end lilypond

Ces alias ne pourront plus, quant à eux, faire l'objet d'un remplacement.

@morerefs
Manuel de notation :
@ref{List of special characters}.

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


@need 1500
@node Controlling output
@chapter Contrôle des sorties


@node Extracting fragments of music
@section Extraction de fragments musicaux

@cindex fragment, extraction
@cindex extraction, fragment
@funindex clip-regions

LilyPond permet d'extraire des fragments d'une partition. La variable
@code{clip-regions}, qui se place dans le bloc @code{\layout} ou
@code{\paper}, permet de définir explicitement le ou les emplacements de
la musique concernés ; ils seront extraits en lançant @command{lilypond}
avec l'option @option{-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
@code{make-rhythmic-location} auront été ajoutées à la liste de
@code{clip-regions}.

Lorsque des débuts ou fins de système sont inclus, les extensions à
l'objet @code{System}, tels que les noms d'instrument, seront eux aussi
inclus.

Les notes d'ornement en terminaison du fragment extrait ne seront pas
incluses.

Chaque fragment fait l'objet d'un fichier particulier. 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. Partant de l'exemple ci-dessus couvre deux lignes du
PDF résultant de @file{toto.ly}, les fichiers d'extraction s'appelleront
@file{toto-@/from-5.1.2-@/to-7.3.4-@/clip.pdf} et
@file{toto-@/from-5.1.2-@/to-7.3.4-@/clip-1.pdf}.


@morerefs
Manuel de notation :
@ref{The layout block}.

Manuel d'utilisation :
@rprogramnamed{Command-line usage, Utilisation en ligne de commande}.
@endmorerefs


@node Skipping corrected music
@section Ignorer des passages de la partition

@cindex saisie, ignorer des passages

@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 « escamoter » le reste et ne
générer que les dernières mesures en définissant une variable
+particulière en début de fichier, comme ceci :

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

@noindent
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. En tant que propriété du contexte @code{Score},
il affecte toutes les voix et portées -- @pxref{Score - the master of
all contexts}.

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 qui interviendraient avant que @code{skipTypesetting} ne
soit désactivé.

@lilypond[quote,ragged-right,verbatim]
\relative c' {
  c4 c c c
  \set Score.skipTypesetting = ##t
  d4 d d d
  \tempo 4 = 80
  e4 e e e
  \set Score.skipTypesetting = ##f
  f4 f f f
}
@end lilypond

@predefined
@code{showLastLength},
@code{showFirstLength}.
@endpredefined

@morerefs
Manuel de notation :
@ref{Interpretation contexts},
@ref{Score - the master of all contexts}.

Référence des propriétés internes :
@rinternalsnamed{Tunable context properties,
Propriétés de contexte ajustables}.
@endmorerefs


@node Alternative output formats
@section Formats de sortie alternatifs

@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 @rprogramnamed{Command-line
usage, Utilisation en ligne de commande} à ce sujet.


@node SVG Output
@subsection Sortie SVG

La sortie SVG peut accessoirement contenir des métadonnées pour les
@emph{grobs} (objets graphiques) tels que têtes de notes, silences, etc.
Ces métadonnées peuvent correspondre aux attributs standards du format
SVG comme @code{id} et @code{class}, ou bien à des attributs
personnalisés. Les attributs et leur valeur se spécifient à l'aide d'une
dérogation à la propriété @code{output-attributes} d'un @emph{grob} par
une liste associative (alist) en Scheme. Les valeurs peuvent être des
nombres, chaînes ou symboles comme, par exemple :

@example
@{
  \once \override NoteHead.output-attributes =
  #'((id . 123)
     (class . "ceci cela")
     (data-quelconque . quelquechose))
  c
@}
@end example

@noindent
Le code ci-dessus produira la balise @code{<g>} (group) suivante dans le
fichier SVG :

@example
<g id="123" class="ceci cela" data-quelconque="quelquechose">
  ...NoteHead grob SVG elements...
</g>
@end example

@noindent
La balise @code{<g>} contient tous les éléments SVG d'un @emph{grob}
donné ; certains @emph{grobs} génèrent de multiples éléments SVG. Dans
la syntaxe SVG, le préfixe @code{data-} s'utilise pour les attributs de
métadonnée personnalisée non-standard.


@node Embedding files in PDF output
@section Intégration de fichiers à la sortie PDF

@cindex PDF, intégration de fichiers
@cindex fichiers, intégration au PDF

L'option en ligne de commande @option{-dembed-source-code} permet à
LilyPond de « joindre » au fichier PDF final tous les fichiers sources
nécessaires à la compilation (voir @rprogramnamed{Advanced command-line
options for LilyPond,Options avancées de @command{lilypond}}). Un
lecteur de PDF permettra ensuite d'extraire ces annexes pour une
utilisation future.

Dans le même ordre d'idée, il est possible d'adjoindre n'importe quel
fichier dans le PDF résultant à l'aide de la fonction
@code{ly:note-extra-source-file} (voir @rinternals{Scheme functions}).


@node Replacing the notation font
@section Changement des fontes musicales

@cindex fontes musicales, modification

Gonville est une alternative au jeu de glyphes @emph{Feta} inclus dans
la fonte Emmentaler que LilyPond utilise par défaut.  Vous pouvez la
télécharger à partir de
@example
@uref{https://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 les glyphes @emph{Feta} de LilyPond :

@sourceimage{Gonville_before,15cm,}


@subsubheading Instructions d'installation

@itemize
@item
Téléchargez puis extrayez les fichiers de fonte.

@item
Copiez@footnote{Il est pour l'instant nécessaire de répéter ces
opération à chaque installation d'une nouvelle version de LilyPond. Si
vous lancez le binaire @command{lilypond} directement du dossier de
construction, consultez @rcontrib{Replacing the notation fonts in
development versions} pour de plus amples informations.} les fichiers

@example
gonville-11.otf
gonville-13.otf
gonville-14.otf
gonville-16.otf
gonville-18.otf
gonville-20.otf
gonville-23.otf
gonville-26.otf
gonville-brace.otf
@end example

@noindent
dans le dossier
@file{@dots{}/@/share/@/lilypond/@/@var{X.Y.Z}/@/fonts/@/otf}.

@item
Si vous disposez des fichiers @file{gonville-*.svg}, copiez les dans
@file{@dots{}/@/share/@/lilypond/@/@var{X.Y.Z}/@/fonts/@/svg}.
@end itemize

Pour de plus amples informations, reportez-vous à @rlearningnamed{Other
sources of information, Autres sources de documentation}.

Il est à noter que les fichiers @file{gonville-*.otf} sont destinés aux
moteurs @code{ps} et @code{cairo} (pour obtenir des fichiers PDF ou
PostScript, ainsi que tous les formats de sortie pour le moteur Cairo) ;
les fichiers @file{gonville-*.svg} sont destinés au moteur @code{svg}.
Pour de plus amples informations, consultez @rprogramnamed{Advanced
command-line options for LilyPond, Options avancées de
@command{lilypond}}.

La syntaxe suivante substitue aux fontes musicales les fontes Gonville.

@example
\paper @{
  property-defaults.fonts.music = "gonville"
@}
@end example

Pour plus d'informations, @pxref{Changing fonts}.

@morerefs
Manuel d'initiation :
@rlearningnamed{Other sources of information,
Autres sources de documentation}.

Manuel de notation :
@ref{Changing fonts},
@ref{The Emmentaler font}.
@endmorerefs

@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 sont absent.
Consultez le site de l'auteur pour de plus amples informations ainsi
qu'à propos des conditions d'utilisation.


@subsubheading Autres fontes musicales

Si vous disposez d'autres fontes musicales telles que
@file{@var{nomfonte}-*.otf} ou @file{@var{nomfonte}-*.svg}, vous pouvez
les utiliser de façon comparable à Gonville.

Autrement dit, copiez les fichiers @file{@var{nomfonte}-*.otf} dans
@file{@dots{}/@/share/@/lilypond/@/@var{X.Y.Z}/@/fonts/@/otf}. Si vous
disposez de fichiers @file{@var{nomfonte}-*@/.svg}, copiez les dans
@file{@dots{}/@/share/@/lilypond/@/@var{X.Y.Z}/@/fonts/@/svg}.

Note : à ce jour, et pour fonctionner correctement, LilyPond requiert la
présence des suffixes suivants dans les dossiers d'installation :
@file{-11}, @file{-13}, @file{-14}, @file{-16}, @file{-18}, @file{-20},
@file{-23}, @file{-26} et @file{-brace}. Par exemple,
@file{emmentaler-11.otf}, @file{emmentaler-20.svg}, etc.

La syntaxe suivante substitue aux fontes musicales les fontes
@var{nomfonte}.

@example
\paper @{
  % fichier de fonte sans suffixe ni extension
  property-defaults.fonts.music = "@var{nomfonte}"
@}
@end example


@node Creating MIDI output
@chapter Génération de fichiers MIDI

@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 grâce à 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.


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

@cindex MIDI, éléments pris en compte

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

@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 paroles,
@item les marques : indications de repère, segnos, indications de coda
et libellés de section,
@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 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}, y compris
des valeurs métronomique sous forme de fraction,
@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{Context
properties for MIDI effects}.

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

@itemize
@item les appoggiatures -- 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{Enhancing MIDI output}.


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

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

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 The MIDI block
@section Le bloc MIDI

@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}@footnote{Il
existe aussi une commande de @emph{markup} @code{\score}, qui ne produit
pas de MIDI, même en présence d'un bloc @code{\midi} -- @pxref{Scores
within markup}.} :

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

Un bloc @code{@bs{}midi} en début de fichier permet d'effectuer des
réglages MIDI de manière globale. Bien entendu, la génération d'un
fichier MIDI ne sera effective qu'en présence d'une section
@code{@bs{}midi} au sein d'un bloc @code{@bs{}score}.

De façon similaire, un bloc @code{@bs{}layout} en début de fichier
affecte la mise en forme de manière globale mais n'est d'aucune
influence sur la production ou non d'un fichier imprimable.}

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{File
structure} :

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

@morerefs
Manuel de notation :
@ref{File structure}.

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

@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 Controlling MIDI dynamics
@section Gestion des nuances en MIDI

@cindex MIDI, gestion des nuances
@cindex nuances et MIDI

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.


@node Dynamic marks in MIDI
@subsection Indication des nuances en MIDI

@cindex MIDI, indications de nuance
@cindex nuances et MIDI, indication

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{ly/midi-init.ly}.

@snippets

@cindex MIDI, nuance personnalisée
@cindex nuance, MIDI, personnalisation
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/creating-custom-dynamics-in-midi-output.ly}

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


@node Setting MIDI volume
@subsection Réglage du volume en MIDI

@cindex MIDI, réglage du volume
@cindex MIDI, égalisation

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} -- grâce 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

@cindex MIDI, égalisation par défaut, adaptation
@cindex @'egalisation en MIDI, adaptation
@cindex instrument MIDI, égalisation
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/replacing-default-midi-instrument-equalization.ly}

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

Manuel de notation :
@ref{Score layout}.

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

@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 Setting MIDI block properties
@subsection Réglage de propriétés dans le bloc MIDI

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'appellent @emph{performers} -- des
« interprètes ».

@morerefs
Manuel d'initiation :
@rlearningnamed{Other sources of information, Autres sources de documentation}.

Manuel de notation :
@ref{Score layout},
@ref{Expressive marks}.

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

Morceaux choisis :
@rlsr{MIDI}.

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

@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 Using MIDI instruments
@section Gestion des instruments MIDI

@cindex instrument, nom d'
@cindex MIDI, instrument
@funindex 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

@noindent
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{MIDI instruments}.

@morerefs
Manuel d'initiation :
@rlearningnamed{Other sources of information, Autres sources de documentation}.

Manuel de notation :
@ref{MIDI instruments},
@ref{Score layout}.

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

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

@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
@rlearningnamed{Other sources of information, Autres sources de
documentation}.


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

@cindex reprise développée
@cindex MIDI et reprise
@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 @{
      \volta 1 @{ g' a' a' g' @}
      \volta 2 @{ f' e' d' c' @}
    @}
  @}
  \midi @{ @}
@}
@end example

Lorsque l'on veut utiliser @code{\unfoldRepeats} seulement pour le rendu
MIDI, il faut établir @strong{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ées correctement dans @strong{toutes} les voix.

@morerefs
Manuel de notation :
@ref{Repeats}.
@endmorerefs


@node MIDI channel mapping
@section Affectation des canaux MIDI

@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 @code

@item '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 '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 '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 une 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
différentes 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

@cindex MIDI, un canal par voix
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/changing-midi-output-to-one-channel-per-voice.ly}


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

@cindex effets MIDI
@cindex MIDI, effets

Les différentes propriétés de contexte qui suivent permettent
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{MIDI channel mapping}.

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 @code

@item Staff.midiPanPosition
@cindex pan, MIDI
@cindex spatialisation (pan), MIDI
@funindex 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 valeur de 0.0
(@code{#CENTER}) distribuera équitablement le son entre les
haut-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 Staff.midiBalance
@cindex stéréo MIDI, balance
@cindex balance MIDI
@funindex 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 Staff.midiExpression
@cindex expression MIDI
@funindex 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 LilyPond Wiki.

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

@item Staff.midiReverbLevel
@cindex reverb MIDI
@funindex 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 Staff.midiChorusLevel
@cindex chorus MIDI
@funindex 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 bits, ou de 0 à 16383 et sur 14
bits 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 Enhancing MIDI output
@section Amélioration du rendu MIDI

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

Des scripts additionnels permettent d'affiner la manière dont les
nuances, articulations et rythme sont rendus en MIDI : le script
@file{articulate} et le script @file{swing}.


@node The articulate script
@subsection Le script @file{articulate}

@cindex @code{articulate.ly} script

L'utilisation du script @code{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 échelonné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

@funindex \articulate
Le script @code{\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}.

@morerefs
Manuel d'initiation :
@rlearningnamed{Other sources of information, Autres sources de documentation}.

Manuel de notation :
@ref{Score layout}.

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

@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 The swing script
@subsection Le script @file{swing}

@cindex @code{swing.ly} script

Le script @file{swing} procure des fonctions additionnelles qui
permettent de jouer des durées égales sur un rythme inégal. L'exemple le
plus évident est l'interprétation @emph{swinguée} que l'on trouve en
jazz où des croches binaires devraient se jouer de façon ternaire.
D'autres interprétations sont toutefois prises en charge.

Ce script doit faire l'objet d'une inclusion en début de fichier
source :

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

Le script fournit trois commandes :
@itemize
@item
@funindex \tripletFeel
@code{\tripletFeel} crée un @emph{swing} sur une base de triolet. Elle
prend deux arguments : les durées à affecter (typiquement @code{8} pour
des croches) et l'expression musicale sur laquelle l'appliquer.

@item
@funindex \applySwing
@code{\applySwing} prend un argument supplémentaire avant l'expression
musicale : une @emph{liste de pondération} de @var{n} nombres de ratio
exprimant la manière dont doivent être jouées les notes régulières. Par
exemple, @code{#'(2 1)} indique que chaque note devrait se jouer deux
fois plus longue que la suivante -- en fait,
@code{\tripletFeel @var{durée} @{@var{musique}@}} est un raccourci de
@code{\applySwing @var{durée} #'(2 1) @{@var{musique}@}} Des croches
chaloupées plus doucement s'obtiennent avec une @emph{liste de
pondération} de @code{#'(3 2)} ou toute autre valeur selon les goûts.

@noindent
Cette liste peut prendre plus de deux valeurs, ce qui permet d'adopter
un schéma de @emph{groove} plus long ou plus sophistiqué. Par exemple,
une impression de samba sur des double-croches peut s'obtenir ainsi :

@example
\score @{
  \applySwing 16 #'(3 2 2 3) @{
    @var{@dots{} music @dots{}}
  @}
  \midi @{ @}
@}
@end example

@item
@funindex \applySwingWithOffset
@code{\applySwingWithOffset} ajoute quant à elle un autre argument entre
la @emph{liste de pondération} et l'expression musicale : une durée de
décalage. Cette commande devrait s'utiliser lorsque l'expression
musicale démarre à contre temps, avec une portion de cycle.
@end itemize

@warning{Tout comme avec le script @file{articulate}, toutes les
commandes seront rendues dans la partition imprimable, ce qui résulte en
un espacement irrégulier. Ceci peut s'éviter en utilisant le script dans
un bloc @code{@bs{}score} dédié à la sortie MIDI.}

Une aide et des informations supplémentaires sont directement incluses
dans le script -- voir @file{ly/swing.ly}.

@morerefs
Manuel d'initiation :
@rlearningnamed{Other sources of information, Autres sources de documentation}.

Manuel de notation :
@ref{Rhythms}.

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

@knownissues
@itemize
@item
Les constructions @code{\repeat} et @code{\repeat unfold} ne sont pas
prises en considération lors de la temporisation des notes. Ceci
entraînera des problèmes à moins que les durées de tous les fragments
répétés soient des multiples entiers du cycle de @emph{swing}.

@item
Ces fonctions sont agnostiques en matière de métrique et de mesure,
raison pour laquelle des décalages doivent être fournis à l'aide de
@code{\applySwingWithOffset} lorsque la musique démarre sur une levée.

@item
Les appoggiatures sont ignorées et laissées telles quelles, tout comme
les triolets.
@end itemize


@node Extracting musical information
@chapter Extraction d'informations musicales

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


@node Displaying LilyPond notation
@section Affichage de notation au format LilyPond

@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. La simple insertion d'un @code{\displayLilyMusic} dans une
expression musicale permet d'obtenir l'information la concernant.

Si l'instruction @code{\displayLilyMusic} interprète et affiche des
informations sur un fragment, la faire précéder d'un @code{\void} aura
pour effet de l'exclure du fichier résultant.

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


@node Displaying Scheme music expressions
@section Affichage de la musique sous forme d'expression Scheme

Voir @rextendnamed{Displaying music expressions, Affichage d'expressions
musicales}.


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

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 « 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.
