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

@ignore
    Translation of GIT committish: db53c05f11bea8831733b1fdf7ebe32cb1f491f4

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@c Translators: Ludovic Sardain, John Mandereau
@c Translation checkers: Jean-Charles Malahieude, Jean-Yves Baudais, Damien Heurtebise
@c Translation status: post-GDP


@node Introduction
@chapter Introduction

Ce chapitre constitue une première présentation de LilyPond et de sa 
documentation.

@menu
* Background::                  
* About the documentation::     
@end menu


@node Background
@section Background

Cette partie présente les objectifs de LilyPond ainsi que son 
architecture.

@menu
* Engraving::                   
* Automated engraving::         
* What symbols to engrave?::    
* Music representation::        
* Example applications::        
@end menu


@node Engraving
@unnumberedsubsec Engraving


@cindex gravure
@cindex typographie musicale
@cindex musique et typographie

L'art de la typographie musicale se nomme la @emph{gravure}.  Ce terme
est issu du processus traditionnel d'impression musicale.  Il y a
seulement quelques dizaines d'années, on faisait les partitions en
coupant et en embossant une plaque de zinc ou d'étain en image miroir.
Cette plaque était ensuite encrée, les dépressions créées par les
creux et les bosses retenant l'encre.  Une image était formée en
pressant du papier sur la plaque.  La découpe et l'embossage étaient
entièrement faits à la main.  Il était pénible d'appliquer une
correction, quand celle-ci n'était pas impossible ; la gravure devait
donc être parfaite du premier coup.  La gravure demandait une
qualification hautement spécialisée : un artisan devait accomplir
environ cinq ans de formation avant de mériter le titre de maître
graveur, et il lui fallait cinq années d'expérience supplémentaires
pour devenir vraiment habile.

De nos jours, toutes les partitions récentes sont produites avec des
ordinateurs.  Ceci a des avantages évidents : le coût des impressions
a diminué, et le travail d'édition peut être envoyé par courriel.
Malheureusement, l'utilisation dominante des ordinateurs a également
diminué la qualité graphique des partitions.  L'impression
informatisée leur donne un aspect fade et mécanique qui les rend
désagréables à jouer.

@c introduce illustrating aspects of engraving, font...
Les images ci-dessous illustrent la différence entre la gravure
traditionelle et l'impression typique par ordinateur, et la troisième
image montre comment LilyPond mime l'aspect traditionnel.  L'image de
gauche est une numérisation d'un symbole bémol d'une édition publiée
en 2000.  Celle du centre montre un bémol d'une gravure à la main de
l'édition Bärenreiter de la même musique.  L'image de gauche illustre
des défauts typiques de l'impression informatique : les lignes de
portée sont minces, l'épaisseur de trait du bémol est la même que les
lignes fines, et il y a un aspect rigide avec des angles pointus.  Par
contraste, le bémol Bärenreiter possède un aspect gras et arrondi,
presque voluptueux.  Notre symbole bémol est créé, entre autres, à
partir de celui-là.  Il est arrondi, et son épaisseur de trait
s'harmonise avec nos lignes de portée, lesquelles sont également plus
épaisses que celles de l'édition informatique.

@multitable @columnfractions .125 .25 .25 .25 .125
@item @tab
@ifnotinfo
@iftex
@image{henle-flat-gray,,4cm}
@end iftex
@ifnottex
@image{henle-flat-gray,,,png}
@end ifnottex

@tab
@iftex
@image{baer-flat-gray,,4cm}
@end iftex
@ifnottex
@image{baer-flat-gray,,,png}
@end ifnottex

@tab
@iftex
@image{lily-flat-bw,,4cm}
@end iftex
@ifnottex
@image{lily-flat-bw,,,png}
@end ifnottex
@end ifnotinfo
@ifinfo
@image{lilypond/henle-flat-bw,,,png} @image{lilypond/baer-flat-bw,,,png}
@image{lilypond/lily-flat-bw,,,png}
@end ifinfo

@item @tab
Henle (2000)
@tab
Bärenreiter (1950)
@tab
Fonte Feta de LilyPond (2003)

@end multitable


@cindex symboles musicaux
@cindex fonte
@cindex police
@cindex épaisseur des caractères
@cindex équilibre

@c introduce illustrating aspects of engraving, spacing...
En matière d'espacement, la répartition de l'espace devrait refléter
les durées entre les notes.  Cependant, beaucoup de partitions
modernes se contentent des durées avec une précision mathématique, ce
qui mène à de mauvais résultats.  Dans l'exemple suivant, un motif est
imprimé deux fois : une fois en utilisant un espacement mathématique
exact, et une autre fois avec des corrections.  Pouvez-vous les
repérer ?

@cindex espacement optique
@c file spacing-optical.
@c need to include it here,  because we want two images.
@lilypond
\paper {
  ragged-right = ##t
  indent = #0.0
}

music = {
   c'4 e''4 e'4 b'4 |
   \stemDown
   b'8[ e'' a' e'']
   \stemNeutral
   e'8[ e'8 e'8 e'8]
}

\score
{
  \music
  \layout {
    \context {
      \Staff
      \override NoteSpacing #'stem-spacing-correction = #0.6
    }
  }
}
@end lilypond

@lilypond
\paper {
  ragged-right = ##t
  indent = #0.0
}

music = {
   c'4 e''4 e'4 b'4 |
   \stemDown
   b'8[ e'' a' e'']
   \stemNeutral
   e'8[ e'8 e'8 e'8]
}
\score
{
  \music
  \layout {
    \context {
      \Staff
      \override NoteSpacing #'stem-spacing-correction = #0.0
      \override NoteSpacing #'same-direction-correction = #0.0
      \override StaffSpacing #'stem-spacing-correction = #0.0
    }
  }
}
@end lilypond

@cindex régulier, rythme
@cindex régulier, espacement
@cindex espacement régulier

L'extrait n'utilise que des notes de même durée ; l'espacement devrait
le refléter.  Malheureusement, notre oeil nous trompe quelque peu ; il
ne se contente pas de remarquer la distance entre les têtes de notes,
il prend en compte également la distance entre les hampes
consécutives.  Ainsi, par compensation, les notes avec une combinaison
@qq{hampe vers le haut}/@/@qq{hampe vers le bas} doivent être éloignées
l'une de l'autre, et les notes avec une combinaison @qq{hampe vers le
bas}/@/@qq{hampe vers le haut} rapprochées, le tout dépendant de la
position verticale des notes.  Les deux premières mesures sont
imprimées avec cette correction, les deux suivantes sans.  Les notes
dans les deux dernières mesures forment des blocs de notes @qq{hampe
vers le bas}/@/@qq{hampe vers le haut}.

@cindex typographie

Les musiciens sont généralement plus absorbés par l'exécution que par
l'étude de l'aspect graphique d'une partition, donc discutailler sur
les détails typographiques peut paraître peu important.  Il n'en est
rien.  Dans de longues pièces avec des rythmes monotones, les
corrections d'espacement engendrent de subtiles variations dans la
mise en forme de chaque ligne, donnant à chacune une signature
visuelle distincte.  Sans cette signature, toutes les lignes auraient
le même aspect, et ressembleraient à un labyrinthe.  Si un musicien
regarde ailleurs un instant ou se déconcentre momentanement, il peut
avoir du mal à se retrouver sur la page.

De même, l'aspect robuste des symboles sur d'épaisses lignes de
portée ressort mieux quand la partition est éloignée du lecteur,
comme sur un pupitre par exemple.  Une organisation minutieuse des
espaces vides permet de minimiser l'espace qu'occupe la musique, tout
en évitant que les symboles s'amassent les uns contre les autres.  Le
résultat permet de réduire le nombre de pages à tourner, ce qui est un
grand avantage.

Ceci est une caractéristique commune à toute typographie.  La
disposition doit être belle, non seulement pour des raisons
esthétiques, mais également pour l'aide apportée au lecteur dans la
tâche qu'il doit accomplir.  Pour du matériel d'exécution comme les
partitions de musique, cela prend une double importance : les
musiciens ont une quantité limitée d'attention.  Moins ils en ont
besoin pour lire, plus ils peuvent se concentrer sur la musique
elle-même.  Autrement dit, une meilleure typographie permet une
meilleure interprétation.

Ces exemples démontrent que la typographie musicale est un art subtil
et complexe, et que la produire demande une expertise considérable,
que les musiciens ne possèdent généralement pas.  LilyPond est le
fruit de nos efforts pour restaurer l'excellence graphique de la
gravure à la main à l'ère de l'ordinateur, et la rendre accessible à
tous les musiciens.  Nous avons conçu nos algorithmes, fontes et
paramètres de programme pour retrouver la qualité d'édition des
anciennes partitions que nous aimons tant lire et jouer.


@node Automated engraving
@unnumberedsubsec Automated engraving

@cindex gravure automatisée
@cindex automatisée, gravure

Comment pouvons-nous implémenter la typographie ? Si les artisans ont
besoin de plus de dix ans pour devenir de vrais maîtres, comment nous,
simples programmeurs, pourrions-nous jamais écrire un programme pour
faire leur travail ?

La réponse est : nous ne le pouvons pas.  La typographie se base sur
le jugement visuel humain, donc les humains ne peuvent pas être
complètement remplacés.  Si LilyPond arrive à traiter la plupart des
situations correctement, ce sera déjà une grande avancée sur les
logiciels existants.  Les problèmes restants peuvent être résolus à la
main.  Au fil des ans, le logiciel peut être affiné pour faire de plus
en plus de choses automatiquement, pour que les ajustements manuels
soient de moins en moins nécessaires.

Quand nous avons commencé, nous avons écrit le programme Lilypond
entièrement dans le language de programmation C++ ; les fonctions du
programme étaient figées par les développeurs.  Ceci s'est avéré
insatisfaisant pour plusieurs raisons :

@itemize 

@item Quand Lilypond fait des erreurs,
les utilisateurs ont besoin de contredire les décisions de formatage.
Les utilisateurs doivent donc avoir accès au moteur de formatage.  Par
conséquent, les règles et les propriétés ne peuvent pas être fixées
par nous au moment de la compilation, mais doivent être accessibles
aux utilisateurs au moment de l'exécution.

@item La gravure est une question de jugement visuel, et donc de goût.
Aussi bien informés que nous le sommes, les utilisateurs peuvent être
en désaccord avec nos décisions personnelles.  Par conséquent, les
définitions du modèle typographique doivent également être accessibles
à l'utilisateur.

@item Enfin, nous affinons continuellement les algorithmes de formatage,
donc nous avons besoin d'une approche souple des règles.  Le langage
C++ oblige à une certaine méthode de groupage des règles qui ne
convient pas bien au fonctionnement de la notation musicale.
 
@end itemize

@cindex langage de programmation Scheme

Ces problèmes ont été résolus en intégrant un interpréteur pour le
langage de programmation Scheme, et en réécrivant des parties de
LilyPond en Scheme.  L'architecture actuelle de formatage est
construite autour de la notion d'objets graphiques, décrits par des
fonctions et des variables Scheme.  Cette architecture comprend les
règles de formatage, le style typographique, et des décisions
individuelles de formatage.  L'utilisateur a un accès direct à la
plupart de ces contrôles.

Les variables Scheme contrôlent les décisions de mise en page.  Par
exemple, beaucoup d'objets graphiques ont une variable de direction
qui encode le choix entre haut et bas (ou gauche et droite).  Vous
pouvez voir ici deux accords, avec des accents, et des arpèges.  Dans
le premier accord, les objets graphiques sont tous dirigés vers le bas
(ou la gauche).  Dans le second accord ils sont tous dirigés vers le
haut (droite).

@lilypond[quote,ragged-right]
\new Score \with {
   \override SpacingSpanner #'spacing-increment = #3
   \override TimeSignature #'transparent = ##t
} \relative c' {
   \stemDown <e g b>4_>-\arpeggio
   \override Arpeggio #'direction = #RIGHT
   \stemUp <e g b>4^>-\arpeggio
}
@end lilypond

@cindex partition, formatage
@cindex formatage d'une partition
@cindex formatage, règles de

@noindent
Le processus de formatage d'une partition consiste à lire et écrire
les variables d'objets graphiques.  Certaines variables ont une valeur
prédéfinie.  Par exemple, l'épaisseur d'un grand nombre de lignes --
une caractéristique du style typographique -- est une variable avec
une valeur prédéfinie.  Vous êtes libres d'altérer cette valeur, ce
qui vous donne une partition avec une impression typographique
différente.

@lilypond[quote,ragged-right]
fragment = {
   \clef bass f8 as8
   c'4-~ c'16 as g f e16 g bes c' des'4
}
<<
   \new Staff \fragment
   \new Staff \with {
      \override Beam #'thickness = #0.3
      \override Stem #'thickness = #0.5
      \override Bar #'thickness = #3.6
      \override Tie #'thickness = #2.2
      \override StaffSymbol #'thickness = #3.0
      \override Tie #'extra-offset = #'(0 .  0.3)
      }
      \fragment
>>
@end lilypond

Les règles de formatage ont aussi des variables prédéfinies : chaque
objet possède des variables contenant des procédures.  Ces procédures
exécutent le formatage, et en les substituant par d'autres, nous
pouvons changer l'apparence des objets.  Dans l'exemple suivant, la
règle du choix de têtes de notes est changée au cours de l'extrait de
musique.

@lilypond[quote,ragged-right]
#(set-global-staff-size 30)

#(define (mc-squared grob orig current)
  (let* ((interfaces (ly:grob-interfaces grob))
         (pos (ly:grob-property grob 'staff-position)))
    (if (memq 'note-head-interface interfaces)
        (begin
          (ly:grob-set-property! grob 'stencil
            (grob-interpret-markup grob
              (make-lower-markup 0.5
                (case pos
                  ((-5) "m")
                  ((-3) "c ")
                  ((-2) (make-smaller-markup (make-bold-markup "2")))
                  (else "bla")))))))))

\new Voice \relative c' {
  \stemUp
  \set autoBeaming = ##f
  \time 2/4
  <d f g>4
  \once \override NoteHead #'stencil = #ly:note-head::brew-ez-stencil
  \once \override NoteHead #'font-size = #-7
  \once \override NoteHead #'font-family = #'sans
  \once \override NoteHead #'font-series = #'bold
  <d f g>4
  \once \override NoteHead #'style = #'cross
  <d f g>4
  \applyOutput #'Voice #mc-squared
  <d f g>4
  <<
    { d8[ es-( fis^^ g] fis2-) }
    \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 }
  >>
}
@end lilypond



@node What symbols to engrave?
@unnumberedsubsec What symbols to engrave?

@cindex gravure
@cindex typographie
@cindex graveur
@cindex greffon

Le processus de formatage décide où placer les symboles.  Cependant,
cela ne peut être fait qu'à partir du moment où il a été décidé
@emph{quels} symboles doivent être imprimés, c'est-à-dire quelle
notation utiliser.

La notation musicale usuelle est un système d'écriture qui a évolué à
travers les dix derniers siècles.  La forme qui est aujourd'hui
communément utilisée date du début de la Renaissance.  Bien que la forme
basique --- les têtes de notes sur une portée de cinq lignes --- n'ait pas
changé, les détails continuent d'évoluer pour exprimer les innovations
de la notation contemporaine.  Par conséquent, elle comprend quelque 500
ans de musique, avec des applications allant des mélodies monodiques à
de monstrueux contrepoints pour grand orchestre.

Comment pouvons nous appréhender un tel monstre à plusieurs têtes, et le
confiner dans l'espace réduit d'un programme informatique ?  Notre
solution consiste à diviser le problème de la notation --- par
opposition à la gravure, ou typographie --- en morceaux digestes et
programmables : chaque type de symbole est géré par un module séparé,
couramment appelé greffon@footnote{traduction de l'anglais
@emph{plug-in}.}.  Chaque greffon est entièrement modulaire et
indépendant, et donc peut être développé et amélioré séparément.  De
tels greffons sont nommés @code{graveur}s@footnote{@code{engraver}s en
anglais.}, par analogie avec les artisans qui traduisent les idées
musicales en symboles graphiques.

Dans l'exemple suivant, voyons comment nous commençons avec un greffon
pour les têtes de notes, le graveur de têtes de note
(@code{Note_heads_engraver}) :

@lilypond[quote,ragged-right]
\include "engraver-example.ily"

\score {
  \topVoice
  \layout {
    \context {
      \Voice
      \remove "Stem_engraver"
      \remove "Phrasing_slur_engraver"
      \remove "Slur_engraver"
      \remove "Script_engraver"
      \remove "Beam_engraver"
      \remove "Auto_beam_engraver"
    }
    \context {
      \Staff
      \remove "Accidental_engraver"
      \remove "Key_engraver"
      \remove "Clef_engraver"
      \remove "Bar_engraver"
      \remove "Time_signature_engraver"
      \remove "Staff_symbol_engraver"
      \consists "Pitch_squash_engraver"
    }
  }
}
@end lilypond

@noindent
Ensuite, le graveur du symbole de portée
(@code{Staff_symbol_engraver}) ajoute la portée

@lilypond[quote,ragged-right]
\include "engraver-example.ily"

\score {
  \topVoice
  \layout {
    \context {
      \Voice
      \remove "Stem_engraver"
      \remove "Phrasing_slur_engraver"
      \remove "Slur_engraver"
      \remove "Script_engraver"
      \remove "Beam_engraver"
      \remove "Auto_beam_engraver"
    }
    \context {
      \Staff
      \remove "Accidental_engraver"
      \remove "Key_engraver"
      \remove "Clef_engraver"
      \remove "Bar_engraver"
      \consists "Pitch_squash_engraver"
      \remove "Time_signature_engraver"
    }
  }
}
@end lilypond

@noindent
le graveur de clef (@code{Clef_engraver}) définit un point de
référence pour la portée

@lilypond[quote,ragged-right]
\include "engraver-example.ily"

\score {
  \topVoice
  \layout {
    \context {
      \Voice
      \remove "Stem_engraver"
      \remove "Phrasing_slur_engraver"
      \remove "Slur_engraver"
      \remove "Script_engraver"
      \remove "Beam_engraver"
      \remove "Auto_beam_engraver"
    }
    \context {
      \Staff
      \remove "Accidental_engraver"
      \remove "Key_engraver"
      \remove "Bar_engraver"
      \remove "Time_signature_engraver"
    }
  }
}
@end lilypond

@noindent
et le graveur de hampes (@code{Stem_engraver}) ajoute les hampes :

@lilypond[quote,ragged-right]
\include "engraver-example.ily"

\score {
  \topVoice
  \layout {
    \context {
      \Voice
      \remove "Phrasing_slur_engraver"
      \remove "Slur_engraver"
      \remove "Script_engraver"
      \remove "Beam_engraver"
      \remove "Auto_beam_engraver"
    }
    \context {
      \Staff
      \remove "Accidental_engraver"
      \remove "Key_engraver"
      \remove "Bar_engraver"
      \remove "Time_signature_engraver"
    }
  }
}
@end lilypond

@noindent
Le graveur de hampe est informé de chaque tête de note qui survient.
Chaque fois qu'une tête de note --- plusieurs pour un accord --- est
rencontrée, un objet hampe est créé et connecté à la tête de note.  En
ajoutant des graveurs pour les barres de ligature, les liaisons, les
accents, les altérations accidentelles, les barres de mesure, la
métrique, et les armures, nous obtenons un jeu de notation complet.

@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\score { \topVoice }
@end lilypond

@cindex polyphonie
@cindex graver plusieurs voix
@cindex contextes

Ce système fonctionne bien pour de la musique monodique, mais qu'en
est-il de la polyphonie ? En notation polyphonique, plusieurs voix
peuvent partager une portée.

@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\new Staff << \topVoice \\ \botVoice >>
@end lilypond

Dans cette situation, la portée et les altérations accidentelles sont
partagées, mais les hampes, liaisons etc., sont spécifiques à chaque
voix.  Par conséquent, les graveurs doivent être groupés.  Les
graveurs des têtes de notes, hampes, liaisons etc., vont dans un
groupe appelé @qq{contexte de Voix} @footnote{@q{Voice context} en
anglais, @q{Voice} commence par une majuscule comme tous les noms de
contexte dans le programme LilyPond.}, alors que les graveurs des clés,
altérations accidentelles, barres de mesure etc., vont dans un groupe
appelé @qq{contexte de Portée}. Dans le cas de la polyphonie, un seul
contexte de Portée contient plusieurs contextes de Voix.  De même,
plusieurs contextes de Portée peuvent être inclus dans un seul
contexte de Partition.  Le contexte de Partition est le contexte de
notation de plus haut niveau.


@seealso
Référence du programme: @rinternals{Contexts}.


@lilypond[quote,ragged-right]
\include "engraver-example.ily"
\score {
   <<
      \new Staff << \topVoice \\ \botVoice >>
      \new Staff << \pah \\ \hoom >>
   >>
}
@end lilypond

@node Music representation
@unnumberedsubsec Music representation

@cindex syntaxe
@cindex structures recursives

Idéalement, le format d'entrée pour n'importe quel système de
formatage est une description abstraite du contenu.  Dans ce cas-ci,
ce serait la musique elle-même.  Cela pose un formidable problème :
comment pouvons-nous définir ce qu'est réellement la musique ? Plutôt
que d'essayer de trouver une réponse, nous avons renversé la question.
Nous écrivons un logiciel capable de produire de la musique écrite, et
adaptons le format pour atteindre la plus grande concision possible.
Quand le format ne peut plus être simplifé, il nous reste par
définition le contenu lui-même.  Notre logiciel sert de définition
formelle d'un document de musique.

Pour LilyPond, la syntaxe est également l'interface utilisateur ; par
conséquent il est facile de saisir

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

@noindent
c'est-à-dire un do central noire et, juste au-dessus, un ré croche

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

Sur une échelle microscopique, une telle syntaxe est facile à
utiliser.  À plus grande échelle, la syntaxe a besoin aussi de
structure.  Comment serait-il possible autrement de rentrer des
pièces complexes comme des symphonies ou des opéras ? La structure
est formée par le concept d'expression musicale : en combinant
de petits fragments de musique pour en former de plus grands, on peut
exprimer de la musique plus complexe.  Par exemple

@lilypond[quote,verbatim,fragment,relative=1]
f4
@end lilypond

@noindent
Des accord peuvent être construits avec @code{<<} et @code{>>} autour
des notes.

@example
<<c4 d4 e4>>
@end example

@lilypond[quote,fragment,relative=1]
\new Voice { <<c4 d4 e>> }
@end lilypond

@noindent
On met cette expression dans une séquence en l'encadrant par
des accolades @code{@{@tie{}@dots{}@tie{}@}}

@example
@{ f4 <<c4 d4 e4>> @}
@end example

@lilypond[quote,relative=1,fragment]
{ f4 <<c d e4>> }
@end lilypond

@noindent
Ceci est également une expression, et peut donc encore une fois
être combiné avec d'autres expressions simultanées (une blanche)
en utilisant <<, @code{\\}, et >>

@example
<< g2 \\ @{ f4 <<c4 d4 e4>> @} >>
@end example

@lilypond[quote,fragment,relative=2]
\new Voice { << g2 \\ { f4 <<c d e>> } >> }
@end lilypond

De telles structures récursives peuvent être spécifiées formellement
et de manière ordonnée dans une grammaire indépendante de tout
contexte.  Le code d'analyse est aussi généré à partir de cette
grammaire.  Autrement dit, la syntaxe de LilyPond est définie
clairement et sans ambiguité.

L'interface utilisateur et la syntaxe sont ce que les gens voient et
manipulent le plus.  Elles sont en partie une affaire de goût, et
aussi sujettes à beaucoup de discussions.  Même si ces discussions sur
les goûts ont leur mérite, elles ne sont pas très productives.  D'un
point de vue plus large sur LilyPond, l'importance de la syntaxe est
minime : il est facile d'inventer une syntaxe concise, alors qu'écrire
un code de formatage décent est beaucoup plus difficile.  Ceci est
également illustré par le nombre de lignes de codes pour les
composants respectifs : l'analyse et la représentation constituent
moins de 10% du code source.

@node Example applications
@unnumberedsubsec Example applications

@cindex exemples simples

Nous avons conçu LilyPond comme une expérimentation visant à
concentrer l'art de la gravure musicale dans un logiciel.  Grâce à
tout ce dur labeur, le programme peut maintenant être utilisé pour
accomplir des travaux utiles.  L'application la plus simple est
d'imprimer des notes :

@lilypond[quote,relative=1]
{
  \time 2/4
  c4 c g'4 g a4 a g2
}
@end lilypond

@noindent
En ajoutant des noms d'accords et des paroles, nous obtenons
une partition de chanson :

@lilypond[quote,ragged-right]
<<
   \chords { c2 c f2 c }
   \new Staff
   \relative c' {
     \time 2/4
     c4 c g' g a a g2
   }
   \addlyrics { twin -- kle twin -- kle lit -- tle star }
>>
@end lilypond

La notation polyphonique et la musique pour piano peuvent également
être générées.  L'exemple suivant associe quelques constructions
plus exotiques :

@lilypond[quote]
\header {
  title = "Screech and boink"
  subtitle = "Random complex notation"
  composer = "Han-Wen Nienhuys"
}

\score {
  \context PianoStaff <<
    \new Staff = "up" {
      \time 4/8
      \key c \minor
      << {
        \revert Stem #'direction
        \change Staff = down
        \set subdivideBeams = ##t
        g16.[
          \change Staff = up
          c'''32
          \change Staff = down
          g32
          \change Staff = up
          c'''32
          \change Staff = down
          g16]
        \change Staff = up
        \stemUp
        \set followVoice = ##t
        c'''32([ b''16 a''16 gis''16 g''32)]
      } \\ {
        s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
      } \\ {
        s4 \autoBeamOff d''8.. f''32
      } \\ {
        s4 es''4
      } >>
    }

    \new Staff = "down" {
      \clef bass
      \key c \minor
      \set subdivideBeams = ##f
      \override Stem  #'french-beaming = ##t
      \override Beam  #'thickness = #0.3
      \override Stem  #'thickness = #4.0
      g'16[ b16 fis16 g16]
      << \makeClusters {
        as16 <as b>
        <g b>
        <g cis>
      } \\ {
        \override Staff.Arpeggio  #'arpeggio-direction =#down
        <cis, e, gis, b, cis>4\arpeggio
      }
    >> }
  >>
  \midi {
    \context {
      \Score
      tempoWholesPerMinute = #(ly:make-moment 60 8)
    }
  }
  \layout {
    \context {
      \Staff
      \consists Horizontal_bracket_engraver
    }
  }
}
@end lilypond

Les extraits exposés ici ont tous été écrits à la main, mais ce n'est
pas une obligation.  Puisque le moteur de formatage est en grande
partie automatique, il peut servir de sortie pour d'autres programmes
qui manipulent la musique.  Par exemple, il peut être utilisé pour
convertir des bases de données d'extraits musicaux en images pour des
sites Internet et des présentations multimédias.

Ce manuel montre également une application : le format d'entrée est du
texte, et peut donc facilement être intégré dans d'autres formats
basés sur le texte comme @LaTeX{}, HTML, ou dans le cas de ce manuel,
Texinfo.  À l'aide d'un programme spécial, les extraits de code
peuvent être remplacés par des images de musiques dans les fichiers de
sortie PDF ou HTML.  Cela donne la possibilité de mélanger de la
musique et du texte dans les documents.



@node About the documentation
@section About the documentation

Cette partie présente les différents volumes de la documentation.

@cindex Manuel d'initiation
@cindex Glossaire musical
@cindex Manuel de notation
@cindex Utilisation des programmes
@cindex Exemples de code
@cindex Référence des propriétés internes

@c leave these lines wrapping around.  It's some texinfo 4.12 thing. -gp
@c This is actually a limitation of texi2html. -jm
@menu
* About the Learning Manual::   introduction à LilyPond, ce manuel explique aux débutants la création de partitions.
* About the Music Glossary::    ce document explique de nombreux termes musicaux et en donne la traduction dans d'autres langues.
* About the Notation Reference::  ce manuel représente la partie la plus volumineuse de la documentation.  Il fournit tous les détails sur la création de notation musicale.  La lecture de cet ouvrage requiert une bonne compréhension des concepts exposés dans le manuel d'initiation.
* About the Application Usage:: ce manuel aborde l'exécution des programmes LilyPond et les particularités dépendant du système d'exploitation.
* About the Snippet List::      ce document rassemble une collection d'extraits de code LilyPond.
* About the Internals Reference:: ce manuel constitue une source d'information sur le fonctionnement interne de LilyPond.  C'est une référence complète pour l'élaboration de retouches.
* Other documentation::         d'autres sources de documentation sont disponibles, telles que les notes de nouveautés et les archives des listes de diffusion.
@end menu


@node About the Learning Manual
@unnumberedsubsec About the Learning Manual

Ce manuel explique comment débuter avec LilyPond, et expose de manière
simple quelques concepts clés.  Il est conseillé de lire ces chapitres
de manière linéaire.

Dans ce manuel se trouve à chaque section un paragraphe @strong{Voir
aussi} contenant des références vers d'autres sections : il est
conseillé de ne pas les suivre en première lecture ; lorsque vous
aurez lu l'ensemble du manuel d'initiation, vous pourrez en relisant
certaines sections suivre ces références pour approfondir certains
aspects.

@itemize

@item
@ref{Introduction} : le pourquoi du comment de LilyPond.

@item
@ref{Tutorial} : introduction en douceur à la typographie musicale.
Les utilisateurs débutants sont invités à commencer par ce chapitre.

@item
@ref{Fundamental concepts} : concepts généraux du format de fichier
@code{ly} spécifique à LilyPond.  Si vous n'êtes pas certain de
l'endroit où placer une commande, lisez ce chapitre !

@item
@ref{Tweaking output} : introduction aux retouches de gravure avec
LilyPond.

@item
@ref{Working on LilyPond projects} : utilisation pratique de LilyPond,
conseils généraux, prévention et résolution des problèmes les plus
courants.  À lire avant de se lancer dans des travaux d'envergure !

@end itemize

Ce volume contient aussi des annexes que vous pouvez consulter au gré de
vos besoins :

@itemize

@item
@ref{Templates} de pièces LilyPond.  Copiez et collez un modèle dans
un fichier, ajoutez les notes, et c'est prêt !

@item
@ref{Scheme tutorial} : courte introduction à Scheme, le langage de
programmation utilisé dans les fonctions de musique.  Ces quelques
lignes vous aideront à construire des retouches avancées ; nombre
d'utilisateurs ne touchent jamais à Scheme.

@end itemize


@node About the Music Glossary
@unnumberedsubsec About the Music Glossary

@cindex Glossaire musical
@cindex jargon
@cindex terminologie
@cindex langues étrangères
@cindex langue
@cindex langage

@rglosnamed{Top,Glossaire musical} : ce document explique en anglais
des termes musicaux, et donne leur traduction dans diverses langues.
Si vous n'êtes pas familier avec la notation et la terminologie
musicales, il est conseillé de consulter le glossaire, notamment pour
les parties non encore traduites de la documentation.


@node About the Notation Reference
@unnumberedsubsec About the Notation Reference

@cindex Manuel de notation
@cindex annexes
@cindex références, tables de
@cindex tables de références

Ce manuel détaille toutes les commandes LilyPond produisant une notation
musicale.  La lecture de cet ouvrage requiert une bonne compréhension des
concepts exposés dans le manuel d'initiation.

@itemize

@c Normalement, il est impossible d'utiliser deux points en français,
@c car une référence externe doit se terminer par un signe de
@c ponctuation dans le format Info.  Cependant, Info
@c n'internationalise pas encore des documents Info, donc nous n'en
@c avons rien à faire pour l'instant. -jm
@item
@ruser{Musical notation} : cette partie décrit la notation de base,
qui sera utile dans la plupart des projets de partition.  Les sujets
sont groupés par type de notation.

@item
@ruser{Specialist notation} : cette partie détaille des éléments de
notation spécifiques à certains instruments ou styles.  Les sujets
sont groupés par type de notation.

@item
@ruser{General input and output} : informations générales sur les
fichiers source LilyPond et le contrôle des sorties.

@item
@ruser{Spacing issues} : différents aspects de l'espacement selon les
axes et échelles, par exemple la sélection de la taille de papier, ou
la gestion des sauts de page.

@item
@ruser{Changing defaults} : ce chapitre est une référence des
différentes formes de retouches, qui permettent d'obtenir de Lilypond
(presque) tout ce que vous désirez.

@item
@ruser{Interfaces for programmers} : création de fonctions de musique
à l'aide de Scheme.

@end itemize

Les annexes de ce manuel contiennent entre autres des tableaux de
référence pratiques.

@itemize

@item
@ruser{Literature list} : choix de livres de référence, pour en savoir
plus sur la notation et la gravure.

@item
@ruser{Notation manual tables} : tableaux montrant les noms d'accord,
les instruments MIDI, les noms de couleur, et la police Feta.

@item
@ruser{Cheat sheet} : référence pratique des commandes LilyPond les
plus courantes.

@item
@ruser{LilyPond command index} : index de toutes les @code{\commandes}
LilyPond.

@item
@ruser{LilyPond index} : un index complet.

@end itemize


@node About the Application Usage
@unnumberedsubsec About the Application Usage

@cindex Utilisation des programmes
@cindex intégration de LilyPond avec d'autres programmes

Ce manuel explique l'exécution des programmes et l'intégration de
partitions LilyPond dans d'autres programmes.

@itemize

@item
@rprogram{Install} : installation --- et éventuellement compilation ---
de LilyPond.

@item
@rprogram{Setup} : configuration de votre système pour une utilisation
optimale de LilyPond, comprenant l'utilisation d'environnements
adaptés pour certains éditeurs de tecte.

@item
@rprogram{Running LilyPond} : exécution de LilyPond et de ses
programmes auxiliaires.  De plus, cette partie explique comment
effectuer la mise à jour de fichiers source écrits avec d'anciennes
versions de LilyPond.

@item
@rprogram{LilyPond-book} : création de documents intégrant des
extraits musicaux, comme ce manuel.

@item
@rprogram{Converting from other formats} : utilisation des programmes
de conversion.  Ces programmes sont livrés avec le paquetage LilyPond,
et convertissent divers formats de musique vers le format @code{.ly}.

@end itemize


@node About the Snippet List
@unnumberedsubsec About the Snippet List

@cindex snippets
@cindex extraits de code
@cindex LSR
@cindex LilyPond Snippet Repository

@rlsrnamed{Top,Exemples de code} :
il s'agit d'une sélection de petits exemples montrant des trucs,
astuces et fonctionnalités particulières de LilyPond, issus de
@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
(LSR).  Tous ces exemples sont dans le domaine public.

Notez bien que cette annexe n'est en aucune manière un miroir ou même
une partie du LSR.  Dans la mesure où le LSR repose sur une version
stable de LilyPond, les exemples illustrant des fonctionnalités
introduites dans la dernière version de développement ne peuvent y
figurer ; c'est pourquoi vous les trouverez dans le répertoire
@file{input/new/} des sources de LilyPond.

La liste des exemples correspondant à chacun des sous-chapitres du
manuel de notation est accessible par des liens dans le paragraphe
@strong{Voir aussi}.


@node About the Internals Reference
@unnumberedsubsec About the Internals Reference

@cindex retoucher
@cindex variables
@cindex propriétés
@cindex lilypond-internals
@cindex documentation du fonctionnement interne
@cindex Scheme
@cindex étendre lilypond
@cindex index

@rinternalsnamed{Top,Référence des propriétés internes} : c'est un
ensemble de pages HTML étroitement liées entre elles, qui documente
les moindres petits détails de chaque classe, objet et fonction de
LilyPond.  Cette documentation est produite directement à partir des
définitions de formatage utilisées.

Presque toutes les fonctions de formatage utilisées en interne sont
directement disponibles pour l'utilisateur.  Par exemple, toutes les
variables qui contrôlent les épaisseurs, les distances etc., peuvent
être modifiées dans les fichiers d'entrée.  Il y a un grand nombre
d'options de formatage, et elles sont toutes décrites dans ce
document.  Chaque section du manuel de notation a un paragraphe @b{Voir
aussi}, qui renvoie à la documentation générée automatiquement.  Dans la
documentation au format HTML, ces paragraphes disposent de liens
cliquables.


@node Other documentation
@unnumberedsubsec Other documentation

Pour finir, présentons d'autres précieuses sources de documentation.

@itemize

@item
@ifhtml
@ifset bigpage
@uref{../topdocs/NEWS.html,Nouveautés} :
@end ifset
@ifclear bigpage
@uref{../../topdocs/NEWS.html,Nouveautés} :
@end ifclear
@end ifhtml
@ifnothtml
Nouveautés :
@end ifnothtml
ce document résume les changements importants et les nouvelles
fonctionalités de LilyPond depuis la dernière version stable.

@item @uref{http://lists.gnu.org/archive/html/lilypond-user/, Les
archives de la liste lilypond-user} : c'est un dépôt archivant les
courriels qui ont été envoyés à la liste anglophone des utilisateurs.
Beaucoup de questions sont apparues plusieurs fois sur la liste, il y
a donc des chances que si vous avez une question, la réponse puisse
être dans ces archives.
@c DIV specific
@uref{http://lists.gnu.org/archive/html/lilypond-user-fr/,Les archives
de la liste francophone} ne sont pas aussi bien fournies, mais vous
pouvez toujours y chercher des conversations passées sur les
traductions, et si vous avez de la chance une réponse à une question.
@c END DIV

@item @uref{http://lists.gnu.org/archive/html/lilypond-devel/, Les
archives de la liste lilypond-devel} : les courriels envoyés à la
liste des développeurs y sont archivés.  Les sujets de discussion sont
plus techniques ; si vous voulez vous renseigner sur l'histoire du
développement ou si vous avez une question très technique, tentez
votre chance en cherchant dans ces archives.

@item Fragments de musique au cours du texte : dans tous les documents
HTML qui incluent des fragments musicaux, le code LilyPond utilisé
pour produire l'image est accessible par un clic sur l'image.

@item L'emplacement des fichiers de documentation mentionnés ici peut varier
d'un système à l'autre.  De temps en temps, ce manuel fait référence
aux fichiers d'exemple et d'initialisation.  Tout au long de ce
manuel, nous donnons les emplacements des fichiers d'entrée
relativement au répértoire racine de l'archive source.  Par exemple,
@file{input/@/test/@/bla@/.ly} peut référer au fichier
@file{lilypond@/2.x.y/@/input/@/test/@/bla@/.ly}.  Dans les paquets
binaires pour les plateformes Unix, la documentation et les exemples
se trouvent généralement sous @file{/usr/@/share/@/doc/@/lilypond/}.
Les fichiers d'initialisation, par exemple @file{scm/@/lily@/.scm}, ou
@file{ly/@/engraver@/-init@/.ly}, se trouvent généralement dans le
répertoire @file{/usr/@/share/@/lilypond/}. @c pas encore en français -jm.
@c Pour plus de détails, consultez @ref{Other sources of information}.

@end itemize