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 @c Translators: Ludovic Sardain
11 @c Translation checkers: Jean-Yves Baudais, Valentin Villenave, John Mandereau, Jean-Charles Malahieude
13 @node Working on LilyPond projects
14 @chapter Working on LilyPond projects
16 Cette section explique comment résoudre ou éviter certains problèmes
17 courants. Si vous avez de l'expérience en programmation, beaucoup de
18 ces astuces peuvent vous paraître évidentes, mais vous ne perdrez tout
19 de même pas votre temps à lire ce chapitre.
22 * Suggestions for writing LilyPond files::
23 * Saving typing with identifiers and functions::
25 * Updating old files::
26 * Troubleshooting (taking it all apart)::
30 @node Suggestions for writing LilyPond files
31 @section Suggestions for writing LilyPond files
33 Maintenant vous êtes prêt à travailler sur de plus gros fichiers
34 LilyPond --- des pièces entières, et plus seulement les petits
35 exemples du tutoriel. Mais comment devriez-vous vous y prendre ?
37 Tant que LilyPond parvient à comprendre vos fichiers et produit le
38 résultat que vous souhaitez, peu importe la manière dont le code est
39 organisé. Néanmoins, quelques critères doivent être pris en compte
40 lorsque l'on écrit un fichier LilyPond.
43 @item Si vous faites une erreur, la structure même du fichier LilyPond
44 peut permettre de la localiser plus ou moins facilement.
46 @item Et si vous souhaitez partager vos fichiers avec quelqu'un
47 d'autre, ou si vous souhaitez modifier vos propres fichiers dans
48 quelques années ? Si certains fichiers LilyPond sont compréhensibles
49 au premier coup d'oeil, d'autres vous feront vous arracher les cheveux
52 @item Et si vous souhaitez mettre à jour votre fichier pour
53 l'utiliser avec une version plus récente de LilyPond ? La syntaxe du
54 langage d'entrée change parfois lorsque LilyPond s'améliore. La
55 plupart des changements peuvent être appliqués automatiquement avec
56 @code{convert-ly}, mais quelques-uns peuvent requérir une intervention
57 manuelle. Vos fichiers LilyPond peuvent être structurés de manière à
58 faciliter leur mise à jour.
62 * General suggestions::
63 * Typesetting existing music::
67 @node General suggestions
68 @subsection General suggestions
70 Voici quelques conseils qui peuvent vous éviter certains problèmes ou
74 @item @strong{Ajoutez le numéro de version dans chaque fichier}.
75 Notez que chaque fichier modèle contient une ligne @code{\version
76 "2.11.32"}. Nous vous conseillons fortement d'inclure cette ligne,
77 même pour de petits fichiers. Par expérience, il est très difficile
78 de se rappeler quelle version de LilyPond on utilisait quelques
79 années auparavant. L'utilitaire @code{convert-ly} demande que vous
80 spécifiiez la version de LilyPond vous utilisiez alors.
82 @item @strong{Ajoutez des contrôles}: @ruser{Bar check}, @ruser{Octave
83 check} et @ruser{Barnumber check}. Si vous avez ajouté des contrôles de
84 loin en loin, et que vous faites une erreur, vous pourrez la retrouver
85 plus rapidement. @qq{De loin en loin}, qu'est-ce à dire ? Cela
86 dépend de la complexité de la musique. Pour de la musique très
87 simple, peut-être une ou deux fois. Pour de la musique très complexe,
88 peut-être à chaque mesure.
90 @item @strong{Une mesure par ligne de texte}. Si la musique en elle-même ou
91 le résultat que vous désirez contient quelque chose de compliqué, il
92 est souvent bon de n'écrire qu'une seule mesure par ligne. Économiser
93 de la place en tassant huit mesures par ligne, ça ne vaut pas vraiment
94 le coup si l'on doît corriger vos fichiers.
96 @item @strong{Ajoutez des commentaires}. Utilisez soit des
97 numéros de mesure (assez souvent), soit des références au contenu
98 musical --- @qq{second thème des violons}, @qq{quatrième variation}, etc.
99 Vous pouvez ne pas avoir besoin des commentaires lorsque vous écrivez
100 une pièce pour la première fois, mais si vous souhaitez y revenir deux
101 ou trois ans plus tard pour changer quelque chose, ou si vous donnez
102 le fichier source à un ami, ce sera beaucoup plus difficile de
103 déterminer vos intentions ou la manière dont votre fichier est
104 structuré si vous n'y avez pas adjoint de commentaires.
106 @item @strong{Indentez les accolades}. Beaucoup de problèmes
107 viennent d'un défaut de parité entre @code{@{} et @code{@}}.
109 @item @strong{Séparez les affinages de mise en forme} de la musique
110 elle-même. Voyez @ruser{Saving typing with identifiers and functions} et
111 @ruser{Style sheets}.
116 @node Typesetting existing music
117 @subsection Typesetting existing music
119 Si vous saisissez de la musique à partir d'une partition existante,
120 c'est-à-dire de la musique déjà écrite,
124 @item n'entrez qu'un seul système de la partition originale
125 à la fois --- mais toujours une seule mesure par ligne de texte ---,
126 et vérifiez chaque système lorsqu'il est terminé. Vous pouvez
127 utiliser la commande @code{showLastLength} pour accélérer la
128 compilation --- voir @ruser{Skipping corrected music} ;
130 @item définissez @code{mBreak = @{\break @}} et insérez
131 @code{\mBreak} dans le fichier d'entrée pour obtenir des sauts de
132 ligne identiques à la partition originale. Cela facilite la
133 comparaison entre la partition originale et la partition de
134 LilyPond. Lorsque vous avez fini de relire votre musique, vous pouvez
135 définir @code{mBreak = @{ @}} pour enlever tous ces sauts de ligne, et
136 laisser LilyPond placer les sauts de ligne selon son propre algorithme.
142 @subsection Large projects
144 Lorsque l'on travaille sur un gros projet, il devient vital
145 de structurer clairement ses fichiers LilyPond.
149 @item @strong{Utilisez un identificateur pour chaque voix},
150 avec un minimum de structure dans la définition. La structure de la
151 section @code{\score} est la plus susceptible de changer, notamment
152 dans une nouvelle version de LilyPond, alors que la définition du
153 @code{violon} l'est beaucoup moins.
156 violin = \relative c'' @{
169 @item @strong{Séparez les retouches} des définitions de
170 musique. Ce conseil a été vu dans @ruser{General suggestions},
171 mais pour les projets d'importance c'est absolument vital. Nous
172 pouvons avoir besoin de changer la définition de
173 @code{fthenp}, mais dans ce cas nous n'aurons besoin de le faire
174 qu'une seule fois, et nous pourrons encore éviter de
175 modifier quoi que ce soit à l'intérieur de la définition
180 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
181 violin = \relative c'' @{
189 @node Saving typing with identifiers and functions
190 @section Saving typing with identifiers and functions
193 @cindex identificateurs
195 Jusqu'à maintenant, vous avez vu ce type de code :
197 @lilypond[quote,verbatim,ragged-right]
198 hornNotes = \relative c'' { c4 b dis c }
206 Vous comprendrez combien cela peut être utile pour écrire de la
207 musique minimaliste :
209 @lilypond[quote,verbatim,ragged-right]
210 fragA = \relative c'' { a4 a8. b16 }
211 fragB = \relative c'' { a8. gis16 ees4 }
212 violin = \new Staff { \fragA \fragA \fragB \fragA }
220 Cependant, vous pouvez aussi utiliser ces identificateurs
221 --- aussi connus sous le nom de variables, macros, ou commandes
222 (définies par l'utilisateur) --- pour des retouches :
224 @lilypond[quote,verbatim,ragged-right]
225 dolce = \markup{ \italic \bold dolce }
226 padText = { \once \override TextScript #'padding = #5.0 }
227 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
228 violin = \relative c'' {
230 c4._\dolce b8 a8 g a b |
232 c4.^"hi there!" d8 e' f g d |
233 c,4.\fthenp b8 c4 c-. |
240 \layout{ragged-right=##t}
244 Ces identificateurs sont évidemment utiles pour économiser de la
245 frappe. Mais ils peuvent l'être même si vous ne les utilisez qu'une
246 seule fois : ils réduisent la complexité. Regardons l'exemple
247 précédent sans aucun identificateur. C'est beaucoup plus laborieux à
248 lire, et particulièrement la dernière ligne.
251 violin = \relative c'' @{
253 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
254 \once \override TextScript #'padding = #5.0
255 c4.^"hi there!" d8 e' f g d |
256 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
257 \hspace #0.1 \dynamic p @} b8 c4 c-. |
262 Jusqu'ici nous avons vu des substitutions statiques : quand LilyPond
263 rencontre @code{\padText}, il le remplace par le contenu que nous lui
264 avons défini --- c'est-à-dire le contenu à droite de @code{padText=}.
266 LilyPond gère également des substitutions non-statiques --- vous
267 pouvez les voir comme des fonctions.
269 @lilypond[quote,verbatim,ragged-right]
271 #(define-music-function (parser location padding) (number?)
273 \once \override TextScript #'padding = #$padding
281 c4^"piu mosso" fis a g
285 Utiliser les identificateurs est aussi un bon moyen pour vous épargner
286 du travail si la syntaxe de LilyPond change un jour --- voir
287 @ruser{Updating old files}. Si vous avez une seule définition, par
288 exemple @code{\dolce}, pour tous vos fichiers (voir @ruser{Style
289 sheets}), et que la syntaxe change, alors vous n'aurez qu'à mettre à
290 jour votre seule définition @code{\dolce}, au lieu de devoir modifier
291 chaque fichier @code{.ly}.
295 @section Style sheets
297 La sortie que produit LilyPond peut être largement modifiée --- voir
298 @ruser{Tweaking output} pour plus de détails. Mais que faire si vous
299 avez beaucoup de fichiers auxquels vous souhaitez appliquer vos
300 retouches ? Ou si vous souhaitez simplement séparer les retouches de
301 la musique elle-même ? Rien de plus facile.
303 Prenons un exemple. Ne vous inquiétez pas si vous ne comprenez pas
304 les parties avec tous les @code{#()}. Celles-ci sont expliquées dans
305 @ruser{Advanced tweaks with Scheme}.
307 @lilypond[quote,verbatim,ragged-right]
308 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
309 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
310 tempoMark = #(define-music-function (parser location markp) (string?)
312 \once \override Score . RehearsalMark #'self-alignment-X = #left
313 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
314 \mark \markup { \bold $markp }
319 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
320 \tempoMark "Poco piu mosso"
321 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
325 Il y a quelques problèmes de chevauchement ; nous allons arranger
326 cela en utilisant les techniques de @ruser{Moving objects}. On peut
327 aussi faire quelque chose pour les définitions de @code{mpdolce}
328 et @code{tempoMark}. Elles produisent le résultat que nous désirons,
329 mais nous pourrions aussi vouloir les utiliser dans une autre pièce.
330 Il suffirait de les copier et les coller au début de chaque
331 fichier, mais c'est fastidieux. De plus, cela laisse les définitions
332 dans nos fichiers de musique, et je trouve personnellement tous ces
333 @code{#()} assez laids. Stockons-les dans un autre fichier :
336 %%% enregistrez ceci dans un fichier nommé "definitions.ly"
337 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
338 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
339 tempoMark = #(define-music-function (parser location markp) (string?)
341 \once \override Score . RehearsalMark #'self-alignment-X = #left
342 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
343 \mark \markup @{ \bold $markp @}
347 Maintenant, modifions notre musique (enregistrez ce fichier
348 sous @file{"musique.ly"}).
350 @c We have to do this awkward example/lilypond-non-verbatim
351 @c because we can't do the \include stuff in the manual.
354 \include "definitions.ly"
358 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
359 \once \override Score.RehearsalMark #'padding = #2.0
360 \tempoMark "Poco piu mosso"
361 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
365 @lilypond[quote,ragged-right]
366 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
367 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
368 tempoMark = #(define-music-function (parser location markp) (string?)
370 \once \override Score . RehearsalMark #'self-alignment-X = #left
371 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
372 \mark \markup { \bold $markp }
377 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
378 \once \override Score.RehearsalMark #'padding = #2.0
379 \tempoMark "Poco piu mosso"
380 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
384 C'est mieux, mais effectuons encore quelques retouches. Le glissando
385 est peu visible, c'est pourquoi nous allons l'épaissir et le
386 rapprocher des têtes de notes. Déplaçons l'indication métronomique
387 au-dessus de la clef, au lieu de la laisser au-dessus de la première
388 note. Et pour finir, mon professeur de composition déteste les
389 chiffrages de mesure en @qq{C}, nous allons donc le transformer en @qq{4/4}.
391 Cependant, ne changez pas le fichier @file{musique.ly}. Remplacez le
392 fichier @file{definitions.ly} par ceci :
396 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
397 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
398 tempoMark = #(define-music-function (parser location markp) (string?)
400 \once \override Score . RehearsalMark #'self-alignment-X = #left
401 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
402 \mark \markup @{ \bold $markp @}
407 \override MetronomeMark #'extra-offset = #'(-9 . 0)
408 \override MetronomeMark #'padding = #'3
411 \override TimeSignature #'style = #'numbered
414 \override Glissando #'thickness = #3
415 \override Glissando #'gap = #0.1
420 @lilypond[quote,ragged-right]
421 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
422 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
423 tempoMark = #(define-music-function (parser location markp) (string?)
425 \once \override Score . RehearsalMark #'self-alignment-X = #left
426 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
427 \mark \markup { \bold $markp }
432 \override MetronomeMark #'extra-offset = #'(-9 . 0)
433 \override MetronomeMark #'padding = #'3
436 \override TimeSignature #'style = #'numbered
439 \override Glissando #'thickness = #3
440 \override Glissando #'gap = #0.1
446 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
447 \once \override Score.RehearsalMark #'padding = #2.0
448 \tempoMark "Poco piu mosso"
449 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
453 C'est encore mieux ! Mais supposons maintenant que je veuille publier
454 cette pièce. Mon professeur de composition n'aime pas les chiffrages
455 de mesure en @qq{C}, mais moi je les aime bien. Copions l'actuel
456 @file{definitions.ly} dans le fichier @file{publication-web.ly}, et
457 modifions ce dernier. Puisque la musique est destinée à produire un
458 fichier PDF affiché sur écran, nous allons aussi augmenter la taille
463 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
464 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
465 tempoMark = #(define-music-function (parser location markp) (string?)
467 \once \override Score . RehearsalMark #'self-alignment-X = #left
468 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
469 \mark \markup @{ \bold $markp @}
472 #(set-global-staff-size 23)
475 \override MetronomeMark #'extra-offset = #'(-9 . 0)
476 \override MetronomeMark #'padding = #'3
481 \override Glissando #'thickness = #3
482 \override Glissando #'gap = #0.1
487 @lilypond[quote,ragged-right]
488 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
489 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
490 tempoMark = #(define-music-function (parser location markp) (string?)
492 \once \override Score . RehearsalMark #'self-alignment-X = #left
493 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
494 \mark \markup { \bold $markp }
497 #(set-global-staff-size 23)
500 \override MetronomeMark #'extra-offset = #'(-9 . 0)
501 \override MetronomeMark #'padding = #'3
504 \override Glissando #'thickness = #3
505 \override Glissando #'gap = #0.1
511 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
512 \once \override Score.RehearsalMark #'padding = #2.0
513 \tempoMark "Poco piu mosso"
514 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
518 Il ne nous reste plus qu'à remplacer @code{\include "definitions.ly"}
519 par @code{\include "publication-web.ly"} dans notre fichier de musique.
521 Il est possible, bien sûr, de rendre cela encore plus pratique. Nous
522 pourrions créer un fichier @file{definitions.ly} qui ne contiendrait
523 que les définitions de @code{mpdolce} et de @code{tempoMark}, un
524 fichier @file{publication-web.ly} qui ne contiendrait que la section
525 @code{layout} décrite ci-dessus et un fichier @file{universite.ly} qui
526 ne contiendrait que les retouches pour produire le résultat que mon
527 professeur préfère. Le début du fichier @file{musique.ly} ressemblerait
531 \include "definitions.ly"
533 %%% Décommentez seulement une de ces deux lignes !
534 \include "publication-web.ly"
535 %\include "universite.ly"
538 Cette approche peut être utile même si vous ne produisez qu'un seul
539 jeu de partitions. J'utilise personnellement une demi-douzaine de
540 fichiers de @qq{feuille de style} pour mes projets. Je commence
541 chaque fichier de musique par @code{\include "../global.ly"} qui contient :
546 #(ly:set-option 'point-and-click #f)
547 \include "../init/init-defs.ly"
548 \include "../init/init-mise-en-page.ly"
549 \include "../init/init-en-tetes.ly"
550 \include "../init/init-papier.ly"
553 @node Updating old files
554 @section Updating old files
556 La syntaxe de LilyPond change de temps en temps. Ces changements de
557 syntaxe du langage d'entrée accompagnent les améliorations du
558 logiciel. Ces changements sont parfois destinés à rendre les fichiers
559 plus faciles à lire et à écrire, ou permettent d'intégrer de nouvelles
562 LilyPond est fourni avec un utilitaire qui facilite cette mise à
563 jour : @code{convert-ly}. Pour savoir comment utiliser ce programme,
564 voir @rprogram{Updating files with convert-ly}.
566 Malheureusement, @code{convert-ly} ne peut pas réaliser toutes les
567 modifications. Il s'occupe des changements qui ne requièrent qu'une
568 simple substitution de texte --- comme @code{raggedright} devenant
569 @code{ragged-right} ---, les autres étant trop compliqués à effectuer.
570 Les changements de syntaxe qui ne sont pas gérés par @code{convert-ly}
571 sont énumérés dans @rprogram{Updating files with convert-ly}.
573 Par exemple, dans les versions 2.4 et antérieures de LilyPond,
574 les accents et les lettres non anglaises étaient entrées en
575 utilisant LaTeX --- par exemple, @samp{No\"el}. À partir de la
576 version 2.6, le caratère @samp{ë} doit être entré directement
577 dans le fichier LilyPond comme caractère UTF-8.
578 @code{convert-ly} ne peut pas changer tous les caractères
579 LaTeX en caractères UTF-8 ; vous devez mettre à jour vos vieux
580 fichiers LilyPond manuellement.
584 @node Troubleshooting (taking it all apart)
585 @section Troubleshooting (taking it all apart)
587 Tôt ou tard, vous écrirez un fichier que LilyPond ne peut pas
588 compiler. Les messages que LilyPond affiche peuvent vous aider à
589 trouver l'erreur, mais dans beaucoup de cas vous aurez besoin de faire
590 quelques recherches pour déterminer la source du problème.
592 Pour ce faire, les outils les plus puissants sont le commentaire de
593 fin de ligne, indiqué par @code{%}, et le commentaire multilignes (ou
594 bloc de commentaire), indiqué par @code{%@{ ... %@}}. Si vous ne
595 pouvez localiser le problème, commencez par mettre en commentaire de
596 grandes parties de votre fichier d'entrée. Après avoir mis en
597 commentaire une section, essayez de compiler à nouveau. Si cela
598 fonctionne, c'est que le problème se situe dans cette partie du
599 fichier. Si cela ne fonctionne pas, continuez à mettre en commentaire
600 d'autres sections, jusqu'à ce que vous ayez quelque chose qui compile.
602 Dans un cas extrême, vous pourriez en arriver à
616 c'est-à-dire un fichier sans aucune musique.
618 Si cela arrive, ne vous découragez pas. Décommentez un peu, la partie
619 de basse par exemple, et voyez si ça fonctionne. Si ce n'est pas le
620 cas, placez en commentaire toute la partie de basse, mais laissez
621 @code{\basse} décommenté dans le bloc @code{\score}.
624 basse = \relative c' @{
632 Maintenant commencez à décommenter petit à petit le partie de
633 @code{basse} jusqu'à ce que vous localisiez la ligne qui pose
636 Une autre technique de déboguage très utile est la construction
638 de @ruser{Minimal examples}.
641 d'@ruser{Minimal examples}.
645 @node Minimal examples
646 @section Minimal examples
648 Un exemple minimal est un exemple de code aussi court que possible.
649 De tels exemples sont bien plus compréhensibles que des exemples
650 longs. Les exemples minimaux sont utilisés pour
653 @item les rapports de bogue,
654 @item les demandes d'aide sur les listes de diffusion,
656 @uref{http://lsr@/.dsi@/.unimi@/.it/,LilyPond Snippet Repository}.
659 Pour construire un exemple minimal, la règle est très simple : enlevez
660 tout ce qui n'est pas nécessaire. Il est préférable de commenter les
661 lignes non nécessaires plutôt que de les effacer : ainsi, si vous vous
662 apercevez que certaines étaient @emph{réellement} nécessaires, vous
663 pouvez les décommenter au lieu de les resaisir.
665 Il y a deux exceptions à cette règle du strict nécessaire :
668 @item incluez le numéro de @code{\version} en début de fichier
669 @item si possible, utilisez @code{\paper@{ ragged-right=##t @}} au
670 début de votre exemple.
673 Tout l'intérêt d'un exemple minimal réside dans sa facilité de lecture :
675 @item évitez d'utiliser des notes, armures ou métriques compliquées, à
676 moins que vous ne vouliez montrer quelque chose en rapport avec
678 @item n'utilisez pas de commandes @code{\override} sauf si elles font
679 l'intérêt de l'exemple.