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

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

@c Translators: Ludovic Sardain, Jean-Charles Malahieude
@c Translation checkers: Jean-Yves Baudais, Valentin Villenave, John Mandereau, Jean-Charles Malahieude

@node Suggestions pour la saisie de fichiers LilyPond
@chapter Suggestions pour la saisie de fichiers LilyPond
@translationof Suggestions for writing files

Maintenant vous êtes prêt à travailler sur de plus gros fichiers
LilyPond -- des pièces entières, et plus seulement les petits
exemples du tutoriel.  Mais comment devriez-vous vous y prendre@tie{}?

Tant que LilyPond parvient à comprendre vos fichiers et produit le
résultat que vous souhaitez, peu importe la manière dont le code est
organisé.  Néanmoins, quelques critères doivent être pris en compte
lorsque l'on écrit un fichier LilyPond.

@itemize
@item
Si vous faites une erreur, la structure même du fichier LilyPond
peut permettre de la localiser plus ou moins facilement.

@item
Et si vous souhaitez partager vos fichiers avec quelqu'un d'autre, ou si
vous souhaitez modifier vos propres fichiers dans quelques années@tie{}?
Si certains fichiers LilyPond sont compréhensibles au premier coup
d'œil, d'autres vous feront vous arracher les cheveux pendant une heure.

@item
Et si vous souhaitez mettre à jour votre fichier pour l'utiliser avec
une version plus récente de LilyPond@tie{}?  La syntaxe du 
langage d'entrée change parfois lorsque LilyPond s'améliore.  La
plupart des changements peuvent être appliqués automatiquement avec
@code{convert-ly}, mais quelques-uns peuvent requérir une intervention
manuelle.  Vos fichiers LilyPond peuvent être structurés de manière à
faciliter leur mise à jour.
@end itemize

@menu
* Suggestions générales::
* Gravure de musique existante::
* Projets d'envergure::
* Résolution de problèmes::
* De la commande make et des fichiers Makefile::
@end menu


@node Suggestions générales
@section Suggestions générales
@translationof General suggestions

Voici quelques conseils qui peuvent vous éviter certains problèmes ou
en résoudre d'autres.

@itemize
@item @strong{Ajoutez le numéro de version dans chaque fichier}.
Notez que chaque fichier modèle contient une ligne
@code{\version@tie{}"@version{}"}.  Nous vous conseillons fortement
d'inclure cette ligne, même pour de petits fichiers.  Par expérience, il
est très difficile de se rappeler quelle version de LilyPond on
utilisait quelques années auparavant.  L'utilitaire @command{convert-ly}
demande que vous spécifiiez la version de LilyPond vous utilisiez alors.

@item @strong{Ajoutez des contrôles}
@rusernamed{Vérifications d'octave,d'octaviation} et
@rusernamed{Vérification des limites et numéros de mesure,de limite ou
numéro de mesure}.  Si vous avez ajouté des contrôles de loin en loin,
et que vous faites une erreur, vous pourrez la retrouver plus
rapidement.  @qq{De loin en loin}, qu'est-ce à dire@tie{}?  Cela dépend
de la complexité de la musique.  Pour de la musique très simple,
peut-être une ou deux fois.  Pour de la musique très complexe, peut-être
à chaque mesure.

@item @strong{Une mesure par ligne de texte}.
Si la musique en elle-même ou le résultat que vous désirez contient
quelque chose de compliqué, il est souvent bon de n'écrire qu'une seule
mesure par ligne. Économiser de la place en tassant huit mesures par
ligne, ça ne vaut pas vraiment le coup si l'on doit corriger vos
fichiers.

@item @strong{Ajoutez des commentaires}.
Utilisez soit des numéros de mesure (assez souvent), soit des références
au contenu musical -- @qq{second thème des violons}, @qq{quatrième
variation}, etc. Vous pouvez ne pas avoir besoin des commentaires
lorsque vous écrivez une pièce pour la première fois, mais si vous
souhaitez y revenir deux ou trois ans plus tard pour changer quelque
chose, ou si vous donnez le fichier source à un ami, ce sera beaucoup
plus difficile de déterminer vos intentions ou la manière dont votre
fichier est structuré si vous n'y avez pas adjoint de commentaires.

@item @strong{Indentez les accolades}.
Beaucoup de problèmes viennent d'un défaut de parité entre @code{@{} et
@code{@}}.

@item @strong{Mentionnez les durées}
au début de chaque section ou variable.  Si vous saisissez @code{c4 d e}
au début d'une phrase, vous vous épargnerez des problèmes si, plus tard,
vous modifiez votre musique.

@item @strong{Séparez les affinages de mise en forme}
de la musique elle-même.  Voyez
@rlearning{Économie de saisie grâce aux identificateurs et fonctions} et
@rlearning{Feuilles de style}.

@end itemize


@node Gravure de musique existante
@section Gravure de musique existante
@translationof Typesetting existing music

Si vous saisissez de la musique à partir d'une partition existante,
c'est-à-dire de la musique déjà écrite,

@itemize

@item 
n'entrez qu'un seul système de la partition originale
à la fois -- avec toujours une seule mesure par ligne de texte --,
et vérifiez chaque système lorsqu'il est terminé.  Vous pouvez
utiliser les commandes @code{showLastLength} et @code{showFirstLength}
pour accélérer la compilation -- voir
@ruser{Ignorer des passages de la partition}@tie{};

@item
définissez @code{mBreak = @{\break @}} et insérez @code{\mBreak} dans le
fichier d'entrée pour obtenir des sauts de ligne identiques à la
partition originale.  Cela facilite la comparaison entre la partition
originale et la partition de LilyPond.  Lorsque vous avez fini de relire
votre musique, vous pouvez définir @code{mBreak@tie{}=@tie{}@{@tie{}@}}
pour enlever tous ces sauts de ligne, et  laisser LilyPond placer les
sauts de ligne selon son propre algorithme@tie{};

@item
encadrez les notes d'une partie pour instrument transpositeur dans un

@example
\transpose c @var{tonalité-naturelle} @{...@}
@end example
(où @var{tonalité-naturelle} correspond à celle de l'instrument en
question) de telle sorte que la musique comprise dans cette variable se
retrouve en ut.  Vous pourrez toujours transposer à l'inverse si besoin
lorsque vous ferez appel à cette variable.  Des erreurs de transposition
seront moins susceptibles de se produire si la musique de toutes les
variables est dans la même et unique tonalité.

De la même manière, prenez toujours le do comme note de départ ou
d'arrivée.  Ceci aura pour simple conséquence que les autres tonalités
que vous utiliserez seront celles propres à chacun des instruments --
sib pour une trompette en si bémol, ou lab pour une clarinette en la bémol.

@end itemize


@node Projets d'envergure
@section Projets d'envergure
@translationof Large projects

Lorsque l'on travaille sur un gros projet, il devient vital
de structurer clairement ses fichiers LilyPond.

@itemize @bullet

@item @strong{Utilisez un identificateur pour chaque voix},
avec un minimum de structure dans la définition.  La structure de la
section @code{\score} est la plus susceptible de changer, notamment
dans une nouvelle version de LilyPond, alors que la définition du
@code{violon} l'est beaucoup moins.

@example
violin = \relative c'' @{
g4 c'8. e16
@}
...
\score @{
 \new GrandStaff @{
   \new Staff @{
     \violin
   @}
 @}
@}
@end example

@item @strong{Séparez les retouches} des définitions de musique.
Nous vous avons déjà invité à adopter une telle pratique, qui
par ailleurs devient vitale pour des projets d'importance.  Nous
pouvons avoir besoin de changer la définition de
@code{fpuisp}, mais dans ce cas nous n'aurons besoin de le faire
qu'une seule fois, et nous pourrons encore éviter de
modifier quoi que ce soit à l'intérieur de la définition
du @code{violon}.

@example
fpuisp = _\markup@{
 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
violin = \relative c'' @{
g4\fpuisp c'8. e16
@}
@end example

@end itemize


@node Résolution de problèmes
@section Résolution de problèmes
@translationof Troubleshooting

Tôt ou tard, vous écrirez un fichier que LilyPond ne peut pas
compiler.  Les messages que LilyPond affiche peuvent vous aider à
trouver l'erreur, mais dans beaucoup de cas vous aurez besoin de faire
quelques recherches pour déterminer la source du problème.

Pour ce faire, les outils les plus puissants sont le commentaire de
fin de ligne, indiqué par @code{%}, et le commentaire multilignes (ou
bloc de commentaire), indiqué par @code{%@{ ... %@}}.  Si vous ne
pouvez localiser le problème, commencez par mettre en commentaire de
grandes parties de votre fichier source.  Après avoir mis en
commentaire une section, essayez de compiler à nouveau.  Si cela
fonctionne, c'est que le problème se situe dans cette partie du
fichier.  Si cela ne fonctionne pas, continuez à mettre en commentaire
d'autres sections, jusqu'à ce que vous ayez quelque chose qui compile.

Dans un cas extrême, vous pourriez en arriver à

@example
\score @{
  <<
    % \melodie
    % \harmonie
    % \basse
  >>
  \layout@{@}
@}
@end example

@noindent
c'est-à-dire un fichier sans aucune musique.

Si cela se produit, ne vous découragez pas.  Décommentez un peu, la
partie de basse par exemple, et voyez si ça fonctionne.  Si ce n'est pas
le cas, placez en commentaire toute la partie de basse, mais laissez
@code{\basse} décommenté dans le bloc @code{\score}.

@example
basse = \relative c' @{
%@{
  c4 c c c
  d d d d
%@}
@}
@end example

Maintenant commencez à décommenter petit à petit le partie de
@code{basse} jusqu'à ce que vous localisiez la ligne qui pose
problème.

Une autre technique de débogage très utile est la construction
d'un @rwebnamed{Exemples minimaux,exemple minimaliste}.




@node De la commande make et des fichiers Makefile
@section De la commande make et des fichiers Makefile
@translationof Make and Makefiles

@cindex makefiles
@cindex make

La plupart des plates-formes sur lesquelles tourne LilyPond disposent
d'un logiciel appelé @code{make}.  Ce logiciel va lire un fichier
spécial, nommé @code{Makefile}, qui contient tout ce qu'il
faut -- les dépendances entre certains fichiers, les instructions
successives à traiter par le système -- pour aboutir au fichier que
vous désirez obtenir.  Il pourrait par exemple contenir tout ce qu'il
faut pour produire @file{ballade.pdf} et @file{ballade.midi} à partir de
@file{ballade.ly} en lançant LilyPond.

La création d'un @code{Makefile} peut se révéler pertinente pour
certains projets, que ce soit par simple goût personnel ou bien par
respect de ceux qui pourront accéder à vos sources.  Cette manière de
procéder est particulièrement indiquée lorsque vous travaillez sur un
projet de grande envergure impliquant de nombreuses inclusions de
fichiers et différentes éditions -- par exemple un conducteur et un
matériel d'orchestre complet avec la partition pour le chef et une
partition séparée pour chacun des pupitres -- ou bien si votre projet
requiert certaines commandes particulières comme @code{lilypond-book}.
Les @emph{Makefiles} varient tant en complexité qu'en flexibilité selon
les besoin et les aptitudes de celui qui les crée.  Le programme GNU Make
est installé par défaut sur les distributions Linux et sur MacOS@tie{}X,
et il en existe une version pour les environnements Windows.

Consultez le @strong{GNU Make Manual} pour plus de détails sur ce dont
@code{make} est capable -- vous pourrez même en trouver des versions
françaises à l'aide des moteurs de recherche --, dans la mesure où ce
qui suit ne donne qu'un bref apperçu de ses possibilités.

Les commandes permettant de définir les règles diffèrent selon la
plate-forme@tie{}: si les différents Linux et MacOS@tie{}X utilisent
@code{bash}, Windows utilise @code{cmd}.  Dans le cas de MacOS@tie{}X,
vous devrez toutefois configurer votre système de telle sorte qu'il
utilise l'interpréteur en ligne de commande.  Voici quelques exemples de
fichier @emph{Makefile}, avec une version pour Linux ou MacOS et une
pour Windows.

Pour commencer, une pièce à quatre mouvements pour orchestre et dont les
fichiers sont répartis selon l'arborescence suivante@tie{}:

@example
Symphonie/
|-- MIDI/
|-- Makefile
|-- Notes/
|   |-- alto.ily
|   |-- cor.ily
|   |-- cello.ily
|   |-- figures.ily
|   |-- hautbois.ily
|   |-- trioCordes.ily
|   |-- violonOne.ily
|   `-- violonTwo.ily
|-- Partitions/
|   |-- symphonie.ly
|   |-- symphonieI.ly
|   |-- symphonieII.ly
|   |-- symphonieIII.ly
|   `-- symphonieIV.ly
|-- PDF/
|-- Pupitres/
|   |-- symphon-alto.ly
|   |-- symphonie-cello.ly
|   |-- symphonie-cor.ly
|   |-- symphonie-hautbois.ly
|   |-- symphonie-violonUn.ly
|   `-- symphonie-violonDeux.ly
`-- symphonieDefs.ily
@end example

Les fichiers @file{.ly} des répertoires @code{Partitions} et
@code{Pupitres} récupèreront la notation des fichiers @file{.ily}
contenus dans le répertoire @code{Notes}@tie{}:

@example
%%% début du fichier "symphone-cello.ly"
\include ../symphonieDefs.ily
\include ../Notes/cello.ily
@end example

Le @emph{Makefile} répertorie des cibles correspondant à @code{score}
(l'intégrale au format conducteur), @code{mouvements} (chacun des
mouvements au format conducteur) et @code{pupitres} (une partition par
pupitre).  Il contient aussi une cible @code{archive} chargée de générer
une archive des fichiers source qui pourra être diffusée sur la toile ou
transmise par courriel.  Voici ce que contiendrait ce @emph{Makefile}
pour Linux ou MacOS@tie{}X.  Ce fichier doit être enregistré sous le nom
de @code{Makefile} à la racine du projet -- ici @code{Symphonie}.

@warning{Lorsque vous définissez une cible ou une règle sur plusieurs
lignes, les lignes à partir de la deuxième @strong{doivent} débuter par
une tabulation, non pas par des espaces.}

@example
# Le préfixe au nom des fichiers résultants
piece = symphonie
# Détermination du nombre de processeurs
CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
# La commande d'appel à lilypond
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click -djob-count=$(CPU_CORES)

# Les suffixes utilisés dans ce Makefile
.SUFFIXES: .ly .ily .pdf .midi

# Les fichiers sources et résultants sont recherchés dans les répertoires
# listés dans la variable VPATH.  Ceux-ci sont tous des sous-répertoires
# du répertoire courant (fourni par la variable de GNU make `CURDIR').
VPATH = \
  $(CURDIR)/Partitions \
  $(CURDIR)/PDF \
  $(CURDIR)/Pupitres \
  $(CURDIR)/Notes

# La règle type pour créer un PDF et un MIDI à partir d'un fichier
# source LY.
# Les .pdf résultants iront dans le sous-répertoire "PDF" et les fichiers
# .midi dans le sous-répertoire "MIDI".
%.pdf %.midi: %.ly
        $(LILY_CMD) $<; \           # cette ligne commence par une tabulation
        if test -f "$*.pdf"; then \
            mv "$*.pdf" PDF/; \
        fi; \
        if test -f "$*.midi"; then \
            mv "$*.midi" MIDI/; \
        fi

notes = \
  alto.ily \
  cello.ily \
  cor.ily \
  hautbois.ily \
  violonUn.ily \
  violonDeux.ily

# Les dépendances selon le mouvement.
$(piece)I.pdf: $(piece)I.ly $(notes)
$(piece)II.pdf: $(piece)II.ly $(notes)
$(piece)III.pdf: $(piece)III.ly $(notes)
$(piece)IV.pdf: $(piece)IV.ly $(notes)

# Les dépendances pour la partition intégrale.
$(piece).pdf: $(piece).ly $(notes)

# Les dépendances pour les pupitres.
$(piece)-alto.pdf: $(piece)-alto.ly alto.ily
$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
$(piece)-cor.pdf: $(piece)-cor.ly cor.ily
$(piece)-hautbois.pdf: $(piece)-hautbois.ly hautbois.ily
$(piece)-violonUn.pdf: $(piece)-violonUn.ly violonUn.ily
$(piece)-violonDeux.pdf: $(piece)-violonDeux.ly violonDeux.ily

# Lancer `make score' pour générer l'intégrale des quatre mouvements en
# un seul fichier.
.PHONY: score
score: $(piece).pdf

# Lancer `make parties' pour obtenir tous les pupitres.
# Lancer `make toto.pdf' pour obtenir la partie instrumentale de toto.
# Par exemple : `make symphonie-cello.pdf'.
.PHONY: parties
parties: $(piece)-cello.pdf \
         $(piece)-violonUn.pdf \
         $(piece)-violonDeux.pdf \
         $(piece)-alto.pdf \
         $(piece)-hautbois.pdf \
         $(piece)-cor.pdf

# Lancer `make mouvements' pour générer un fichier séparé pour chacun
# des mouvements.
.PHONY: mouvements
mouvements: $(piece)I.pdf \
            $(piece)II.pdf \
            $(piece)III.pdf \
            $(piece)IV.pdf

all: score parties mouvements

archive:
        tar -cvvf symphonie.tar \      # cette ligne commence par une tabulation
        --exclude=*pdf --exclude=*~ \
        --exclude=*midi --exclude=*.tar \
        ../Symphonie/*
@end example


Les choses se compliquent sous Windows.  Une fois GNU Make pour Windows
téléchargé et installé, il vous faudra correctement définir le chemin
d'accès au programme @emph{Make} -- dans les variables d'environnement
du système --  afin que l'interpréteur de commandes DOS puisse le
localiser.  Pour cela, faites un clic droite sur @qq{Poste de travail},
choisissez @code{Propriétés} puis @code{Avancées}.  Cliquez sur
@code{Variables d'environnement} puis, dans l'onglet
@code{Variables@tie{}système}, mettez @code{path} en surbrillance et
cliquez sur @code{Modifier}.  Ajoutez alors le chemin d'accès complet à
l'exécutable de GNU Make, qui devrait ressembler à@tie{}:

@example
C:\Program Files\GnuWin32\bin
@end example

Il va également falloir adapter le @emph{makefile} aux particularités de
l'interpréteur de commandes et à la présence d'espaces dans le nom de
certains répertoire de ce système.
La cible @code{archive} est tout bonnement supprimée, puisque Windows ne
dispose pas de la commande @code{tar}.  Enfin, les fichiers MIDI ont une
extension par défaut propre à Windows.


@example
## VERSION POUR WINDOWS
##
piece = symphonie
LILY_CMD = lilypond -ddelete-intermediate-files \
                    -dno-point-and-click \
                    -djob-count=$(NUMBER_OF_PROCESSORS)

#get the 8.3 name of CURDIR (workaround for spaces in PATH)
workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
          do @@echo %%~sb)

.SUFFIXES: .ly .ily .pdf .mid

VPATH = \
  $(workdir)/Partitions \
  $(workdir)/PDF \
  $(workdir)/Pupitress \
  $(workdir)/Notes

%.pdf %.mid: %.ly
        $(LILY_CMD) $<      # cette ligne commence par une tabulation
        if exist "$*.pdf"  move /Y "$*.pdf"  PDF/ # tabulation au début
        if exist "$*.mid" move /Y "$*.mid" MIDI/  # tabulation au début

notes = \
  cello.ily \
  figures.ily \
  cor.ily \
  hautbois.ily \
  trioCordes.ily \
  alto.ily \
  violonUn.ily \
  violonDeux.ily

$(piece)I.pdf: $(piece)I.ly $(notes)
$(piece)II.pdf: $(piece)II.ly $(notes)
$(piece)III.pdf: $(piece)III.ly $(notes)
$(piece)IV.pdf: $(piece)IV.ly $(notes)

$(piece).pdf: $(piece).ly $(notes)

$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
$(piece)-cor.pdf: $(piece)-cor.ly cor.ily
$(piece)-hautbois.pdf: $(piece)-hautbois.ly hautbois.ily
$(piece)-alto.pdf: $(piece)-alto.ly alto.ily
$(piece)-violonUn.pdf: $(piece)-violonUn.ly violonUn.ily
$(piece)-violonDeux.pdf: $(piece)-violonDeux.ly violonDeux.ily

.PHONY: score
score: $(piece).pdf

.PHONY: parties
parties: $(piece)-cello.pdf \
         $(piece)-violonUn.pdf \
         $(piece)-violonDeux.pdf \
         $(piece)-alto.pdf \
         $(piece)-hautbois.pdf \
         $(piece)-cor.pdf

.PHONY: mouvements
mouvements: $(piece)I.pdf \
           $(piece)II.pdf \
           $(piece)III.pdf \
           $(piece)IV.pdf

all: score parties mouvements
@end example


Le @emph{Makefile} suivant convient pour un document
@command{lilypond-book} réalisé avec @LaTeX{}.  Ce projet contiendra un
index, ce qui nécessitera de lancer une deuxième fois @command{latex}
pour mettre à jour les liens.  Les fichiers résultants iront dans le
répertoire @code{out} pour ce qui est des .pdf et dans le répertoire
@code{htmlout} pour ce qui est du html.

@example
SHELL=/bin/sh
FILE=monprojet
OUTDIR=out
WEBDIR=htmlout
VIEWER=acroread
BROWSER=firefox
LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
PDF=cd $(OUTDIR) && pdflatex $(FILE)
HTML=cd $(WEBDIR) && latex2html $(FILE)
INDEX=cd $(OUTDIR) && makeindex $(FILE)
PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &

all: pdf web keep

pdf:
        $(LILYBOOK_PDF)  # tabulation en début de ligne
        $(PDF)           # tabulation en début de ligne
        $(INDEX)         # tabulation en début de ligne
        $(PDF)           # tabulation en début de ligne
        $(PREVIEW)       # tabulation en début de ligne

web:
        $(LILYBOOK_HTML) # tabulation en début de ligne
        $(HTML)          # tabulation en début de ligne
        cp -R $(WEBDIR)/$(FILE)/ ./  # tabulation en début de ligne
        $(BROWSER) $(FILE)/$(FILE).html &  # tabulation en début de ligne

keep: pdf
        cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf  # tabulation en début de ligne

clean:
        rm -rf $(OUTDIR) # tabulation en début de ligne

web-clean:
        rm -rf $(WEBDIR) # tabulation en début de ligne

archive:
        tar -cvvf monprojet.tar \ # tabulation en début de ligne
        --exclude=out/* \
        --exclude=htmlout/* \
        --exclude=monprojet/* \
        --exclude=*midi \
        --exclude=*pdf \
        --exclude=*~ \
        ../MonProjet/*
@end example

AVENIR: faire que ça marche sous Windows

Ce @emph{makefile} n'est malheureusement pas opérationnel sous Windows.
La seule alternative qui s'offre aux utilisateurs de Windows consiste à
créer un fichier de traitement par lot (@code{.bat}) qui contienne les
différentes commandes successives.  Bien que cette manière de procéder
ne tienne aucun compte des dépendances entre fichiers, elle permet de
réduire le nombre de processus à lancer dans une seule commande.  Vous
devrez enregistrer les lignes suivantes dans un fichier
@code{construire.bat} ou @code{construire.cmd}.  Ce fichier pourra être
exécuté soit en ligne de commande, soit par un double clic sur son
icone.

@example
lilypond-book --output=out --pdf monprojet.lytex
cd out
pdflatex monprojet
makeindex monprojet
pdflatex monprojet
cd ..
copy out\monprojet.pdf MonProjet.pdf
@end example


@seealso
Manuel d'utilisation :
@ref{Utilisation en ligne de commande},
@ref{lilypond-book}