1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: bfbaf6488d99ab4cdfcb4efdc67eaca63a636106
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 requérir 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.32"}. 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 la version de LilyPond vous utilisiez alors.
79 @item @strong{Ajoutez des contrôles}: @ruser{Bar check}, @ruser{Octave
80 check} et @ruser{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 @ruser{Saving typing with identifiers and functions} et
108 @ruser{Style sheets}.
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 @ruser{Skipping corrected music} ;
127 @item définissez @code{mBreak = @{\break @}} et insérez
128 @code{\mBreak} dans le fichier d'entrée pour obtenir des sauts de
129 ligne identiques à la partition originale. Cela facilite la
130 comparaison entre la partition originale et la partition de
131 LilyPond. Lorsque vous avez fini de relire votre musique, vous pouvez
132 définir @code{mBreak = @{ @}} pour enlever tous ces sauts de ligne, et
133 laisser LilyPond placer les sauts 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 @ruser{General suggestions},
168 mais pour les projets d'importance 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]
268 #(define-music-function (parser location padding) (number?)
270 \once \override TextScript #'padding = #$padding
278 c4^"piu mosso" fis a g
282 Utiliser les identificateurs est aussi un bon moyen pour vous épargner
283 du travail si la syntaxe de LilyPond change un jour --- voir
284 @ruser{Updating old files}. Si vous avez une seule définition, par
285 exemple @code{\dolce}, pour tous vos fichiers (voir @ruser{Style
286 sheets}), et que la syntaxe change, alors vous n'aurez qu'à mettre à
287 jour votre seule définition @code{\dolce}, au lieu de devoir modifier
288 chaque fichier @code{.ly}.
292 @section Style sheets
294 La sortie que produit LilyPond peut être largement modifiée --- voir
295 @ruser{Tweaking output} pour plus de détails. Mais que faire si vous
296 avez beaucoup de fichiers auxquels vous souhaitez appliquer vos
297 retouches ? Ou si vous souhaitez simplement séparer les retouches de
298 la musique elle-même ? Rien de plus facile.
300 Prenons un exemple. Ne vous inquiétez pas si vous ne comprenez pas
301 les parties avec tous les @code{#()}. Celles-ci sont expliquées dans
302 @ruser{Advanced tweaks with Scheme}.
304 @lilypond[quote,verbatim,ragged-right]
305 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
306 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
307 tempoMark = #(define-music-function (parser location markp) (string?)
309 \once \override Score . RehearsalMark #'self-alignment-X = #left
310 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
311 \mark \markup { \bold $markp }
316 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
317 \tempoMark "Poco piu mosso"
318 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
322 Il y a quelques problèmes de chevauchement ; nous allons arranger
323 cela en utilisant les techniques de @ruser{Moving objects}. On peut
324 aussi faire quelque chose pour les définitions de @code{mpdolce}
325 et @code{tempoMark}. Elles produisent le résultat que nous désirons,
326 mais nous pourrions aussi vouloir les utiliser dans une autre pièce.
327 Il suffirait de les copier et les coller au début de chaque
328 fichier, mais c'est fastidieux. De plus, cela laisse les définitions
329 dans nos fichiers de musique, et je trouve personnellement tous ces
330 @code{#()} assez laids. Stockons-les dans un autre fichier :
333 %%% enregistrez ceci dans un fichier nommé "definitions.ly"
334 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
335 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
336 tempoMark = #(define-music-function (parser location markp) (string?)
338 \once \override Score . RehearsalMark #'self-alignment-X = #left
339 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
340 \mark \markup @{ \bold $markp @}
344 Maintenant, modifions notre musique (enregistrez ce fichier
345 sous @file{"musique.ly"}).
347 @c We have to do this awkward example/lilypond-non-verbatim
348 @c because we can't do the \include stuff in the manual.
351 \include "definitions.ly"
355 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
356 \once \override Score.RehearsalMark #'padding = #2.0
357 \tempoMark "Poco piu mosso"
358 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
362 @lilypond[quote,ragged-right]
363 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
364 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
365 tempoMark = #(define-music-function (parser location markp) (string?)
367 \once \override Score . RehearsalMark #'self-alignment-X = #left
368 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
369 \mark \markup { \bold $markp }
374 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
375 \once \override Score.RehearsalMark #'padding = #2.0
376 \tempoMark "Poco piu mosso"
377 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
381 C'est mieux, mais effectuons encore quelques retouches. Le glissando
382 est peu visible, c'est pourquoi nous allons l'épaissir et le
383 rapprocher des têtes de notes. Déplaçons l'indication métronomique
384 au-dessus de la clef, au lieu de la laisser au-dessus de la première
385 note. Et pour finir, mon professeur de composition déteste les
386 chiffrages de mesure en @qq{C}, nous allons donc le transformer en @qq{4/4}.
388 Cependant, ne changez pas le fichier @file{musique.ly}. Remplacez le
389 fichier @file{definitions.ly} par ceci :
393 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
394 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
395 tempoMark = #(define-music-function (parser location markp) (string?)
397 \once \override Score . RehearsalMark #'self-alignment-X = #left
398 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
399 \mark \markup @{ \bold $markp @}
404 \override MetronomeMark #'extra-offset = #'(-9 . 0)
405 \override MetronomeMark #'padding = #'3
408 \override TimeSignature #'style = #'numbered
411 \override Glissando #'thickness = #3
412 \override Glissando #'gap = #0.1
417 @lilypond[quote,ragged-right]
418 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
419 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
420 tempoMark = #(define-music-function (parser location markp) (string?)
422 \once \override Score . RehearsalMark #'self-alignment-X = #left
423 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
424 \mark \markup { \bold $markp }
429 \override MetronomeMark #'extra-offset = #'(-9 . 0)
430 \override MetronomeMark #'padding = #'3
433 \override TimeSignature #'style = #'numbered
436 \override Glissando #'thickness = #3
437 \override Glissando #'gap = #0.1
443 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
444 \once \override Score.RehearsalMark #'padding = #2.0
445 \tempoMark "Poco piu mosso"
446 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
450 C'est encore mieux ! Mais supposons maintenant que je veuille publier
451 cette pièce. Mon professeur de composition n'aime pas les chiffrages
452 de mesure en @qq{C}, mais moi je les aime bien. Copions l'actuel
453 @file{definitions.ly} dans le fichier @file{publication-web.ly}, et
454 modifions ce dernier. Puisque la musique est destinée à produire un
455 fichier PDF affiché sur écran, nous allons aussi augmenter la taille
460 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
461 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
462 tempoMark = #(define-music-function (parser location markp) (string?)
464 \once \override Score . RehearsalMark #'self-alignment-X = #left
465 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
466 \mark \markup @{ \bold $markp @}
469 #(set-global-staff-size 23)
472 \override MetronomeMark #'extra-offset = #'(-9 . 0)
473 \override MetronomeMark #'padding = #'3
478 \override Glissando #'thickness = #3
479 \override Glissando #'gap = #0.1
484 @lilypond[quote,ragged-right]
485 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
486 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
487 tempoMark = #(define-music-function (parser location markp) (string?)
489 \once \override Score . RehearsalMark #'self-alignment-X = #left
490 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
491 \mark \markup { \bold $markp }
494 #(set-global-staff-size 23)
497 \override MetronomeMark #'extra-offset = #'(-9 . 0)
498 \override MetronomeMark #'padding = #'3
501 \override Glissando #'thickness = #3
502 \override Glissando #'gap = #0.1
508 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
509 \once \override Score.RehearsalMark #'padding = #2.0
510 \tempoMark "Poco piu mosso"
511 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
515 Il ne nous reste plus qu'à remplacer @code{\include "definitions.ly"}
516 par @code{\include "publication-web.ly"} dans notre fichier de musique.
518 Il est possible, bien sûr, de rendre cela encore plus pratique. Nous
519 pourrions créer un fichier @file{definitions.ly} qui ne contiendrait
520 que les définitions de @code{mpdolce} et de @code{tempoMark}, un
521 fichier @file{publication-web.ly} qui ne contiendrait que la section
522 @code{layout} décrite ci-dessus et un fichier @file{universite.ly} qui
523 ne contiendrait que les retouches pour produire le résultat que mon
524 professeur préfère. Le début du fichier @file{musique.ly} ressemblerait
528 \include "definitions.ly"
530 %%% Décommentez seulement une de ces deux lignes !
531 \include "publication-web.ly"
532 %\include "universite.ly"
535 Cette approche peut être utile même si vous ne produisez qu'un seul
536 jeu de partitions. J'utilise personnellement une demi-douzaine de
537 fichiers de @qq{feuille de style} pour mes projets. Je commence
538 chaque fichier de musique par @code{\include "../global.ly"} qui contient :
543 #(ly:set-option 'point-and-click #f)
544 \include "../init/init-defs.ly"
545 \include "../init/init-mise-en-page.ly"
546 \include "../init/init-en-tetes.ly"
547 \include "../init/init-papier.ly"
550 @node Updating old files
551 @section Updating old files
553 La syntaxe de LilyPond change de temps en temps. Ces changements de
554 syntaxe du langage d'entrée accompagnent les améliorations du
555 logiciel. Ces changements sont parfois destinés à rendre les fichiers
556 plus faciles à lire et à écrire, ou permettent d'intégrer de nouvelles
559 LilyPond est fourni avec un utilitaire qui facilite cette mise à
560 jour : @code{convert-ly}. Pour savoir comment utiliser ce programme,
561 voir @rprogram{Updating files with convert-ly}.
563 Malheureusement, @code{convert-ly} ne peut pas réaliser toutes les
564 modifications. Il s'occupe des changements qui ne requièrent qu'une
565 simple substitution de texte --- comme @code{raggedright} devenant
566 @code{ragged-right} ---, les autres étant trop compliqués à effectuer.
567 Les changements de syntaxe qui ne sont pas gérés par @code{convert-ly}
568 sont énumérés dans @rprogram{Updating files with convert-ly}.
570 Par exemple, dans les versions 2.4 et antérieures de LilyPond,
571 les accents et les lettres non anglaises étaient entrées en
572 utilisant LaTeX --- par exemple, @samp{No\"el}. À partir de la
573 version 2.6, le caratère @samp{ë} doit être entré directement
574 dans le fichier LilyPond comme caractère UTF-8.
575 @code{convert-ly} ne peut pas changer tous les caractères
576 LaTeX en caractères UTF-8 ; vous devez mettre à jour vos vieux
577 fichiers LilyPond manuellement.
581 @node Troubleshooting (taking it all apart)
582 @section Troubleshooting (taking it all apart)
584 Tôt ou tard, vous écrirez un fichier que LilyPond ne peut pas
585 compiler. Les messages que LilyPond affiche peuvent vous aider à
586 trouver l'erreur, mais dans beaucoup de cas vous aurez besoin de faire
587 quelques recherches pour déterminer la source du problème.
589 Pour ce faire, les outils les plus puissants sont le commentaire de
590 fin de ligne, indiqué par @code{%}, et le commentaire multilignes (ou
591 bloc de commentaire), indiqué par @code{%@{ ... %@}}. Si vous ne
592 pouvez localiser le problème, commencez par mettre en commentaire de
593 grandes parties de votre fichier d'entrée. Après avoir mis en
594 commentaire une section, essayez de compiler à nouveau. Si cela
595 fonctionne, c'est que le problème se situe dans cette partie du
596 fichier. Si cela ne fonctionne pas, continuez à mettre en commentaire
597 d'autres sections, jusqu'à ce que vous ayez quelque chose qui compile.
599 Dans un cas extrême, vous pourriez en arriver à
613 c'est-à-dire un fichier sans aucune musique.
615 Si cela arrive, ne vous découragez pas. Décommentez un peu, la partie
616 de basse par exemple, et voyez si ça fonctionne. Si ce n'est pas le
617 cas, placez en commentaire toute la partie de basse, mais laissez
618 @code{\basse} décommenté dans le bloc @code{\score}.
621 basse = \relative c' @{
629 Maintenant commencez à décommenter petit à petit le partie de
630 @code{basse} jusqu'à ce que vous localisiez la ligne qui pose
633 Une autre technique de déboguage très utile est la construction
635 de @ruser{Minimal examples}.
638 d'@ruser{Minimal examples}.
642 @node Minimal examples
643 @section Minimal examples
645 Un exemple minimal est un exemple de code aussi court que possible.
646 De tels exemples sont bien plus compréhensibles que des exemples
647 longs. Les exemples minimaux sont utilisés pour
650 @item les rapports de bogue,
651 @item les demandes d'aide sur les listes de diffusion,
653 @uref{http://lsr@/.dsi@/.unimi@/.it/,LilyPond Snippet Repository}.
656 Pour construire un exemple minimal, la règle est très simple : enlevez
657 tout ce qui n'est pas nécessaire. Il est préférable de commenter les
658 lignes non nécessaires plutôt que de les effacer : ainsi, si vous vous
659 apercevez que certaines étaient @emph{réellement} nécessaires, vous
660 pouvez les décommenter au lieu de les resaisir.
662 Il y a deux exceptions à cette règle du strict nécessaire :
665 @item incluez le numéro de @code{\version} en début de fichier
666 @item si possible, utilisez @code{\paper@{ ragged-right=##t @}} au
667 début de votre exemple.
670 Tout l'intérêt d'un exemple minimal réside dans sa facilité de lecture :
672 @item évitez d'utiliser des notes, armures ou métriques compliquées, à
673 moins que vous ne vouliez montrer quelque chose en rapport avec
675 @item n'utilisez pas de commandes @code{\override} sauf si elles font
676 l'intérêt de l'exemple.