1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: a765cf7a841733570469b8f8b5c5ba538c4187d6
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
10 @node Working on LilyPond projects
11 @chapter Working on LilyPond projects
13 Cette section explique comment résoudre ou éviter certains problèmes
14 courants. Si vous avez de l'expérience en programmation, beaucoup de
15 ces astuces peuvent vous paraître évidentes, mais vous ne perdrez tout
16 de même pas votre temps à lire ce chapitre.
19 * Suggestions for writing LilyPond files::
20 * Saving typing with identifiers and functions::
22 * Updating old files::
23 * Troubleshooting (taking it all apart)::
27 @node Suggestions for writing LilyPond files
28 @section Suggestions for writing LilyPond files
30 Maintenant vous êtes prêt à travailler sur de plus gros fichiers
31 LilyPond --- des pièces entières, et plus seulement les petits
32 exemples du tutoriel. Mais comment devriez-vous vous y prendre ?
34 Tant que LilyPond parvient à comprendre vos fichiers et produit le
35 résultat que vous souhaitez, peu importe la manière dont le code est
36 organisé. Néanmoins, quelques critères doivent être pris en compte
37 lorsque l'on écrit un fichier LilyPond.
40 @item Si vous faites une erreur, la structure même du fichier LilyPond
41 peut permettre de la localiser plus ou moins facilement.
43 @item Et si vous souhaitez partager vos fichiers avec quelqu'un
44 d'autre, ou si vous souhaitez modifier vos propres fichiers dans
45 quelques années ? Si certains fichiers LilyPond sont compréhensibles
46 au premier coup d'oeil, d'autres vous feront vous arracher les cheveux
49 @item Et si vous souhaitez mettre à jour votre fichier pour
50 l'utiliser avec une version plus récente de LilyPond ? La syntaxe du
51 langage d'entrée change parfois lorsque LilyPond s'améliore. La
52 plupart des changements peuvent être appliqués automatiquement avec
53 @code{convert-ly}, mais quelques-uns peuvent demander une intervention
54 manuelle. Vos fichiers LilyPond peuvent être structurés de manière à
55 faciliter leur mise à jour.
59 * General suggestions::
60 * Typesetting existing music::
64 @node General suggestions
65 @subsection General suggestions
67 Voici quelques conseils qui peuvent vous éviter certains problèmes ou
71 @item @strong{Ajoutez le numéro de version dans chaque fichier}.
72 Notez que chaque fichier modèle contient une ligne @code{\version
73 "2.11.15"}. Nous vous conseillons fortement d'inclure cette ligne,
74 même pour de petits fichiers. Par expérience, il est très difficile
75 de se rappeler quelle version de LilyPond on utilisait quelques
76 années auparavant. L'utilitaire @code{convert-ly} demande que vous
77 spécifiiez quelle version de LilyPond vous utilisiez.
79 @item @strong{Ajoutez des contrôles}: @ref{Bar check}, @ref{Octave
80 check} et @ref{Barnumber check}. Si vous avez ajouté des contrôles de
81 loin en loin, et que vous faites une erreur, vous pourrez la retrouver
82 plus rapidement. @qq{De loin en loin}, qu'est-ce à dire ? Cela
83 dépend de la complexité de la musique. Pour de la musique très
84 simple, peut-être une ou deux fois. Pour de la musique très complexe,
85 peut-être à chaque mesure.
87 @item @strong{Une mesure par ligne de texte}. Si la musique en elle-même ou
88 le résultat que vous désirez contient quelque chose de compliqué, il
89 est souvent bon de n'écrire qu'une seule mesure par ligne. Économiser
90 de la place en tassant huit mesures par ligne, ça ne vaut pas vraiment
91 le coup si l'on doît corriger vos fichiers.
93 @item @strong{Ajoutez des commentaires}. Utilisez soit des
94 numéros de mesure (assez souvent), soit des références au contenu
95 musical --- @qq{second thème des violons}, @qq{quatrième variation}, etc.
96 Vous pouvez ne pas avoir besoin des commentaires lorsque vous écrivez
97 une pièce pour la première fois, mais si vous souhaitez y revenir deux
98 ou trois ans plus tard pour changer quelque chose, ou si vous donnez
99 le fichier source à un ami, ce sera beaucoup plus difficile de
100 déterminer vos intentions ou la manière dont votre fichier est
101 structuré si vous n'y avez pas adjoint de commentaires.
103 @item @strong{Indentez les accolades}. Beaucoup de problèmes
104 viennent d'un défaut de parité entre @code{@{} et @code{@}}.
106 @item @strong{Séparez les affinages de mise en forme} de la musique
107 elle-même. Voyez @ref{Saving typing with identifiers and functions} et
113 @node Typesetting existing music
114 @subsection Typesetting existing music
116 Si vous saisissez de la musique à partir d'une partition existante,
117 c'est-à-dire de la musique déjà écrite,
121 @item n'entrez qu'un seul système de la partition originale
122 à la fois --- mais toujours une seule mesure par ligne de texte ---,
123 et vérifiez chaque système lorsqu'il est terminé. Vous pouvez
124 utiliser la commande @code{showLastLength} pour accélérer la
125 compilation --- voir @ref{Skipping corrected music} ;
127 @item définissez @code{mBreak = @{\break @}} et insérez
128 @code{\mBreak} dans le fichier d'entrée des sauts de ligne identiques à la
129 partition originale. Cela facilite la comparaison entre la partition
130 originale et la partition de LilyPond. Lorsque vous avez fini de
131 relire votre musique, vous pouvez définir @code{mBreak = @{ @}} pour
132 enlever tous ces sauts de ligne, et laisser LilyPond placer les sauts
133 de ligne selon son propre algorithme.
139 @subsection Large projects
141 Lorsque l'on travaille sur un gros projet, il devient vital
142 de structurer clairement ses fichiers LilyPond.
146 @item @strong{utilisez un identificateur pour chaque voix},
147 avec un minimum de structure dans la définition. La structure de la
148 section @code{\score} est la plus susceptible de changer, notamment
149 dans une nouvelle version de LilyPond, alors que la définition du
150 @code{violon} l'est beaucoup moins.
153 violin = \relative c'' @{
166 @item @strong{Séparez les retouches} des définitions de
167 musique. Ce conseil a été vu dans @ref{General suggestions},
168 mais pour les gros projets c'est absolument vital. Nous
169 pouvons avoir besoin de changer la définition de
170 @code{fthenp}, mais dans ce cas nous n'aurons besoin de le faire
171 qu'une seule fois, et nous pourrons encore éviter de
172 modifier quoi que ce soit à l'intérieur de la définition
177 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
178 violin = \relative c'' @{
186 @node Saving typing with identifiers and functions
187 @section Saving typing with identifiers and functions
190 @cindex identificateurs
192 Jusqu'à maintenant, vous avez vu ce type de code :
194 @lilypond[quote,verbatim,ragged-right]
195 hornNotes = \relative c'' { c4 b dis c }
203 Vous comprendrez combien cela peut être utile pour écrire de la
204 musique minimaliste :
206 @lilypond[quote,verbatim,ragged-right]
207 fragA = \relative c'' { a4 a8. b16 }
208 fragB = \relative c'' { a8. gis16 ees4 }
209 violin = \new Staff { \fragA \fragA \fragB \fragA }
217 Cependant, vous pouvez aussi utiliser ces identificateurs
218 --- aussi connus sous le nom de variables, macros, ou commandes
219 (définies par l'utilisateur) --- pour des retouches :
221 @lilypond[quote,verbatim,ragged-right]
222 dolce = \markup{ \italic \bold dolce }
223 padText = { \once \override TextScript #'padding = #5.0 }
224 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
225 violin = \relative c'' {
227 c4._\dolce b8 a8 g a b |
229 c4.^"hi there!" d8 e' f g d |
230 c,4.\fthenp b8 c4 c-. |
237 \layout{ragged-right=##t}
241 Ces identificateurs sont évidemment utiles pour économiser de la
242 frappe. Mais ils peuvent l'être même si vous ne les utilisez qu'une
243 seule fois : ils réduisent la complexité. Regardons l'exemple
244 précédent sans aucun identificateur. C'est beaucoup plus laborieux à
245 lire, et particulièrement la dernière ligne.
248 violin = \relative c'' @{
250 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
251 \once \override TextScript #'padding = #5.0
252 c4.^"hi there!" d8 e' f g d |
253 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
254 \hspace #0.1 \dynamic p @} b8 c4 c-. |
259 Jusqu'ici nous avons vu des substitutions statiques : quand LilyPond
260 rencontre @code{\padText}, il le remplace par le contenu que nous lui
261 avons défini --- c'est-à-dire le contenu à droite de @code{padText=}).
263 LilyPond gère également des substitutions non-statiques --- vous
264 pouvez les voir comme des fonctions.
266 @lilypond[quote,verbatim,ragged-right]
267 #(define-music-function (parser location padding) (number?)
269 \once \override TextScript #'padding = #$padding
277 c4^"piu mosso" fis a g
281 Utiliser les identificateurs est aussi un bon moyen pour vous épargner
282 du travail si la syntaxe de LilyPond change un jour --- voir
283 @ref{Updating old files}. Si vous avez une seule définition, par
284 exemple @code{\dolce}, pour tous vos fichiers (voir @ref{Style
285 sheets}), et que la syntaxe change, alors vous n'aurez qu'à mettre à
286 jour votre seule définition @code{\dolce}, au lieu de devoir modifier
287 chaque fichier @code{.ly}.
291 @section Style sheets
293 La sortie que produit LilyPond peut être largement modifiée --- voir
294 @ref{Tweaking output} pour plus de détails. Mais que faire si vous
295 avez beaucoup de fichiers auxquels vous souhaitez appliquer vos
296 retouches ? Ou si vous souhaitez simplement séparer les retouches de
297 la musique elle-même ? Rien de plus facile.
299 Prenons un exemple. Ne vous inquiétez pas si vous ne comprenez pas
300 les parties avec tous les @code{#()}. Celles-ci sont expliquées dans
301 @ref{Advanced tweaks with Scheme}.
303 @lilypond[quote,verbatim,ragged-right]
304 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
305 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
306 tempoMark = #(define-music-function (parser location markp) (string?)
308 \once \override Score . RehearsalMark #'self-alignment-X = #left
309 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
310 \mark \markup { \bold $markp }
315 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
316 \tempoMark "Poco piu mosso"
317 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
321 Il y a quelques problèmes de chevauchement ; nous allons arranger
322 cela en utilisant les techniques de @ref{Moving objects}. On peut
323 aussi aussi faire quelque chose pour les définitions de @code{mpdolce}
324 et @code{tempoMark}. Elles produisent le résultat que nous désirons,
325 mais nous pourrions aussi vouloir les utiliser dans une autre pièce.
326 Il suffirait de les copier et les coller au début de chaque
327 fichier, mais c'est fastidieux. De plus, cela laisse les définitions
328 dans nos fichiers de musique, et je trouve personnellement tous ces
329 @code{#()} assez laids. Stockons-les dans un autre fichier :
332 %%% enregistrez ceci dans un fichier nommé "definitions.ly"
333 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
334 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
335 tempoMark = #(define-music-function (parser location markp) (string?)
337 \once \override Score . RehearsalMark #'self-alignment-X = #left
338 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
339 \mark \markup @{ \bold $markp @}
343 Maintenant, modifions notre musique (enregistrez ce fichier
344 sous @file{"musique.ly"}).
346 @c We have to do this awkward example/lilypond-non-verbatim
347 @c because we can't do the \include stuff in the manual.
350 \include "definitions.ly"
354 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
355 \once \override Score.RehearsalMark #'padding = #2.0
356 \tempoMark "Poco piu mosso"
357 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
361 @lilypond[quote,ragged-right]
362 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
363 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
364 tempoMark = #(define-music-function (parser location markp) (string?)
366 \once \override Score . RehearsalMark #'self-alignment-X = #left
367 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
368 \mark \markup { \bold $markp }
373 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
374 \once \override Score.RehearsalMark #'padding = #2.0
375 \tempoMark "Poco piu mosso"
376 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
380 C'est mieux, mais effectuons encore quelques retouches. Le glissando
381 est peu visible, c'est pourquoi nous allons l'épaissir et le
382 rapprocher des têtes de notes. Déplaçons l'indication métronomique
383 au-dessus de la clef, au lieu de la laisser au-dessus de la première
384 note. Et pour finir, mon professeur de composition déteste les
385 chiffrages de mesure en @qq{C}, nous allons donc le transformer en @qq{4/4}.
387 Cependant, ne changez pas le fichier @file{musique.ly}. Remplacez le
388 fichier @file{definitions.ly} par ceci :
392 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
393 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
394 tempoMark = #(define-music-function (parser location markp) (string?)
396 \once \override Score . RehearsalMark #'self-alignment-X = #left
397 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
398 \mark \markup @{ \bold $markp @}
403 \override MetronomeMark #'extra-offset = #'(-9 . 0)
404 \override MetronomeMark #'padding = #'3
407 \override TimeSignature #'style = #'numbered
410 \override Glissando #'thickness = #3
411 \override Glissando #'gap = #0.1
416 @lilypond[quote,ragged-right]
417 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
418 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
419 tempoMark = #(define-music-function (parser location markp) (string?)
421 \once \override Score . RehearsalMark #'self-alignment-X = #left
422 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
423 \mark \markup { \bold $markp }
428 \override MetronomeMark #'extra-offset = #'(-9 . 0)
429 \override MetronomeMark #'padding = #'3
432 \override TimeSignature #'style = #'numbered
435 \override Glissando #'thickness = #3
436 \override Glissando #'gap = #0.1
442 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
443 \once \override Score.RehearsalMark #'padding = #2.0
444 \tempoMark "Poco piu mosso"
445 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
449 C'est encore mieux ! Mais supposons maintenant que je veuille publier
450 cette pièce. Mon professeur de composition n'aime pas les chiffrages
451 de mesure en @qq{C}, mais moi je les aime bien. Copions l'actuel
452 @file{definitions.ly} dans le fichier @file{publication-web.ly}, et
453 modifions ce dernier. Puisque la musique est destinée à produire un
454 fichier PDF affiché sur écran, nous allons aussi augmenter la taille
459 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
460 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
461 tempoMark = #(define-music-function (parser location markp) (string?)
463 \once \override Score . RehearsalMark #'self-alignment-X = #left
464 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
465 \mark \markup @{ \bold $markp @}
468 #(set-global-staff-size 23)
471 \override MetronomeMark #'extra-offset = #'(-9 . 0)
472 \override MetronomeMark #'padding = #'3
477 \override Glissando #'thickness = #3
478 \override Glissando #'gap = #0.1
483 @lilypond[quote,ragged-right]
484 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
485 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
486 tempoMark = #(define-music-function (parser location markp) (string?)
488 \once \override Score . RehearsalMark #'self-alignment-X = #left
489 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
490 \mark \markup { \bold $markp }
493 #(set-global-staff-size 23)
496 \override MetronomeMark #'extra-offset = #'(-9 . 0)
497 \override MetronomeMark #'padding = #'3
500 \override Glissando #'thickness = #3
501 \override Glissando #'gap = #0.1
507 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
508 \once \override Score.RehearsalMark #'padding = #2.0
509 \tempoMark "Poco piu mosso"
510 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
514 Il ne nous reste plus qu'à remplacer @code{\include "definitions.ly"}
515 par @code{\include "publication-web.ly"} dans notre fichier de musique.
517 Il est possible, bien sûr, de rendre cela encore plus pratique. Nous
518 pourrions créer un fichier @file{definitions.ly} qui ne contiendrait
519 que les définitions de @code{mpdolce} et de @code{tempoMark}, un
520 fichier @file{publication-web.ly} qui ne contiendrait que la section
521 @code{layout} décrite ci-dessus et un fichier @file{universite.ly} qui
522 ne contiendrait que les retouches pour produire le résultat que mon
523 professeur préfère. Le début du fichier @file{musique.ly} ressemblerait
527 \include "definitions.ly"
529 %%% Décommentez seulement une de ces deux lignes !
530 \include "publication-web.ly"
531 %\include "universite.ly"
534 Cette approche peut être utile même si vous ne produisez qu'un seul
535 jeu de partitions. J'utilise une demi-douzaine de fichiers de
536 @qq{feuille de style} pour mes projets. Je commence chaque fichier de
537 musique par @code{\include "../global.ly"} qui contient :
542 #(ly:set-option 'point-and-click #f)
543 \include "../init/init-defs.ly"
544 \include "../init/init-mise-en-page.ly"
545 \include "../init/init-en-tetes.ly"
546 \include "../init/init-papier.ly"
549 @node Updating old files
550 @section Updating old files
552 La syntaxe de LilyPond change de temps en temps. Ces changements de
553 syntaxe du langage d'entrée accompagnent les améliorations du
554 logiciel. Ces changements sont parfois destinés à rendre les fichiers
555 plus faciles à lire et à écrire, ou permettent d'intégrer de nouvelles
558 LilyPond est fourni avec un utilitaire qui facilite cette mise à
559 jour : @code{convert-ly}. Pour savoir comment utiliser ce programme,
560 voir @ref{Updating files with convert-ly}.
562 Malheureusement, @code{convert-ly} ne peut pas réaliser toutes les
563 modifications. Il s'occupe des changements qui ne requièrent qu'une
564 simple substitution de texte --- comme @code{raggedright} devenant
565 @code{ragged-right} ---, les autres étant trop compliqués à effectuer.
566 Les changements de syntaxe qui ne sont pas gérés par @code{convert-ly}
567 sont énumérés dans @ref{Updating files with convert-ly}.
569 Par exemple, dans les versions 2.4 et antérieures de LilyPond,
570 les accents et les lettres non anglaises étaient entrées en
571 utilisant LaTeX --- par exemple, @samp{No\"el}. À partir de la
572 version 2.6, le caratère @samp{ë} doit être entré directement
573 dans le fichier LilyPond comme caractère UTF-8.
574 @code{convert-ly} ne peut pas changer tous les caractères
575 LaTeX en caractères UTF-8 ; vous devez mettre à jour vos vieux
576 fichiers LilyPond manuellement.
580 @node Troubleshooting (taking it all apart)
581 @section Troubleshooting (taking it all apart)
583 Tôt ou tard, vous écrirez un fichier que LilyPond ne peut pas
584 compiler. Les messages que LilyPond affiche peuvent vous aider à
585 trouver l'erreur, mais dans beaucoup de cas vous aurez besoin de faire
586 quelques recherches pour déterminer la source du problème.
588 Pour ce faire, les outils les plus puissants sont le commentaire de
589 fin de ligne, indiqué par @code{%}, et le commentaire multilignes (ou
590 bloc de commentaire), indiqué par @code{%@{ ... %@}}. Si vous ne
591 pouvez localiser le problème, commencez par mettre en commentaire de
592 grandes parties de votre fichier d'entrée. Après avoir mis en
593 commentaire une section, essayez de compiler à nouveau. Si cela
594 fonctionne, c'est que le problème se situe dans cette partie du
595 fichier. Si cela ne fonctionne pas, continuez à mettre en commentaire
596 d'autres sections, jusqu'à ce que vous ayez quelque chose qui compile.
598 Dans un cas extrême, vous pourriez en arriver à
612 c'est-à-dire un fichier sans aucune musique.
614 Si cela arrive, ne vous découragez pas. Décommentez un peu, la partie
615 de basse par exemple, et voyez si ça fonctionne. Si ce n'est pas le
616 cas, placez en commentaire toute la partie de basse, mais laissez
617 @code{\basse} décommenté dans le bloc @code{\score}.
620 basse = \relative c' @{
628 Maintenant commencez à décommenter petit à petit le partie de
629 @code{basse} jusqu'à ce que vous localisiez la ligne qui pose
632 Une autre technique de déboguage très utile est la construction
634 de @ref{Minimal examples}.
637 d'@ref{Minimal examples}.
641 @node Minimal examples
642 @section Minimal examples
644 Un exemple minimal est un exemple de code aussi court que possible.
645 De tels exemples sont bien plus compréhensibles que des exemple
646 longs. Les exemples minimaux sont utilisés pour
649 @item les rapports de bogue,
650 @item les demandes d'aide sur les listes de diffusion,
652 @uref{http://lsr@/.dsi@/.unimi@/.it/,LilyPond Snippet Repository}.
655 Pour construire un exemple minimal, la règle est très simple : enlevez
656 tout ce qui n'est pas nécessaire. Il est préférable de commenter les
657 lignes non nécessaires plutôt que de les effacer : ainsi, si vous vous
658 apercevez que certaines étaient @emph{réellement} nécessaires, vous
659 pouvez les décommenter au lieu de les resaisir.
661 Il y a deux exceptions à cette règle du strict nécessaire :
664 @item incluez le numéro de @code{\version} en début de fichier
665 @item si possible, utilisez @code{\paper@{ ragged-right=##t @}} au
666 début de votre exemple.
669 Tout l'intérêt d'un exemple minimal réside dans sa facilité de lecture :
671 @item évitez d'utiliser des notes, armures ou métriques compliquées, à
672 moins que vous vouliez montrer quelque chose en rapport avec
674 @item n'utilisez pas de commandes @code{\override} sauf si elles font
675 l'intérêt de l'exemple.